npm package: @luqi_test/cordova-plugin-vibration
Description: Cordova vibration Plugin
Author: Huawei Device, Inc. Ltd. and
Latest version: 3.1.1

# 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 前提条件

在安装插件前，请确保开发环境满足以下基础要求：


1. 已安装 Node.js (v14.0.0 及以上) 和 npm (v6.0.0 及以上)，可通过 `node -v` 和 `npm -v` 命令验证版本。

2. 已全局安装 Cordova CLI (v10.0.0 及以上)，若未安装，可执行以下命令：

```bash
npm install -g hcordova
```

1. 已创建 Cordova 项目（若尚未创建，可通过 `hcordova create MyVibrationApp com.example.vibrationapp 振动示例应用` 命令快速创建）。


### 3.2 插件安装命令

在 Cordova 项目根目录下，根据需求选择以下方式安装插件：

#### 指定平台安装

通过 npm 仓库安装稳定版本，适合大多数开发场景：

```bash
hcordova plugin add cordova-plugin-vibration --platform ohos
```

#### 从 GitCode 源码安装

若需使用最新开发版本（可能包含未发布的新功能或 Bug 修复），可从 GitCode 源码安装：

```bash
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-vibration.git --platform ohos
```

### 3.3 插件卸载命令

若需移除插件，在项目根目录执行以下命令：


```bash
#全平台卸载
hcordova plugin remove cordova-plugin-vibration
#指定平台卸载
hcordova plugin remove cordova-plugin-vibration --platform ohos
```

### 3.4 插件查看命令

安装完成后，可通过以下命令验证插件是否成功添加到项目中：


```bash
hcordova plugin list
```

若输出结果包含 `cordova-plugin-vibration`，则表示插件已成功安装。

## 4. 核心 API 说明

插件通过全局对象 `navigator.vibrate` 和 `navigator.notification.vibrate`暴露振动控制 API，支持两种核心振动模式：**单次振动**和**自定义模式振动**。以下是各 API 的详细说明：

### 4.1 单次振动（基础用法）

用于触发设备的单次振动，可指定振动时长（单位：毫秒），适用于简单的操作反馈（如按钮点击、消息提醒）。

#### 方法说明


```bash
# 标准 API
navigator.vibrate(time);

#或使用以下方式
navigator.vibration.vibrate(time);
```

#### 参数说明



| 参数名    | 类型     | 是否必选 | 说明                                                      |
| ------ | ------ | ---- | ------------------------------------------------------- |
| `time` | Number | 否    | 振动时长（单位：毫秒），默认值为 500ms（不同平台默认值可能有差异）。若传入 0 ，将停止当前振动。 |

#### 示例代码


```js
// 等待 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 自定义模式振动（高级用法）


#### 方法举例

```json
// 标准 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
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ]
};
```

```bash
#兼容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 种振动类型：

1. **transient 类型**：瞬态短振动，特点是振动响应快、反馈干脆有力，适用于 “点击反馈”“碰撞提示” 等短时长场景；

2. **continuous 类型**：稳态长振动，具备长时间输出强劲且稳定振动的能力，适用于 “持续震动提醒”“场景模拟振动” 等长时长场景。

##### 3. Event 属性（单个振动事件）

`Event` 是构成振动序列的基本单元，代表 1 个完整的振动动作，需包含以下属性：



1. **Type**：振动事件类型，必填项。仅支持取值为 `transient`（瞬态振动）或 `continuous`（稳态振动）；

2. **StartTime**：振动起始时间，必填项。单位为毫秒（ms），有效取值范围为 [0, 1800000]（即 0 ms 至 30 分钟）；

3. **Duration**：振动持续时间，条件必填项。仅当 `Type` 为 `continuous` 时生效且为必填，单位为毫秒（ms），有效取值范围为 [0, 5000]（即 0 ms 至 5 秒）；

4. **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` 文件中使用：

```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 平台

1. **振动权限**：

* OHOS使用的是原生震动，不支持W3C震动
* 在主项目的module.json5中添加：

```json
{
  "name": "ohos.permission.VIBRATE"
}
```
1. **在手机设置情景模式下不会震动**

* 在手机设置为免打扰、睡眠模式、学习模式等情景模式下，不会震动

## 7. 许可证

本插件基于 **Apache License 2.0** 开源协议发布，详细许可条款请查看项目根目录下的 [LICENSE](LICENSE) 文件。

你可以自由地：

* 使用、复制、修改本插件的源代码；

* 将修改后的代码用于商业或非商业项目；

* 分发本插件的源代码或二进制文件。


## 8. 联系方式与支持

### 震动参数参考资料:
* [https://docs.openharmony.cn/pages/v5.0.3/zh-cn/device-dev/driver/driver-peripherals-vibrator-des.md](https://docs.openharmony.cn/pages/v5.0.3/zh-cn/device-dev/driver/driver-peripherals-vibrator-des.md)

### OHOS

* GitCode 仓库：[https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-vibration](https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-vibration)

### Android/iOS

* Apache Cordova (Android/iOS)官方论坛：[https://cordova.apache.org/community/](https://cordova.apache.org/community/)