开源鸿蒙 Cordova 设备信息插件开发详解

项目背景与概述

什么是 Cordova 插件？

Apache Cordova 是一个开源的移动应用开发框架，允许开发者使用 HTML、CSS 和 JavaScript 构建跨平台移动应用。Cordova 通过插件机制提供了访问设备原生功能的能力，使 Web 应用能够调用系统 API。

为什么需要设备信息插件？

在移动应用开发中，获取设备信息是一个常见需求，包括：

设备型号：用于适配不同屏幕尺寸和硬件特性
操作系统版本：用于判断系统功能可用性
设备唯一标识：用于用户识别和数据分析
制造商信息：用于品牌特定的功能适配
虚拟设备检测：用于区分真机和模拟器

cordova-plugin-device 正是为了满足这些需求而开发的核心插件。

HarmonyOS 平台的挑战

HarmonyOS 作为华为推出的分布式操作系统，其架构与 Android/iOS 存在显著差异：

使用 ArkTS（基于 TypeScript）作为主要开发语言
采用全新的 API 体系（如 @kit.BasicServicesKit）
需要适配 OpenHarmony 的底层实现

因此，需要为 HarmonyOS 平台重新实现设备信息插件，而不能直接复用 Android/iOS 的代码。

技术架构设计

三层架构模型

本插件采用了经典的三层架构设计：

复制代码

┌─────────────────────────────────────┐
│   JavaScript API 层 (device.js)    │  ← Web 应用调用接口
├─────────────────────────────────────┤
│   C++ 桥接层 (Device.cpp/h)         │  ← 桥接 JavaScript 和原生代码
├─────────────────────────────────────┤
│   ArkTS 原生层 (GetDeviceInfo.ets)  │  ← 调用 HarmonyOS 系统 API
└─────────────────────────────────────┘

各层职责说明

JavaScript API 层
- 提供统一的 device 全局对象
- 处理 Cordova 生命周期事件
- 封装异步调用逻辑
C++ 桥接层
- 实现 Cordova 插件接口规范
- 处理 JSON 数据序列化/反序列化
- 管理回调上下文和异步通信
ArkTS 原生层
- 调用 HarmonyOS 系统 API 获取设备信息
- 处理数据持久化（如字体缩放设置）
- 返回结构化数据给 C++ 层

开发环境准备

必需工具

HCordova CLI
bash 复制代码
```
npm install -g hcordova
```
HarmonyOS 开发工具
- DevEco Studio（HarmonyOS IDE）
- HarmonyOS SDK
依赖要求
- cordova-openharmony >= 2.0.0
- hcordova >= 1.0.0

项目结构

复制代码

cordova-plugin-device/
├── plugin.xml              # Cordova 插件配置文件
├── package.json            # NPM 包配置
├── www/
│   └── device.js          # JavaScript API 实现
└── src/
    └── main/
        ├── cpp/
        │   └── Device/
        │       ├── Device.h      # C++ 头文件
        │       └── Device.cpp    # C++ 实现文件
        └── ets/
            └── components/
                └── PluginAction/
                    └── GetDeviceInfo.ets  # ArkTS 原生实现

插件配置文件详解

plugin.xml 核心配置

plugin.xml 是 Cordova 插件的核心配置文件，定义了插件的元数据和平台特定配置：

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
        id="cordova-plugin-device"
        version="1.0.0">
    <name>device</name>
    <description>Cordova device Plugin</description>
    <license>Apache 2.0</license>
    
    <engines>
        <engine name="cordova-openharmony" version=">=2.0.0" />
    </engines>

    <platform name="ohos">
        <!-- 1. 注册插件功能 -->
        <config-file target="src/main/resources/rawfile/config.xml" 
                     parent="/*" 
                     modules-targets-name="default">
            <feature name="Device">
                <param name="harmony-package" value="Device" />
            </feature>
        </config-file>

        <!-- 2. 配置 CMake 构建 -->
        <CMakeLists target="src/main/cpp/CMakeLists.txt" 
                    modules-name="cordova">
            <param target="add_library" value="Device/Device.cpp"/>
        </CMakeLists>

        <!-- 3. 注册 C++ 源文件 -->
        <source-file type="h" 
                     src="src/main/cpp/Device/Device.h" 
                     target-dir="src/main/cpp/Device" 
                     modules-name="cordova"/>
        <source-file type="cpp" 
                     src="src/main/cpp/Device/Device.cpp" 
                     target-dir="src/main/cpp/Device" 
                     modules-name="cordova"/>
        
        <!-- 4. 注册 ArkTS 源文件 -->
        <source-file type="ets" 
                     src="src/main/ets/components/PluginAction/GetDeviceInfo.ets" 
                     target-dir="src/main/ets/components/PluginAction" 
                     modules-name="cordova" 
                     runtimeOnly="true"/>
        
        <!-- 5. 注册 JavaScript 模块 -->
        <js-module src="www/device.js" 
                   name="device"  
                   modules-targets-name="default">
            <clobbers target="device" />
        </js-module>
    </platform>
