@cordova-ohos/cordova-plugin-ionic-keyboard
v2.2.1
Published
Cordova keyboard Plugin
Readme
cordova-plugin-ionic-keyboard
本项目基于 [email protected] 开发,本文档重点阐述其在 OpenHarmony(OHOS)系统中的具体应用。
简介
cordova-plugin-ionic-keyboard 是 Harmony Cordova 生态系统中一款核心插件,是一款 Cordova 键盘控制插件,专为混合移动应用设计,提供跨平台、精细化的键盘操作与适配解决方案。插件封装了 Android/iOS/OHOS 原生键盘 API,支持键盘显示/隐藏控制等核心功能,解决混合应用中键盘遮挡输入框、页面布局错乱、键盘操作无响应等常见问题,适用于表单填写、聊天输入、搜索框交互等各类场景。
重要提示: 在 OHOS 系统中,设置键盘模式在 OHOS cordova 的 mainPage 组件中,有参数设置 webKeyboardAvoidMode 设置键盘的避让方式,无需安装插件,该插件主要为兼容原 Android 项目移植使用。框架库链接
插件核心优势:
跨平台兼容:统一 Android/iOS/OHOS 键盘控制逻辑,API 调用无需区分平台
精细化控制:支持手动显示/隐藏键盘、禁用键盘、调整键盘行为(如回车按钮样式)
丰富事件监听:提供键盘显示/隐藏、高度变化、输入完成等完整事件回调
轻量无依赖:不依赖第三方库,插件体积<50KB,集成成本低
原生体验优化:适配平台特有键盘特性
支持平台
Android:API 19 及以上(Android 4.4+)
iOS:10.0 及以上
OHOS:5.0 及以上
下载安装
通过 hcordova CLI 即可快速安装插件,支持从 npm 仓库或 GitCode 仓库获取。
从 npm 安装(推荐)
# 使用 hcordova CLI 安装
# 安装 hcordova 命令化工具
npm install -g hcordova
# 全平台安装插件(基础安装)
hcordova plugin add cordova-plugin-ionic-keyboard指定平台安装 ohos
仅为 OHOS 平台安装插件:
# 仅安装到 OHOS 平台
hcordova plugin add cordova-plugin-ionic-keyboard --platform ohos
# 安装指定版本并指定 OHOS 平台
hcordova plugin add [email protected] --platform ohos从 GitCode 仓库安装
仅为 OHOS 平台安装插件(获取最新开发版):
# 仅安装到 OHOS 平台(开发版)
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-ionic-keyboard.git --platform ohos
# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-ionic-keyboard.git@develop --platform ohos离线安装(本地包)
适用于无网络环境,先下载插件包到本地,再执行离线安装:
# 下载插件包到本地(示例路径:~/Downloads/cordova-plugin-ionic-keyboard)
# 执行离线安装
hcordova plugin add ~/Downloads/cordova-plugin-ionic-keyboard --platform ohos安装后验证
安装完成后,可通过以下命令验证插件是否成功添加到项目中:
# 查看已安装的插件列表,若包含本插件 ID 则表示插件已成功安装
hcordova plugin list卸载
# Cordova CLI 全平台卸载
hcordova plugin remove cordova-plugin-ionic-keyboard
# 指定平台卸载
hcordova plugin remove cordova-plugin-ionic-keyboard --platform ohos约束与限制
- OHOS 系统中,mainPage 组件已提供 webKeyboardAvoidMode 参数设置键盘避让方式,无需安装本插件,本插件主要用于兼容原 Android 项目移植场景;
- 插件仅负责键盘控制相关功能,OHOS 平台键盘避让逻辑优先遵循 mainPage 组件配置;
- 部分精细化键盘行为(如回车按钮样式)需结合各平台原生特性,可能存在细微差异。
兼容性
支持:
| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |
在以下版本中已测试通过:
| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |
使用示例
1. 显示键盘,并监听获取到高度
window.addEventListener('keyboardDidShow', (event) => {
console.log("显示键盘:keyboardDidShow 事件:" + event.keyboardHeight);
});
window.addEventListener('keyboardWillShow', (event) => {
console.log("显示键盘:keyboardWillShow 事件:" + event.keyboardHeight);
});
window.addEventListener('keyboardWillHide', () => {
console.log("隐藏键盘:keyboardWillHide 事件");
});
window.addEventListener('keyboardDidHide', () => {
console.log("隐藏键盘:keyboardDidHide 事件");
});
function showKeyboard() {
// 显示键盘
cordova.plugins.Keyboard.show();
// 获取焦点也可以显示键盘
document.getElementById("inputId").focus();
}2. 隐藏键盘
function hideKeyboard2() {
cordova.plugins.Keyboard.hide();
}3. 键盘的显示说明
在 OHOS Cordova 框架中,mainPage 组件有设置键盘的弹窗方式参数,请参考 框架库 的说明
使用说明
核心 API
键盘事件监听
keyboardDidShow:键盘显示完成后触发,event 参数包含 keyboardHeight(键盘高度)keyboardWillShow:键盘即将显示时触发,event 参数包含 keyboardHeight(键盘高度)keyboardWillHide:键盘即将隐藏时触发,无额外参数keyboardDidHide:键盘隐藏完成后触发,无额外参数
键盘控制方法
cordova.plugins.Keyboard.show():手动显示键盘cordova.plugins.Keyboard.hide():手动隐藏键盘
配置参数
无额外全局配置参数,API 调用无需传入额外配置,直接调用即可实现对应功能;OHOS 平台键盘避让方式需在 mainPage 组件中通过 webKeyboardAvoidMode 参数设置。
使用注意
- OHOS 新项目建议直接使用 mainPage 组件的 webKeyboardAvoidMode 参数设置键盘避让,无需安装本插件;
- 原 Android 项目移植到 OHOS 时,可安装本插件保持键盘控制接口统一;
- 调用键盘显示方法时,建议配合输入框 focus() 方法,确保键盘正常弹出;
- 事件监听建议在页面初始化时注册,避免重复注册导致回调异常。
新增特性
- 适配 OHOS 5.0+ 系统,严格遵循 OpenHarmony 开发规范;
- 保留原有插件核心 API 接口和事件监听机制,确保原 Android 项目移植到 OHOS 后无需大量修改代码;
- 补充 OHOS 平台使用说明,明确插件适用场景及与 mainPage 组件的配合方式;
- 兼容 Cordova 14.0.1-ohos 版本,插件体积轻量无依赖,集成成本低。
目录结构
cordova-plugin-ionic-keyboard/
├── src/ # 源代码目录
│ └── main/ # 主要源代码
│ ├── cpp/ # C++ 原生代码
│ │ └── Keyboard/ # 键盘模块
│ │ ├── CDVIonicKeyboard.cpp # 键盘功能的 C++ 实现
│ │ └── CDVIonicKeyboard.h # 键盘功能的头文件
│ └── ets/ # ArkTS 代码(OpenHarmony API)
│ └── components/ # 组件目录
│ └── Keyboard/ # 键盘组件
│ └── KeyboardAction.ets # 键盘动作的 ArkTS 实现
├── www/ # Web 资源目录
│ └── android/ # 平台资源
│ └── keyboard.js # JavaScript 键盘接口(Cordova 桥接层)
├── .gitignore # Git 忽略文件配置
├── LICENSE # 项目开源许可证
├── OAT.xml # OpenHarmony 审核配置文件
├── package.json # Node.js 包配置
├── plugin.xml # Cordova 插件描述文件(核心配置)
└── README.md # 项目说明文档贡献代码
使用过程中发现任何问题都可以提 Issue ,当然也非常欢迎发 PR 共建。
许可证
本插件基于 Apache License 2.0 开源,详见 LICENSE 文件。
官方资源
OHOS Cordova https://gitcode.com/CPF-Cordova/cordova-plugin-ionic-keyboard
Android/iOS:https://npmjs.com/cordova-plugin-ionic-keyboard/issues
