HarmonyOS ArkTS 软键盘（Keyboard）管理指南
鸿蒙第四期开发者活动
这篇笔记不像属性表那样干巴巴，而是按日常开发者思考路径写出来：什么是软键盘、什么时候我们需要管理它、怎么控制它显示/隐藏、如何监听它的状态、以及一些常见布局适配思路。所有内容都是基于官方指南和社区实践整理的。华为开发者
一、软键盘在 ArkTS 里是什么？
在移动端（包括 HarmonyOS 设备）开发里，软键盘（Soft Keyboard）指的是当用户在 TextInput / TextArea / RichEditor 等输入组件中输入时自动弹出的输入界面。它不是 UI 组件本身，而是 系统层的输入工具，由系统在需要时自动显示或隐藏。华为开发者
默认行为：
- 用户点击输入框 → 键盘弹出
- 输入完成/失去焦点 → 键盘隐藏
- 然而，有些场景我们需要 主动控制键盘 或 监听键盘状态 → 这时就需要管理软键盘。
二、什么时候需要我们“管理键盘”？
下面是常见需要干预键盘显示/隐藏的场景：
登录页自动弹出键盘
点击输入框以外的地方隐藏键盘
在富文本/评论输入场景自定义键盘
输入框遮挡整个布局，需要调整页面滚动/位移
软键盘显示后需要重新布局页面元素
这些情境都不是系统默认“帮你搞定”的，因此我们需要手动控制或监听键盘。华为开发者
三、控制软键盘显示与隐藏（最常用的 API）
1. 从代码主动 显示软键盘
当你想在某一时刻弹出软键盘（比如进入登录页自动让账号输入框获得焦点并弹出键盘），可以：
- 获取输入法控制器（InputMethodController）
- 调用显示方法
import inputMethod from '@ohos.inputMethod';// 获取输入法控制器
const imController = inputMethod.getController();// 主动显示软键盘
imController.showTextInput();
如果键盘没有弹出，请确保当前界面有一个可获焦的输入组件（如 TextInput）已获取焦点。DEV Community
2. 隐藏软键盘（常用于“点击空白处收起”）
当用户点击其他区域或提交表单时，常常需要手动隐藏软键盘：
import inputMethod from '@ohos.inputMethod';const imController = inputMethod.getController();// 隐藏软键盘
imController.hideTextInput();
这在很多场景非常常用，例如“点完登录按钮后收起键盘”。DEV Community
Tips：
有时你还可以调用 stopInputSession() 来彻底结束输入会话（相当于“强制收起键盘”）。CSDN
四、监听键盘弹出/隐藏的状态
有些场景我们不仅要控制键盘，还要 监听键盘状态变化，例如动态调整布局高度：
方式 1 — 监听键盘高度变化
在 ArkUI/ArkTS 里可以利用 Window 或 InputMethod 相关事件监听键盘高度：
window.getLastWindow(context, (err, win) => {win.on('keyboardHeightChange', (event) => {console.log('Keyboard height:', event.height);// 你可以根据键盘高度调整布局});
});
这种监听不仅告诉你是否显示，还返回键盘高度数据，适用于“动态布局适配”场景。华为开发者
五、输入组件自身控制焦点也是键盘控制的一部分
在 ArkTS 里，输入组件（如 TextInput）默认点击会显示键盘。如果你想程序控制它是否获得焦点（从而显示或收起键盘），可以使用焦点控制机制：
让输入框获得焦点
TextInput().onFocus(() => console.log('Input focused, keyboard may show')).onBlur(() => console.log('Input lost focus, keyboard may hide'));
或者在需要的时候：
focusControl.requestFocus('myInputId');
这也会导致软键盘弹出（前提是控件可获焦）。Medium
六、自定义键盘场景（可替换系统键盘）
在一些业务场景下（比如数字输入、密码键盘、自定义输入工具栏）我们不想使用系统默认软键盘，而是使用 customKeyboard：
RichEditor({customKeyboard: CustomKeyboardBuilder()
})
这样，当文本组件获得焦点时，不会使用系统输入法，而是加载你定义的自定义键盘 UI。OpenHarmony
这在金融输入页、计算器式输入场景、密码键盘场景非常有用。
七、软键盘弹出导致的页面布局适配问题
软键盘弹出后经常会遮挡底部表单或按钮，这时需要做“键盘避让处理”（Keyboard Avoid Mode）：
响应软键盘的布局调整策略
通常有两种模式：
◆ 1) OFFSET（上移模式）
默认行为是“把页面内容整体上移”，让输入框露出来，但这种模式在某些设计稿里可能不美观。DEV Community
◆ 2) RESIZE（压缩模式）
将页面可视区域“压缩”，让布局整体在键盘上方显示，没有额外空白。可以通过 API 设置布局模式：
uiContext.setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
这种模式在列表页/表单页里看起来更加连贯，不会出现大段空白。DEV Community
八、实战建议（像真实项目里要注意的事）
不要盲目 showTextInput()
除非确实需要主动打开软键盘，否则依赖输入框自身获得焦点更自然。DEV Community
监听高度变化比监听 show/hide 更可靠
有些设备/版本里 show/hide 事件不够准确，监听高度变化可以更稳健地调整布局。华为开发者
自定义键盘要处理好输入和焦点逻辑
当你使用 customKeyboard 时，需要自己处理光标、输入反馈等逻辑（不像系统键盘那样自动处理全部内容）。OpenHarmony
避免遮挡底部按钮
用键盘避让模式或者监听键盘高度动态设置底部容器 margin/translate，避免按钮被遮挡。华为开发者
九、总结（像人写的开发者笔记式）
- 软键盘是系统层提供的输入工具，默认由输入组件控制。华为开发者
- 主动控制键盘：可以使用
inputMethod.getController().showTextInput()和hideTextInput()。DEV Community - 监听状态/高度变化：用
keyboardHeightChange更适合动态 UI 适配。华为开发者 - 布局避让：用不同的避让模式处理输入框遮挡问题。DEV Community
- 自定义输入场景：RichEditor 等支持 customKeyboard 实现业务专用键盘。OpenHarmony