鸿蒙RN TextInput键盘收起与输入框遮挡适配

鸿蒙专家

前言
TextInput 是 App 中最常用的组件之一，登录、搜索、评论、聊天都离不开。iOS 和 Android 上体验较顺，但在鸿蒙上键盘相关交互容易出现异常。原文提到一次真实经历：在鸿蒙上测登录页，输入账号密码后点登录，键盘收不起来，最终发现是 keyboardShouldPersistTaps 没设对，与鸿蒙键盘行为有关。

基础用法：受控输入
TextInput 的核心是让用户输入文字，再通过 onChangeText 拿到内容。每次输入都会触发 onChangeText，在其中更新 state 即可。关键点是必须用 value 属性绑定 state，否则输入框会变成非受控组件，React 不再管理它的值，容易出现输入框内容与 state 不一致的问题。

常用属性与鸿蒙差异
placeholder 用于空输入时的提示，placeholderTextColor 可自定义提示颜色。keyboardType 控制键盘类型：phone-pad 弹数字键盘，email-address 弹带 @ 的键盘，numeric 弹纯数字键盘，url 弹带 .com 的键盘。原文指出，这些类型在鸿蒙上基本支持，但 decimal-pad 有时不生效，会退化成普通键盘。
secureTextEntry 用于密码输入，把文字显示为圆点。maxLength 限制字符数，例如验证码最多 6 位。multiline 用于多行输入，但 Android 和鸿蒙上默认会垂直居中，需要加 textAlignVertical: 'top' 才能让文字从顶部开始。editable 可设为 false 禁用输入框。returnKeyType 控制回车键样式，search 显示搜索，done 显示完成，next 显示下一个。

鸿蒙上的典型坑与处理

坑 1：键盘收不起来
这是最常见的问题。iOS 上点击输入框外部区域键盘会自动收起，但鸿蒙上有时不收。解决方法是设置 keyboardShouldPersistTaps。它有三个值：never 表示点击任何地方键盘都收起，但子组件收不到点击事件；always 表示键盘永远不收起；handled 表示如果子组件处理了点击事件，键盘不收起，否则收起。大多数场景下 handled 最合适。

2. <ScrollView keyboardShouldPersistTaps="handled">
3.   <TextInput placeholder="输入框1" />
4.   <TextInput placeholder="输入框2" />
5.   <Button title="提交" onPress={handleSubmit} />
6. </ScrollView>

复制代码

坑 2：输入框被键盘遮挡
输入框在页面底部时，键盘弹出会遮住它。原文方案是用 ScrollView 包裹整个页面，并设置 keyboardShouldPersistTaps 为 handled；也可以使用 KeyboardAvoidingView，但在鸿蒙上效果可能不太好。点击按钮或结果项时，可用 Keyboard.dismiss 主动收起键盘。

坑 3：multiline 高度自适应
聊天输入框等场景需要根据内容自动调整高度。原文尝试监听 onContentSizeChange 并更新 inputHeight，在 iOS 上效果不错，但在鸿蒙上事件触发时机可能不对，高度计算不准确，导致输入框跳动。目前没有特别好的解决方案，可暂时用固定高度加 ScrollView 替代。

坑 4：secureTextEntry 下粘贴失灵
密码输入框设置 secureTextEntry={true} 后，鸿蒙上长按粘贴有时会失灵。原文测试发现是粘贴板内容格式问题：如果用户从其他 App 复制密码，粘贴板里可能带有特殊格式，TextInput 会拒绝接收。目前的 workaround 是在 onChangeText 中过滤不可见字符，例如把 x00 到 x1F、x7F 等不可见字符去掉后再 setPassword。

坑 5：autoFocus 时机问题
设置 autoFocus={true} 可以让输入框自动获取焦点，但鸿蒙上有时失灵。原文遇到的情况是：从上一个页面跳转过来并设置 autoFocus，输入框没有自动获取焦点，原因是页面渲染还没完成，焦点就被抢走了。方案是延迟一下再设置焦点：

2. const inputRef = useRef<TextInput>(null);
3. useEffect(() => {
4.   const timer = setTimeout(() => {
5.     inputRef.current?.focus();
6.   }, 300);
7.   return () => clearTimeout(timer);
8. }, []);
10. <TextInput ref={inputRef} />

复制代码

实战：登录页
登录页通常包含手机号和密码两个输入框。原文示例中，外层 ScrollView 设置 keyboardShouldPersistTaps 为 handled；手机号输入框用 phone-pad，maxLength 为 11；密码输入框用 secureTextEntry，并可通过按钮切换明文/密文；点击登录时先 Keyboard.dismiss，再校验并提示。手机号输入完按回车通过 onSubmitEditing 聚焦密码框，密码输入完按回车直接登录。这些处理能减少鸿蒙上键盘不收、焦点不跳转的问题。

实战：搜索页
搜索页的搜索框设置 autoFocus 自动聚焦，clearButtonMode 为 while-editing 提供清除按钮，returnKeyType 为 search 让回车键显示搜索。输入时实时更新关键词并展示 FlatList 结果，点击取消或结果项时调用 Keyboard.dismiss 收起键盘。原文通过模拟搜索展示了这类页面的基本结构。

总结
TextInput 是 RN 的基础输入组件，在鸿蒙上的兼容性总体还行，但细节需要注意。排查时可优先关注：键盘收起设置 keyboardShouldPersistTaps 为 handled；输入框遮挡用 ScrollView 包裹并处理键盘避让，KeyboardAvoidingView 在鸿蒙上效果可能不好；多行高度自适应在鸿蒙上可能跳动，建议固定高度；密码粘贴过滤不可见字符；自动聚焦延迟处理；keyboardType 中 decimal-pad 有时不生效；multiline 需设置 textAlignVertical 为 top。
这些问题的共同点是键盘交互、焦点管理、粘贴板格式和渲染时机，在鸿蒙 RN 开发中优先从属性配置与时序处理入手，能减少大部分异常。