</plugin>

配置项解析

<config-file>：在应用配置文件中注册插件功能，使 Cordova 框架能够识别并加载插件
<CMakeLists>：配置 C++ 代码的编译规则，将 Device.cpp 添加到构建系统
<source-file>：声明需要复制到目标项目的源文件
<js-module> ：注册 JavaScript 模块，clobbers 属性表示将模块导出为全局 device 对象

JavaScript API 层实现

核心代码分析

让我们深入分析 www/device.js 的实现：

javascript 复制代码

var argscheck = require('cordova/argscheck');
var channel = require('cordova/channel');
var utils = require('cordova/utils');
var exec = require('cordova/exec');
var cordova = require('cordova');

// 创建并等待设备信息就绪事件
channel.createSticky('onCordovaInfoReady');
channel.waitForInitialization('onCordovaInfoReady');

Device 构造函数

javascript 复制代码

function Device () {
    // 初始化所有设备属性
    this.available = false;
    this.platform = null;
    this.version = null;
    this.uuid = null;
    this.cordova = null;
    this.model = null;
    this.manufacturer = null;
    this.isVirtual = null;
    this.serial = null;

    var me = this;

    // 监听 Cordova 就绪事件
    channel.onCordovaReady.subscribe(function () {
        me.getInfo(function (info) {
            // 填充设备信息
            me.available = true;
            me.platform = info.platform;
            me.version = info.version;
            me.uuid = info.uuid;
            me.cordova = cordova.version;  // 使用 Cordova 框架版本
            me.model = info.model;
            me.isVirtual = info.isVirtual;
            me.manufacturer = info.manufacturer || 'unknown';
            me.serial = info.serial || 'unknown';
            
            // 触发设备信息就绪事件
            channel.onCordovaInfoReady.fire();
        }, function (e) {
            me.available = false;
            utils.alert('[ERROR] Error initializing Cordova: ' + e);
        });
    });
}

关键设计模式

事件驱动架构
- 使用 Cordova 的 channel 机制管理异步初始化
- createSticky 创建持久化事件，确保后续订阅者也能收到事件
- waitForInitialization 确保依赖项在初始化完成前不会执行

异步调用封装

javascript 复制代码

Device.prototype.getInfo = function (successCallback, errorCallback) {
    argscheck.checkArgs('fF', 'Device.getInfo', arguments);
    exec(successCallback, errorCallback, 'Device', 'getDeviceInfo', []);
};

exec 是 Cordova 提供的桥接函数，用于调用原生代码
参数：(成功回调, 失败回调, 插件类名, 方法名, 参数数组)

单例模式
javascript 复制代码
```
module.exports = new Device();
```
- 导出单例实例，确保全局只有一个 device 对象

C++ 桥接层实现

类结构设计

Device.h 定义了插件类的接口：

cpp 复制代码

class Device : public CordovaPlugin{
    // 设备信息成员变量
    string m_strUuid;
    string m_strVersion;
    string m_strPlatform;
    string m_strModel;
    string m_strManufacturer;
    string m_strSerial;
    string m_strSdkVersion;
    
    // 回调上下文
    CallbackContext m_cbc;
    CallbackContext m_cbc2;
    
public:
    Device(){
        m_strPlatform = "HarmonyOS";
        m_strManufacturer = "Huawei";
    }
    
