@cordova-ohos/cordova-plugin-device-orientation
v3.0.0
Published
Cordova device-orientation Plugin
Downloads
13
Readme
cordova-plugin-device-orientation
cordova-plugin-device-orientation 是 Cordova 设备方向传感器插件，用于获取移动设备的物理方向与空间姿态数据（如指南针方位、倾斜角度）。基于设备原生传感器（磁力计、加速度计、陀螺仪）开发，支持实时方向监听与精度配置，适用于地图导航、AR/VR、运动姿态检测、设备方位校准等场景。
W3C已具备功能，可以使用W3C功能，无需插件支持该功能，但是需要网页授权，需要在mainPage中传入onPermissionRequest函数授权，onPermissionRequest的使用参考鸿蒙Cordova框架README ArkTs侧示例代码。
1. 插件概述
作为 Cordova 生态中设备姿态感知类的核心插件，cordova-plugin-device-orientation 具备以下核心能力：
多维度方向数据：支持获取磁北方位角、真北方位角、设备倾斜角度（俯仰角、翻滚角）
高精度模式：可启用高精度定位（融合多传感器数据），提升方向检测准确性
实时动态监听：通过事件监听机制实时获取方向变化，支持动态启停与频率配置
跨平台兼容：统一 Android、iOS、Windows、Browser，OHOS 平台 API 调用方式，减少适配成本
校准支持：提供磁力计校准触发接口，解决磁场干扰导致的方向偏差问题
低功耗设计：支持按需开启 / 关闭传感器，平衡精度与设备电量消耗
该插件广泛应用于地图导航 APP、AR 游戏、运动健身设备、智能家居控制等领域，是 Cordova 应用实现设备空间姿态感知的首选方案。
2. 安装方式
2.1 基础安装（推荐）
在 Cordova 项目根目录执行以下命令，插件会自动处理各平台依赖与基础配置：
#安装hcordova
npm install -g hcordova
# 安装最新版本
hcordova plugin add cordova-plugin-device-orientation
# 安装指定版本
hcordova plugin add [email protected] --platform ohos3.4 卸载插件
如需移除插件，执行以下命令即可清理相关配置与依赖：
# 全平台卸载
hcordova plugin remove cordova-plugin-device-orientation
# 指定鸿蒙平台卸载
hcordova plugin remove cordova-plugin-device-orientation --platform ohos4. 核心概念
在使用插件前，需理解以下核心概念，确保正确解读方向与姿态数据：
4.1 方位角定义
插件采用标准地理方位角定义，关键参数说明如下：
磁北方位角（magneticHeading）：设备当前朝向与磁北方向的夹角，范围 0°-360°（0°= 磁北，90°= 磁东，180°= 磁南，270°= 磁西），受地磁场干扰影响
真北方位角（trueHeading）：设备当前朝向与真北方向的夹角，范围 0°-360°，需结合 GPS 定位数据计算（部分设备 / 平台不支持）
偏差角（headingAccuracy）：方位角的误差范围，单位为度（值越小精度越高，通常 <10° 为高精度，>50° 需校准）
4.2 倾斜角度定义
设备在空间中的倾斜状态通过以下两个角度描述：
俯仰角（tiltHeading/pitch）：设备绕 X 轴旋转的角度，范围 -90°-90°（设备水平向前倾斜为正，向后倾斜为负）
翻滚角（roll）：设备绕 Y 轴旋转的角度，范围 -180°-180°（设备水平向右倾斜为正，向左倾斜为负）
4.3 精度等级
根据 headingAccuracy 可将方向检测精度分为三个等级：
高精度：
headingAccuracy < 10°，适用于导航、AR 等场景中精度：
10° ≤ headingAccuracy ≤ 50°，适用于普通方位指示场景低精度：
headingAccuracy > 50°或headingAccuracy === null，需触发传感器校准
5. API 文档
插件通过全局对象 navigator.compass 暴露所有 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.compass.watchHeading(
(heading) => {
console.log("设备方向数据：", heading);
/*
heading 结构示例：
{
magneticHeading: 45.2, // 磁北方位角（度，0°-360°）
trueHeading: 46.5, // 真北方位角（度，0°-360°，不支持时为 null）
headingAccuracy: 8.3, // 方位角精度（度，值越小越精确）
tiltHeading: 5.1, // 俯仰角（度，-90°-90°，部分平台返回 pitch）
roll: -2.3, // 翻滚角（度，-180°-180°，部分平台不支持）
timestamp: 1699999999999 // 数据采集时间戳（毫秒）
}
*/
},
(error) => {
console.error("获取方向数据失败：", error);
/*
error 结构示例：
{
code: 1, // 错误码（1=权限不足，2=设备不支持，3=传感器校准失败，4=内部错误）
message: "设备不支持磁力计，无法获取方向数据" // 错误描述
}
*/
},
{
frequency: 200, // 采样频率（毫秒/次，即 5Hz，默认 1000ms）
enableHighAccuracy: true // 是否启用高精度模式（默认 false，启用后功耗增加）
}
);5.1.2 单次获取方向数据
/**
* 单次获取设备方向数据
* @param {Function} successCallback - 成功回调
* @param {Function} errorCallback - 失败回调
* @param {Object} options - 配置选项（可选）
*/
navigator.compass.getCurrentHeading(
(heading) => {
console.log("单次方向数据：", heading);
// 业务处理（如单次方位校准）
if (heading.headingAccuracy > 50) {
console.log("方向精度过低，建议校准传感器");
triggerCompassCalibration(); // 触发校准
}
},
(error) => {
console.error("单次获取方向数据失败：", error);
},
{ enableHighAccuracy: true }
);5.1.3 停止方向数据监听
/**
* 停止方向数据监听
* @param {Number} watchId - 监听ID（从 watchHeading 返回）
*/
navigator.compass.clearWatch(watchId);
console.log("已停止方向数据监听");OHOS权限配置
在主工程的module.json5中添加权限
{
"name" : "ohos.permission.GYROSCOPE" // 陀螺仪权限
}许可证
本插件基于 MIT License 开源，详见 LICENSE 文件。