{"_id":"@cordova-ohos/cordova-plugin-device-motion","_rev":"3-04e92327a11942b5fe9dc3b6f093007a","name":"@cordova-ohos/cordova-plugin-device-motion","dist-tags":{"latest":"2.0.2"},"versions":{"2.0.1":{"name":"@cordova-ohos/cordova-plugin-device-motion","version":"2.0.1","keywords":["cordova","device-motion","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-device-motion@2.0.1","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-device-motion/issues"},"dist":{"shasum":"0f44649d573b51f318a308e71d34ceed0e3085ad","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-device-motion/-/cordova-plugin-device-motion-2.0.1.tgz","fileCount":9,"integrity":"sha512-aQsbpIuzIoOPiM9eCQWXIfz3V9R6JSD1YgyqVRKXoizEEYLZUEqO7+h6dxDQj8e0g7J35QVQWz8ljJMkniDM6A==","signatures":[{"sig":"MEUCIQCFqQvOtlQJrQ4pnxO5FtbRCc7hqLtGknuZOXPQkznXkwIgci+n7KfzwYvl5xQlWz3cEfiU7teUnVRV22dLjnEo9W0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42777},"cordova":{"id":"cordova-plugin-device-motion","platforms":["ohos"]},"engines":{"cordovaDependencies":{"2.0.1":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"e66144646abd5ef26cb6d699450a1e599180caf6","_npmUser":{"name":"wanpengsz","email":"wanpengsz@163.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-device-motion","type":"git"},"_npmVersion":"9.6.2","description":"Cordova device-motion Plugin","directories":{},"_nodeVersion":"20.16.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-device-motion_2.0.1_1773989954171_0.8978173849122053","host":"s3://npm-registry-packages-npm-production"}},"2.0.2":{"name":"@cordova-ohos/cordova-plugin-device-motion","version":"2.0.2","description":"Cordova device-motion Plugin","cordova":{"id":"cordova-plugin-device-motion","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-device-motion"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-device-motion/issues"},"keywords":["cordova","device-motion","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"2.0.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-device-motion@2.0.2","gitHead":"ef7f8f1a832f366821065e44d4db23bfe34d91e1","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-GCmBM36pR9dflBSRzuO7k2PyC2yzlHqDUtCHqmsBdfoxjCPXnPFq7blE48e0HJn9IOFoTU12ZZQtoqrmI/REqA==","shasum":"d8ec89ccf4f9ee0ffde2a567cc48a1d531031a8f","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-device-motion/-/cordova-plugin-device-motion-2.0.2.tgz","fileCount":10,"unpackedSize":67817,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDSHVS1K691cdX2pz60JcBLaJhQvWSTmaECqjmN9OFRigIgGtbGy/ugEYljejVutcxeZHCgdUTfgfVNPns9Qucq39I="}]},"_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-device-motion_2.0.2_1785151047659_0.20998691965011762"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-20T06:59:14.035Z","modified":"2026-07-27T11:17:28.014Z","2.0.1":"2026-03-20T06:59:14.310Z","2.0.2":"2026-07-27T11:17:27.784Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-device-motion/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","device-motion","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-device-motion"},"description":"Cordova device-motion 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":"# <center>cordova-plugin-device-motion</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-device-motion@2.0.1](https://www.npmjs.com/package/cordova-plugin-device-motion/v/2.0.1) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-device-motion](#cordova-plugin-device-motion)\r\n  - [简介](#简介)\r\n  - [支持平台](#支持平台)\r\n  - [下载安装](#下载安装)\r\n    - [1. 从 npm 安装（推荐）](#1-从-npm-安装推荐)\r\n    - [2. 安装指定版本](#2-安装指定版本)\r\n    - [3. 从 GitCode 安装（开发版本）](#3-从-gitcode-安装开发版本)\r\n    - [4. 离线安装（本地包）](#4-离线安装本地包)\r\n    - [5. 安装后验证](#5-安装后验证)\r\n    - [6. 卸载插件](#6-卸载插件)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n    - [平台配置](#平台配置)\r\n      - [OHOS 配置](#ohos-配置)\r\n      - [权限说明](#权限说明)\r\n  - [核心概念](#核心概念)\r\n    - [1.1 坐标系定义](#11-坐标系定义)\r\n    - [1.2 数据类型说明](#12-数据类型说明)\r\n    - [1.3 采样频率](#13-采样频率)\r\n  - [使用示例](#使用示例)\r\n    - [示例 1：持续监听加速度（含重力）](#示例-1持续监听加速度含重力)\r\n    - [示例 2：单次获取加速度（含重力）](#示例-2单次获取加速度含重力)\r\n    - [示例 3：停止加速度监听](#示例-3停止加速度监听)\r\n  - [使用说明](#使用说明)\r\n    - [API 文档](#api-文档)\r\n      - [1.1 加速度数据监听 API](#11-加速度数据监听-api)\r\n        - [1.1.1 持续监听加速度（含重力）](#111-持续监听加速度含重力)\r\n        - [1.1.2 单次获取加速度（含重力）](#112-单次获取加速度含重力)\r\n        - [1.1.3 停止加速度监听](#113-停止加速度监听)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\n`cordova-plugin-device-motion` 是 Cordova 设备运动传感器插件，用于获取移动设备的加速度、旋转速率等运动数据。基于设备原生传感器（如加速度计、陀螺仪）开发，支持实时数据监听与采样频率配置，适用于运动类应用（如计步器、健身 APP）、游戏控制（如重力感应游戏）、设备姿态检测等场景。\r\n\r\n重要说明：W3C 已具备相关功能，可直接使用 W3C 功能无需插件支持，但需进行网页授权，需在 mainPage 中传入 onPermissionRequest 函数授权，onPermissionRequest 的使用参考 OHOS Cordova 框架 README ArkTS 侧示例代码。\r\n\r\n- 多维度数据采集：支持获取设备在 X/Y/Z 三轴的加速度（含重力/不含重力）、旋转速率数据\r\n\r\n- 灵活配置：可自定义数据采样频率（如 10Hz、50Hz），平衡数据精度与设备功耗\r\n\r\n- 实时监听：通过事件监听机制实时获取运动数据，支持动态开启/关闭监听\r\n\r\n- 跨平台兼容：统一 Android、iOS、Windows、Browser、OHOS 平台 API 调用方式，减少适配成本\r\n\r\n- 低功耗设计：支持按需开启/关闭传感器，降低设备电量消耗\r\n\r\n- 原生性能：基于设备硬件传感器开发，数据响应延迟低，采样精度高\r\n\r\n## 支持平台\r\n\r\n- **Android**：API 19 及以上（Android 4.4+）\r\n\r\n- **iOS**：10.0 及以上\r\n\r\n- **OHOS**：5.0+\r\n\r\n- **Windows**：主流 Windows 系统版本\r\n\r\n- **Browser**：主流桌面及移动浏览器\r\n\r\n## 下载安装\r\n\r\n通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库获取，可指定 OHOS 平台和版本安装，安装前确保已创建 Cordova 项目并进入项目根目录。\r\n\r\n### 1. 从 npm 安装（推荐）\r\n\r\n通过 npm 安装最新稳定版，自动集成到 Cordova 项目，支持全平台或指定 OHOS 平台安装：\r\n\r\n```bash\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# 全平台安装\r\nhcordova plugin add cordova-plugin-device-motion\r\n\r\n# 指定 OHOS 平台安装\r\nhcordova plugin add cordova-plugin-device-motion --platform ohos\r\n```\r\n\r\n### 2. 安装指定版本\r\n\r\n如需兼容特定 Cordova 或平台版本，可指定版本号安装（仅 OHOS 平台）：\r\n\r\n```bash\r\n# 安装 1.0.0 版本（指定 OHOS 平台）\r\nhcordova plugin add cordova-plugin-device-motion@1.0.0 --platform ohos\r\n```\r\n\r\n### 3. 从 GitCode 安装（开发版本）\r\n\r\n如需测试最新功能或问题修复，可从 GitCode 仓库安装开发分支（仅 OHOS 平台）：\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-device-motion.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-device-motion.git@develop --platform ohos\r\n```\r\n\r\n### 4. 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-device-motion）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-plugin-device-motion  --platform ohos\r\n```\r\n\r\n### 5. 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n### 6. 卸载插件\r\n\r\n如需移除插件，执行以下命令，支持全平台卸载或仅卸载 OHOS 平台插件：\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-device-motion\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-device-motion --platform ohos\r\n```\r\n\r\n## 约束与限制\r\n\r\n* 依赖插件：无强制依赖，插件集成后可直接使用，无需额外配置\r\n\r\n* 权限要求：OHOS 平台需配置加速度传感器权限，否则无法获取运动数据\r\n\r\n* 调用时机：所有 API 需在 `deviceready` 事件触发后调用，避免因原生接口未初始化导致错误\r\n\r\n* 替代方案：W3C 已具备相关功能，可无需插件直接使用，但需在 mainPage 中传入 onPermissionRequest 函数完成网页授权\r\n\r\n* 设备限制：部分低端设备可能未配备加速度计、陀螺仪，会导致插件无法正常获取数据\r\n\r\n* 功耗说明：采样频率越高，设备功耗越大，建议根据业务场景选择合适的采样频率\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插件安装后需根据目标平台进行必要配置，确保插件功能正常运行，以下重点说明 OHOS 平台的配置要求（Android、iOS 平台配置参考官方指南）。\r\n\r\n#### OHOS 配置\r\n\r\n使用该插件需要配置获取加速度相关权限，需在应用配置文件中添加以下权限配置：\r\n\r\n```json\r\n\"requestPermissions\": [\r\n    {\r\n    \"name\" : \"ohos.permission.ACCELEROMETER\"\r\n    }\r\n]\r\n```\r\n\r\n#### 权限说明\r\n\r\n- ohos.permission.ACCELEROMETER：加速度权限\r\n\r\n## 核心概念\r\n\r\n在使用插件前，需理解以下核心概念，确保正确解读运动数据：\r\n\r\n### 1.1 坐标系定义\r\n\r\n插件采用设备默认坐标系，各轴方向定义如下：\r\n\r\n- **X 轴**：水平方向，从设备左侧指向右侧（设备横向握持时，X 轴与地面平行）\r\n\r\n- **Y 轴**：垂直方向，从设备底部指向顶部（与设备屏幕垂直，向上为正方向）\r\n\r\n- **Z 轴**：垂直于设备屏幕，从屏幕内侧指向外侧（设备平放时，Z 轴垂直于地面向上）\r\n\r\n### 1.2 数据类型说明\r\n\r\n| **数据类型** | **描述** | **单位** | **应用场景** |\r\n|---|---|---|---|\r\n| 加速度（含重力） | 设备在三轴的总加速度，包含重力加速度（9.8m/s²） | m/s² | 检测设备整体运动状态（如掉落、撞击） |\r\n| 加速度（不含重力） | 设备在三轴的实际运动加速度，剔除重力影响 | m/s² | 检测设备主动运动（如摇晃、平移） |\r\n| 旋转速率 | 设备绕三轴的旋转角速度 | rad/s | 检测设备旋转状态（如旋转屏幕、晃动手机） |\r\n\r\n### 1.3 采样频率\r\n\r\n采样频率指单位时间内获取运动数据的次数，单位为 Hz（次/秒）：\r\n\r\n- **低频率（1-10Hz）**：适用于低精度场景（如计步、简单姿态检测），功耗低\r\n\r\n- **中频率（10-50Hz）**：适用于中等精度场景（如健身 APP、普通游戏控制）\r\n\r\n- **高频率（50-100Hz）**：适用于高精度场景（如 AR/VR、专业运动分析），功耗较高\r\n\r\n## 使用示例\r\n\r\n### 示例 1：持续监听加速度（含重力）\r\n\r\n```js\r\n/**\r\n* 持续获取设备加速度数据（含重力加速度）\r\n* @param {Function} successCallback - 成功回调（参数：加速度数据对象）\r\n* @param {Function} errorCallback - 失败回调（参数：错误信息）\r\n* @param {Object} options - 配置选项（可选）\r\n* @returns {Number} watchId - 监听 ID（用于停止监听）\r\n*/\r\n\r\nconst watchId = navigator.accelerometer.watchAcceleration(\r\n   (acceleration) => {\r\n       console.log(\"加速度数据（含重力）：\", acceleration);\r\n       /*\r\n       acceleration 结构示例：\r\n       {\r\n          x: 0.23, // X 轴加速度（m/s²）\r\n           y: 9.78, // Y 轴加速度（含重力，约 9.8m/s²）\r\n           z: -0.15, // Z 轴加速度（m/s²）\r\n           timestamp: 1699999999999 // 数据采集时间戳（毫秒）\r\n       }\r\n       */\r\n   },\r\n   (error) => {\r\n       console.error(\"获取加速度数据失败：\", error);\r\n       /*\r\n       error 结构示例：\r\n       {\r\n           code: 1, // 错误码（1=权限不足，2=设备不支持，3=内部错误）\r\n           message: \"设备不支持加速度传感器\" // 错误描述\r\n       }\r\n       */\r\n   },\r\n   {\r\n       frequency: 100 // 采样频率（毫秒/次，即 10Hz，默认 1000ms）\r\n   }\r\n);\r\n\r\n```\r\n\r\n### 示例 2：单次获取加速度（含重力）\r\n\r\n```js\r\n/**\r\n* 单次获取设备加速度数据（含重力）\r\n* @param {Function} successCallback - 成功回调\r\n* @param {Function} errorCallback - 失败回调\r\n*/\r\n\r\nnavigator.accelerometer.getCurrentAcceleration(\r\n   (acceleration) => {\r\n       console.log(\"单次加速度数据（含重力）：\", acceleration);\r\n       // 业务处理（如单次姿态检测）\r\n       if (Math.abs(acceleration.y) < 1) {\r\n           console.log(\"设备当前处于水平放置状态\");\r\n       }\r\n   },\r\n   (error) => {\r\n       console.error(\"单次获取加速度失败：\", error);\r\n   }\r\n);\r\n\r\n```\r\n\r\n### 示例 3：停止加速度监听\r\n\r\n```js\r\n/**\r\n* 停止加速度数据监听\r\n* @param {Number} watchId - 监听 ID（从 watchAcceleration 返回）\r\n*/\r\n\r\nnavigator.accelerometer.clearWatch(watchId);\r\nconsole.log(\"已停止加速度数据监听\");\r\n\r\n```\r\n\r\n## 使用说明\r\n\r\n### API 文档\r\n\r\n插件通过全局对象 `navigator.accelerometer` 暴露所有 API，支持回调函数式调用。所有 API 需在 `deviceready` 事件触发后调用，避免因原生接口未初始化导致的错误。\r\n\r\n#### 1.1 加速度数据监听 API\r\n\r\n##### 1.1.1 持续监听加速度（含重力）\r\n\r\n用于持续获取设备三轴加速度数据（含重力影响），返回监听 ID，可用于后续停止监听。\r\n\r\nAPI 格式：navigator.accelerometer.watchAcceleration(successCallback, errorCallback, options);\r\n\r\n- successCallback：成功回调函数，参数为加速度数据对象（包含 x、y、z 轴加速度及时间戳）\r\n\r\n- errorCallback：失败回调函数，参数为错误对象（包含错误码和错误描述）\r\n\r\n- options：可选配置对象，主要参数为 frequency（采样频率，单位毫秒/次，默认 1000ms）\r\n\r\n##### 1.1.2 单次获取加速度（含重力）\r\n\r\n用于单次获取设备三轴加速度数据（含重力影响），适用于无需持续监听的场景。\r\n\r\nAPI 格式：navigator.accelerometer.getCurrentAcceleration(successCallback, errorCallback);\r\n\r\n- successCallback：成功回调函数，参数为加速度数据对象\r\n\r\n- errorCallback：失败回调函数，参数为错误对象\r\n\r\n##### 1.1.3 停止加速度监听\r\n\r\n用于停止已开启的加速度数据监听，需传入 watchAcceleration 返回的监听 ID。\r\n\r\nAPI 格式：navigator.accelerometer.clearWatch(watchId);\r\n\r\n- watchId：监听 ID，由 watchAcceleration 方法返回\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-device-motion/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       └── cpp/                  # C++ 原生代码\r\n│           └── Device/           # 设备模块\r\n│               ├── AccelListener.cpp  # 加速度监听功能的 C++ 实现\r\n│               └── AccelListener.h    # 加速度监听功能的头文件\r\n├── www/                          # Web 资源目录\r\n│   ├── Acceleration.js           # 加速度数据模型定义\r\n│   └── accelerometer.js          # JavaScript 加速度计接口（Cordova 桥接层）\r\n├── .gitignore                    # Git 忽略文件配置\r\n├── LICENSE                       # 项目开源许可证\r\n├── OAT.xml                       # OpenHarmony 审核配置文件\r\n├── package.json                  # Node.js 包配置\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-device-motion/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-device-motion/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- OHOS：[https://gitcode.com/CPF-Cordova/cordova-plugin-device-motion](https://gitcode.com/CPF-Cordova/cordova-plugin-device-motion)\r\n\r\n- Android、iOS 插件说明：[https://www.npmjs.com/package/cordova-plugin-device-motion](https://www.npmjs.com/package/cordova-plugin-device-motion)\r\n","readmeFilename":"README.md"}