    // 核心方法
    bool execute(const string& action, cJSON* args, CallbackContext cbc) override;
    void initialize(CallbackContext cbc);
    bool onArKTsResult(cJSON* args);
    void sendResult();
};

插件注册机制

cpp 复制代码

#include "Device.h"
REGISTER_PLUGIN_CLASS(Device)

REGISTER_PLUGIN_CLASS 是一个宏，用于将插件类注册到 Cordova 插件系统中，使得 JavaScript 层可以通过类名找到对应的 C++ 实现。

execute 方法 - 命令分发中心

cpp 复制代码

bool Device::execute(const string& action, cJSON* args, CallbackContext cbc)
{
    if(action == "getDeviceInfo") {
        m_cbc = cbc;
        if(m_strModel == "") {
            // 首次调用，需要初始化
            initialize(cbc);
            return true;
        }
        // 已初始化，直接返回缓存结果
        sendResult();
    }
    
    if(action == "onArKTsResult") {
        // 处理 ArkTS 层的回调结果
        return onArKTsResult(args);
    }
    
    // ... 其他功能（字体缩放等）
    return true;
}

设计亮点：

命令模式 ：通过 action 字符串分发不同的操作
缓存机制：首次调用后缓存设备信息，后续调用直接返回，提高性能
异步处理：保存回调上下文，等待 ArkTS 层返回结果后再调用

initialize 方法 - 初始化流程

cpp 复制代码

void Device::initialize(CallbackContext cbc)
{
    executeArkTs("./PluginAction/GetDeviceInfo/GetDeviceInfo", 0, "", "Device", cbc);
    return;
}

executeArkTs 是框架提供的函数，用于调用 ArkTS 层的代码：

第一个参数：ArkTS 模块路径和函数名
第二个参数：参数数量
第三个参数：参数字符串
第四个参数：插件类名（用于回调识别）
第五个参数：回调上下文

onArKTsResult 方法 - 处理 ArkTS 回调

cpp 复制代码

bool Device::onArKTsResult(cJSON* args)
{
    string content = cJSON_GetObjectItem(args, "content")->valuestring;
    cJSON* json = cJSON_GetObjectItem(args, "result");
    
    if(json != NULL && json->type == cJSON_Array) {
        int count = cJSON_GetArraySize(json);
        for(int i=0; i<count; i++) {
            switch(i) {
            case 0: m_strUuid = cJSON_GetArrayItem(json,i)->valuestring; break;
            case 1: m_strVersion = cJSON_GetArrayItem(json,i)->valuestring; break;
            case 2: m_strPlatform = cJSON_GetArrayItem(json,i)->valuestring; break;
            case 3: m_strSdkVersion = cJSON_GetArrayItem(json,i)->valuestring; break;
            case 4: m_strSerial = cJSON_GetArrayItem(json,i)->valuestring; break;
            case 5: m_strModel = cJSON_GetArrayItem(json,i)->valuestring; break;    
            }
        }
    }
    
    // 如果有待处理的回调，发送结果
    if(m_cbc.getQueue() != NULL) {
        sendResult();
    }
    return true;
}

关键点：

使用 cJSON 库解析 JSON 数据
按数组索引顺序解析设备信息
检查回调队列，如果有等待的回调则立即返回结果

sendResult 方法 - 构建并返回结果

cpp 复制代码

void Device::sendResult()
{
    cJSON* json = cJSON_CreateObject();
    cJSON_AddStringToObject(json, "version", m_strVersion.c_str());
    cJSON_AddStringToObject(json, "platform", m_strPlatform.c_str());
    cJSON_AddStringToObject(json, "model", m_strModel.c_str());
    cJSON_AddStringToObject(json, "manufacturer", m_strManufacturer.c_str());
    
    // 特殊处理：模拟器检测
    if(m_strModel == "emulator") {
        cJSON_AddStringToObject(json, "uuid", "emulator123456");
        cJSON_AddTrueToObject(json, "isVirtual");
        cJSON_AddStringToObject(json, "serial", "emulator123456");
    } else {
        cJSON_AddStringToObject(json, "uuid", m_strUuid.c_str());
        cJSON_AddFalseToObject(json, "isVirtual");
        cJSON_AddStringToObject(json, "serial", m_strSerial.c_str());
    }
    
    cJSON_AddStringToObject(json, "sdkVersion", m_strSdkVersion.c_str());
    m_cbc.success(json);  // 调用成功回调
    cJSON_Delete(json);   // 释放内存
}

