HarmonyOS开发者社区

键盘遮挡输入框是移动开发的常见痛点。鸿蒙ArkTS提供了多层级的解决方案。第一层（最简单）：在page或window级别设置keyboardAvoidMode属性为KeyboardAvoidMode.RESIZE或KeyboardAvoidMode.OFFSET，框架会自动调整页面布局或滚动页面使输入框可见。第二层：使用Scroll组件包裹表单，配合TextInput的onFocus事件，在获得焦点时手动滚动到指定位置。第三层（最灵活）：监听window.on('keyboardHeightChange')获取键盘高度，然后动态调整底部内边距或使用translate偏移整个页面。对于包含List或Grid的表单，可以使用scrollToIndex方法将当前输入项滚动到可视区域。此外，从API version 18开始，TextInput组件增加了enableKeyboardOnFocus属性，可以控制是否自动弹出键盘。最佳实践是：将表单放入Scroll容器，并设置.keyboardAvoidMode(KeyboardAvoidMode.RESIZE)，大部分场景都能覆盖。

// 方案一：设置页面级别的键盘避让模式
@Entry
@Component
struct FormPage {
build() {
Scroll() { // 必须配合Scroll使用
Column({ space: 20 }) {
TextInput({ placeholder: '用户名' }).margin({ top: 100 })
TextInput({ placeholder: '密码' }).type(InputType.Password)
TextInput({ placeholder: '详细地址' })
TextArea({ placeholder: '备注信息' }).height(100)
}.padding(20)
}
.keyboardAvoidMode(KeyboardAvoidMode.RESIZE) // 键盘弹出时自动调整Scroll高度
.width('100%').height('100%')
}
}

// 方案二：手动监听键盘高度并偏移
@Entry
@Component
struct ManualKeyboardAvoid {
@State keyboardHeight: number = 0;
private windowStage: window.WindowStage = this.getUIContext().getHostContext()?.windowStage;

aboutToAppear() {
this.windowStage?.getMainWindow().then((win) => {
win.on('keyboardHeightChange', (data) => {
this.keyboardHeight = data.height;
});
});
}

build() {
Column() {
TextInput({ placeholder: '输入内容' }).margin({ top: 300 })
}
.margin({ bottom: this.keyboardHeight }) // 动态增加底部边距
.animation({ duration: 200 }) // 平滑过渡
}
}