@capacitor/keyboard

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/keyboard是capacitor生态系统中的核心插件，提供完善的键盘控制API，支持对设备键盘进行显示、隐藏操作，同时可监听键盘弹出、收起相关事件，为跨平台应用开发提供设备差异化适配能力，兼容capacitor的Android、iOS等主流移动平台及浏览器环境，本文档只说明在OpenHarmony系统中的使用。

API 允许对设备键盘进行显示与隐藏控制，同时支持监听键盘弹出和收起时的事件，满足应用中键盘交互的各类场景需求。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm i @capacitor/keyboard

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/keyboard

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

[
  {
    "pkg": "@capacitor/keyboard",
    "classpath": "Keyboard"
  }
]

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Keyboard)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Keyboard
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中src/main/cpp/Keyboard目录下的Keyboard.h、Keyboard.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/Keyboard目录下。

将源码中src/main/ets/components/Keyboard目录下的Keyboard.ets文件引入到capacitor模块中src/main/ets/components/Keyboard目录下。

4. 添加 ArkTS 配置

在capacitor模块的build-profile.json5文件中，buildOption/arkOptions/runtimeOnly/sources配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

{
  "buildOption": {
    // ...
    "arkOptions": {
      "runtimeOnly": [
        // ...
        "./src/main/ets/components/Keyboard/Keyboard.ets"
        // ...
      ]
    }
  }
}

卸载

# 卸载 keyboard 插件
hionic plugin remove @capacitor/keyboard

约束与限制

兼容性

在以下版本中已测试通过：

• capacitor: 8.0.0-ohos-8.0.0; SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

OpenHarmony系统中，键盘控制相关操作无需额外申请权限，插件可直接调用相关API实现功能。

使用示例

示例1：显示键盘

import { Keyboard } from '@capacitor/keyboard';

const handleShowKeyboard = async () => {
  try {
    // 使用capacitor Keyboard插件显示键盘
    await Keyboard.show();

    apiButtonSectionRef.value?.updateButtonResult('show-keyboard', {
      message: '键盘显示命令已发送（仅Android支持）',
      status: 'success'
    });
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    apiButtonSectionRef.value?.updateButtonResult('show-keyboard', {
      message: `显示键盘失败: ${errorMsg}`,
      status: 'error'
    });
  }
};

示例2：隐藏键盘

import { Keyboard } from '@capacitor/keyboard';

const handleHideKeyboard = async () => {
  try {
    // 使用capacitor Keyboard插件隐藏键盘
    await Keyboard.hide();

    apiButtonSectionRef.value?.updateButtonResult('hide-keyboard', {
      message: '键盘隐藏命令已发送',
      status: 'success'
    });
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    apiButtonSectionRef.value?.updateButtonResult('hide-keyboard', {
      message: `隐藏键盘失败: ${errorMsg}`,
      status: 'error'
    });
  }
};

示例3：添加键盘监听事件

import { Keyboard } from '@capacitor/keyboard';

const handleAddListeners = async () => {
  try {
    // 使用capacitor Keyboard插件添加键盘事件监听器
    Keyboard.addListener('keyboardWillShow', (info) => {
      console.log('键盘即将显示:', info);
    });

    Keyboard.addListener('keyboardDidShow', (info) => {
      console.log('键盘已显示:', info);
    });

    Keyboard.addListener('keyboardWillHide', () => {
      console.log('键盘即将隐藏');
    });

    Keyboard.addListener('keyboardDidHide', () => {
      console.log('键盘已隐藏');
    });

    apiButtonSectionRef.value?.updateButtonResult('add-listeners', {
      message: '键盘事件监听器已添加',
      status: 'success'
    });
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    apiButtonSectionRef.value?.updateButtonResult('add-listeners', {
      message: `添加键盘事件监听器失败: ${errorMsg}`,
      status: 'error'
    });
  }
};

示例4：移除所有键盘监听事件

import { Keyboard } from '@capacitor/keyboard';

const handleRemoveAllListeners = async () => {
  try {
    // 使用capacitor Keyboard插件移除所有键盘事件监听器
    await Keyboard.removeAllListeners();

    apiButtonSectionRef.value?.updateButtonResult('remove-listeners', {
      message: '所有键盘事件监听器已移除',
      status: 'success'
    });
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    apiButtonSectionRef.value?.updateButtonResult('remove-listeners', {
      message: `移除键盘事件监听器失败: ${errorMsg}`,
      status: 'error'
    });
  }
};

使用说明

Keyboard是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效，所有API均基于Promise实现，支持异步调用。

| 方法名 | 返回类型 | 描述 | 备注 | |----------------------------------------------------------------------------------------|--------------------------------------------------------------|---------------|--------------| | show() | Promise<void> | 显示键盘 | 仅Android支持 | | hide() | Promise<void> | 隐藏键盘 | 无 | | addListener(eventName: 'keyboardWillShow', listenerFunc: (info: KeyboardInfo) => void) | Promise<PluginListenerHandle> | 监听键盘即将弹出的事件 | 从API20之后开始支持 | | addListener(eventName: 'keyboardDidShow', listenerFunc: (info: KeyboardInfo) => void) | Promise<PluginListenerHandle> | 监听键盘弹出的事件 | 从API18之后开始支持 | | addListener(eventName: 'keyboardWillHide', listenerFunc: (info: KeyboardInfo) => void) | Promise<PluginListenerHandle> | 监听键盘即将隐藏的事件 | 从API20之后开始支持 | | addListener(eventName: 'keyboardDidHide', listenerFunc: (info: KeyboardInfo) => void) | Promise<PluginListenerHandle> | 监听键盘隐藏的事件 | 从API18之后开始支持 | | removeAllListeners() | Promise<void> | 移除该插件的所有原生监听器 | 无 |

数据结构

PluginListenerHandle

| 属性 | 类型 | 描述 | |--------|---------------------------|------------| | remove | () => Promise<void> | 移除当前监听器的方法 |

KeyboardInfo

| 属性 | 类型 | 描述 | |----------------|--------|--------------| | keyboardHeight | number | 键盘的高度（单位：像素） |

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |----cpp  # C++ 代码
|           |----ets   # ArkTS 代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。