重要细节：

模拟器检测：通过检查 model 是否为 "emulator" 来判断是否为虚拟设备
内存管理：使用 cJSON_Delete 释放 JSON 对象，避免内存泄漏
回调机制：通过 CallbackContext.success() 将结果返回给 JavaScript 层

ArkTS 原生层实现

导入依赖

typescript 复制代码

import { ArkTsAttribute, cordovaWebTagToObjectGlobe, NativeAttribute } from "../PluginGlobal";
import { deviceInfo } from "@kit.BasicServicesKit";
import cordova from 'libcordova.so';
import { common } from "@kit.AbilityKit";
import { preferences } from "@kit.ArkData";
import { MainPage } from "../MainPage";

关键依赖说明：

@kit.BasicServicesKit：HarmonyOS 基础服务套件，提供设备信息 API
libcordova.so：Cordova 原生库，提供与 C++ 层的通信接口
@kit.ArkData：数据持久化套件，用于存储用户设置

GetDeviceInfo 函数 - 核心实现

typescript 复制代码

export function GetDeviceInfo(pageIndex:NativeAttribute):void {
  let deviceArray:Array<string> = new Array();
  
  // 按顺序收集设备信息
  deviceArray.push(deviceInfo.ODID);           // [0] UUID/序列号
  deviceArray.push(deviceInfo.versionId);       // [1] 版本 ID
  deviceArray.push(deviceInfo.osFullName);      // [2] 操作系统全名
  deviceArray.push(deviceInfo.sdkApiVersion+""); // [3] SDK 版本
  deviceArray.push(deviceInfo.ODID);           // [4] 序列号（复用 ODID）
  deviceArray.push(deviceInfo.productModel);    // [5] 产品型号
  
  // 构建结果对象
  let result: ArkTsAttribute = {
    content:"", 
    result:deviceArray
  };
  
  // 通过 Cordova 桥接返回结果给 C++ 层
  cordova.onArkTsResult(
    JSON.stringify(result), 
    pageIndex.pageObject, 
    pageIndex.pageWebTag
  );
}

HarmonyOS API 详解

deviceInfo.ODID
- ODID（Open Device Identifier）是 HarmonyOS 提供的开发者匿名设备标识符
- 用于替代传统的设备 UUID，保护用户隐私
- 普通应用无法获取真实的设备 UUID，因此使用 ODID
deviceInfo.versionId
- 完整的版本标识符，格式为：
  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
deviceInfo.osFullName
- 操作系统全名，格式：OpenHarmony-x.x.x.x
- 用于标识系统版本
deviceInfo.productModel
- 产品型号，如：TAS-AL00
- 用于设备识别和适配

数据流转机制

typescript 复制代码

cordova.onArkTsResult(JSON.stringify(result), pageIndex.pageObject, pageIndex.pageWebTag);

这个调用会：

将结果序列化为 JSON 字符串
通过 JNI/FFI 桥接传递给 C++ 层
C++ 层的 onArKTsResult 方法被调用
解析 JSON 并更新成员变量
通过回调上下文返回给 JavaScript 层

额外功能：字体缩放

插件还实现了字体缩放功能，展示了如何处理用户设置：

typescript 复制代码

// 设置字体大小
export function SetScaleFont(pageIndex:NativeAttribute) {
  // 获取页面对象
  let mainPage = cordovaWebTagToObjectGlobe.get(pageIndex.pageWebTag) as MainPage;
  let fontScale:number = Number(pageIndex.pageArgs);
  
  // 应用字体缩放
  mainPage.textZoomRatio = 100 * fontScale;
  
  // 持久化存储
  const context: common.UIAbilityContext = getContext() as common.UIAbilityContext;
  let options: preferences.Options = { name: 'cordovaStore' };
  let dataPreferences: preferences.Preferences = 
    preferences.getPreferencesSync(context, options);
  dataPreferences.putSync('scaleFont', pageIndex.pageArgs);
  dataPreferences.flush();
  
  // 返回结果
  let result: ArkTsAttribute = {content:"setScaleFont", result:[]};
  cordova.onArkTsResult(JSON.stringify(result), pageIndex.pageObject, pageIndex.pageWebTag);
}

