@cordova-ohos/cordova-plugin-vibration
v3.1.1
Published
Cordova vibration Plugin
Downloads
148
Readme
cordova-plugin-vibration
1. 插件介绍
cordova-plugin-vibration 是一款专为 Cordova/PhoneGap 应用设计的设备振动控制插件，旨在帮助开发者快速实现跨平台的设备振动功能。通过该插件，开发者无需关注不同操作系统对振动硬件的底层控制差异，即可通过简洁的 JavaScript API 调用设备振动功能，适用于消息通知、操作反馈、游戏交互等多种场景，为用户提供更直观的触觉交互体验,本文档主要介绍该插件在OHOS系统中的应用。
该插件完全遵循 Cordova 插件开发规范，支持自定义振动时长、振动模式（如长短交替振动），并适配主流移动平台及桌面平台，可无缝集成到各类 Cordova 应用中。
2. 支持平台
该插件已针对以下操作系统和平台完成适配，确保振动功能的稳定性和一致性：
Android (API 级别 21 及以上，覆盖 Android 5.0 及更高版本)
iOS (iOS 10.0 及以上，支持 iPhone、iPad 等全系列 iOS 设备，注：iPad 部分机型无振动硬件)
Windows (Windows 10 及以上，包含 UWP 通用应用场景，仅支持具备振动功能的设备)
Browser (主流桌面及移动浏览器，如 Chrome、Firefox、Edge，通过浏览器 API 模拟振动效果)
OHOS (5.0+)
3. 安装步骤
3.1 前提条件
在安装插件前，请确保开发环境满足以下基础要求：
已安装 Node.js (v14.0.0 及以上) 和 npm (v6.0.0 及以上)，可通过
node -v和npm -v命令验证版本。已全局安装 Cordova CLI (v10.0.0 及以上)，若未安装，可执行以下命令：
npm install -g hcordova- 已创建 Cordova 项目（若尚未创建，可通过
hcordova create MyVibrationApp com.example.vibrationapp 振动示例应用命令快速创建）。
3.2 插件安装命令
在 Cordova 项目根目录下，根据需求选择以下方式安装插件：
指定平台安装
通过 npm 仓库安装稳定版本，适合大多数开发场景：
hcordova plugin add cordova-plugin-vibration --platform ohos从 GitCode 源码安装
若需使用最新开发版本（可能包含未发布的新功能或 Bug 修复），可从 GitCode 源码安装：
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-vibration.git --platform ohos3.3 插件卸载命令
若需移除插件，在项目根目录执行以下命令：
#全平台卸载
hcordova plugin remove cordova-plugin-vibration
#指定平台卸载
hcordova plugin remove cordova-plugin-vibration --platform ohos3.4 插件查看命令
安装完成后，可通过以下命令验证插件是否成功添加到项目中：
hcordova plugin list若输出结果包含 cordova-plugin-vibration，则表示插件已成功安装。
4. 核心 API 说明
插件通过全局对象 navigator.vibrate 和 navigator.notification.vibrate暴露振动控制 API，支持两种核心振动模式：单次振动和自定义模式振动。以下是各 API 的详细说明：
4.1 单次振动（基础用法）
用于触发设备的单次振动，可指定振动时长（单位：毫秒），适用于简单的操作反馈（如按钮点击、消息提醒）。
方法说明
# 标准 API
navigator.vibrate(time);
#或使用以下方式
navigator.vibration.vibrate(time);参数说明
| 参数名 | 类型 | 是否必选 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------- |
| time | Number | 否 | 振动时长（单位：毫秒），默认值为 500ms（不同平台默认值可能有差异）。若传入 0 ，将停止当前振动。 |
示例代码
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
// 1. 触发 500ms 的单次振动（默认时长）
document.getElementById('vibrateShort').addEventListener('click', function() {
navigator.vibrate(500);
console.log('已触发 500ms 振动');
});
// 2. 触发 2000ms 的长时间振动
document.getElementById('vibrateLong').addEventListener('click', function() {
navigator.vibrate(2000);
console.log('已触发 2000ms 振动');
});
// 3. 停止当前振动（传入 0）
document.getElementById('stopVibrate').addEventListener('click', function() {
navigator.vibrate(0);
console.log('已停止当前振动');
});
}, false);4.2 自定义模式振动（高级用法）
方法举例
// 标准 API（推荐）
var ob = {
"MetaData": {
"Create": "2023-01-09",
"Description": "a haptic case",
"Version": 1.0,
"ChannelNumber": 1
},
"Channels": [
{
"Parameters": {
"Index": 0
},
"Pattern": [
{
"Event": {
"Type": "transient",
"StartTime": 0,
"Parameters": {
"Frequency": 31,
"Intensity": 100
}
}
},
{
"Event": {
"Type": "continuous",
"StartTime": 40,
"Duration": 3000,
"Parameters": {
"Frequency": 30,
"Intensity": 38,
"Curve": [
{
"Time": 0,
"Frequency": 0,
"Intensity": 0
},
{
"Time": 1,
"Frequency": 15,
"Intensity": 0.5
},
{
"Time": 40,
"Frequency": -8,
"Intensity": 1.0
},
{
"Time": 54,
"Frequency": 0,
"Intensity": 0
}
]
}
}
}
]
}
]
};#兼容W3C方式
navigator.vibrate(ob);
#或使用一下方式
navigator.vibration.vibrate(ob);参数说明
1. MetaData 属性（文件头信息）
可在以下属性中添加文件描述信息，明确文件基础配置：
Version：必填项，文件格式的版本号，具备向前兼容特性，目前仅支持版本 1.0；
ChannelNumber：必填项，用于标识马达振动的通道数量，最大支持双马达通道（即 2 个通道）；
Create：可选项，用于记录文件的创作时间，格式建议遵循 “YYYY-MM-DD HH:MM:SS” 以保证可读性；
Description：可选项，可补充说明振动效果（如 “游戏爆炸振动”“通知提醒振动”）、创建人信息、适用场景等附加内容。
2. Channels 属性（马达振动通道信息）
Channels 为 JSON 数组类型，存储各个振动通道的详细配置信息，每个通道需包含以下 2 个核心属性：
2.1 Parameters（通道参数）
仅包含 1 个必填属性：
- Index：通道编号标识，必填项。取值规则为：0 表示全通道同步发送振动指令，1 对应左马达通道，2 对应右马达通道。
2.2 Pattern（马达振动序列）
Pattern 为 JSON 数组类型，存储单个通道的振动事件序列，每个数组元素通过 Event 属性定义 1 个独立的振动事件。支持以下 2 种振动类型：
transient 类型：瞬态短振动，特点是振动响应快、反馈干脆有力，适用于 “点击反馈”“碰撞提示” 等短时长场景；
continuous 类型：稳态长振动，具备长时间输出强劲且稳定振动的能力，适用于 “持续震动提醒”“场景模拟振动” 等长时长场景。
3. Event 属性（单个振动事件）
Event 是构成振动序列的基本单元，代表 1 个完整的振动动作，需包含以下属性：
Type：振动事件类型，必填项。仅支持取值为
transient（瞬态振动）或continuous（稳态振动）；StartTime：振动起始时间，必填项。单位为毫秒（ms），有效取值范围为 [0, 1800000]（即 0 ms 至 30 分钟）；
Duration：振动持续时间，条件必填项。仅当
Type为continuous时生效且为必填，单位为毫秒（ms），有效取值范围为 [0, 5000]（即 0 ms 至 5 秒）；Parameters：振动事件参数配置，必填项。用于定义振动的强度、频率等核心参数，包含以下子属性：
Intensity：振动事件基础强度，必填项。有效取值范围为 [0, 100]，数值越大振动越强（0 表示无振动，100 表示最大强度）；
Frequency：振动事件基础频率，必填项。有效取值范围为 [0, 100]，数值越大振动频率越高（需结合硬件支持范围使用）；
Curve：振动参数调节曲线，可选项。仅当
Type为continuous时生效，为 JSON 数组类型，用于设置振动过程中强度和频率的动态变化，具体要求如下：调节点数量：最小需包含 4 个调节点，最大不超过 16 个调节点；
每个调节点需包含以下 3 个属性：
Time：相对事件起始时间的偏移量，单位与
StartTime一致（ms）。最小取值为 0，最大取值不得超过当前事件的Duration（避免超出振动时长）；Intensity：相对事件基础强度的增益系数。取值范围为 [0, 1]，最终实际强度 = 此增益系数 × 事件
Parameters中的Intensity；Frequency：相对事件基础频率的变化量。取值范围为 [-100, 100]，最终实际频率 = 此变化量 + 事件
Parameters中的Frequency（最终频率需确保在 [0, 100] 范围内，避免无效值）。
4. 其他限制要求
| 参数 | 要求 | | -------------- | ----------------- | | 振动事件（event）的数量 | 单个配置文件中不得超过 128 个 | | 振动配置文件长度 | 整个文件大小不得超过 64KB |
5. 完整示例项目
以下是一个包含所有振动功能的完整 Cordova 页面示例，可直接复制到项目的 www/index.html 文件中使用：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
<title>cordova-plugin-vibration 示例</title>
<style>
body {
font-family: Arial, sans-serif;
padding: 20px;
max-width: 600px;
margin: 0 auto;
text-align: center;
}
.btn {
display: block;
width: 100%;
padding: 15px;
margin: 12px 0;
border: none;
border-radius: 6px;
font-size: 16px;
cursor: pointer;
color: white;
}
.btn-short {
background-color: #2196F3; /* 蓝色：短振动 */
}
.btn-long {
background-color: #4CAF50; /* 绿色：长振动 */
}
.btn-stop {
background-color: #F44336; /* 红色：停止振动 */
}
.btn:hover {
opacity: 0.9;
transform: translateY(-2px);
transition: all 0.2s;
}
h1 {
color: #333;
margin-bottom: 30px;
}
.note {
color: #666;
font-size: 14px;
margin-top: 20px;
padding: 10px;
background-color: #f5f5f5;
border-radius: 4px;
text-align: left;
}
</style>
<script type="text/javascript" src="cordova.js"></script>
<script type="text/javascript">
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', onDeviceReady, false);
function onDeviceReady() {
console.log('Cordova 环境已就绪，可调用振动 API');
// 绑定按钮点击事件
document.getElementById('shortVibrate').addEventListener('click', () => vibrateShort());
document.getElementById('longVibrate').addEventListener('click', () => vibrateLong());
document.getElementById('stopVibrate').addEventListener('click', () => stopVibrate());
}
// 短振动（500ms）
function vibrateShort() {
navigator.vibrate(500);
showToast('已触发 500ms 短振动');
}
// 长振动（2000ms）
function vibrateLong() {
navigator.vibrate(2000);
showToast('已触发 2000ms 长振动');
}
// 停止振动
function stopVibrate() {
navigator.vibrate(0);
showToast('已停止当前振动');
}
// 显示提示消息（模拟 Toast）
function showToast(message) {
const toast = document.getElementById('toast');
toast.textContent = message;
toast.style.display = 'block';
setTimeout(() => {
toast.style.display = 'none';
}, 2000);
}
</script>
</head>
<body>
<h1>设备振动插件示例</h1>
<button id="shortVibrate" class="btn btn-short">触发 500ms 短振动</button>
<button id="longVibrate" class="btn btn-long">触发 2000ms 长振动</button>
<button id="stopVibrate" class="btn btn-stop">停止当前振动</button>
</body>
</html>6. 平台特定注意事项
6.1 OHOS 平台
- 振动权限：
- OHOS使用的是原生震动，不支持W3C震动
- 在主项目的module.json5中添加：
{
"name": "ohos.permission.VIBRATE"
}- 在手机设置情景模式下不会震动
- 在手机设置为免打扰、睡眠模式、学习模式等情景模式下，不会震动
7. 许可证
本插件基于 Apache License 2.0 开源协议发布，详细许可条款请查看项目根目录下的 LICENSE 文件。
你可以自由地：
使用、复制、修改本插件的源代码；
将修改后的代码用于商业或非商业项目；
分发本插件的源代码或二进制文件。
8. 联系方式与支持
震动参数参考资料:
OHOS
Android/iOS
- Apache Cordova (Android/iOS)官方论坛：https://cordova.apache.org/community/