uni-app X 键盘控制 API 实战指南：hideKeyboard、onKeyboardHeightChange 与 offKeyboardHeightChange 全解析

uni-app X 键盘控制 API 实战指南hideKeyboard、onKeyboardHeightChange 与 offKeyboardHeightChange 全解析【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本篇技术指南以 uni-app X 仓库中 键盘 API 文档 为核心系统讲解uni.hideKeyboard、uni.onKeyboardHeightChange、uni.offKeyboardHeightChange三个全局键盘 API 的参数定义、跨端兼容性与底层实现原理。读完本文你将能够在 AppAndroid/iOS/HarmonyOS、微信小程序与 Web 端正确隐藏系统键盘、全局监听键盘弹出收起与高度变化并结合input/textarea组件与自动化测试写出健壮的键盘交互逻辑。一、三 API 总览与适用场景uni-app X 的键盘能力由uni-keyboard插件模块提供对应目录 src/uni_modules/uni-keyboard插件清单见 package.json对外暴露三个全局 API| API | 作用 | 是否需要注册监听 | 返回 | | :- | :- | :- | :- | |uni.hideKeyboard(options?)| 隐藏键盘 | 否 |void| |uni.onKeyboardHeightChange(callback)| 监听键盘高度变化事件 | 是 |number监听 id | |uni.offKeyboardHeightChange(id?)| 移除键盘高度变化事件的监听函数 | 是 |void|三个 API 的方法名常量定义在 protocol.uts 中API_HIDE_KEYBOARD、API_ON_KEYBOARD_HEIGHT_CHANGE、API_OFF_KEYBOARD_HEIGHT_CHANGE类型定义集中在 interface.uts。核心应用场景输入完成后程序化收起键盘如点击页面空白处或发送按钮全局监听键盘弹出/收起驱动消息列表滚动到底部、聊天输入框上移等布局变化App 内嵌 web-view 场景web-view 内部的键盘变化无法在input/textarea组件上监听只能使用onKeyboardHeightChange这一全局 API 捕获——这是该 API 相对组件事件的核心价值详见下文第四节。二、uni.hideKeyboard程序化隐藏键盘2.1 函数签名与参数uni.hideKeyboard(options?: HideKeyboardOptions | null): void参数options为可选对象类型HideKeyboardOptions属性如下| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | success |(res: HideKeyboardSuccess) void| 否 | 成功回调函数 | | fail |(res: HideKeyboardFail) void| 否 | 失败回调函数 | | complete |(res: any) void| 否 | 完成回调函数成功、失败均执行 |其中HideKeyboardSuccess与HideKeyboardFail均为空对象类型见 interface.utssuccess/complete回调收到一个空对象{}作为结果。2.2 兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 4.71 | 4.71 | 4.61 |即自 uni-app x 4.0 起 Web 端可用App 三端需 4.61/4.71 及以上微信小程序需基础库 4.41 及以上。HBuilderX 最低版本要求为^3.6.8见 package.json同时支持 Vue 2 与 Vue 3interface.uts 标注uniVueVersion 2,3。2.3 底层实现Android 侧关键细节Android 端实现位于 src/uni_modules/uni-keyboard/utssdk/app-android/index.utsexport const hideKeyboard: HideKeyboard (options?: HideKeyboardOptions | null) { var activity: Activity UTSAndroid.getUniActivity()!; if (inputManager null) { inputManager activity.getSystemService(Context.INPUT_METHOD_SERVICE) as InputMethodManager } let focusView activity.getCurrentFocus() if (focusView ! null) { focusView!.postDelayed(class implements Runnable { override run() { let shouldClearFocus !isWebViewRelatedFocusView(focusView!) let result inputManager!.hideSoftInputFromWindow(focusView!.getWindowToken(), 0) if (result shouldClearFocus) { focusView!.clearFocus() // 临时验证隐藏软键盘不失去焦点 } } }, 16) } var success: HideKeyboardSuccess {} options?.success?.(success) options?.complete?.(success) }从源码可以提炼出几个重要的实现事实通过InputMethodManager.hideSoftInputFromWindow()隐藏软键盘调用被延迟16mspostDelayed执行以确保在输入法弹起过程中调用隐藏也足够稳定焦点保持策略隐藏键盘后默认会调用clearFocus()使输入框失去焦点但如果当前焦点视图位于WebView内部通过isWebViewRelatedFocusView向上遍历父视图判断见同文件 index.uts则不会清除焦点避免内嵌 web-view 的输入交互被打断。iOS 端实现更为简洁直接调用原生桥UTSiOS.hideKeyboard()见 app-ios/index.utsHarmonyOS 端则通过inputMethod.getController().hideTextInput()异步隐藏成功时exec.resolve()、失败时exec.reject(err.message)见 app-harmony/index.uts。三、uni.onKeyboardHeightChange全局监听键盘高度3.1 函数签名与参数uni.onKeyboardHeightChange(callback: OnKeyboardHeightChangeCallback): numbercallback为必填参数接收一个OnKeyboardHeightChangeCallbackResult对象其唯一属性为| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | height | number | 是 | 键盘高度单位 px |注意返回值该方法返回一个number类型的监听 id应妥善保存用于后续uni.offKeyboardHeightChange(id)精确移除该监听。3.2 与组件事件的区别input和textarea组件上也有用于监听键盘高度变化的组件事件参见 input 组件文档 与 textarea 组件文档。本 API 是全局 API可以全局监听键盘弹出、收起和高度变化特别是App 内嵌 web-view 中的键盘变化无法在组件上监听只能使用本 API 全局监听。3.3 兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x不支持 | 4.41 | 4.71 | 4.71 | 5.08 |从源码标注看interface.uts微信小程序要求基础库2.7HarmonyOS 需 5.08 及以上而Web 端明确标注x即不支持。因此跨端使用时需要对 Web 做能力判断或降级处理例如 Web 端依赖组件级事件或 CSS 环境变量。3.4 底层实现Android 全局布局监听Android 端实现app-android/index.uts在首次调用时创建单例监听器OnKeyBoardChangedListener随后通过ViewTreeObserver.addOnGlobalLayoutListener挂载全局布局监听同文件 index.uts。其核心原理用rootView.getWindowVisibleDisplayFrame(rect)与根视图总高度计算差值diffHeight fullHeight - rect.height() - systemBarHeight差值即键盘占用高度通过UTSAndroid.devicePX2px()将设备像素转换为逻辑像素后通过callback回调内部记录lastKeyboardHeight去重避免相同高度重复触发该监听器继承UniActivityLifeCycleCallback即使页面被遮挡如切换 Activity 后返回也能通过onResume重新挂载监听保证回调不中断同文件 index.uts。HarmonyOS 端通过window.on(keyboardHeightChange, wrappedCallback)订阅系统窗口事件并把原始像素高度用px2vp()转换为 vp 单位app-harmony/index.utsiOS 端通过原生桥UTSiOS.onKeyboardHeightChange()桥接app-ios/index.uts。四、uni.offKeyboardHeightChange移除键盘高度监听4.1 函数签名与参数uni.offKeyboardHeightChange(id?: number | null): void| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | id | number | 否 |onKeyboardHeightChange返回的监听 id |传入id仅移除该 id 对应的那一个监听函数不传 id或传 null移除全部键盘高度监听。4.2 兼容性与onKeyboardHeightChange一致微信小程序 4.41、Android 4.71、iOS 4.71、HarmonyOS 5.08Web 不支持。4.3 底层行为Android传入 id 时从内部HashMap删除对应回调并在回调集合为空时调用listener.unwatch()移除全局布局监听不传 id 时清空整个回调集合并unwatch()app-android/index.uts。HarmonyOS不传 id 时遍历内部 Map对每个回调执行window.off(keyboardHeightChange, ...)并清空 Map传 id 时仅移除对应回调app-harmony/index.uts。最佳实践在页面onUnload页面卸载时调用uni.offKeyboardHeightChange()清理监听防止页面销毁后回调泄漏若同一页面注册了多个监听则用 id 逐个精准移除。五、完整实战示例键盘高度实时显示与一键隐藏仓库中 src/pages/API/keyboard/keyboard.uvue 提供了完整的可运行示例与 docs/api/keyboard.md 中的示例一致实现点击输入框显示键盘、点击按钮隐藏键盘、实时显示键盘高度与状态template view classcontainer view classinput-section input iduni-input-box classinput-box typetext :valuedata.inputValue placeholder点击输入框显示键盘 :focusdata.isFocus hold-keyboardtrue / button classbtn clickhideKeyboard隐藏键盘/button /view view classinfo-section text classinfo-text键盘高度: {{data.keyboardHeight}}px/text text classinfo-text键盘状态: {{data.keyboardStatus}}/text /view /view /template script setup languts type DataType { inputValue: string, isFocus: boolean, keyboardHeight: number, keyboardStatus: string, } // 使用reactive包装数据便于自动化测试获取 const data reactive({ inputValue: , isFocus: false, keyboardHeight: 0, keyboardStatus: 未显示, } as DataType) function hideKeyboard() { uni.hideKeyboard(); } onLoad(() { // 监听键盘高度变化 uni.onKeyboardHeightChange(res { data.keyboardHeight res.height; data.keyboardStatus res.height 0 ? 显示中 : 已隐藏; }); }) onUnload(() { // 页面卸载时移除监听 uni.offKeyboardHeightChange(); }) defineExpose({ data, hideKeyboard }) /script5.1 示例要点拆解hold-keyboardtrueinput组件属性表示聚焦时保持键盘不收起如点击按钮等操作后键盘仍然保持显示配合hideKeyboard实现按需收起onLoad注册、onUnload注销在页面生命周期中成对出现避免监听泄漏状态判定技巧用res.height 0判断键盘是显示中还是已隐藏——键盘完全收起时回调高度为 0defineExpose将data与hideKeyboard暴露给自动化测试框架便于在测试中读取状态与触发方法。六、自动化测试验证如何断言键盘行为仓库在 src/pages/API/keyboard/keyboard.test.js 中提供了配套的自动化测试基于 uni-app x 的 uni-test 框架完整覆盖显示键盘 → 隐藏键盘的闭环const PAGE_PATH /pages/API/keyboard/keyboard const platformInfo process.env.uniTestPlatformInfo.toLocaleLowerCase() const isAndroid platformInfo.startsWith(android) const isIOS platformInfo.startsWith(ios) const isWeb platformInfo.startsWith(web) const isMP platformInfo.startsWith(mp) const isHarmony platformInfo.startsWith(harmony) describe(keyboard, () { let page; if (isWeb || isMP || isIOS || isHarmony) { it(not support, async () { expect(1).toBe(1) }) return } beforeAll(async () { page await program.reLaunch(PAGE_PATH) await page.waitFor(600); }); it(Check hideKeyboard, async () { // 显示键盘 await page.setData({ data: { isFocus: true } }) await page.waitFor(1000) let keyboardStatus await page.data(data.keyboardStatus) expect(keyboardStatus).toBe(显示中) let keyboardHeight await page.data(data.keyboardHeight) expect(keyboardHeight).toBeGreaterThan(0) await page.callMethod(hideKeyboard); await page.waitFor(1000) // 验证键盘是否隐藏 keyboardStatus await page.data(data.keyboardStatus) expect(keyboardStatus).toBe(已隐藏) keyboardHeight await page.data(data.keyboardHeight) expect(keyboardHeight).toBe(0) }); });从测试源码可以得到两个可直接复用的实战结论平台分流该测试仅在 Android 上真实执行Web/小程序/iOS/HarmonyOS 走not support占位分支这与前文兼容性表格中Web 不支持高度监听的事实相互印证——测试需要等待键盘动画完成waitFor(1000)后断言断言模式以keyboardHeight 0断言键盘显示中以keyboardHeight 0与状态文本已隐藏断言键盘收起这套断言逻辑可以直接迁移到你自己的页面测试中。七、通用类型说明uni.hideKeyboard的success回调结果HideKeyboardSuccess与fail回调结果HideKeyboardFail均为空对象文档末尾还给出了通用回调结果类型GeneralCallbackResult见 docs/api/keyboard.md| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errMsg | string | 是 | 错误信息 |该类型是 uni-app X 各 API 回调结果的通用结构在键盘 API 中主要体现于失败/异常信息的承载。八、常见问题与注意事项Web 端不支持高度监听onKeyboardHeightChange/offKeyboardHeightChange在 Web 端标注为x跨端项目建议在 Web 上降级为组件级键盘事件input/textarea的keyboardheightchange参见 input 组件文档或固定布局方案web-view 键盘监听只能走全局 APIApp 内嵌 web-view 中的输入无法触发组件事件务必使用uni.onKeyboardHeightChange全局监听并配合 web-view 的message等机制联动布局web-view 组件文档隐藏键盘与焦点Android 端默认在隐藏键盘时清除输入框焦点WebView 焦点除外如果你的业务需要隐藏后继续保留焦点需基于isWebViewRelatedFocusView之外的场景自行设计例如重新focus输入框监听清理在onUnload中调用uni.offKeyboardHeightChange()多监听场景务必保存onKeyboardHeightChange的返回值并按 id 移除版本前提上述 API 对 HBuilderX 的最低要求为^3.6.8package.jsonApp 三端需要对应的 unixuni-app x版本达标如 HarmonyOS 的onKeyboardHeightChange需 5.08 及以上。九、深入阅读键盘 API 官方文档docs/api/keyboard.md类型定义与 Uni 接口声明src/uni_modules/uni-keyboard/utssdk/interface.utsAPI 常量协议src/uni_modules/uni-keyboard/utssdk/protocol.utsAndroid 原生实现src/uni_modules/uni-keyboard/utssdk/app-android/index.utsiOS 原生实现src/uni_modules/uni-keyboard/utssdk/app-ios/index.utsHarmonyOS 原生实现src/uni_modules/uni-keyboard/utssdk/app-harmony/index.uts插件配置与平台支持矩阵src/uni_modules/uni-keyboard/package.json可运行示例页面src/pages/API/keyboard/keyboard.uvue自动化测试用例src/pages/API/keyboard/keyboard.test.js相关组件input 组件文档 / textarea 组件文档 / web-view 组件文档【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考