鸿蒙中 Keyboard软键盘的弹出与隐藏

最新推荐文章于 2025-12-19 15:50:15 发布

原创最新推荐文章于 2025-12-19 15:50:15 发布 · 506 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #华为 #软键盘 #鸿蒙 #Keyboard

鸿蒙专栏收录该内容

388 篇文章

订阅专栏

本文同步发表于微信公众号，微信搜索程语新视界即可关注，每个工作日都有文章更新

一、软键盘

软键盘是用户交互的重要途径，提供文本输入功能。HarmonyOS支持在使用输入框组件（如TextInput、TextArea、Search、RichEditor）时，控制软键盘的弹出和收起行为。

二、弹出软键盘的方式

1. 自动弹出

默认情况下，当焦点转移到输入框时，软键盘会自动弹出。

2. 焦点转移方式

（1）人机交互获得焦点

用户通过点击、双击、长按输入框等方式获取焦点。

（2）通过代码设置焦点

使用 requestFocus() 或 defaultFocus() 方法将焦点转移到输入框。

代码：通过按钮点击请求焦点

@Entry
@Component
struct demo {
  controller: TextInputController = new TextInputController();
  @State inputValue: string = "";
  
  build() {
    Column({ space: 20 }) {
      Button('输入框请求焦点').onClick(() => {
        this.getUIContext().getFocusController().requestFocus("textInput123")
      })
      
      TextInput({ controller: this.controller, text: this.inputValue })
        .id("textInput123")
    }
    .height('100%')
    .width('80%')
    .margin('10%')
    .justifyContent(FlexAlign.Center)
  }
}

3）使用外接键盘按键走焦

外接物理键盘时，按Tab、Shift+Tab、方向键可转移焦点。

3. 软键盘类型与属性控制

系统软键盘：受 enableKeyboardOnFocus 属性影响
自定义键盘：不受 enableKeyboardOnFocus 影响

三、收起软键盘的方式

1. 常见收起场景

（1）用户主动点击软键盘的关闭按钮

（2）拖拽文本

（3）页面切换

（4）通过输入框的controller退出编辑态

代码：

@Entry
@Component
struct demo {
  controller: TextInputController = new TextInputController();
  @State inputValue: string = "";
  
  build() {
    Column({ space: 30 }) {
      Button('关闭键盘').onClick(() => {
        this.controller.stopEditing()
      })
      TextInput({ controller: this.controller, text: this.inputValue })
    }
    .width('80%')
    .height('100%')
    .margin('10%')
    .justifyContent(FlexAlign.Center)
  }
}

（5）焦点转移到不需要软键盘的组件

代码1：焦点转移到按钮

@Entry
@Component
struct TextInputExample {
  controller: TextInputController = new TextInputController();
  @State inputValue: string = "";
  
  build() {
    Column({ space: 20 }) {
      Button('change focus').onClick(() => {
        this.getUIContext().getFocusController().requestFocus("button")
      }).id("button")
      TextInput({ controller: this.controller, text: this.inputValue })
    }
    .justifyContent(FlexAlign.Center)
    .height('100%')
    .width('80%')
    .margin('10%')
  }
}

代码2：List滚动时收起键盘

@Entry
@Component
struct Index {
  private arr: number[] = Array.from<number, number>(
    { length: 100 } as ArrayLike<number>,
    (_, i: number) => i + 1
  );
  
  build() {
    Column() {
      List({ space: 20, initialIndex: 0 }) {
        ForEach(this.arr, (item: number, index?: number) => {
          ListItem() {
            Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) {
              TextInput({ placeholder: 'TextInput ' + item })
            }
          }
        }, (item: string) => item)
      }
      .onScrollStart(() => {
        this.getUIContext().getFocusController().clearFocus()
      })
      .width('80%')
      .height('80%')
      .margin('10%')
    }
    .justifyContent(FlexAlign.Center)
  }
}

四、常见问题

1. 获得焦点时阻止弹出软键盘

代码：设置空自定义键盘

@Entry
@Component
struct demo {
  controller: TextInputController = new TextInputController();
  @State inputValue: string = "";
  
  @Builder
  CustomKeyboardBuilder() {
    Column() {
      // 空的键盘组件
    }
  }
  
  build() {
    Column() {
      TextInput({ 
        placeholder: 'TextInput', 
        controller: this.controller, 
        text: this.inputValue 
      })
      .customKeyboard(this.CustomKeyboardBuilder())
    }
    .justifyContent(FlexAlign.Center)
    .width('80%')
    .margin('10%')
    .height('100%')
  }
}

2. 点击发送按钮后不收起键盘

代码：使用keepEditableState保持编辑态

@Entry
@Component
struct demo {
  build() {
    Column({ space: 20 }) {
      TextArea({ placeholder: '点击发送收起键盘' })
        .enterKeyType(EnterKeyType.Send)
      
      TextArea({ 
        placeholder: 'onSubmit中设置keepEditableState，点击发送不收起键盘' 
      })
        .enterKeyType(EnterKeyType.Send)
        .onSubmit((enterKey: EnterKeyType, event: SubmitEvent) => {
          event.keepEditableState();
        })
    }
    .justifyContent(FlexAlign.Center)
    .height('100%')
    .width('80%')
    .margin('10%')
  }
}