概述

自定義鍵盤是一種替換系統默認鍵盤的解決方案，可實現鍵盤個性化交互。允許用戶結合業務需求與操作習慣，對按鍵布局進行可視化重構、設置多功能組合鍵位，使輸入更加便捷和舒適。在安全防護層面，自定義鍵盤可以增強用戶輸入的安全性，避免敏感信息被截取或者泄露。本文介紹了自定義鍵盤的實現，并結合自定義鍵盤和系統鍵盤的切換、自定義鍵盤的布局避讓等場景，介紹了自定義鍵盤的實際使用方式。

自定義鍵盤的實現

自定義鍵盤的實現包括以下5個步驟：

自定義鍵盤布局實現

輸入控件綁定自定義鍵盤布局

自定義鍵盤輸入控制

自定義鍵盤光標控制

自定義鍵盤彈出與收起

自定義鍵盤布局實現

自定義鍵盤的布局以自定義組件的方式呈現，根據具體業務場景由開發者實現。自定義鍵盤的高度通過自定義組件根節點的height屬性設置，寬度不可設置，默認鋪滿屏幕。

@Component
exportstructCustomKeyboard{
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 {
@ConsumeinputText: string;
 build() {
  Button(this.getEnglishText(this.item), { type: ButtonType.Normal })
   .onClick(() => {
   // 攔截自定義鍵盤按鈕的點擊事件，根據業務場景修改狀態變量
   this.inputText =this.keyBoardController.onInput(this.getEnglishText(this.item));
   })
 }
}

通過對狀態變量inputText的修改，實現文本輸入。

@Component
exportstructTextInputComponent{
@ProvideinputText: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;
 }
returnthis.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生命周期，獲取自定義鍵盤的高度，根據實際場景設置布局的避讓。

總結

自定義鍵盤作為可定制化輸入解決方案，通過模塊化架構實現系統鍵盤的功能替代，其核心價值在于支持按鍵布局的重構與界面功能的自定義配置，同時集成場景化功能擴展模塊，顯著提升鍵盤輸入效率與操作舒適度，構建輸入數據鏈路防護體系，有效規避敏感信息泄露風險。