// 获取字体大小
export function GetScaleFont(pageIndex:NativeAttribute) {
  const context: common.UIAbilityContext = getContext() as common.UIAbilityContext;
  let options: preferences.Options = { name: 'cordovaStore'};
  let dataPreferences: preferences.Preferences = 
    preferences.getPreferencesSync(context, options);
  let fontScale:string = dataPreferences.getSync('scaleFont', '1').toString();
  
  let result: ArkTsAttribute = {content:"getScaleFont", result:[fontScale]};
  cordova.onArkTsResult(JSON.stringify(result), pageIndex.pageObject, pageIndex.pageWebTag);
}

技术要点：

使用 preferences API 进行数据持久化
通过 textZoomRatio 属性控制 WebView 的字体缩放
使用 cordovaWebTagToObjectGlobe 全局映射表管理页面对象

数据流转过程

完整调用链

让我们追踪一次完整的 device.getInfo() 调用：

复制代码

1. JavaScript 层
   ↓
   document.addEventListener("deviceready", ...)
   ↓
   device.getInfo(successCallback, errorCallback)
   ↓
   exec('Device', 'getDeviceInfo', [])

2. C++ 桥接层
   ↓
   Device::execute("getDeviceInfo", args, cbc)
   ↓
   Device::initialize(cbc)
   ↓
   executeArkTs("./PluginAction/GetDeviceInfo/GetDeviceInfo", ...)

3. ArkTS 原生层
   ↓
   GetDeviceInfo(pageIndex)
   ↓
   deviceInfo.ODID, deviceInfo.versionId, ...
   ↓
   cordova.onArkTsResult(JSON.stringify(result), ...)

4. 回调到 C++ 层
   ↓
   Device::onArKTsResult(args)
   ↓
   解析 JSON，更新成员变量
   ↓
   Device::sendResult()
   ↓
   m_cbc.success(json)

5. 返回到 JavaScript 层
   ↓
   successCallback(info)
   ↓
   更新 device 对象的属性
   ↓
   channel.onCordovaInfoReady.fire()

时序图

复制代码

JavaScript          C++ Bridge          ArkTS Native
    |                    |                    |
    |--getDeviceInfo()-->|                    |
    |                    |--executeArkTs()--->|
    |                    |                    |--GetDeviceInfo()
    |                    |                    |--deviceInfo.ODID
    |                    |                    |--deviceInfo.versionId
    |                    |<--onArkTsResult()--|
    |                    |--parse JSON-------->|
    |                    |--sendResult()------>|
    |<--success(info)----|                    |
    |--update properties-|                    |
    |--fire event--------|                    |

关键技术要点

1. 异步通信机制

问题：JavaScript 是单线程异步模型，而原生代码调用是同步的，如何协调？

解决方案：

使用回调函数处理异步结果
C++ 层保存 CallbackContext，等待 ArkTS 层返回后再调用
JavaScript 层使用 Promise-like 的回调模式

2. 数据序列化

问题：不同语言层之间如何传递复杂数据结构？

解决方案：

统一使用 JSON 格式进行数据交换
C++ 层使用 cJSON 库解析和构建 JSON
ArkTS 层使用 JSON.stringify() 和 JSON.parse()

3. 内存管理

问题：C++ 需要手动管理内存，如何避免泄漏？

解决方案：

使用 cJSON_Delete() 释放 JSON 对象
字符串使用 std::string 自动管理内存
回调上下文由框架管理生命周期

4. 插件注册机制

问题：如何让 Cordova 框架找到并加载插件？

解决方案：

使用 REGISTER_PLUGIN_CLASS 宏注册插件类
在 plugin.xml 中声明插件功能
通过类名字符串匹配（"Device"）找到对应实现

5. 模拟器检测

问题：如何区分真机和模拟器？

解决方案：

cpp 复制代码

