文章目录前言一、问题本质键盘占用的是「屏幕底部矩形区域」二、KeyboardAvoidMode系统避让模式全解析2.1 API 入口2.2 各模式对比表2.3 OFFSET vs RESIZE 怎么选2.4 踩坑模式NONE三、avoidArea 实战窗口避让区 API3.1 什么是 avoidArea3.2 三种获取键盘高度的方式方式 1keyboardHeightChange 事件方式 2avoidAreaChange 事件方式 3getWindowAvoidArea 同步读取3.3 px 与 vp 转换3.4 生命周期注册与注销四、手动 padding关闭系统避让 自己顶起4.1 为什么需要手动方案4.2 Demo 实现逻辑4.3 手动方案注意事项五、Demo 代码走读5.1 场景配置KeyboardAvoidTypes.ets5.2 模式切换KeyboardAvoidPitfallDemo.ets5.3 表单设计FeedbackFormSection.ets六、safeAreaPadding 与 expandSafeArea 补充七、常见错误与排查7.1 错误清单7.2 排查流程八、方案选型决策树九、真机体验指南配合 Demo十、总结附录Demo 文件结构附录快速参考卡前言在移动端开发中「输入框被软键盘挡住」是最常见、也最令人沮丧的体验问题之一。用户点击页面底部的备注框键盘弹起光标和输入区域消失在键盘下方——用户看不到自己在打什么字只能凭感觉盲打或者反复拖动页面碰运气。不少 HarmonyOS 开发者初次遇到这个问题时的反应是「我明明用了Scroll为什么还是挡」「加了paddingBottom: 300就好了但不同手机键盘高度不一样……」「听说有个 avoidArea到底怎么用」HarmonyOS 提供了两套互补机制来解决键盘遮挡系统级避让UIContext.setKeyboardAvoidMode()由框架自动顶起或压缩页面窗口级避让区avoidArea通过window.getWindowAvoidArea()、avoidAreaChange、keyboardHeightChange获取键盘占用区域开发者手动调整padding/ 滚动位置。本文结合项目中的可运行 Demo从原理、API 对比、代码走读、手动 padding 实战到选型建议做一次完整解析。读完后你应该能回答OFFSET和RESIZE有什么区别avoidArea和keyboardHeightChange该听哪个什么时候用系统避让什么时候自己算 padding一、问题本质键盘占用的是「屏幕底部矩形区域」软键盘弹出时系统会在屏幕底部划出一一块不可布局区域——即Avoid Area避让区。窗口的可交互内容区被压缩若不做处理原本位于底部的TextInput/TextArea就会与键盘重叠。┌─────────────────────────────┐ │ 状态栏 / 标题 │ ├─────────────────────────────┤ │ │ │ Scroll 内容区 │ │ ... │ │ [ 备注输入框 ] ← 聚焦 │ ← 若在此易被遮挡 ├─────────────────────────────┤ │ ███ 软键盘 ███ │ ← AvoidArea TYPE_KEYBOARD └─────────────────────────────┘解决思路只有两类思路谁来做典型 API系统自动避让框架KeyboardAvoidMode.OFFSET / RESIZE开发者手动补偿业务keyboardHeightChange→paddingBottom二、KeyboardAvoidMode系统避让模式全解析2.1 API 入口在任意Component内通过UIContext设置import{KeyboardAvoidMode}fromkit.ArkUI// 在 aboutToAppear 或页面进入时this.getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET)注意KeyboardAvoidMode需从kit.ArkUI即ohos.arkui.UIContext导入其枚举值为OFFSET、RESIZE、OFFSET_WITH_CARET、RESIZE_WITH_CARET、NONE等。不要与 Dialog 里另一套KeyboardAvoidMode混淆。2.2 各模式对比表模式行为适用场景Demo 场景 idOFFSET整体上移页面使聚焦输入框露出普通表单、注册页SYSTEM_OFFSETRESIZE压缩窗口可视高度内容区变短聊天页、IM 底部输入栏SYSTEM_RESIZEOFFSET_WITH_CARET上移且光标位置变化时也调整多行文本、光标移动—RESIZE_WITH_CARET压缩且光标变化时也调整复杂编辑器—NONE不做任何避让全屏游戏、自定义键盘 UIWRONG_NONE踩坑演示默认模式为OFFSETAPI 11 文档说明。页面退出时 Demo 会恢复为OFFSET避免影响其他页面aboutToDisappear():void{this.avoidController.detach()this.getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET)}2.3 OFFSET vs RESIZE 怎么选OFFSET整体上移整个页面上移一截顶部内容可能被推出屏幕。适合字段不多的表单用户本来就会滚动。RESIZE压缩高度页面「窗口」变矮内部Scroll的滚动区域随之变短底部输入栏相对键盘位置固定。适合「消息列表 底部输入框」的 IM 结构。Demo 中切换场景 chip 即可在真机上对比两种模式的视觉差异。2.4 踩坑模式NONEDemo 故意提供WRONG_NONE场景uiContext.setKeyboardAvoidMode(KeyboardAvoidMode.NONE)此时系统完全不顶起页面。配合底部TextArea备注字段键盘弹起后输入框几乎一定被遮挡。Demo 在检测到风险时显示警告privateisBlockedRisk():boolean{returnthis.selectedCaseKeyboardAvoidCase.WRONG_NONEthis.keyboardHeightVp0(this.focusedFieldremark||this.focusedFieldaddress)}常见误触 NONE 的场景从其他模块复制了setKeyboardAvoidMode(NONE)却忘记改回或在全屏自定义页面设置了 NONE 后未在子页面恢复。三、avoidArea 实战窗口避让区 API3.1 什么是 avoidAreaavoidArea是窗口管理器维护的不可显示区域描述类型由AvoidAreaType枚举AvoidAreaType含义TYPE_SYSTEM系统栏状态栏、导航栏TYPE_CUTOUT刘海 / 挖孔TYPE_KEYBOARD软键盘…其他系统区域与键盘遮挡直接相关的是TYPE_KEYBOARD。3.2 三种获取键盘高度的方式Demo 封装在KeyboardAvoidController.ets中统一监听并上报来源方式 1keyboardHeightChange事件win.on(keyboardHeightChange,(heightPx:number):void{listener(uiContext.px2vp(heightPx),keyboardHeightChange)})回调参数为px键盘收起时高度为0最直接、最常用。方式 2avoidAreaChange事件win.on(avoidAreaChange,(options:window.AvoidAreaOptions):void{if(options.typewindow.AvoidAreaType.TYPE_KEYBOARD){listener(uiContext.px2vp(options.area.bottomRect.height),avoidAreaChange)}})避让区变化时触发键盘、系统栏等需过滤type TYPE_KEYBOARD适合需要同时处理多种 avoidArea 的复杂页面。方式 3getWindowAvoidArea同步读取constinitAreawin.getWindowAvoidArea(window.AvoidAreaType.TYPE_KEYBOARD)listener(uiContext.px2vp(initArea.bottomRect.height),getWindowAvoidArea)页面初始化时获取当前键盘区高度适合进入页面时键盘已打开的边缘场景。3.3 px 与 vp 转换窗口 API 返回px布局使用vp。必须通过UIContext.px2vp()转换constheightVpuiContext.px2vp(heightPx)Demo 顶部状态栏实时显示模式: OFFSET | 键盘高度: 312 vp | 来源: keyboardHeightChange3.4 生命周期注册与注销aboutToAppear():void{consthostContextthis.getUIContext().getHostContext()this.avoidController.attach(hostContext,this.getUIContext(),listener)}aboutToDisappear():void{this.avoidController.detach()// off 事件防泄漏}务必在aboutToDisappear中off监听否则页面销毁后仍收到回调可能引发内存泄漏或已销毁组件的状态更新错误。四、手动 padding关闭系统避让 自己顶起4.1 为什么需要手动方案系统OFFSET/RESIZE在大多数页面够用但以下场景可能需要手动控制页面有多层嵌套Scroll系统顶起范围不符合预期只需顶起底部某一块区域如工具栏而非整页键盘上方需要固定显示自定义「完成」栏与Navigation、半屏 Sheet 组合时行为需精细定制。4.2 Demo 实现逻辑选手动模式时setKeyboardAvoidMode(KeyboardAvoidMode.NONE)—— 关闭系统避让避免双重顶起监听键盘高度写入State manualPaddingVp给Scroll内Column设置动态paddingBottom.padding({left:0,right:0,top:0,bottom:this.manualPaddingVp// 随键盘高度变化})键盘收起时keyboardHeightChange回调0manualPaddingVp归零布局恢复。4.3 手动方案注意事项要点说明必须配合 Scroll否则 padding 只撑开容器输入框仍可能不在可视区键盘收起要归零忘记恢复 padding 会留下大块空白不要与 OFFSET 叠加系统已顶起时再 padding 会「顶两次」考虑安全区底部有 Home 指示条时需额外处理五、Demo 代码走读5.1 场景配置KeyboardAvoidTypes.ets四种场景一目了然exportconstKEYBOARD_AVOID_SCENARIOS:KeyboardAvoidScenario[][{id:WRONG_NONE,title:❌ NONE · 不避让键盘,...},{id:SYSTEM_OFFSET,title:✅ OFFSET · 整体上移,...},{id:SYSTEM_RESIZE,title:✅ RESIZE · 压缩布局,...},{id:MANUAL_AVOID_AREA,title:✅ avoidArea 手动 padding,...},]5.2 模式切换KeyboardAvoidPitfallDemo.etsprivateapplyKeyboardAvoidMode():void{constuiContextthis.getUIContext()if(this.selectedCaseWRONG_NONE||this.selectedCaseMANUAL_AVOID_AREA){uiContext.setKeyboardAvoidMode(KeyboardAvoidMode.NONE)}elseif(this.selectedCaseSYSTEM_OFFSET){uiContext.setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET)}else{uiContext.setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE)}}手动模式与 NONE 共用KeyboardAvoidMode.NONE区别在于手动模式额外应用manualPaddingVp。5.3 表单设计FeedbackFormSection.ets表单包含 5 个输入控件「备注」TextArea 放在最底部专门用于测试遮挡TextArea({text:this.form.remark,placeholder:点击这里测试键盘遮挡…}).onFocus(():void{this.focusedFieldremark})在 NONE 模式下该字段高亮红色边框highlightBottom: true提示用户这是测试焦点。六、safeAreaPadding 与 expandSafeArea 补充除窗口 avoidArea 外ArkUI 组件级还提供// API 14组件安全区内边距.safeAreaPadding({bottom:12})// 扩展组件布局到安全区外.expandSafeArea([SafeAreaType.KEYBOARD],[SafeAreaEdge.BOTTOM])SafeAreaType.KEYBOARD表示软键盘区域。复杂页面可将系统 KeyboardAvoidMode组件 safeAreaPadding组合使用而不是只靠一种手段。Demo 要点文案中已收录复杂页可 safeAreaPadding 配合键盘区 SafeAreaType.KEYBOARD七、常见错误与排查7.1 错误清单现象可能原因修复底部输入框被挡误设NONE改OFFSET或RESIZE页面被顶太高OFFSET 手动 padding 叠加手动模式时设 NONEpadding 不消失未监听高度变 0检查 keyboardHeightChange高度不对直接用 px 当 vppx2vp()转换监听无效未 getLastWindow用window.getLastWindow(context)泄漏 / 崩溃未 off 监听aboutToDisappear中 detachScroll 无效外层 Column 无高度约束内层 Scroll 设layoutWeight(1)7.2 排查流程输入框被挡 ├─ getKeyboardAvoidMode() 是否为 NONE → 改为 OFFSET/RESIZE ├─ 是否嵌套多层 Scroll → 简化结构或改 RESIZE ├─ 是否手动 padding 未生效 → 检查 keyboardHeightChange 绑定 └─ 是否 px/vp 混用 → 统一 px2vp八、方案选型决策树需要键盘避让 │ ├─ 普通表单页 ──────────────→ KeyboardAvoidMode.OFFSET默认 │ ├─ 聊天/列表底栏 ─────────→ KeyboardAvoidMode.RESIZE │ ├─ 多行编辑、光标频繁移动 ─→ OFFSET_WITH_CARET / RESIZE_WITH_CARET │ ├─ 全屏自定义/游戏 ────────→ NONE 自绘键盘 │ └─ 局部顶起/复杂嵌套 ──────→ NONE avoidArea 手动 padding │ ├─ keyboardHeightChange首选 └─ avoidAreaChange TYPE_KEYBOARD备选九、真机体验指南配合 Demo运行 App默认选中❌ NONE滚动到底部点击「备注」TextArea观察键盘弹起输入框被挡顶部出现 ⚠️ 警告状态栏显示键盘高度切换✅ OFFSET再次聚焦备注 → 页面自动上顶输入框可见切换✅ RESIZE→ 可视区压缩Scroll 滚动范围变短切换✅ 手动 avoidArea→ 观察绿色提示paddingBottom N vpScroll 底部留出键盘等高空白。十、总结软键盘遮挡输入框不是 Scroll 的 bug而是键盘避让策略未正确配置。核心结论说明首选方案大多数页面用KeyboardAvoidMode.OFFSETIM 场景用RESIZE压缩可视高度关闭避让NONE会导致底部输入框被挡avoidAreaTYPE_KEYBOARD描述键盘占用矩形监听 APIkeyboardHeightChangepxpx2vp手动顶起NONE 动态paddingBottom键盘收起归零生命周期aboutToDisappear注销监听、恢复默认模式记住一句话简单页交给 OFFSET聊天页用 RESIZE精细控制听 avoidArea用完记得 off 监听。附录Demo 文件结构文件职责KeyboardAvoidTypes.ets场景枚举、要点、表单模型KeyboardAvoidController.ets窗口监听封装FeedbackFormSection.ets多输入框测试表单KeyboardAvoidPitfallDemo.ets主交互页pages/Index.ets入口附录快速参考卡// 系统避让import{KeyboardAvoidMode}fromkit.ArkUIthis.getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET)// 键盘高度监听import{window}fromkit.ArkUIconstwinawaitwindow.getLastWindow(context)win.on(keyboardHeightChange,(hPx){this.kbPaddingthis.getUIContext().px2vp(hPx)})win.on(avoidAreaChange,(opt){if(opt.typewindow.AvoidAreaType.TYPE_KEYBOARD){this.kbPaddingthis.getUIContext().px2vp(opt.area.bottomRect.height)}})// 手动补偿Scroll(){Column().padding({bottom:this.kbPadding}){/* 表单 */}}// 清理win.off(keyboardHeightChange,handler)this.getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET)