HarmonyOS应用自定义键盘解决方案

概述

自定义键盘是一种替换系统默认键盘的解决方案，可实现键盘个性化交互。允许用户结合业务需求与操作习惯，对按键布局进行可视化重构、设置多功能组合键位，使输入更加便捷和舒适。在安全防护层面，自定义键盘可以增强用户输入的安全性，避免敏感信息被截取或者泄露。本文介绍了自定义键盘的实现，并结合自定义键盘和系统键盘的切换、自定义键盘的布局避让等场景，介绍了自定义键盘的实际使用方式。

自定义键盘的实现

自定义键盘的实现包括以下5个步骤：

自定义键盘布局实现

输入控件绑定自定义键盘布局

自定义键盘输入控制

自定义键盘光标控制

自定义键盘弹出与收起

自定义键盘布局实现

自定义键盘的布局以自定义组件的方式呈现，根据具体业务场景由开发者实现。自定义键盘的高度通过自定义组件根节点的height属性设置，宽度不可设置，默认铺满屏幕。

 

@Component
export struct CustomKeyboard {
  build() {
    Column() {
    }
    // 修改自定义组件根节点的height属性
    .height($r('app.float.keyboard_total_height'))
  }
}

 

输入控件绑定自定义键盘布局

输入控件（TextArea、TextInput、RichEditor、Search）支持通过customKeyboard属性绑定自定义键盘布局。绑定自定义键盘后，输入控件获取焦点时，不会拉起系统键盘，而是加载指定的自定义键盘。本文后续以TextInput控件为例进行介绍。

代码示例如下：

 

build() {
  Column() {
    TextInput({
      placeholder: '绑定自定义键盘',
      text: this.inputText,
      controller: this.textInputController
    })
      // 绑定自定义键盘布局
      .customKeyboard(this.customKeyboard())
  }
}
@Builder
customKeyboard() {
  CustomKeyboard()
}

 

自定义键盘输入控制

自定义键盘可以拦截手势事件，通过对状态变量的修改，实现文本的输入。

以英文键盘为例，监听EnglishButton的onClick事件，修改状态变量。

 

@Component
struct EnglishButton {
  @Consume inputText: string;
  build() {
    Button(this.getEnglishText(this.item), { type: ButtonType.Normal })
       .onClick(() => {
        // 拦截自定义键盘按钮的点击事件，根据业务场景修改状态变量
        this.inputText = this.keyBoardController.onInput(this.getEnglishText(this.item));
      })
  }
}

 

通过对状态变量inputText的修改，实现文本输入。

 

@Component
export struct TextInputComponent {
  @Provide inputText: string = '';
  build() {
    Column() {
      TextInput({
        placeholder: '绑定自定义键盘',
        text: this.inputText,
        controller: this.textInputController
      })
    }
  }
}

 

自定义键盘光标控制

通过监听TextInput的onTextSelectionChange生命周期，获取初始光标位置、文本输入后，调用TextInputController的caretPosition方法，设置最终光标位置。

获取光标位置：

 

TextInput({
  placeholder: '绑定自定义键盘',
  text: this.inputText,
  controller: this.textInputController
})
  // 监听光标位置变化
  .onTextSelectionChange((start: number, end: number) => {
    this.keyBoardController.setCaretPosition(start, end);
  })

 

设置光标位置：

 

onChange(value: string) {
  this.text = value;
  if (this.keyBoardType !== Constants.SYSTEM_KEYBOARD) {
    // 设置光标位置
    this.textInputController?.caretPosition(this.targetCaretPos);
  }
}

 

自定义键盘弹出与收起

通过对焦点进行控制，可以实现键盘的弹出和收起。开发者也可以通过TextInputController的stopEditing方法控制键盘关闭，下面的自定义键盘示例中，点击确认按键关闭自定义键盘。

 

onInput(value: string): string {
  switch (value) {
    case '确定':
      this.textInputController?.stopEditing();
      break;
  }
  return this.text;
}

 

自定义键盘和系统键盘的切换

当需要实现同一个输入框内可以切换自定义键盘和系统键盘时，可以通过如下方式实现：

Tab栏点击“123”、“ABC”按钮，this.isCustomKeyboardAttach为true，TextInput绑定自定义键盘；点击“中文”按钮，this.isCustomKeyboardAttach为false，切换系统键盘。

 

TextInput({
  placeholder: '绑定自定义键盘',
  text: this.inputText,
  controller: this.textInputController
})
  .customKeyboard(this.isCustomKeyboardAttach ? this.customKeyboard() : null)

 

自定义键盘的布局避让

使用系统提供的自定义键盘避让功能

为了确保输入框不被自定义键盘挡住，系统默认提供了输入框避让自定义键盘的能力。在TextInput组件的customKeyboard属性设置supportAvoidance为true，开启系统提供的自定义键盘避让功能。

 

TextInput({
  placeholder: '绑定自定义键盘',
  text: this.inputText,
  controller: this.textInputController
})
  .customKeyboard(this.customKeyboard(), { supportAvoidance: true })

 

系统默认的自定义键盘避让功能只能保证输入框不被遮挡，输入框下方的组件可能会被自定义键盘挡住，如上图中所示，输入框下方的tab栏被自定义键盘挡住。为解决这一问题，需要开发者自己实现自定义键盘的避让功能。

开发者自己实现自定义键盘的避让功能

开发者需要监听自定义键盘根节点的onAreaChange生命周期，获取自定义键盘的高度，根据实际场景设置布局的避让。

总结

自定义键盘作为可定制化输入解决方案，通过模块化架构实现系统键盘的功能替代，其核心价值在于支持按键布局的重构与界面功能的自定义配置，同时集成场景化功能扩展模块，显著提升键盘输入效率与操作舒适度，构建输入数据链路防护体系，有效规避敏感信息泄露风险。