如何在 React Native 中动态提升 TextInput 避开键盘遮挡

问题背景

在React Native开发的移动端应用中，当用户点击页面底部的TextInput组件唤起键盘时，键盘往往会直接覆盖输入框，导致用户无法看到自己输入的内容，这种情况在全面屏设备和不同系统版本的手机上表现差异很大，固定调整布局的方式很难适配所有场景，因此需要实现动态提升TextInput的效果。

核心实现思路

要实现动态提升TextInput避开键盘遮挡，核心分为三个步骤：首先监听键盘的弹出和收起事件，获取键盘的高度；其次测量TextInput组件在页面中的当前位置；最后根据键盘高度和输入框位置计算需要提升的偏移量，动态调整页面布局。

1. 监听键盘事件

React Native提供了Keyboard模块，可以监听键盘的状态变化，我们可以分别在键盘弹出和收起时获取对应的键盘高度，同时记录当前的状态。

import { Keyboard, KeyboardAvoidingView, Platform } from 'react-native';

// 监听键盘弹出事件
const showSubscription = Keyboard.addListener(
  Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow',
  (e) => {
    // 获取键盘高度，不同系统获取方式略有差异
    const keyboardHeight = e.endCoordinates.height;
    // 记录键盘高度到状态中
    setKeyboardHeight(keyboardHeight);
    setIsKeyboardShow(true);
  }
);

// 监听键盘收起事件
const hideSubscription = Keyboard.addListener(
  Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide',
  (e) => {
    setKeyboardHeight(0);
    setIsKeyboardShow(false);
  }
);

// 组件卸载时移除监听
useEffect(() => {
  return () => {
    showSubscription.remove();
    hideSubscription.remove();
  };
}, []);

2. 测量TextInput位置

需要获取TextInput组件距离页面顶部的距离，以及组件自身的高度，这样才能判断键盘弹出时是否会覆盖输入框。我们可以使用onLayout方法获取组件的布局信息。

const [inputLayout, setInputLayout] = useState({ y: 0, height: 0 });

const handleInputLayout = (e) => {
  const { y, height } = e.nativeEvent.layout;
  // y是输入框距离页面顶部的距离，height是输入框自身高度
  setInputLayout({ y, height });
};

3. 计算提升偏移量

计算偏移量时需要结合屏幕高度、键盘高度、输入框位置来判断：如果输入框底部距离屏幕底部的距离小于键盘高度，说明会被遮挡，需要提升的高度为键盘高度减去输入框底部到屏幕底部的距离。

import { Dimensions } from 'react-native';

const screenHeight = Dimensions.get('window').height;

const calculateOffset = () => {
  // 输入框底部距离屏幕顶部的距离
  const inputBottom = inputLayout.y + inputLayout.height;
  // 输入框底部距离屏幕底部的距离
  const distanceToBottom = screenHeight - inputBottom;
  // 如果距离底部的距离小于键盘高度，说明会被遮挡
  if (distanceToBottom < keyboardHeight) {
    // 需要提升的高度 = 键盘高度 - 输入框底部到屏幕底部的距离
    return keyboardHeight - distanceToBottom;
  }
  return 0;
};

完整示例代码

下面是一个完整的可运行示例，实现了TextInput动态提升避开键盘遮挡的效果，适配了iOS和Android两个平台。

import React, { useState, useEffect } from 'react';
import { 
  View, 
  TextInput, 
  Keyboard, 
  KeyboardAvoidingView, 
  Platform, 
  Dimensions, 
  StyleSheet,
  ScrollView
} from 'react-native';

const screenHeight = Dimensions.get('window').height;

const KeyboardAvoidInput = () => {
  const [keyboardHeight, setKeyboardHeight] = useState(0);
  const [isKeyboardShow, setIsKeyboardShow] = useState(false);
  const [inputLayout, setInputLayout] = useState({ y: 0, height: 0 });
  const [inputValue, setInputValue] = useState('');

  // 监听键盘事件
  useEffect(() => {
    const showEvent = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow';
    const hideEvent = Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide';

    const showSubscription = Keyboard.addListener(showEvent, (e) => {
      const height = e.endCoordinates.height;
      setKeyboardHeight(height);
      setIsKeyboardShow(true);
    });

    const hideSubscription = Keyboard.addListener(hideEvent, () => {
      setKeyboardHeight(0);
      setIsKeyboardShow(false);
    });

    return () => {
      showSubscription.remove();
      hideSubscription.remove();
    };
  }, []);

  // 计算需要提升的偏移量
  const getOffset = () => {
    if (!isKeyboardShow || keyboardHeight === 0) return 0;
    const inputBottom = inputLayout.y + inputLayout.height;
    const distanceToBottom = screenHeight - inputBottom;
    if (distanceToBottom < keyboardHeight) {
      return keyboardHeight - distanceToBottom + 20; // 额外加20的缓冲距离
    }
    return 0;
  };

  return (
    <View style={styles.container}>
      <ScrollView 
        contentContainerStyle={styles.scrollContent}
        keyboardShouldPersistTaps="handled"
      >
        <View style={styles.placeholder}>
          <Text>上方占位内容</Text>
        </View>
        <View style={styles.inputWrapper}>
          <TextInput
            style={styles.input}
            value={inputValue}
            onChangeText={setInputValue}
            placeholder="请输入内容"
            onLayout={(e) => {
              const { y, height } = e.nativeEvent.layout;
              setInputLayout({ y, height });
            }}
          />
        </View>
      </ScrollView>
      <View style={{ height: getOffset() }}></View>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#f5f5f5',
  },
  scrollContent: {
    padding: 20,
    paddingBottom: 100, // 给输入框预留足够底部空间
  },
  placeholder: {
    height: 600,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#e0e0e0',
    marginBottom: 20,
    borderRadius: 8,
  },
  inputWrapper: {
    marginTop: 20,
  },
  input: {
    height: 50,
    borderWidth: 1,
    borderColor: '#ccc',
    borderRadius: 8,
    paddingHorizontal: 15,
    backgroundColor: '#fff',
    fontSize: 16,
  },
});

export default KeyboardAvoidInput;

注意事项

• iOS和Android的键盘事件名称不同，iOS使用keyboardWillShow和keyboardWillHide，Android使用keyboardDidShow和keyboardDidHide，需要做平台适配。
• 如果页面使用了ScrollView，建议设置keyboardShouldPersistTaps="handled"，避免点击输入框外的区域收起键盘时触发其他事件。
• 计算偏移量时可以额外增加10-20的缓冲距离，让输入框和键盘之间保留一定间隙，提升用户体验。
• 如果页面中有多个TextInput，需要分别测量每个输入框的位置，在聚焦时动态获取当前聚焦输入框的布局信息来计算偏移量。

React_NativeTextInput键盘遮挡动态提升修改时间：2026-07-22 19:18:36