{"_id":"@cordova-ohos/cordova-plugin-vibration","_rev":"5-3873c94db6911fc6f223e62133254841","name":"@cordova-ohos/cordova-plugin-vibration","dist-tags":{"latest":"3.1.2"},"versions":{"3.1.1":{"name":"@cordova-ohos/cordova-plugin-vibration","version":"3.1.1","keywords":["cordova","vibration","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-vibration@3.1.1","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-vibration/issues"},"dist":{"shasum":"641ecc13f39963dc9ad8247859c85514fcf5310b","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-vibration/-/cordova-plugin-vibration-3.1.1.tgz","fileCount":8,"integrity":"sha512-AZlt3hQywjwFx/kHAN6h7kuWqKgw135XwleaZzED8tGkPWXybbFz1gjuT5zzkj8OvilfT5TwNBs3PA6Updn4VA==","signatures":[{"sig":"MEUCIQCEuwCeuTC1uLG3SwMK9ZwcKqYI3B4xMBHfxXs5L3k7CgIgGnpwXH1pohB6VmcsFERBls13FXpqGUIlL1J3wA3jFas=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":41824},"cordova":{"id":"cordova-plugin-vibration","platforms":["ohos"]},"engines":{"cordovaDependencies":{"3.1.1":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"4d9517ce97067362923b36cb0f824a876b9c0844","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-vibration","type":"git"},"_npmVersion":"10.5.1","description":"Cordova vibration Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-vibration_3.1.1_1773924726494_0.7036781598980348","host":"s3://npm-registry-packages-npm-production"}},"3.1.2":{"name":"@cordova-ohos/cordova-plugin-vibration","version":"3.1.2","description":"Cordova Vibration Plugin","cordova":{"id":"cordova-plugin-vibration","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-vibration"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-vibration/issues"},"keywords":["cordova","vibration","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"3.1.2":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-vibration@3.1.2","gitHead":"1ee5599739debb5bc3a6d84b495f0b2ca47534e9","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-JtJTMg/BIYhT4/7vIoyYfOktegUOanhl53tU+kTr5sNC2mxUsmGuDIxLKYCRfXAKOvhO3Wg+Jiu5Rv1v4QFK/g==","shasum":"a759fc582bc5db5af5ea5805e13b0fe2cf7c457e","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-vibration/-/cordova-plugin-vibration-3.1.2.tgz","fileCount":9,"unpackedSize":92192,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEj6k2IAYTJ0DuxpXd9+reGn4UNmT/uOtnkgnfDCoBIPAiBhJVPrQT0lOI1Vl4wHT+rkv2xsVizVLrbPjRSuIuvNRA=="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-vibration_3.1.2_1785141631854_0.8068547478530921"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T12:52:06.416Z","modified":"2026-07-27T08:40:32.374Z","3.1.1":"2026-03-19T12:52:06.694Z","3.1.2":"2026-07-27T08:40:31.994Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-vibration/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","vibration","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-vibration"},"description":"Cordova Vibration Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# cordova-plugin-vibration\r\n\r\n[](README.md)\r\n[](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-vibration@3.1.1](https://npmjs.com/package/cordova-plugin-vibration/v/3.1.1) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-vibration](#cordova-plugin-vibration)\r\n - [简介](#简介)\r\n - [功能特性](#功能特性)\r\n - [支持平台](#支持平台)\r\n - [前置准备](#前置准备)\r\n - [下载安装](#下载安装)\r\n - [前提条件](#前提条件)\r\n - [从 npm 安装](#从-npm-安装)\r\n - [从 GitCode 仓库安装（开发版）](#从-gitcode-仓库安装开发版)\r\n - [离线安装（本地包）](#离线安装本地包)\r\n - [安装后验证](#安装后验证)\r\n - [卸载](#卸载)\r\n - [OHOS 配置](#ohos-配置)\r\n - [1. 权限配置](#1-权限配置)\r\n - [2. 参数配置](#2-参数配置)\r\n - [约束与限制](#约束与限制)\r\n - [兼容性](#兼容性)\r\n - [使用示例](#使用示例)\r\n - [1. 基础用法：单次振动（常用场景）](#1-基础用法单次振动常用场景)\r\n - [2. 高级用法：自定义模式振动（复杂场景）](#2-高级用法自定义模式振动复杂场景)\r\n - [3. 完整页面示例（可直接使用）](#3-完整页面示例可直接使用)\r\n - [使用说明](#使用说明)\r\n - [1. 核心 API 说明](#1-核心-api-说明)\r\n - [1.1 单次振动（基础用法）](#11-单次振动基础用法)\r\n - [1.2 自定义模式振动（高级用法）](#12-自定义模式振动高级用法)\r\n - [2. 核心参数说明](#2-核心参数说明)\r\n - [2.1 单次振动参数（time）](#21-单次振动参数time)\r\n - [2.2 自定义模式振动参数（vibrationConfig）](#22-自定义模式振动参数vibrationconfig)\r\n - [2.2.1 MetaData 属性（文件头信息）](#221-metadata-属性文件头信息)\r\n - [2.2.2 Channels 属性（马达振动通道信息）](#222-channels-属性马达振动通道信息)\r\n - [2.2.3 Event 属性（单个振动事件）](#223-event-属性单个振动事件)\r\n - [2.2.4 Parameters 子属性说明](#224-parameters-子属性说明)\r\n - [2.2.5 限制要求](#225-限制要求)\r\n - [3. 常见问题（FAQ）](#3-常见问题faq)\r\n - [Q1: 调用振动 API 后无反应怎么办？](#q1-调用振动-api-后无反应怎么办)\r\n - [Q2: OHOS 平台自定义模式振动不生效怎么办？](#q2-ohos-平台自定义模式振动不生效怎么办)\r\n - [Q3: 如何停止正在进行的振动？](#q3-如何停止正在进行的振动)\r\n - [4. 注意事项](#4-注意事项)\r\n - [目录结构](#目录结构)\r\n - [贡献代码](#贡献代码)\r\n - [许可证](#许可证)\r\n - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\n`cordova-plugin-vibration` 是一款专为 Cordova/PhoneGap 应用设计的设备振动控制插件，旨在帮助开发者快速实现跨平台的设备振动功能。通过该插件，开发者无需关注不同操作系统对振动硬件的底层控制差异，即可通过简洁的 JavaScript API 调用设备振动功能，适用于消息通知、操作反馈、游戏交互等多种场景，为用户提供更直观的触觉交互体验。本文档主要介绍该插件在 OHOS 系统中的应用、配置及注意事项。\r\n\r\n该插件完全遵循 Cordova 插件开发规范，支持自定义振动时长、振动模式（如长短交替振动），并适配主流移动平台及桌面平台，可无缝集成到各类 Cordova 应用中。\r\n\r\n## 功能特性\r\n\r\n- **跨平台适配**：完美适配 Android、iOS、Windows、Browser、OHOS 多平台，统一 API 调用方式，无需额外适配不同平台底层差异\r\n\r\n- **两种振动模式**：支持单次振动（自定义时长）和自定义模式振动（可配置频率、强度、动态曲线），满足不同场景需求\r\n\r\n- **简洁 API 调用**：通过全局对象 `navigator.vibrate` 和 `navigator.notification.vibrate` 暴露接口，调用简单，上手快速\r\n\r\n- **振动控制灵活**：支持随时停止振动，可自定义振动强度、频率及动态变化曲线，适配复杂交互场景\r\n\r\n- **OHOS 原生适配**：针对 OHOS 平台做专属优化，支持原生振动，适配 OHOS 5.0+ 版本，明确权限配置及场景限制\r\n\r\n- **丰富场景适配**：适用于消息通知、按钮点击反馈、游戏交互、预警提示等多种触觉交互场景\r\n\r\n- **轻量无依赖**：插件体积小，无强制依赖插件，可直接集成到 Cordova 项目中使用\r\n\r\n## 支持平台\r\n\r\n- **Android**（API 级别 21 及以上，覆盖 Android 5.0 及更高版本）\r\n\r\n- **iOS**（iOS 10.0 及以上，支持 iPhone、iPad 等全系列 iOS 设备，注：iPad 部分机型无振动硬件）\r\n\r\n- **Windows**（Windows 10 及以上，包含 UWP 通用应用场景，仅支持具备振动功能的设备）\r\n\r\n- **Browser**（主流桌面及移动浏览器，如 Chrome、Firefox、Edge，通过浏览器 API 模拟振动效果）\r\n\r\n- **OHOS**（5.0 及以上）\r\n\r\n## 前置准备\r\n\r\n在集成插件前，确保开发环境已满足以下基础条件，无需额外在第三方平台注册配置：\r\n\r\n- 已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 `node -v` 和 `npm -v` 命令验证版本\r\n\r\n- 已全局安装 HCordova CLI（v10.0.0 及以上），用于插件的安装、卸载和管理\r\n\r\n- 已创建 Cordova 项目（若尚未创建，可通过 `hcordova create MyVibrationApp com.example.vibrationapp 振动示例应用` 命令快速创建）\r\n\r\n- OHOS 平台需提前了解设备振动硬件支持情况，部分低端设备可能不具备振动功能\r\n\r\n## 下载安装\r\n\r\n通过 hcordova CLI 即可快速安装插件，支持指定 OHOS 平台安装、从 GitCode 仓库获取开发版，安装流程简洁高效，安装后可通过命令验证安装结果。\r\n\r\n### 前提条件\r\n\r\n安装插件前，需先安装 HCordova CLI，执行以下命令安装：\r\n\r\n```bash\r\nnpm install -g hcordova\r\n```\r\n\r\n### 从 npm 安装\r\n\r\n通过 npm 仓库安装稳定版本，适合大多数开发场景，仅安装到 OHOS 平台：\r\n\r\n```bash\r\n# 全平台安装\r\nhcordova plugin add cordova-plugin-vibration \r\n\r\n# 指定 OHOS 平台\r\nhcordova plugin add cordova-plugin-vibration --platform ohos\r\n\r\n# 指定版本安装\r\nhcordova plugin add cordova-plugin-vibration@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 仓库安装（开发版）\r\n\r\n若需使用最新开发版本（可能包含未发布的新功能或 Bug 修复），可从 GitCode 源码安装，仅适配 OHOS 平台：\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-vibration.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-vibration.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-vibration）\r\n# 执行离线安装\r\nhcordova plugin add ~/Downloads/cordova-plugin-vibration --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n\r\n# 若输出结果包含 cordova-plugin-vibration 则表示插件已成功安装\r\n```\r\n\r\n### 卸载\r\n\r\n如需移除插件，进入项目根目录执行以下命令，卸载后建议重新构建项目以清理残留文件：\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-vibration\r\n\r\n# 指定 OHOS 卸载\r\nhcordova plugin remove cordova-plugin-vibration --platform ohos\r\n```\r\n\r\n## OHOS 配置\r\n\r\nOHOS 平台集成插件后，需完成权限配置才能确保振动功能正常运行，无需额外进行复杂配置，具体步骤如下：\r\n\r\n### 1. 权限配置\r\n\r\nOHOS 平台使用原生振动，不支持 W3C 震动，需在主项目的 module.json5 文件中添加振动权限：\r\n\r\n```json\r\n{\r\n \"name\": \"ohos.permission.VIBRATE\"\r\n}\r\n```\r\n\r\n说明：该权限用于允许应用调用设备振动硬件，若未添加此权限，振动功能将无法正常触发，且无权限相关报错提示。\r\n\r\n### 2. 参数配置\r\n\r\nOHOS 平台无需额外配置参数，安装插件、添加权限后，重新构建项目即可正常使用振动功能。需注意，振动功能的正常触发依赖设备振动硬件支持，部分低端设备可能不具备振动功能，调用 API 后无响应。\r\n\r\n## 约束与限制\r\n\r\n- 依赖插件：无强制依赖，可直接集成到 Cordova 项目中使用\r\n\r\n- 权限限制：OHOS 平台必须添加 `ohos.permission.VIBRATE` 权限，否则无法触发振动功能\r\n\r\n- 平台差异限制：OHOS 使用原生振动，不支持 W3C 震动，自定义模式振动需按 OHOS 原生规范配置参数\r\n\r\n- 设备硬件限制：仅支持具备振动硬件的设备，部分低端 OHOS 设备、iPad 部分机型无振动硬件，调用 API 后无响应\r\n\r\n- 情景模式限制：OHOS 设备在免打扰、睡眠模式、学习模式等情景模式下，振动功能会被禁用，无法触发振动\r\n\r\n- 参数限制：自定义模式振动中，单个配置文件不得超过 64KB，单个配置文件中振动事件数量不得超过 128 个\r\n\r\n- API 调用限制：所有振动 API 需在 `deviceready` 事件触发后调用，否则会出现 API 未定义、调用失败等异常\r\n\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n## 使用示例\r\n\r\n插件通过全局对象 `navigator.vibrate` 和 `navigator.notification.vibrate` 暴露振动控制 API，支持两种核心振动模式：单次振动和自定义模式振动。所有 API 需在 `deviceready` 事件触发后调用，以下为各核心功能的完整使用示例，可直接复制到项目中使用。\r\n\r\n### 1. 基础用法：单次振动（常用场景）\r\n\r\n触发设备单次振动，可自定义振动时长，适用于按钮点击、消息提醒等简单反馈场景，支持停止当前振动：\r\n\r\n```javascript\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n // 1. 触发 500ms 的单次振动（默认时长，适合按钮点击反馈）\r\n document.getElementById('vibrateShort').addEventListener('click', function() {\r\n navigator.vibrate(500);\r\n console.log('已触发 500ms 振动');\r\n });\r\n\r\n // 2. 触发 2000ms 的长时间振动（适合消息提醒）\r\n document.getElementById('vibrateLong').addEventListener('click', function() {\r\n navigator.vibrate(2000);\r\n console.log('已触发 2000ms 振动');\r\n });\r\n\r\n // 3. 停止当前振动（传入 0 即可停止所有正在进行的振动）\r\n document.getElementById('stopVibrate').addEventListener('click', function() {\r\n navigator.vibrate(0);\r\n console.log('已停止当前振动');\r\n });\r\n}, false);\r\n```\r\n\r\n### 2. 高级用法：自定义模式振动（复杂场景）\r\n\r\n适用于游戏交互、复杂通知提醒等场景，可配置振动频率、强度、动态变化曲线，支持多通道振动（OHOS 原生支持）：\r\n\r\n```javascript\r\ndocument.addEventListener('deviceready', function() {\r\n // 自定义振动模式配置（OHOS 原生支持，不支持 W3C 震动）\r\n var vibrationConfig = {\r\n \"MetaData\": {\r\n \"Create\": \"2023-01-09\",\r\n \"Description\": \"游戏爆炸振动效果\",\r\n \"Version\": 1.0,\r\n \"ChannelNumber\": 1\r\n },\r\n \"Channels\": [\r\n {\r\n \"Parameters\": {\r\n \"Index\": 0 // 0 表示全通道同步振动，1 左马达，2 右马达\r\n },\r\n \"Pattern\": [\r\n {\r\n \"Event\": {\r\n \"Type\": \"transient\", // 瞬态短振动（点击/碰撞反馈）\r\n \"StartTime\": 0,\r\n \"Parameters\": {\r\n \"Frequency\": 31,\r\n \"Intensity\": 100 // 最大强度\r\n }\r\n }\r\n },\r\n {\r\n \"Event\": {\r\n \"Type\": \"continuous\", // 稳态长振动（持续提醒）\r\n \"StartTime\": 40,\r\n \"Duration\": 3000, // 持续 3 秒\r\n \"Parameters\": {\r\n \"Frequency\": 30,\r\n \"Intensity\": 38,\r\n \"Curve\": [ // 动态调节曲线（强度和频率随时间变化）\r\n {\r\n \"Time\": 0,\r\n \"Frequency\": 0,\r\n \"Intensity\": 0\r\n },\r\n {\r\n \"Time\": 1,\r\n \"Frequency\": 15,\r\n \"Intensity\": 0.5\r\n },\r\n {\r\n \"Time\": 40,\r\n \"Frequency\": -8,\r\n \"Intensity\": 1.0\r\n },\r\n {\r\n \"Time\": 54,\r\n \"Frequency\": 0,\r\n \"Intensity\": 0\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n }\r\n ]\r\n };\r\n\r\n // 触发自定义模式振动\r\n document.getElementById('customVibrate').addEventListener('click', function() {\r\n navigator.vibrate(vibrationConfig);\r\n console.log('已触发自定义模式振动');\r\n });\r\n\r\n // 停止自定义模式振动\r\n document.getElementById('stopCustomVibrate').addEventListener('click', function() {\r\n navigator.vibrate(0);\r\n console.log('已停止自定义模式振动');\r\n });\r\n}, false);\r\n```\r\n\r\n### 3. 完整页面示例（可直接使用）\r\n\r\n以下是包含所有振动功能的完整 Cordova 页面示例，可直接复制到项目的 `www/index.html` 文件中使用：\r\n\r\n```html\r\n\r\n\r\n\r\n \r\n \r\n cordova-plugin-vibration 示例\r\n \r\n\r\n \r\n \r\n\r\n\r\n 设备振动插件示例
\r\n \r\n \r\n \r\n \r\n \r\n\r\n\r\n```\r\n\r\n## 使用说明\r\n\r\n以下为插件使用的核心说明，包括 API 详解、参数说明、常见问题及注意事项等，帮助开发者快速上手并避免异常，重点突出 OHOS 平台特性。\r\n\r\n### 1. 核心 API 说明\r\n\r\n插件所有方法均挂载在全局对象 `navigator.vibrate` 和 `navigator.notification.vibrate` 下，无需额外引入，两者用法一致。所有 API 均为异步执行，需在 Cordova 加载完成后（`deviceready` 事件触发后）调用，否则会出现 API 未定义、调用失败等异常。支持两种核心振动模式：单次振动和自定义模式振动。\r\n\r\n#### 1.1 单次振动（基础用法）\r\n\r\n功能：触发设备的单次振动，可指定振动时长，传入 0 可停止当前所有振动，适用于简单的操作反馈场景。\r\n\r\n语法：\r\n\r\n```javascript\r\n// 标准 API（推荐使用）\r\nnavigator.vibrate(time);\r\n\r\n// 兼容写法\r\nnavigator.vibration.vibrate(time);\r\n```\r\n\r\n#### 1.2 自定义模式振动（高级用法）\r\n\r\n功能：触发复杂振动效果，可配置振动频率、强度、动态变化曲线、多通道振动，仅 OHOS 原生支持，不支持 W3C 震动。\r\n\r\n语法：\r\n\r\n```javascript\r\n// 标准 API（推荐使用）\r\nnavigator.vibrate(vibrationConfig);\r\n\r\n// 兼容写法\r\nnavigator.vibration.vibrate(vibrationConfig);\r\n```\r\n\r\n### 2. 核心参数说明\r\n\r\n#### 2.1 单次振动参数（time）\r\n\r\n| 参数名 | 类型 | 是否必选 | 说明 | 默认值 |\r\n|---|---|---|---|---|\r\n| time | Number | 否 | 振动时长（单位：毫秒），默认值为 500ms（不同平台默认值可能有差异）。若传入 0，将停止当前所有振动。 | 500 |\r\n\r\n#### 2.2 自定义模式振动参数（vibrationConfig）\r\n\r\n为 JSON 对象，包含 MetaData（文件头信息）、Channels（马达振动通道信息）两个核心属性，具体参数如下：\r\n\r\n##### 2.2.1 MetaData 属性（文件头信息）\r\n\r\n用于添加文件描述信息，明确文件基础配置，部分属性为必填项：\r\n\r\n| 参数名 | 类型 | 是否必选 | 说明 |\r\n|---|---|---|---|\r\n| Version | Number | 是 | 文件格式的版本号，具备向前兼容特性，目前仅支持版本 1.0。 |\r\n| ChannelNumber | Number | 是 | 用于标识马达振动的通道数量，最大支持双马达通道（即 2 个通道）。 |\r\n| Create | String | 否 | 用于记录文件的创作时间，格式建议遵循 \"YYYY-MM-DD HH:MM:SS\" 以保证可读性。 |\r\n| Description | String | 否 | 可补充说明振动效果（如“游戏爆炸振动”“通知提醒振动”）、创建人信息、适用场景等附加内容。 |\r\n\r\n##### 2.2.2 Channels 属性（马达振动通道信息）\r\n\r\nJSON 数组类型，存储各个振动通道的详细配置信息，每个通道需包含 Parameters 和 Pattern 两个核心属性：\r\n\r\n- Parameters（通道参数）：仅包含 Index 一个必填属性，用于标识通道编号，取值规则为：0 表示全通道同步发送振动指令，1 对应左马达通道，2 对应右马达通道。\r\n\r\n- Pattern（马达振动序列）：JSON 数组类型，存储单个通道的振动事件序列，每个数组元素通过 Event 属性定义 1 个独立的振动事件。\r\n\r\n##### 2.2.3 Event 属性（单个振动事件）\r\n\r\n构成振动序列的基本单元，代表 1 个完整的振动动作，需包含 Type、StartTime、Parameters 三个必填属性，具体如下：\r\n\r\n| 参数名 | 类型 | 是否必选 | 说明 |\r\n|---|---|---|---|\r\n| Type | String | 是 | 振动事件类型，仅支持取值为 `transient`（瞬态振动，短时长、响应快）或 `continuous`（稳态振动，长时长、稳定）。 |\r\n| StartTime | Number | 是 | 振动起始时间，单位为毫秒（ms），有效取值范围为 [0, 1800000]（即 0 ms 至 30 分钟）。 |\r\n| Duration | Number | 条件必填 | 振动持续时间，仅当 Type 为 continuous 时生效且为必填，单位为毫秒（ms），有效取值范围为 [0, 5000]（即 0 ms 至 5 秒）。 |\r\n| Parameters | Object | 是 | 振动事件参数配置，包含 Intensity、Frequency 两个必填属性，Curve 一个可选属性。 |\r\n\r\n##### 2.2.4 Parameters 子属性说明\r\n\r\n| 参数名 | 类型 | 是否必选 | 说明 |\r\n|---|---|---|---|\r\n| Intensity | Number | 是 | 振动事件基础强度，有效取值范围为 [0, 100]，数值越大振动越强（0 表示无振动，100 表示最大强度）。 |\r\n| Frequency | Number | 是 | 振动事件基础频率，有效取值范围为 [0, 100]，数值越大振动频率越高（需结合硬件支持范围使用）。 |\r\n| Curve | Array | 否 | 振动参数调节曲线，仅当 Type 为 continuous 时生效，用于设置振动过程中强度和频率的动态变化，最小需包含 4 个调节点，最大不超过 16 个调节点。 |\r\n\r\n##### 2.2.5 限制要求\r\n\r\n| 参数 | 要求 |\r\n|---|---|\r\n| 振动事件（event）的数量 | 单个配置文件中不得超过 128 个 |\r\n| 振动配置文件长度 | 整个文件大小不得超过 64KB |\r\n\r\n### 3. 常见问题（FAQ）\r\n\r\n#### Q1: 调用振动 API 后无反应怎么办？\r\n\r\n1. 检查 API 调用时机：确保在 `deviceready` 事件触发后调用该方法，否则 `navigator.vibrate` 可能未定义\r\n\r\n2. 检查插件安装：执行 `hcordova plugin list` 确认插件已成功安装\r\n\r\n3. 检查 OHOS 权限配置：确认主项目的 module.json5 文件中已添加 `ohos.permission.VIBRATE` 权限\r\n\r\n4. 检查设备硬件：确认设备具备振动功能，部分低端 OHOS 设备、iPad 部分机型无振动硬件\r\n\r\n5. 检查设备情景模式：确认设备未处于免打扰、睡眠模式、学习模式等，此类模式下振动会被禁用\r\n\r\n6. 重新构建项目：执行 `hcordova build ohos`，确保插件资源和权限配置正确加载\r\n\r\n#### Q2: OHOS 平台自定义模式振动不生效怎么办？\r\n\r\n1. 检查配置参数：确认 vibrationConfig 格式正确，Version 为 1.0，ChannelNumber、Index 等必填参数完整\r\n\r\n2. 检查参数范围：确认 Intensity、Frequency、StartTime、Duration 等参数在有效取值范围内\r\n\r\n3. 检查 Curve 配置：若配置了 Curve，确保调节点数量在 4-16 个之间，Time 不超过当前事件的 Duration\r\n\r\n4. 确认平台特性：OHOS 使用原生振动，不支持 W3C 震动，避免使用 W3C 相关振动配置\r\n\r\n#### Q3: 如何停止正在进行的振动？\r\n\r\n调用振动 API 时传入 0 即可停止当前所有正在进行的振动，无论其是单次振动还是自定义模式振动，示例代码：`navigator.vibrate(0);`\r\n\r\n### 4. 注意事项\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现 navigator.vibrate 未定义、调用失败等异常。\r\n\r\n- OHOS 权限要求：OHOS 平台必须添加 `ohos.permission.VIBRATE` 权限，否则振动功能无法正常触发，且无报错提示。\r\n\r\n- OHOS 平台特性：OHOS 使用原生振动，不支持 W3C 震动，自定义模式振动需按 OHOS 原生规范配置参数，不可使用 W3C 相关配置。\r\n\r\n- 设备情景模式：OHOS 设备在免打扰、睡眠模式、学习模式等情景模式下，振动功能会被系统禁用，调用 API 后无响应，需提前告知用户。\r\n\r\n- 设备硬件差异：不同设备的振动强度、频率支持范围不同，建议在多种 OHOS 设备上测试，确保振动效果一致。\r\n\r\n- 参数限制：自定义模式振动需严格遵循参数范围要求，避免出现配置文件过大、振动事件过多、参数超出有效范围等问题，否则振动可能不生效。\r\n\r\n- 兼容性提示：确保 OHOS 设备版本为 5.0 及以上，HCordova CLI 版本为 10.0.0 及以上，否则可能出现功能异常。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-vibration # [根目录] 震动功能插件项目根目录\r\n├── src # [源码目录] 存放原生平台代码\r\n│ └── main # [主目录] 主代码目录\r\n│ └── cpp # [C++ 目录] C++ 原生代码目录\r\n│ └── vibrate # [C++ 模块] 震动功能 C++ 模块文件夹\r\n│ ├── vibrate.cpp # [C++ 实现] C++ 源文件，调用系统 API 实现震动逻辑\r\n│ └── vibrate.h # [C++ 声明] C++ 头文件，定义震动接口\r\n├── www # [前端目录] 存放供 Web 端调用的 JS 接口文件\r\n│ └── vibration.js # [JS 文件] 暴露给 Web 端的 JS 接口，如 navigator.vibrate\r\n├── .gitignore # [配置] Git 版本控制忽略文件配置\r\n├── LICENSE # [文本] 开源许可证文件\r\n├── OAT.xml # [配置] 门禁配置文件\r\n├── package.json # [配置] NPM 包配置文件\r\n├── plugin.xml # [配置] Cordova 插件配置文件，定义插件元数据和平台适配\r\n└── README.md # [文档] 插件使用说明和文档\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-vibration/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-vibration/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- 振动参数参考资料：[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)\r\n\r\n- OHOS GitCode 仓库：[https://gitcode.com/CPF-Cordova/cordova-plugin-vibration](https://gitcode.com/CPF-Cordova/cordova-plugin-vibration)\r\n\r\n- Android/iOS 官方论坛：[https://cordova.apache.org/community/](https://cordova.apache.org/community/)\r\n","readmeFilename":"README.md"}