前言软键盘弹出时遮挡输入框是移动开发的常见问题。HarmonyOS提供了键盘避让模式设置pura/harmony-utils的KeyboardUtil封装了键盘相关控制方法帮助开发者解决键盘遮挡问题。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解帮助开发者快速掌握并应用到实际项目中。一、KeyboardUtil核心APIKeyboardUtil提供了以下键盘控制方法方法说明参数使用场景setKeyboardAvoidMode(mode)设置键盘避让模式KeyboardAvoidMode解决键盘遮挡getKeyboardAvoidMode()获取当前避让模式无状态查询isKeyboardShowing()判断键盘是否显示无键盘状态感知1.1 核心特性简洁易用封装复杂API为一行调用降低使用门槛类型安全完整的TypeScript类型定义编译期即可发现错误异常处理内置异常捕获机制避免运行时崩溃即时生效避让模式设置后立即生效1.2 避让模式对比避让模式效果适用场景OFFSET页面上推聊天页面、表单RESIZE布局调整滚动列表页面二、完整使用步骤2.1 安装依赖ohpminstallpura/harmony-utils2.2 设置键盘避让模式import{KeyboardUtil}frompura/harmony-utils;Button(设置上推避让).width(100%).onClick((){try{KeyboardUtil.setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET);this.result上推避让模式已设置 ⬆️\n键盘弹出时页面上推;}catch(e){this.result异常: e;}})Button(设置平移避让).width(100%).onClick((){try{KeyboardUtil.setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);this.result平移避让模式已设置 ↔️\n键盘弹出时布局调整;}catch(e){this.result异常: e;}})2.3 查询键盘状态Button(查询键盘状态).width(100%).onClick((){try{letmodeKeyboardUtil.getKeyboardAvoidMode();this.result当前避让模式:${mode};}catch(e){this.result异常: e;}})三、完整页面示例import{KeyboardUtil}frompura/harmony-utils;EntryComponentstruct KeyboardDemo{Stateresult:string;build(){Column({space:12}){Button(设置上推避让).width(100%).onClick((){KeyboardUtil.setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET);this.result上推避让已设置;});Button(查询避让模式).width(100%).onClick((){letmodeKeyboardUtil.getKeyboardAvoidMode();this.result避让模式:${mode};});TextInput().width(100%).placeholder(点击此处弹出键盘测试)Text(this.result).fontSize(14).fontColor(#333333)}.padding(16)}}四、进阶用法4.1 聊天页面键盘适配import{KeyboardUtil}frompura/harmony-utils;aboutToAppear(){KeyboardUtil.setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);}4.2 表单页面键盘适配aboutToAppear(){KeyboardUtil.setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET);}五、注意事项避让模式选择根据页面布局选择合适的避让模式测试覆盖不同输入框位置都需要测试键盘避让效果初始化依赖使用前需确保AppUtil.init()已调用模式切换页面切换时注意恢复避让模式键盘高度不同设备的键盘高度可能不同六、常见问题Q1: 设置避让模式后输入框仍然被遮挡检查是否使用了Scroll组件某些布局结构可能影响避让效果。Q2: OFFSET和RESIZE有什么区别OFFSET将整个页面上推RESIZE调整布局大小。聊天页面推荐RESIZE表单页面推荐OFFSET。Q3: 如何在特定输入框聚焦时切换避让模式可以在TextInput的onFocus回调中动态切换避让模式。Q4: 键盘弹出时列表滚动位置异常建议使用RESIZE模式配合Scroll组件避免手动计算偏移量。总结KeyboardUtil的键盘避让方法为解决键盘遮挡问题提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理选择避让模式可以确保输入框始终可见提升用户体验。本文基于pura/harmony-utils工具库更多功能请参考官方文档与后续系列文章。