软键盘常见问题的解决方法

软键盘是用户进行交互的重要途径之一，同时软键盘的弹出和收起，可能会影响到正在显示的UI元素，影响用户体验，出现如下常见的软键盘布局适配问题：

重要信息被软键盘遮挡：当软键盘弹出时，输入框或其它重要UI元素可能会被键盘遮挡，导致用户无法看到或访问它们。

软键盘弹出导致布局错位：内容可能会不恰当上移，影响用户体验。

软键盘弹出导致弹窗过度上抬：弹窗被键盘上顶，造成不好的体验。

针对以上问题，本文将帮助开发者了解软键盘的弹出和收起的控制、避让机制以及软键盘常见问题的解决方法。

1、软键盘的弹出收起和监听

用户点击输入框时，软键盘默认弹出。但在特定场景下，需要对软键盘的弹出和收起进行控制，如点击空白区域收起软键盘，进入页面时输入框主动获焦。开发者还需根据软键盘状态和高度调整页面布局。

主动获焦弹出软键盘

有时候进入页面，希望页面中的输入框能主动获焦并且弹出软键盘，方便用户直接输入，比如，点击应用首页的搜索框。这可以通过将输入框的defaultFocus设置为true来实现。

 

TextInput()
  .defaultFocus(true)

 

代码控制弹出软键盘

开发者可以使用FocusController的requestFocus()方法，通过组件的id将焦点转移到组件树对应的实体节点，并且弹出软键盘。例如，表情面板切换到文本输入时，点击表情图标拉起系统软键盘，便于用户直接输入。

 

TextInput({ placeholder: 'Please enter a contact name' })
  .id('input1')
Button('login')
  .onClick(() => {
    this.getUIContext().getFocusController().requestFocus('input1');
  })

 

代码控制收起软键盘

通过全局的焦点控制对象FocusController的clearFocus方法，软键盘收起，例如在下面的搜索页面中，点击搜索按钮时软键盘收起。

 

Button('Search')
  .onClick(() => {
    this.getUIContext().getFocusController().clearFocus();
  })

 

此外，开发者可调用stopEditing()方法来关闭键盘，该方法需为输入框单独绑定一个TextInputController对象。在存在多个输入框的场景下，需要绑定多个TextInputController对象，使用起来较为繁琐，推荐改用clearFocus()方法来解除焦点。

 

@Component
struct StopEditingCpt {
  private controller: TextInputController = new TextInputController();
  build() {
    Column() {
      TextInput({ placeholder: 'Input', controller: this.controller })
      Button('Search')
        .onClick(() => {
          this.controller.stopEditing();
        })
    }
  }
}

 

监听获取软键盘高度、键盘弹出和收起

开发者可以通过获取软键盘高度、监听软键盘的弹出和收起状态，调整组件位置以适配界面或显示隐藏某些组件。通过window模块的on('keyboardHeightChange')方法开启固定态软键盘高度变化的监听，实时获取软键盘宽高。

 

 aboutToAppear(): void {
    window.getLastWindow(this.getUIContext().getHostContext()).then(currentWindow => {
      currentWindow.on('keyboardHeightChange', (data: number) => {
        this.keyboardHeight = this.getUIContext().px2vp(data);
      })
    })
  }

 

监听获取安全区域高度

 

window.getLastWindow(this.getUIContext().getHostContext()).then(curWindow => {
      curWindow.on('avoidAreaChange', data => {
        if (data.area.bottomRect.height <= 0) {
          this.isKeyBoardHidden = true;
        } else {
          this.isKeyBoardHidden = false;
        }
      })
    })}

 

2、软键盘避让机制

默认避让效果

解决软键盘的界面适配问题，首先需要了解在HarmonyOS系统中软键盘的避让机制是怎么样的。

如果当前输入框不会被软键盘遮挡，则不上抬组件，如图所示点击输入框1，组件不会上抬。

当前输入框会被软键盘遮挡，则上抬组件至刚好在软键盘上方显示完整的输入框，输入框上方的组件会跟着抬起，下方的组件不会露出，如下方的输入框12。

弹窗内输入框避让规则

弹窗避让可以通过BaseDialogOptions，设置弹窗的避让模式KeyboradAvoidMode，当设置为默认避让Default模式时，如果软键盘弹出会覆盖输入框，弹窗整体会上抬，并且为了UX美观，会存在默认的间隔，默认大小为16vp。

键盘避让模式

当用户在输入时，为了确保输入框不会被键盘遮挡，系统提供了避让模式来解决这一问题。开发者可以通过setKeyboardAvoidMode控制虚拟键盘抬起时页面的避让模式，键盘抬起时默认页面避让模式为上抬模式，下面列举了几种常见的避让模式。

1、上抬模式（KeyboardAvoidMode.OFFSET）：为了避让软键盘，Page内容会整体上抬。如下示例代码，软键盘弹出时，页面整体上抬： 2、压缩模式（KeyboardAvoidMode.RESIZE）：当软键盘高度改变时，调整Page大小。Page下设置百分比宽高的组件会跟随压缩，直接设置宽高的组件保持固定大小。注意，设置KeyboardAvoidMode.RESIZE时，安全区设置expandSafeArea 无效。 3、不避让模式（KeyboardAvoidMode.NONE）：软键盘将直接覆盖页面UI，不会触发界面布局调整。例如在全屏沉浸式场景（游戏/视频播放器等），为保障用户体验的完整性，开发者可以使用KeyboardAvoidMode.NONE模式。   图：压缩模式，底部工具栏抬起    

3、软键盘避让常见问题

重要信息被软键盘遮挡

例如下面这个电子邮件示例，内容包括标题栏、内容区域和底部操作栏。点击输入内容的输入框时，软键盘会遮挡底部操作栏，影响用户体验。这种情况只要设置避让模式为压缩模式即可。

 

aboutToAppear(): void {
  this.getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
}

 

需要注意的是内容区域高度的设置需要用百分比的方式实现

软键盘弹出导致布局错位

例如下面这样的一个聊天界面，顶部是一个自定义的标题，下方为可滚动聊天消息区域，底部是消息输入框。

想要顶部标题不被软键盘向上抬，需要给标题组件设置

.expandSafeArea([SafeAreaType.KEYBOARD])属性，使标题组件不避让键盘。

软键盘弹出导致弹窗过度上抬

当用户点击弹窗底部的输入框的时候，弹窗会整体上抬，输入框上抬的距离也过多。

为了解决以上问题，可以使用Navigation.Dialog，通过设置NavDestination的mode为NavDestinationMode.DIALOG弹窗类型，此时整个NavDestination默认透明显示。同时，设置键盘避让模式为压缩模式KeyboardAvoidMode.RESIZE。

设置软键盘和弹窗组件距离

弹窗类组件默认额避让模式下，软键盘弹起之后弹窗组件之间16vp间隔，开发者可以通过弹窗参数BaseDialogOptions中keyboardAvoidDistance，调整系统设置的避让间距弹窗组件和软键盘之间的距离。设置软键盘间距时，需要将keyboardAvoidMode值设为KeyboardAvoidMode.DEFAULT。