@cordova-ohos/cordova-plugin-device-motion
v2.0.1
Published
Cordova device-motion Plugin
Readme
cordova-plugin-device-motion
cordova-plugin-device-motion 是 Cordova 设备运动传感器插件，用于获取移动设备的加速度、旋转速率等运动数据。基于设备原生传感器（如加速度计、陀螺仪）开发，支持实时数据监听与采样频率配置，适用于运动类应用（如计步器、健身 APP）、游戏控制（如重力感应游戏）、设备姿态检测等场景。
W3C已具备功能，可以使用W3C功能，无需插件支持该功能，但是需要网页授权，需要在mainPage中传入onPermissionRequest函数授权，onPermissionRequest的使用参考鸿蒙Cordova框架README ArkTs侧示例代码。
1. 插件概述
作为 Cordova 生态中设备传感器类的核心插件，cordova-plugin-device-motion 具备以下核心能力：
多维度数据采集：支持获取设备在 X/Y/Z 三轴的加速度（含重力 / 不含重力）、旋转速率数据
灵活配置：可自定义数据采样频率（如 10Hz、50Hz），平衡数据精度与设备功耗
实时监听：通过事件监听机制实时获取运动数据，支持动态开启 / 关闭监听
跨平台兼容：统一 Android、iOS、Windows、Browser 、OHOS平台 API 调用方式，减少适配成本
低功耗设计：支持按需开启 / 关闭传感器，降低设备电量消耗
原生性能：基于设备硬件传感器开发，数据响应延迟低，采样精度高
该插件广泛应用于健康运动、游戏娱乐、AR/VR、设备姿态控制等领域，是 Cordova 应用获取设备运动状态的首选方案。
2. 安装方式
2.1 基础安装（推荐）
在 Cordova 项目根目录执行以下命令，插件会自动处理各平台依赖与基础配置：
# 安装hcordova
npm install -g hcordova
# 安装最新版本
hcordova plugin add cordova-plugin-device-motion
# 安装指定版本
hcordova plugin add [email protected] --platform ohos3.4 卸载插件
如需移除插件，执行以下命令即可清理相关配置与依赖：
# 全平台卸载
hcordova plugin remove cordova-plugin-device-motion
# 指定OHOS卸载
hcordova plugin remove cordova-plugin-device-motion --platform ohos4. 核心概念
在使用插件前，需理解以下核心概念，确保正确解读运动数据：
4.1 坐标系定义
插件采用设备默认坐标系，各轴方向定义如下：
X 轴：水平方向，从设备左侧指向右侧（设备横向握持时，X 轴与地面平行）
Y 轴：垂直方向，从设备底部指向顶部（与设备屏幕垂直，向上为正方向）
Z 轴：垂直于设备屏幕，从屏幕内侧指向外侧（设备平放时，Z 轴垂直于地面向上）
4.2 数据类型说明
| 数据类型 | 描述 | 单位 | 应用场景 | | --------- | --------------------------- | ----- | -------------------- | | 加速度（含重力） | 设备在三轴的总加速度，包含重力加速度（9.8m/s²） | m/s² | 检测设备整体运动状态（如掉落、撞击） | | 加速度（不含重力） | 设备在三轴的实际运动加速度，剔除重力影响 | m/s² | 检测设备主动运动（如摇晃、平移） | | 旋转速率 | 设备绕三轴的旋转角速度 | rad/s | 检测设备旋转状态（如旋转屏幕、晃动手机） |
4.3 采样频率
采样频率指单位时间内获取运动数据的次数，单位为 Hz（次 / 秒）：
- 低频率（1-10Hz）：适用于低精度场景（如计步、简单姿态检测），功耗低
- 中频率（10-50Hz）：适用于中等精度场景（如健身 APP、普通游戏控制）
- 高频率（50-100Hz）：适用于高精度场景（如 AR/VR、专业运动分析），功耗较高
5. API 文档
插件通过全局对象 navigator.accelerometer 暴露所有 API，支持回调函数式调用。所有 API 需在 deviceready 事件触发后调用，避免因原生接口未初始化导致的错误。
5.1 加速度数据监听 API
5.1.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）
}
);5.1.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);
}
);5.1.3 停止加速度监听
/**
* 停止加速度数据监听
* @param {Number} watchId - 监听ID（从 watchAcceleration 返回
*/
navigator.accelerometer.clearWatch(watchId);
console.log("已停止加速度数据监听");OHOS权限配置
在主工程的module.json5中增加加速度传感器
{
"name" : "ohos.permission.ACCELEROMETER" // 加速度权限
}许可证
本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。