@ionic-native/device

本项目基于 @ionic-native/[email protected] 开发。

简介

@ionic-native/device 是 OpenHarmony Cordova 生态系统中的核心插件，用于获取当前运行应用的设备硬件信息与软件环境数据，为跨平台应用开发提供设备差异化适配能力。兼容 Android、iOS 和 OpenHarmony 平台，为跨平台应用开发提供统一的设备信息获取能力。本文档主要说明在 OpenHarmony 系统中的应用。

@ionic-native/device 提供全局 device 对象，该对象在 Cordova 设备就绪事件（deviceready）触发后可用，可用于获取设备型号、操作系统版本、唯一标识符等关键信息。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从 npm 仓库获取。

命令行安装（推荐）

安装 hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm 安装：

# 安装插件
npm install @ionic-native/device

# 同步插件
hionic sync

hionic CLI 安装：

hionic plugin add @ionic-native/device

手动引入安装

1.添加插件配置

根据 plugin.xml 的 config-json 项，找到 entry 模块中 config.xml 文件，并根据 param 标签添加配置

<feature name="Device">
  <param name="harmony-package" value="Device" />
  <param name="onload" value="true" />
</feature>

2.修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，找到 cordova 模块，路径为 target 字段的文件 CMakeLists.txt，添加 add_library

add_library(cordova SHARED
  // ...
  Device/Device.cpp
  // ...
)

3.复制源码文件

根据 plugin.xml 的 source-file 项，将 src 字段的路径代码复制到 cordova 模块中 target-dir 字段的目录中：

将源码中 src/main/cpp/Device 目录下的 Device.h、Device.cpp 文件引入到 cordova 模块中 src/main/cpp/Device 目录下。

将源码中 src/main/ets/components/Device 目录下的 Device.ets 文件引入到 cordova 模块中 src/main/ets/components/Device 目录下。

4.添加 ArkTS 配置

在 cordova 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入步骤 3 中拷贝的 ets 文件路径:

"buildOption":{
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/Device/Device.ets"
        // ...
      ]
    }
  }
}

卸载

# hionic CLI 卸载
hionic plugin remove @ionic-native/device

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

不涉及

使用示例

示例1：获取设备信息

实现获取设备型号、操作系统、唯一标识符、系统版本、制造商、是否为虚拟设备、序列号、Cordova 版本和设备信息可用状态的功能。

// 等待 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);
  console.log("Cordova 版本（cordova）：", device.cordova);
  console.log("设备信息是否可用（available）：", device.available);
}

使用说明

插件在全局对象 device 下暴露所有功能接口，使用前需确保设备就绪事件（deviceready）已触发。

属性列表与说明

| 属性名 | 类型 | 描述 | |-------|------|------| | device.model | String | 设备型号 | | device.platform | String | 设备操作系统名称 | | device.uuid | String | ODID | | device.version | String | 操作系统版本 | | device.manufacturer | String | 设备制造商 | | device.isVirtual | Boolean | 标识设备是否为模拟器/虚拟设备（模拟器返回 true，真机返回 false） | | device.serial | String | ODID | | device.cordova | String | Cordova 版本信息 | | device.available | Boolean | 设备信息是否可用 |

1. 设备型号

返回设备的型号名称。

属性签名

device.model

2. 操作系统

返回设备的操作系统名称。

属性签名

device.platform

3. 设备唯一标识

返回设备的唯一标识符（ODID）。

属性签名

device.uuid

4. 操作系统版本

返回设备的操作系统版本号。

属性签名

device.version

5. 设备制造商

返回设备的制造商名称。

属性签名

device.manufacturer

6. 是否为虚拟设备

返回设备是否为模拟器或虚拟设备。

属性签名

device.isVirtual

7. 设备序列号

返回设备的序列号（ODID）。

属性签名

device.serial

8. Cordova 版本

返回 Cordova 的版本信息。

属性签名

device.cordova

9. 设备信息是否可用

返回设备信息是否可用。

属性签名

device.available

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |---- cpp  # C++ 代码
|           |---- ets  # ArkTS 代码
|     |---- www    # Web 侧代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。