前言

软键盘弹出时遮挡输入框是移动开发的常见问题。HarmonyOS提供了键盘避让模式设置，@pura/harmony-utils 的 KeyboardUtil 封装了键盘相关控制方法，帮助开发者解决键盘遮挡问题。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、KeyboardUtil核心API

KeyboardUtil 提供了以下键盘控制方法：

方法	说明	参数	使用场景
setKeyboardAvoidMode(mode)	设置键盘避让模式	KeyboardAvoidMode	解决键盘遮挡
getKeyboardAvoidMode()	获取当前避让模式	无	状态查询
isKeyboardShowing()	判断键盘是否显示	无	键盘状态感知

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 即时生效：避让模式设置后立即生效

1.2 避让模式对比

避让模式	效果	适用场景
OFFSET	页面上推	聊天页面、表单
RESIZE	布局调整	滚动列表页面

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 设置键盘避让模式

import { KeyboardUtil } from '@pura/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 {
      let mode = KeyboardUtil.getKeyboardAvoidMode();
      this.result = `当前避让模式: ${mode}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { KeyboardUtil } from '@pura/harmony-utils';

@Entry
@Component
struct KeyboardDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('设置上推避让').width('100%').onClick(() => {
        KeyboardUtil.setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET);
        this.result = '上推避让已设置';
      });
      Button('查询避让模式').width('100%').onClick(() => {
        let mode = KeyboardUtil.getKeyboardAvoidMode();
        this.result = `避让模式: ${mode}`;
      });
      TextInput().width('100%').placeholder('点击此处弹出键盘测试')
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 聊天页面键盘适配

import { KeyboardUtil } from '@pura/harmony-utils';

aboutToAppear() {
  KeyboardUtil.setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
}

4.2 表单页面键盘适配

aboutToAppear() {
  KeyboardUtil.setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET);
}

五、注意事项

1. 避让模式选择：根据页面布局选择合适的避让模式
2. 测试覆盖：不同输入框位置都需要测试键盘避让效果
3. 初始化依赖：使用前需确保 AppUtil.init() 已调用
4. 模式切换：页面切换时注意恢复避让模式
5. 键盘高度：不同设备的键盘高度可能不同

六、常见问题

Q1: 设置避让模式后输入框仍然被遮挡？

检查是否使用了Scroll组件，某些布局结构可能影响避让效果。

Q2: OFFSET和RESIZE有什么区别？

OFFSET将整个页面上推，RESIZE调整布局大小。聊天页面推荐RESIZE，表单页面推荐OFFSET。

Q3: 如何在特定输入框聚焦时切换避让模式？

可以在TextInput的onFocus回调中动态切换避让模式。

Q4: 键盘弹出时列表滚动位置异常？

建议使用RESIZE模式配合Scroll组件，避免手动计算偏移量。

总结

KeyboardUtil 的键盘避让方法为解决键盘遮挡问题提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理选择避让模式，可以确保输入框始终可见，提升用户体验。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。