大网数据广告活动
OpenHarmony 设备与应用开发

键盘判断事件

· 52CE 我爱测

当组件获得焦点时,获焦组件触发该事件。系统会根据该事件回调函数返回值,判断是否需要键盘。

键盘判断事件

当组件获得焦点时,获焦组件触发该事件。系统会根据该事件回调函数返回值,判断是否需要键盘。

说明:

  • 本模块首批接口从API version 24开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

  • 本模块接口仅可在Stage模型下使用。

onNeedSoftkeyboard

onNeedSoftkeyboard(onNeedSoftkeyboardCallback: OnNeedSoftkeyboardCallback | undefined): T

设置组件判断是否需要键盘时触发的回调。主要用于键盘接续场景,当焦点从输入框切换到其他组件时,如果切换后的组件回调函数OnNeedSoftkeyboardCallback的返回值设置为true,则表示该组件需要键盘,此时键盘将不会收起,如果返回值设置为false,则表示该组件不需要键盘,此时键盘将收起。

对于不能获焦的组件,本接口不生效。

输入框组件使用该接口并将返回值设置为false时,点击输入框将不会拉起键盘。

Web组件使用该方法时,如果返回值为true,Web组件会判断组件中是否有可编辑节点,如果有可编辑节点才会保留键盘,如果返回值为false,无论是否有可编辑节点,键盘都不会保留。

XComponent组件使用该方法时,如果返回值为true且XComponent组件使用OH_ArkUI_XComponent_SetNeedSoftKeyboard()设置了需要键盘,才会保留键盘,如果返回值为false,无论组件如何设置,键盘都不会保留。

当接口返回true时,应用的自绘制输入框需要主动attach,建立输入法框架和输入法应用的通信,否则点击键盘会失去响应(失焦时输入法框架和输入法应用的通信会断开)。

该接口只适用于对输入法应用接续的场景,对自定义键盘不生效。自定义键盘接续详见setCustomKeyboardContinueFeature。

原子化服务API: 从API version 24开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
onNeedSoftkeyboardCallback OnNeedSoftkeyboardCallback | undefined 是 事件触发时执行的回调,系统会根据回调的返回值决定是否需要键盘。
设置为undefined时,不会触发回调,输入框类组件行为等同返回true。其他组件行为等同返回false。

返回值:

类型 说明
T 返回当前组件。

OnNeedSoftkeyboardCallback

type OnNeedSoftkeyboardCallback = () => boolean

当绑定该方法的组件判断是否需要键盘时,将触发此回调。

原子化服务API: 从API version 24开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

类型 说明
boolean 是否需要键盘。
若此回调的返回值为true,则表明该组件需要键盘;返回值为false,则表明该组件不需要键盘。

示例

示例1(设置键盘接续)

该示例通过onNeedSoftkeyboard接口,设置按钮需要键盘。在从输入框拉起键盘后,点击按钮使焦点切换到按钮,此时键盘将不会收起,再次点击输入框可继续输入。

从API version 24开始,新增onNeedSoftkeyboard接口。

@Entry
@Component
struct Index {
  build() {
    Column() {
      Button('切换焦点到Button')
        .onClick(() => {
          this.getUIContext().getFocusController().requestFocus('Button')
        })
        .key('Button')
        .fontSize(20)
        .width('80%')
        .margin('10')
        .onNeedSoftkeyboard((): boolean => {
          return true;
        })
      TextInput()
        .key('TextInput1')
    }
    .height('100%')
    .width('100%')
  }
}

[图示请参阅官方原文]

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。