@capacitor/device

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/device是capacitor生态系统中的核心插件，用于获取当前运行应用的设备硬件信息与软件环境数据，为跨平台应用开发提供设备差异化适配能力，兼容capacitor的Android、iOS 等主流移动平台及浏览器环境中使用，本文档说明在OpenHarmony系统中的使用。

设备API会公开设备的内部信息，例如型号和操作系统版本，以及用户相关信息（如唯一标识符）。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @capacitor/device

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/device

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/device",
  "classpath": "Device"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Device)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Device
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

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

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

4. 添加 ArkTS 配置

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

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

卸载

# 卸载 device 插件
hionic plugin remove @capacitor/device

约束与限制

兼容性

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

1. capacitor: 8.0.0-ohos-8.0.0;SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

无需额外申请权限。

使用示例

示例1：基础示例

获取设备、电池、语言代码、语言标签信息并打印。

import { Device } from '@capacitor/device';

const getId = async () => {
  const info = await Device.getId();
  console.log(info);
};

const getInfo = async () => {
  const info = await Device.getInfo();
  console.log(info);
};

const getBatteryInfo = async () => {
  const info = await Device.getBatteryInfo();
  console.log(info);
};

const getLanguageCode = async () => {
  const info = await Device.getLanguageCode();
  console.log(info);
};

const getLanguageTag = async () => {
  const info = await Device.getLanguageTag();
  console.log(info);
};

使用说明

引入@capacitor/device插件的device模块使用，所有API均基于Promise实现，支持异步调用。

1. 获取设备唯一标识符（getId）

用于获取设备唯一标识，OpenHarmony平台返回ODID。

方法签名

getId(): Promise<DeviceId>

返回值说明

DeviceId

| 属性名 | 类型 | 说明 | |------------|--------|---------| | identifier | string | 设备唯一标识符 |

2. 获取设备基本信息（getInfo）

用于获取设备的基础软硬件信息，包括设备名称、型号、系统版本、制造商等数据。

方法签名

getInfo(): Promise<DeviceInfo>

返回值说明

DeviceInfo

| 属性名 | 类型 | 说明 | |-------------------|---------|-------------------------------------| | name | string | 设备名称 | | model | string | 设备型号 | | platform | string | 设备平台 | | operatingSystem | string | 设备的操作系统 | | osVersion | string | 操作系统版本 | | iOSVersion | number | 仅跨平台兼容，OpenHarmony平台不涉及 | | androidSDKVersion | number | 仅跨平台兼容，OpenHarmony平台不涉及 | | manufacturer | string | 设备制造商 | | isVirtual | boolean | 标识设备是否为模拟器/虚拟设备，模拟器返回true，真机返回false | | memUsed | number | 当前应用使用的内存大小，单位为字节 | | webViewVersion | string | webView浏览器版本，API20及以上版本支持获取 |

3. 获取电池信息（getBatteryInfo）

用于获取设备当前的电池电量和充电状态。

方法签名

getBatteryInfo(): Promise<BatteryInfo>

返回值说明

BatteryInfo

| 属性名 | 类型 | 说明 | |--------------|---------|------------------------| | batteryLevel | number | 电池电量百分比，取值范围0到1之间，可选返回 | | isCharging | boolean | 电池是否正在充电 |

4. 获取设备语言代码（getLanguageCode）

用于获取设备当前的语言代码，例如zh、en等。

方法签名

getLanguageCode(): Promise<GetLanguageCodeResult>

返回值说明

GetLanguageCodeResult

| 属性名 | 类型 | 说明 | |-------|--------|--------| | value | string | 设备语言代码 |

5. 获取设备语言标签（getLanguageTag）

用于获取设备当前的语言标签，例如zh-Hans、zh-Hans-CN等。

方法签名

getLanguageTag(): Promise<LanguageTag>

返回值说明

LanguageTag

| 属性名 | 类型 | 说明 | |-------|--------|--------| | value | string | 设备语言标签 |

目录结构

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

贡献代码

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

许可证

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