{"_id":"@cordova-ohos/cordova-plugin-device-orientation","_rev":"3-0a2ca08ca3c8847ee2ff09c000098721","name":"@cordova-ohos/cordova-plugin-device-orientation","dist-tags":{"latest":"3.0.1"},"versions":{"3.0.0":{"name":"@cordova-ohos/cordova-plugin-device-orientation","version":"3.0.0","keywords":["cordova","device-orientation","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-device-orientation@3.0.0","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-orientation/issues"},"dist":{"shasum":"a1a464b76820e817f424eb32488ec34b3d718aac","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-device-orientation/-/cordova-plugin-device-orientation-3.0.0.tgz","fileCount":10,"integrity":"sha512-yurehac5m3+F7WBKnCRoaDx57O20CQYoBRadT1fhBDjSeSxg+f6lCM/DNnCEvpknErGTbixxbSYsOtJvQmJfxg==","signatures":[{"sig":"MEYCIQDEM4dPsrGKwd/6Vb5293pG+hydTiZvsoMEAm8X1YJUbAIhALzUubEB4WfeZ25hD8IBIRCZVSkNkm75BWneFgAdTVyc","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44575},"cordova":{"id":"cordova-plugin-device-orientation","platforms":["ohos"]},"engines":{"cordovaDependencies":{"3.0.0":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"cd5888ba2d3e6f17d2679f3e1c9fbd5305219c57","_npmUser":{"name":"wanpengsz","email":"wanpengsz@163.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-device-orientation","type":"git"},"_npmVersion":"9.6.2","description":"Cordova device-orientation Plugin","directories":{},"_nodeVersion":"20.16.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-device-orientation_3.0.0_1773990578757_0.977048183112466","host":"s3://npm-registry-packages-npm-production"}},"3.0.1":{"name":"@cordova-ohos/cordova-plugin-device-orientation","version":"3.0.1","description":"Cordova device-orientation Plugin","cordova":{"id":"cordova-plugin-device-orientation","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-device-orientation"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-device-orientation/issues"},"keywords":["cordova","device-orientation","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"3.0.1":{"@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-orientation@3.0.1","gitHead":"a7e81d96842642621c6a91767e2f55879ccf1464","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-f6uYlzZolUKcCCvXKyxhKvLxJkUlFEitncWevIW3rWQq+VPBKzaBAlMyJhfezosMyg/zhiKxBPIA/gZe1+HC/g==","shasum":"426a1391dddece55563422aba409a12f23adce65","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-device-orientation/-/cordova-plugin-device-orientation-3.0.1.tgz","fileCount":11,"unpackedSize":69872,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHqofvumRD2zJmPQID1WYNRO96Zb+by3Vll1o1hfKXziAiEAx8nRrb8XKn8yfnjsb8MjbWhNR+1wM8itT7iZ0/OaZ74="}]},"_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-orientation_3.0.1_1785151350425_0.23035265062664512"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-20T07:09:38.684Z","modified":"2026-07-27T11:22:30.778Z","3.0.0":"2026-03-20T07:09:38.916Z","3.0.1":"2026-07-27T11:22:30.565Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-device-orientation/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","device-orientation","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-device-orientation"},"description":"Cordova device-orientation 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-orientation</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-orientation@3.0.0](https://www.npmjs.com/package/cordova-plugin-device-orientation/v/3.0.0) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-device-orientation](#cordova-plugin-device-orientation)\r\n  - [简介](#简介)\r\n  - [支持平台](#支持平台)\r\n  - [下载安装](#下载安装)\r\n    - [从 npm 安装（推荐）](#从-npm-安装推荐)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证)\r\n    - [卸载](#卸载)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n    - [平台配置](#平台配置)\r\n    - [OHOS 配置](#ohos-配置)\r\n    - [权限说明](#权限说明)\r\n  - [核心概念](#核心概念)\r\n    - [1. 方位角定义](#1-方位角定义)\r\n    - [2. 倾斜角度定义](#2-倾斜角度定义)\r\n    - [3. 精度等级](#3-精度等级)\r\n  - [使用示例](#使用示例)\r\n    - [示例 1：持续监听方向数据](#示例-1持续监听方向数据)\r\n    - [示例 2：单次获取方向数据](#示例-2单次获取方向数据)\r\n    - [示例 3：停止方向数据监听](#示例-3停止方向数据监听)\r\n  - [使用说明](#使用说明)\r\n    - [API 文档](#api-文档)\r\n      - [方向数据监听 API](#方向数据监听-api)\r\n        - [1. 持续监听方向数据](#1-持续监听方向数据)\r\n        - [2. 单次获取方向数据](#2-单次获取方向数据)\r\n        - [3. 停止方向数据监听](#3-停止方向数据监听)\r\n    - [OHOS 权限配置](#ohos-权限配置)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\n`cordova-plugin-device-orientation` 是 Cordova 设备方向传感器插件，用于获取移动设备的物理方向与空间姿态数据（如指南针方位、倾斜角度）。基于设备原生传感器（磁力计、加速度计、陀螺仪）开发，支持实时方向监听与精度配置，适用于地图导航、AR/VR、运动姿态检测、设备方位校准等场景。\r\n\r\n重要说明：W3C 已具备相关功能，可直接使用 W3C 功能无需插件支持，但需进行网页授权，需在 mainPage 中传入 onPermissionRequest 函数授权，onPermissionRequest 的使用参考 OHOS Cordova 框架 README ArkTS 侧示例代码。\r\n\r\n- 多维度方向数据：支持获取磁北方位角、真北方位角、设备倾斜角度（俯仰角、翻滚角）\r\n\r\n- 高精度模式：可启用高精度定位（融合多传感器数据），提升方向检测准确性\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### 从 npm 安装（推荐）\r\n\r\n```bash\r\n# 使用 hcordova CLI 安装\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# 全平台安装最新版本插件\r\nhcordova plugin add cordova-plugin-device-orientation\r\n\r\n# 安装指定版本（示例：1.0.0 版本），仅安装到 OHOS 平台\r\nhcordova plugin add cordova-plugin-device-orientation@1.0.0 --platform ohos\r\n\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-device-orientation）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-plugin-device-orientation  --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\r\n### 卸载\r\n\r\n如需移除插件，执行以下命令即可清理相关配置与依赖：\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-device-orientation\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-device-orientation --platform ohos\r\n\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| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| SystemCapability | SystemCapability.Sensors.Sensor |\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\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      \"name\" : \"ohos.permission.GYROSCOPE\" // 陀螺仪权限\r\n    }\r\n]\r\n```\r\n### 权限说明\r\n\r\n- ohos.permission.GYROSCOPE：陀螺仪权限\r\n  \r\n## 核心概念\r\n\r\n在使用插件前，需理解以下核心概念，确保正确解读方向与姿态数据：\r\n\r\n### 1. 方位角定义\r\n\r\n插件采用标准地理方位角定义，关键参数说明如下：\r\n\r\n- **磁北方位角（magneticHeading）**：设备当前朝向与磁北方向的夹角，范围 0°-360°（0°= 磁北，90°= 磁东，180°= 磁南，270°= 磁西），受地磁场干扰影响\r\n\r\n- **真北方位角（trueHeading）**：设备当前朝向与真北方向的夹角，范围 0°-360°，需结合 GPS 定位数据计算（部分设备/平台不支持）\r\n\r\n- **偏差角（headingAccuracy）**：方位角的误差范围，单位为度（值越小精度越高，通常 <10° 为高精度，>50° 需校准）\r\n\r\n### 2. 倾斜角度定义\r\n\r\n设备在空间中的倾斜状态通过以下两个角度描述：\r\n\r\n- **俯仰角（tiltHeading/pitch）**：设备绕 X 轴旋转的角度，范围 -90°-90°（设备水平向前倾斜为正，向后倾斜为负）\r\n\r\n- **翻滚角（roll）**：设备绕 Y 轴旋转的角度，范围 -180°-180°（设备水平向右倾斜为正，向左倾斜为负）\r\n\r\n### 3. 精度等级\r\n\r\n根据 `headingAccuracy` 可将方向检测精度分为三个等级：\r\n\r\n- **高精度**：`headingAccuracy < 10°`，适用于导航、AR 等场景\r\n\r\n- **中精度**：`10° ≤ headingAccuracy ≤ 50°`，适用于普通方位指示场景\r\n\r\n- **低精度**：`headingAccuracy > 50°` 或 `headingAccuracy === null`，需触发传感器校准\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.compass.watchHeading(\r\n   (heading) => {\r\n       console.log(\"设备方向数据：\", heading);\r\n       /*\r\n       heading 结构示例：\r\n       {\r\n           magneticHeading: 45.2, // 磁北方位角（度，0°-360°）\r\n           trueHeading: 46.5,     // 真北方位角（度，0°-360°，不支持时为 null）\r\n           headingAccuracy: 8.3,  // 方位角精度（度，值越小越精确）\r\n           tiltHeading: 5.1,      // 俯仰角（度，-90°-90°，部分平台返回 pitch）\r\n           roll: -2.3,            // 翻滚角（度，-180°-180°，部分平台不支持）\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=传感器校准失败，4=内部错误）\r\n           message: \"设备不支持磁力计，无法获取方向数据\" // 错误描述\r\n       }\r\n       */\r\n   },\r\n   {\r\n       frequency: 200, // 采样频率（毫秒/次，即 5Hz，默认 1000ms）\r\n       enableHighAccuracy: true // 是否启用高精度模式（默认 false，启用后功耗增加）\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* @param {Object} options - 配置选项（可选）\r\n*/\r\n\r\nnavigator.compass.getCurrentHeading(\r\n   (heading) => {\r\n       console.log(\"单次方向数据：\", heading);\r\n       // 业务处理（如单次方位校准）\r\n       if (heading.headingAccuracy > 50) {\r\n           console.log(\"方向精度过低，建议校准传感器\");\r\n           triggerCompassCalibration(); // 触发校准\r\n       }\r\n   },\r\n   (error) => {\r\n       console.error(\"单次获取方向数据失败：\", error);\r\n   },\r\n   { enableHighAccuracy: true }\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（从 watchHeading 返回）\r\n*/\r\n\r\nnavigator.compass.clearWatch(watchId);\r\nconsole.log(\"已停止方向数据监听\");\r\n\r\n```\r\n\r\n## 使用说明\r\n\r\n### API 文档\r\n\r\n插件通过全局对象 `navigator.compass` 暴露所有 API，支持回调函数式调用。所有 API 需在 `deviceready` 事件触发后调用，避免因原生接口未初始化导致的错误。\r\n\r\n#### 方向数据监听 API\r\n\r\n##### 1. 持续监听方向数据\r\n\r\n用于持续获取设备方向数据（磁北方位角、真北方位角、倾斜角度等），返回监听 ID，可用于后续停止监听。\r\n\r\nAPI 格式：navigator.compass.watchHeading(successCallback, errorCallback, options);\r\n\r\n- successCallback：成功回调函数，参数为方向数据对象（包含磁北方位角、真北方位角、精度、倾斜角度及时间戳）\r\n\r\n- errorCallback：失败回调函数，参数为错误对象（包含错误码和错误描述）\r\n\r\n- options：可选配置对象，主要参数为 frequency（采样频率，单位毫秒/次，默认 1000ms）、enableHighAccuracy（是否启用高精度模式，默认 false）\r\n\r\n##### 2. 单次获取方向数据\r\n\r\n用于单次获取设备方向数据，适用于无需持续监听的场景，支持配置高精度模式。\r\n\r\nAPI 格式：navigator.compass.getCurrentHeading(successCallback, errorCallback, options);\r\n\r\n- successCallback：成功回调函数，参数为方向数据对象\r\n\r\n- errorCallback：失败回调函数，参数为错误对象\r\n\r\n- options：可选配置对象，主要参数为 enableHighAccuracy（是否启用高精度模式，默认 false）\r\n\r\n##### 3. 停止方向数据监听\r\n\r\n用于停止已开启的方向数据监听，需传入 watchHeading 返回的监听 ID。\r\n\r\nAPI 格式：navigator.compass.clearWatch(watchId);\r\n\r\n- watchId：监听 ID，由 watchHeading 方法返回\r\n\r\n### OHOS 权限配置\r\n\r\n在主工程的 module.json5 中增加陀螺仪权限配置，否则无法正常获取方向与姿态数据：\r\n\r\n```json\r\n[\r\n  {\r\n    \"name\" : \"ohos.permission.ACCELEROMETER\"// 加速度权限\r\n  },\r\n  {\r\n  \"name\" : \"ohos.permission.GYROSCOPE\"     // 陀螺仪权限\r\n  }\r\n]\r\n```\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-device-orientation/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       └── cpp/                  # C++ 原生代码\r\n│           └── Device/           # 设备模块\r\n│               ├── CompassListener.cpp  # 方向监听功能的 C++ 实现\r\n│               └── CompassListener.h    # 方向监听功能的头文件\r\n├── www/                          # Web 资源目录\r\n│   ├── compass.js                # JavaScript 方向传感器接口（Cordova 桥接层）\r\n│   ├── CompassError.js           # 方向传感器错误码定义\r\n│   └── CompassHeading.js         # 方向数据模型定义\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-orientation/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-device-orientation/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-orientation](https://gitcode.com/CPF-Cordova/cordova-plugin-device-orientation)\r\n\r\n- Android、iOS 插件说明：[https://www.npmjs.com/package/cordova-plugin-device-orientation](https://www.npmjs.com/package/cordova-plugin-device-orientation)\r\n","readmeFilename":"README.md"}