@ionic-native/keyboard

本项目基于@ionic-native/[email protected]开发。

简介

@ionic-native/keyboard是OpenHarmony Cordova生态系统中的核心插件，提供键盘的显示与可见性控制功能，同时支持监听键盘弹出和收起时的事件，为跨平台应用开发提供设备差异化适配能力。兼容Android、iOS 和OpenHarmony平台，为跨平台应用开发提供统一的键盘控制能力。本文档主要说明在OpenHarmony系统中的应用。

@ionic-native/keyboardAPI提供键盘的显示与隐藏功能，同时支持监听键盘事件。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @ionic-native/keyboard

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @ionic-native/keyboard

手动引入安装

1.添加插件配置

根据 plugin.xml 的 config-json 项，找到 entry 模块中 config.xml 文件，并根据 param 标签添加配置

<feature name="Keyboard">
  <param name="harmony-package" value="Keyboard" />
  <param name="onload" value="true" />
</feature>

2.修改CMake配置

根据 plugin.xml 的 CMakeLists 项，找到 cordova 模块，路径为 target 字段的文件 CMakeLists.txt，添加 add_library

add_library(cordova SHARED
  // ...
  Keyboard/CDVIonicKeyboard.cpp
  // ...
)

3.复制源码文件

根据 plugin.xml 的 source-file 项，将 src 字段的路径代码复制到 cordova 模块中 target-dir 字段的目录中：

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

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

4.添加ArkTS配置

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

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

卸载

# hionic CLI 卸载
hionic plugin remove @ionic-native/keyboard

约束与限制

兼容性

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

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

使用示例

示例1：显示键盘

实现显示键盘功能。

import { Keyboard } from '@ionic-native/keyboard';

await Keyboard.show();

示例2：隐藏键盘

实现隐藏键盘功能。

await Keyboard.hide();

示例3：监听键盘即将弹出事件

监听键盘即将弹出的事件，从API20之后开始支持。

await Keyboard.addListener('keyboardWillShow', (info) => {
  console.log('键盘高度:', info.keyboardHeight);
});

示例4：监听键盘弹出事件

监听键盘弹出的事件，从API18之后开始支持。

await Keyboard.addListener('keyboardDidShow', (info) => {
  console.log('键盘高度:', info.keyboardHeight);
});

示例5：监听键盘即将隐藏事件

监听键盘即将隐藏的事件，从API20之后开始支持。

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

示例6：监听键盘隐藏事件

监听键盘隐藏的事件，从API18之后开始支持。

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

示例7：移除所有监听器

移除该插件的所有原生监听器。

await Keyboard.removeAllListeners();

使用说明

接口方法

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

数据结构

PluginListenerHandle

| Prop | Type | |------|------| | remove | () => Promise<void> |

KeyboardInfo

| Prop | Type | Description | |------|------|-------------| | keyboardHeight | number | 键盘的高度 |

方法参数说明

1. 显示键盘

Keyboard.show(): Promise<void>;

2. 隐藏键盘

Keyboard.hide(): Promise<void>;

3. 添加事件监听器

Keyboard.addListener(
  eventName: string, // 事件名称：'keyboardWillShow' | 'keyboardDidShow' | 'keyboardWillHide' | 'keyboardDidHide'
  listenerFunc: (info?: KeyboardInfo) => void // 监听回调函数
): Promise<PluginListenerHandle>;

4. 移除所有监听器

Keyboard.removeAllListeners(): Promise<void>;

目录结构

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

贡献代码

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

许可证

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