if(m_strModel == "emulator") {
    cJSON_AddStringToObject(json, "uuid", "emulator123456");
    cJSON_AddTrueToObject(json, "isVirtual");
    cJSON_AddStringToObject(json, "serial", "emulator123456");
}

HarmonyOS 模拟器的 productModel 返回 "emulator"，通过检测这个值来判断。

6. 隐私保护

问题：如何获取设备标识符而不侵犯用户隐私？

解决方案：

使用 HarmonyOS 提供的 ODID（Open Device Identifier）
ODID 是匿名标识符，无法追溯到具体用户
符合 GDPR 等隐私法规要求

开发流程总结

步骤 1：项目初始化

bash 复制代码

# 创建插件目录结构
mkdir cordova-plugin-device
cd cordova-plugin-device

# 初始化 NPM 包
npm init

# 创建目录结构
mkdir -p www
mkdir -p src/main/cpp/Device
mkdir -p src/main/ets/components/PluginAction

步骤 2：编写 plugin.xml

定义插件元数据、平台配置、源文件注册等。

步骤 3：实现 JavaScript API 层

创建 www/device.js
实现 Device 构造函数
实现 getInfo 方法
处理 Cordova 生命周期事件

步骤 4：实现 C++ 桥接层

创建 Device.h 定义类接口
创建 Device.cpp 实现核心逻辑
实现 execute 方法处理命令分发
实现 onArKTsResult 处理回调
实现 sendResult 构建返回数据

步骤 5：实现 ArkTS 原生层

创建 GetDeviceInfo.ets
导入 HarmonyOS API
实现 GetDeviceInfo 函数
调用 deviceInfo API 获取信息
通过 cordova.onArkTsResult 返回结果

步骤 6：测试与调试

javascript 复制代码

// 在测试应用中
document.addEventListener("deviceready", function() {
    console.log("设备型号:", device.model);
    console.log("操作系统:", device.platform);
    console.log("设备 UUID:", device.uuid);
    console.log("系统版本:", device.version);
    console.log("制造商:", device.manufacturer);
    console.log("是否虚拟设备:", device.isVirtual);
    console.log("序列号:", device.serial);
}, false);

步骤 7：打包与发布

bash 复制代码

# 安装到项目
hcordova plugin add ./cordova-plugin-device

# 构建应用
hcordova build harmonyos

# 发布到 NPM（可选）
npm publish

常见问题与解决方案

Q1: 为什么 `uuid` 和 `serial` 返回相同的值？

A : 在 HarmonyOS 中，普通应用无法获取真实的设备 UUID 和序列号，出于隐私保护考虑，两者都返回 ODID。在模拟器中，两者都返回固定的 "emulator123456"。

Q2: 如何判断设备是否为模拟器？

A : 检查 device.isVirtual 属性，或检查 device.model 是否为 "emulator"。

Q3: 插件初始化失败怎么办？

确保在 deviceready 事件之后调用
检查 plugin.xml 配置是否正确
查看 C++ 和 ArkTS 层的日志输出
确认 HarmonyOS API 权限已配置

Q4: 如何扩展插件功能？

在 Device.cpp 的 execute 方法中添加新的 action 分支
在 ArkTS 层实现对应的函数
在 JavaScript 层添加新的 API 方法
更新 plugin.xml 注册新的源文件（如需要）

总结

本文详细介绍了 HarmonyOS Cordova 设备信息插件的开发过程，涵盖了：

架构设计：三层架构模型，职责清晰
技术实现：JavaScript、C++、ArkTS 三层协同工作
数据流转：完整的异步调用链和回调机制
关键技术：异步通信、数据序列化、内存管理等
开发流程：从初始化到发布的完整步骤

这个插件展示了如何在 HarmonyOS 平台上开发 Cordova 插件的标准模式，可以作为其他插件开发的参考模板。通过理解这个插件的实现，开发者可以：

掌握 Cordova 插件开发的基本流程
理解跨语言调用的桥接机制
学习 HarmonyOS API 的使用方法
了解异步编程和事件驱动的设计模式

希望本文能够帮助开发者更好地理解和开发 HarmonyOS Cordova 插件！

开源鸿蒙 Cordova 设备信息插件开发详解