鸿蒙cordova键盘插件
Access rate limit exceeded. Please log in to continue.
cordova-plugin-ionic-keyboard
This project is developed based on cordova-plugin-ionic-keyboard@2.2.0. This document focuses on its specific application in the OpenHarmony (OHOS) system.
- cordova-plugin-ionic-keyboard
Introduction
cordova-plugin-ionic-keyboard is a core plugin in the Harmony Cordova ecosystem, a Cordova keyboard control plugin designed specifically for hybrid mobile applications, providing cross-platform, refined keyboard operation and adaptation solutions. The plugin encapsulates native keyboard APIs for Android/iOS/OHOS, supporting core functions such as keyboard show/hide control. It solves common problems in hybrid applications such as keyboard covering input fields, page layout disorder, and keyboard operation unresponsiveness. It is suitable for various scenarios such as form filling, chat input, and search box interaction.
Important Note: In the OHOS system, the keyboard mode is set in the mainPage component of OHOS Cordova, which has a parameter webKeyboardAvoidMode to set the keyboard avoidance method. Plugin installation is not required. This plugin is mainly used for compatibility when porting existing Android projects. Framework Library Link
Core Advantages of the Plugin:
-
Cross-Platform Compatibility: Unifies Android/iOS/OHOS keyboard control logic, API calls without platform differentiation
-
Refined Control: Supports manual show/hide keyboard, disable keyboard, adjust keyboard behavior (such as return button style)
-
Rich Event Listening: Provides complete event callbacks for keyboard show/hide, height change, input completion, etc.
-
Lightweight with No Dependencies: No third-party libraries, plugin size <50KB, low integration cost
-
Native Experience Optimization: Adapts to platform-specific keyboard features
Supported Platforms
-
Android: API 19+ (Android 4.4+)
-
iOS: 10.0+
-
OHOS: 5.0+
Installation
Plugins can be quickly installed via the hcordova CLI, available from the npm registry or the GitCode repository.
Install from npm (Recommended)
# Install using hcordova CLI
# Install hcordova CLI tool
npm install -g hcordova
# Install plugin for all platforms (basic installation)
hcordova plugin add cordova-plugin-ionic-keyboard
Install for OHOS Platform
Install the plugin only for the OHOS platform:
# Install only to the OHOS platform
hcordova plugin add cordova-plugin-ionic-keyboard --platform ohos
# Install specific version and specify OHOS platform
hcordova plugin add cordova-plugin-ionic-keyboard@1.0.0 --platform ohos
Install from GitCode Repository
Install the plugin only for the OHOS platform (get the latest development version):
# Install only to OHOS platform (development version)
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-ionic-keyboard.git --platform ohos
# Install from specific tag/branch
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-ionic-keyboard.git@develop --platform ohos
Offline Installation (Local Package)
For environments without network access, download the plugin package locally first, then perform offline installation:
# Download the plugin package locally (example path: ~/Downloads/cordova-plugin-ionic-keyboard)
# Perform offline installation
hcordova plugin add ~/Downloads/cordova-plugin-ionic-keyboard --platform ohos
Post-Installation Verification
After installation, verify that the plugin has been successfully added to the project using the following command:
# List installed plugins; if the plugin ID appears, the plugin was successfully installed
hcordova plugin list
Uninstallation
# Uninstall from all platforms using Cordova CLI
hcordova plugin remove cordova-plugin-ionic-keyboard
# Uninstall from specific platform
hcordova plugin remove cordova-plugin-ionic-keyboard --platform ohos
Constraints and Limitations
- In the OHOS system, the mainPage component provides the
webKeyboardAvoidModeparameter to set the keyboard avoidance method. Plugin installation is not required. This plugin is mainly used for compatibility when porting existing Android projects. - The plugin is only responsible for keyboard control functions. On the OHOS platform, keyboard avoidance logic should prioritize the mainPage component configuration.
- Some refined keyboard behaviors (such as return button style) may have minor differences depending on platform-specific characteristics.
Compatibility
Supported:
| Item | Version/Info |
|---|---|
| SDK | API12+ |
| IDE | DevEco Studio: 5.0+ |
| ROM | 5.1+ |
| Emulator | OpenHarmony 6.0+ |
Tested with the following versions:
| Item | Version/Info |
|---|---|
| @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) |
Usage Examples
1. Show Keyboard and Listen for Height
window.addEventListener('keyboardDidShow', (event) => {
console.log("Keyboard shown: keyboardDidShow event, height: " + event.keyboardHeight);
});
window.addEventListener('keyboardWillShow', (event) => {
console.log("Keyboard will show: keyboardWillShow event, height: " + event.keyboardHeight);
});
window.addEventListener('keyboardWillHide', () => {
console.log("Keyboard will hide: keyboardWillHide event");
});
window.addEventListener('keyboardDidHide', () => {
console.log("Keyboard hidden: keyboardDidHide event");
});
function showKeyboard() {
// Show keyboard
cordova.plugins.Keyboard.show();
// Gaining focus can also show the keyboard
document.getElementById("inputId").focus();
}
2. Hide Keyboard
function hideKeyboard2() {
cordova.plugins.Keyboard.hide();
}
3. Keyboard Display Notes
In the OHOS Cordova framework, the mainPage component has parameters for setting the keyboard popup method. Please refer to the framework library documentation for details.
Usage Instructions
Core API
Keyboard Event Listening
-
keyboardDidShow: Triggered after the keyboard is displayed. The event parameter containskeyboardHeight(keyboard height) -
keyboardWillShow: Triggered when the keyboard is about to be displayed. The event parameter containskeyboardHeight(keyboard height) -
keyboardWillHide: Triggered when the keyboard is about to be hidden. No additional parameters -
keyboardDidHide: Triggered after the keyboard is hidden. No additional parameters
Keyboard Control Methods
-
cordova.plugins.Keyboard.show(): Manually shows the keyboard -
cordova.plugins.Keyboard.hide(): Manually hides the keyboard
Configuration Parameters
No additional global configuration parameters are required. API calls do not require passing additional configuration; simply call them directly to achieve the corresponding functions. On the OHOS platform, the keyboard avoidance method needs to be set via the webKeyboardAvoidMode parameter in the mainPage component.
Important Notes
- For new OHOS projects, it is recommended to directly use the
webKeyboardAvoidModeparameter of the mainPage component to set keyboard avoidance, without installing this plugin. - When porting existing Android projects to OHOS, this plugin can be installed to maintain a unified keyboard control interface.
- When calling the keyboard show method, it is recommended to use it together with the input field's
focus()method to ensure the keyboard pops up properly. - It is recommended to register event listeners during page initialization to avoid callback anomalies caused by duplicate registration.
New Features
- Adapted for OHOS 5.0+ system, strictly following OpenHarmony development specifications.
- Retains the original plugin core API interfaces and event listening mechanisms, ensuring that existing Android projects ported to OHOS require minimal code modification.
- Added usage instructions for the OHOS platform, clarifying applicable scenarios for the plugin and how it works with the mainPage component.
- Compatible with Cordova 14.0.1-ohos version; the plugin is lightweight with no dependencies and low integration cost.
Directory Structure
cordova-plugin-ionic-keyboard/
├── src/ # Source code directory
│ └── main/ # Main source code
│ ├── cpp/ # C++ native code
│ │ └── Keyboard/ # Keyboard module
│ │ ├── CDVIonicKeyboard.cpp # C++ implementation of keyboard functionality
│ │ └── CDVIonicKeyboard.h # Header file for keyboard functionality
│ └── ets/ # ArkTS code (OpenHarmony API)
│ └── components/ # Components directory
│ └── Keyboard/ # Keyboard component
│ └── KeyboardAction.ets # ArkTS implementation of keyboard actions
├── www/ # Web resource directory
│ └── android/ # Platform resources
│ └── keyboard.js # JavaScript keyboard interface (Cordova bridge layer)
├── .gitignore # Git ignore file configuration
├── LICENSE # Project open source license
├── OAT.xml # OpenHarmony review configuration file
├── package.json # Node.js package configuration
├── plugin.xml # Cordova plugin description file (core configuration)
└── README.md # Project documentation
Contribute
If you encounter any issues during use, please feel free to submit an Issue. Pull requests PR for collaborative development are also very welcome.
License
This plugin is open-sourced under the Apache License 2.0. See the LICENSE file for details.
Official Resources
OHOS Cordova https://gitcode.com/CPF-Cordova/cordova-plugin-ionic-keyboard
Android/iOS: https://npmjs.com/cordova-plugin-ionic-keyboard