@cordova-ohos/cordova-plugin-device
v3.0.1
Published
Cordova Device Plugin
Readme
cordova-plugin-device
本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。
简介
cordova-plugin-device 是 OpenHarmony Cordova 生态系统中的核心插件，用于获取当前运行应用的设备硬件信息与软件环境数据，为跨平台应用开发提供设备差异化适配能力，兼容 Apache Cordova 的 Android、iOS 等主流移动平台及浏览器环境中使用，本文档只说明在 OpenHarmony 系统中的使用。插件提供全局 device 对象，该对象在 Cordova 设备就绪事件（deviceready）触发后可用，可用于获取设备型号、操作系统版本、唯一标识符等关键信息，解决跨平台设备信息获取差异化的难题。
跨平台兼容：兼容 Android、iOS、OHOS 及浏览器环境，本文档专注说明 OpenHarmony 系统中的使用
全局对象：提供全局
device对象，设备就绪后即可使用，无需额外初始化丰富信息：支持获取设备型号、操作系统、唯一标识、制造商等多种关键设备信息
适配性强：适配 OpenHarmony 系统特性，准确返回符合系统规范的设备信息（如 ODID）
易用便捷：API 简洁，无需深入原生开发，快速实现设备信息获取功能
支持平台
Android：API 19 及以上（Android 4.4+）
iOS：10.0 及以上
OHOS：5.0+（本文档重点说明该平台使用）
Browser：主流桌面及移动浏览器
下载安装
通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库获取，可指定 OHOS 平台安装，安装前确保已创建 Cordova 项目并进入项目根目录。
1. 从 npm 安装（推荐）
通过 npm 安装最新稳定版，自动集成到 Cordova 项目，支持全平台或指定 OHOS 平台安装：
# 安装 hcordova 命令化工具
npm install -g hcordova
# 全平台安装
hcordova plugin add cordova-plugin-device
# 指定 OHOS 平台安装
hcordova plugin add cordova-plugin-device --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.git --platform ohos
# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-device.git@develop --platform ohos4. 离线安装（本地包）
适用于无网络环境，先下载插件包到本地，再执行离线安装：
# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-device）
# 执行离线安装
hcordova plugin add ../Downloads/cordova-plugin-device --platform ohos5. 安装后验证
安装完成后，可通过以下命令验证插件是否成功添加到项目中：
# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list6. 卸载插件
如需移除插件，执行以下命令，支持全平台卸载或仅卸载 OHOS 平台插件：
# 全平台卸载
hcordova plugin remove cordova-plugin-device
# 指定 OHOS 平台卸载
hcordova plugin remove cordova-plugin-device --platform ohos约束与限制
依赖插件：无强制依赖，插件集成后可直接使用，无需额外配置
调用时机：
device对象必须在 Cordova 设备就绪事件（deviceready）触发后使用，未触发前调用会导致device为undefined标识限制：OpenHarmony 系统中，
uuid和serial均返回 ODID（开发者匿名设备标识符），虚拟机中二者固定为emulator123456信息差异：不同 OpenHarmony 版本、不同设备型号返回的设备信息可能存在细微差异，以实际设备返回为准
兼容性
支持：
| 项目 | 版本/信息 | |-----|--------| | 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) |
使用示例
在项目的 www/js/index.js 中添加以下代码，在设备就绪后获取并打印设备信息：
// 等待 Cordova 设备就绪事件
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log("Cordova 设备就绪，开始获取设备信息...");
// 打印所有核心设备属性
console.log("设备型号（model）：", device.model);
console.log("操作系统（platform）：", device.platform);
console.log("设备唯一标识（uuid）：", device.uuid);
console.log("系统版本（version）：", device.version);
console.log("设备制造商（manufacturer）：", device.manufacturer);
console.log("是否为虚拟设备（isVirtual）：", device.isVirtual);
console.log("设备序列号（serial）：", device.serial);
}
使用说明
核心 API：device 对象
device 是全局对象，必须在 deviceready 事件触发后使用（Cordova 插件初始化依赖该事件），未触发前调用会导致 device 为 undefined。通过该对象可获取设备硬件信息与软件环境数据，核心属性如下。
属性列表与说明
| 属性名 | 类型 | 描述 |
|---|---|---|
| device.model | String | 设备型号（认证型号，示例：ALN-AL00） |
| device.platform | String | 设备操作系统名称（系统版本，版本格式 OpenHarmony-x.x.x.x，x 为数值） |
| device.uuid | String | ODID，开发者匿名设备标识符 |
| device.version | String | 操作系统版本（版本 ID：由 deviceType、manufacture、brand、productSeries、osFullName、productModel、softwareModel、sdkApiVersion、incrementalVersion、buildType 拼接组成。示例：wearable/HUAWEI/HUAWEI/TAS/OpenHarmony-5.0.0.1/TAS-AL00/TAS-AL00/12/default/release:nolog） |
| device.manufacturer | String | 设备制造商（Huawei） |
| device.isVirtual | Boolean | 标识设备是否为模拟器 / 虚拟设备（模拟器返回 true，真机返回 false） |
| device.serial | String | ODID，开发者匿名设备标识符 |
常见问题（FAQ）
1. 为什么 uuid 会改变？
- 原因：OHOS 的
uuid普通应用无法获取，因此返回的是 ODID，ODID 可能因设备环境变化而改变。
2. 虚拟机中 uuid 和 serial 为固定值？
- 原因：OHOS 的虚拟机中
uuid和serial返回相同的值：emulator123456，属于正常现象。
目录结构
cordova-plugin-device/
├── src/ # 源代码目录
│ └── main/ # 主要源代码
│ ├── cpp/ # C++ 原生代码
│ │ └── Device/ # 设备模块
│ │ ├── Device.cpp # 设备信息获取功能的 C++ 实现
│ │ └── Device.h # 设备信息获取功能的头文件
│ └── ets/ # ArkTS 代码（OpenHarmony API）
│ └── components/ # 组件目录
│ └── PluginAction/ # 插件动作组件
│ └── GetDeviceInfo.ets # 获取设备信息的 ArkTS 实现
├── www/ # Web 资源目录
│ └── device.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 文件。
官方资源
OHOS 系统设备信息说明：https://docs.openharmony.cn
Android、iOS 插件说明：https://www.npmjs.com/package/cordova-plugin-device