@cordova-ohos/cordova-plugin-device-motion
v2.0.2
Published
Cordova device-motion Plugin
Readme
cordova-plugin-device-motion
本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。
简介
cordova-plugin-device-motion 是 Cordova 设备运动传感器插件，用于获取移动设备的加速度、旋转速率等运动数据。基于设备原生传感器（如加速度计、陀螺仪）开发，支持实时数据监听与采样频率配置，适用于运动类应用（如计步器、健身 APP）、游戏控制（如重力感应游戏）、设备姿态检测等场景。
重要说明：W3C 已具备相关功能，可直接使用 W3C 功能无需插件支持，但需进行网页授权，需在 mainPage 中传入 onPermissionRequest 函数授权，onPermissionRequest 的使用参考 OHOS Cordova 框架 README ArkTS 侧示例代码。
多维度数据采集：支持获取设备在 X/Y/Z 三轴的加速度（含重力/不含重力）、旋转速率数据
灵活配置：可自定义数据采样频率（如 10Hz、50Hz），平衡数据精度与设备功耗
实时监听：通过事件监听机制实时获取运动数据，支持动态开启/关闭监听
跨平台兼容：统一 Android、iOS、Windows、Browser、OHOS 平台 API 调用方式，减少适配成本
低功耗设计：支持按需开启/关闭传感器，降低设备电量消耗
原生性能：基于设备硬件传感器开发，数据响应延迟低，采样精度高
支持平台
Android：API 19 及以上（Android 4.4+）
iOS：10.0 及以上
OHOS：5.0+
Windows：主流 Windows 系统版本
Browser：主流桌面及移动浏览器
下载安装
通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库获取，可指定 OHOS 平台和版本安装，安装前确保已创建 Cordova 项目并进入项目根目录。
1. 从 npm 安装（推荐）
通过 npm 安装最新稳定版，自动集成到 Cordova 项目，支持全平台或指定 OHOS 平台安装：
# 安装 hcordova 命令化工具
npm install -g hcordova
# 全平台安装
hcordova plugin add cordova-plugin-device-motion
# 指定 OHOS 平台安装
hcordova plugin add cordova-plugin-device-motion --platform ohos2. 安装指定版本
如需兼容特定 Cordova 或平台版本，可指定版本号安装（仅 OHOS 平台）：
# 安装 1.0.0 版本（指定 OHOS 平台）
hcordova plugin add [email protected] --platform ohos3. 从 GitCode 安装（开发版本）
如需测试最新功能或问题修复，可从 GitCode 仓库安装开发分支（仅 OHOS 平台）：
# 仅支持 OHOS 平台
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-device-motion.git --platform ohos
# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-device-motion.git@develop --platform ohos4. 离线安装（本地包）
适用于无网络环境，先下载插件包到本地，再执行离线安装：
# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-device-motion）
# 执行离线安装
hcordova plugin add ../Downloads/cordova-plugin-device-motion --platform ohos5. 安装后验证
安装完成后，可通过以下命令验证插件是否成功添加到项目中：
# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list6. 卸载插件
如需移除插件，执行以下命令，支持全平台卸载或仅卸载 OHOS 平台插件：
# 全平台卸载
hcordova plugin remove cordova-plugin-device-motion
# 指定 OHOS 平台卸载
hcordova plugin remove cordova-plugin-device-motion --platform ohos约束与限制
依赖插件：无强制依赖，插件集成后可直接使用，无需额外配置
权限要求：OHOS 平台需配置加速度传感器权限，否则无法获取运动数据
调用时机：所有 API 需在
deviceready事件触发后调用，避免因原生接口未初始化导致错误替代方案：W3C 已具备相关功能，可无需插件直接使用，但需在 mainPage 中传入 onPermissionRequest 函数完成网页授权
设备限制：部分低端设备可能未配备加速度计、陀螺仪，会导致插件无法正常获取数据
功耗说明：采样频率越高，设备功耗越大，建议根据业务场景选择合适的采样频率
兼容性
支持：
| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |
在以下版本中已测试通过：
| 项目 | 版本/信息 | |-----|--------| | @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) |
平台配置
插件安装后需根据目标平台进行必要配置，确保插件功能正常运行，以下重点说明 OHOS 平台的配置要求（Android、iOS 平台配置参考官方指南）。
OHOS 配置
使用该插件需要配置获取加速度相关权限，需在应用配置文件中添加以下权限配置：
"requestPermissions": [
{
"name" : "ohos.permission.ACCELEROMETER"
}
]权限说明
- ohos.permission.ACCELEROMETER：加速度权限
核心概念
在使用插件前，需理解以下核心概念，确保正确解读运动数据：
1.1 坐标系定义
插件采用设备默认坐标系，各轴方向定义如下：
X 轴：水平方向，从设备左侧指向右侧（设备横向握持时，X 轴与地面平行）
Y 轴：垂直方向，从设备底部指向顶部（与设备屏幕垂直，向上为正方向）
Z 轴：垂直于设备屏幕，从屏幕内侧指向外侧（设备平放时，Z 轴垂直于地面向上）
1.2 数据类型说明
| 数据类型 | 描述 | 单位 | 应用场景 | |---|---|---|---| | 加速度（含重力） | 设备在三轴的总加速度，包含重力加速度（9.8m/s²） | m/s² | 检测设备整体运动状态（如掉落、撞击） | | 加速度（不含重力） | 设备在三轴的实际运动加速度，剔除重力影响 | m/s² | 检测设备主动运动（如摇晃、平移） | | 旋转速率 | 设备绕三轴的旋转角速度 | rad/s | 检测设备旋转状态（如旋转屏幕、晃动手机） |
1.3 采样频率
采样频率指单位时间内获取运动数据的次数，单位为 Hz（次/秒）：
低频率（1-10Hz）：适用于低精度场景（如计步、简单姿态检测），功耗低
中频率（10-50Hz）：适用于中等精度场景（如健身 APP、普通游戏控制）
高频率（50-100Hz）：适用于高精度场景（如 AR/VR、专业运动分析），功耗较高
使用示例
示例 1：持续监听加速度（含重力）
/**
* 持续获取设备加速度数据（含重力加速度）
* @param {Function} successCallback - 成功回调（参数：加速度数据对象）
* @param {Function} errorCallback - 失败回调（参数：错误信息）
* @param {Object} options - 配置选项（可选）
* @returns {Number} watchId - 监听 ID（用于停止监听）
*/
const watchId = navigator.accelerometer.watchAcceleration(
(acceleration) => {
console.log("加速度数据（含重力）：", acceleration);
/*
acceleration 结构示例：
{
x: 0.23, // X 轴加速度（m/s²）
y: 9.78, // Y 轴加速度（含重力，约 9.8m/s²）
z: -0.15, // Z 轴加速度（m/s²）
timestamp: 1699999999999 // 数据采集时间戳（毫秒）
}
*/
},
(error) => {
console.error("获取加速度数据失败：", error);
/*
error 结构示例：
{
code: 1, // 错误码（1=权限不足，2=设备不支持，3=内部错误）
message: "设备不支持加速度传感器" // 错误描述
}
*/
},
{
frequency: 100 // 采样频率（毫秒/次，即 10Hz，默认 1000ms）
}
);
示例 2：单次获取加速度（含重力）
/**
* 单次获取设备加速度数据（含重力）
* @param {Function} successCallback - 成功回调
* @param {Function} errorCallback - 失败回调
*/
navigator.accelerometer.getCurrentAcceleration(
(acceleration) => {
console.log("单次加速度数据（含重力）：", acceleration);
// 业务处理（如单次姿态检测）
if (Math.abs(acceleration.y) < 1) {
console.log("设备当前处于水平放置状态");
}
},
(error) => {
console.error("单次获取加速度失败：", error);
}
);
示例 3：停止加速度监听
/**
* 停止加速度数据监听
* @param {Number} watchId - 监听 ID（从 watchAcceleration 返回）
*/
navigator.accelerometer.clearWatch(watchId);
console.log("已停止加速度数据监听");
使用说明
API 文档
插件通过全局对象 navigator.accelerometer 暴露所有 API，支持回调函数式调用。所有 API 需在 deviceready 事件触发后调用，避免因原生接口未初始化导致的错误。
1.1 加速度数据监听 API
1.1.1 持续监听加速度（含重力）
用于持续获取设备三轴加速度数据（含重力影响），返回监听 ID，可用于后续停止监听。
API 格式：navigator.accelerometer.watchAcceleration(successCallback, errorCallback, options);
successCallback：成功回调函数，参数为加速度数据对象（包含 x、y、z 轴加速度及时间戳）
errorCallback：失败回调函数，参数为错误对象（包含错误码和错误描述）
options：可选配置对象，主要参数为 frequency（采样频率，单位毫秒/次，默认 1000ms）
1.1.2 单次获取加速度（含重力）
用于单次获取设备三轴加速度数据（含重力影响），适用于无需持续监听的场景。
API 格式：navigator.accelerometer.getCurrentAcceleration(successCallback, errorCallback);
successCallback：成功回调函数，参数为加速度数据对象
errorCallback：失败回调函数，参数为错误对象
1.1.3 停止加速度监听
用于停止已开启的加速度数据监听，需传入 watchAcceleration 返回的监听 ID。
API 格式：navigator.accelerometer.clearWatch(watchId);
- watchId：监听 ID，由 watchAcceleration 方法返回
目录结构
cordova-plugin-device-motion/
├── src/ # 源代码目录
│ └── main/ # 主要源代码
│ └── cpp/ # C++ 原生代码
│ └── Device/ # 设备模块
│ ├── AccelListener.cpp # 加速度监听功能的 C++ 实现
│ └── AccelListener.h # 加速度监听功能的头文件
├── www/ # Web 资源目录
│ ├── Acceleration.js # 加速度数据模型定义
│ └── accelerometer.js # JavaScript 加速度计接口（Cordova 桥接层）
├── .gitignore # Git 忽略文件配置
├── LICENSE # 项目开源许可证
├── OAT.xml # OpenHarmony 审核配置文件
├── package.json # Node.js 包配置
├── plugin.xml # Cordova 插件描述文件（核心配置）
└── README.md # 项目说明文档贡献代码
使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。
许可证
本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。