欢迎加入开源鸿蒙 PC 社区

欢迎在 PC 社区平台申请新建项目

框架与适配:Cordova OpenHarmony 平台适配

本文示例与复现材料

把已有巡检表单迁到鸿蒙 PC,最容易原样照搬的是前端校验。若本地插件约定的是 UTF-8 字节上限,沿用 JavaScript 的字符串长度就可能放过超限内容。这篇保留原 Web 表单,用一次 Cordova 原生调用拿到真实字节数,重点看两端怎样约定同一个单位。

前言

巡检交接里经常会加一个符号。我在示例里用了「巡检📝」,把它填进鸿蒙 PC 的 Cordova 页面后,左边的字符串长度是 4,右边的原生结果是 10。换成带一个空格的 Check OK,两边却都是 8。假如原来的 Web 表单拿 value.length 做字节上限校验,光试一条英文很难发现这个差异。

这次迁移验证保留了 Web 编辑区和样本切换,把 UTF-8 字节计算交给 Cordova 的鸿蒙插件。页面同时显示本地长度与插件结果。用两条输入和一次清空就能检查三件事:页面何时可以发调用,原生端收到了什么,以及错误是否也能回到原来那个按钮。

先把三个结果摆在一起

输入页面 UTF-16 码元数插件实测页面变化
Check OK8成功回调 8显示 8 字节
巡检📝4成功回调 10显示 10 字节
清空后点击校验0错误回调 EMPTY_NOTE字节栏显示横线,页面提示记录为空

MateBook Pro 2in1 模拟器全屏,英文样本显示 8 码元和 8 字节

MateBook Pro 2in1 模拟器全屏,英文样本显示 8 码元和 8 字节

MateBook Pro 2in1 模拟器全屏,巡检加表情显示 4 码元和 10 字节

MateBook Pro 2in1 模拟器全屏,巡检加表情显示 4 码元和 10 字节

MateBook Pro 2in1 模拟器全屏,空输入触发错误回调

MateBook Pro 2in1 模拟器全屏,空输入触发错误回调

同一台模拟器的窄窗全屏,空输入提示在缩窗后仍然可见

同一台模拟器的窄窗全屏,空输入提示在缩窗后仍然可见

「巡」和「检」各占一个 UTF-16 码元,「📝」由两个码元表示。换到 UTF-8,前两个汉字各占 3 字节,表情占 4 字节,所以原生端算出 10。示例只用 trim() 判断空白输入,编码时仍传原字符串,输入两侧的空格也会计入实际字节数。

模拟器实录,依次校验英文、中文和表情、空输入,最后拖动窗口

模拟器实录,依次校验英文、中文和表情、空输入,最后拖动窗口

把三份样本带到 MateBook 14

上面的三个数字先在 API 24 模拟器里算过。换到 MateBook 14,我先保留同一份页面和同一个 NoteMeter,只换鸿蒙容器的编译架构与签名。Cordova 原先只打包了 x86_64 库。我给它加上 arm64-v8a,并放入同架构的 OpenSSL 头文件和两份动态库。签名后通过 USB 安装并启动,bm dump 显示 1.0.0。打开页先等「Cordova 已连接」,再送样本给插件。

设备系统与 ABI运行结果
HUAWEI MateBook 14(MNTXM-24B)HarmonyOS 7.0.0,软件版本 7.0.0.115(SP11C00E103R12P2patch01),API 26.0.0,aarch64签名 HAP 安装、启动;英文 8 字节,中文与表情 10 字节,空输入被拒绝
MateBook Pro 2in1 模拟器HarmonyOS 6.1.0,软件版本 6.1.0.125(SP12DEVC00E47R1P3),API 6.1.1(24),x86_64原来的未签名调试验证,包含三组回调、宽窄窗与 GIF

MateBook 14 真机「关于本机」全屏,保留设备型号、完整软件版本和 API

MateBook 14 真机「关于本机」全屏,保留设备型号、完整软件版本和 API

先按设备巡检样本,页面读到 8 个码元,插件返回 8 个字节。换成「巡检📝」后,左侧仍是 4,右侧变成 10。清空再校验,左侧为 0,右侧保持横线,下面显示空输入的说明。最后这一按验证了原生返回的是 EMPTY_NOTE,页面没有把空输入显示成成功的 0 字节。

MateBook 14 真机全屏,英文样本 Check OK 两边均显示 8

MateBook 14 真机全屏,英文样本 Check OK 两边均显示 8

MateBook 14 真机全屏,中文与表情样本显示 4 个码元、10 个字节

MateBook 14 真机全屏,中文与表情样本显示 4 个码元、10 个字节

MateBook 14 真机全屏,清空后没有字节结果,页面提示输入为空

MateBook 14 真机全屏,清空后没有字节结果,页面提示输入为空

MateBook 14 真机全屏录屏。先校验 Check OK(8 个码元、8 个字节),拖窗后切到「巡检📝」(4 个码元、10 个字节),最后清空并再次校验,页面提示记录为空。原始 MP4 为 2880 × 1920,拖窗期间测得一秒内 60 个不同画面,整段平均约 18 fps。

查看原始 MP4 录屏

hvigor Finished :entry:default@SignHap
install bundle successfully.
start ability successfully.
versionName: 1.0.0
NoteMeter: measure bytes=8
NoteMeter: measure bytes=10
NoteMeter: reject reason=EMPTY_NOTE

这段 GIF 录自模拟器窗口,保留桌面、程序坞和状态栏。编码后共 97 个不同画面,时长 14.35 秒。拖动缩窄和拉宽的连续变化区间实测分别约 18.7 和 19.1 帧/秒,停留时保留较长帧间隔。

从按钮追到原生回调

在鸿蒙 PC 上打开 Cordova 页面时,我先看右上角是否显示「Cordova 已连接」。这个提示来自 deviceready,事件触发后才解除校验按钮的禁用状态。点击校验,页面把文本放在参数数组里,传给服务名 NoteMeter、动作名 measureUtf8。服务名和 ArkTS 注册项对应,动作名由插件的 execute 选择。调用语法见 Apache Cordova 插件开发文档。

这条链路上有两份可以对照的证据。页面显示的是成功或错误回调收到的值,NoteMeter 的 HiLog 记录的是鸿蒙插件侧计算或拒绝的结果。换样本时页面先清空右侧数字,然后再校验。输入改动会更新请求序号,旧回调晚到时不会覆盖当前输入的状态。按钮旁的横线表示当前没有结果,读者可以用这个状态区分「还没校验」和「收到错误」。

鸿蒙侧只注册这一个服务

入口页沿用 Cordova 鸿蒙平台提供的 MainPage,它加载包内 rawfile/www/index.html。NoteMeter 作为本项目的 ArkTS 插件注册进去。原生端用 util.TextEncoder().encodeInto(note).byteLength 计数,成功回调传十进制字符串,空白输入走错误回调。编码接口见 华为 util 文档。

entry/src/main/ets/pages/Index.ets

import { MainPage, pageBackPress, pageHideEvent, pageShowEvent, PluginEntry } from '@cordova-ohos/ohos/Index';
import { NoteMeter } from '../entryability/NoteMeter';


@Entry
@Component
struct Index {
  private plugins: PluginEntry[] = [{ pluginName: 'NoteMeter', pluginObject: new NoteMeter() }];

  onPageShow(){
    pageShowEvent(); //页面显示通知cordova
  }
  onBackPress() {
    pageBackPress(); //拦截返回键由cordova处理
    return true;
  }
  onPageHide() {
    pageHideEvent(); //页面隐藏通知cordova
  }
  build() {
    RelativeContainer() {
      //默认加载rawfile/www/index.html
      MainPage({ isWebDebug: false, cordovaPlugs: this.plugins });
    }
    .height('100%')
    .width('100%')
  }
}

entry/src/main/ets/entryability/NoteMeter.ets

import { util } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { CallbackContext, CordovaPlugin } from '@cordova-ohos/ohos/Index';

export class NoteMeter extends CordovaPlugin {
  execute(action: string, args: ESObject[], callback: CallbackContext): boolean {
    if (action !== 'measureUtf8') {
      return false;
    }
    const note = args[0] as string;
    if (typeof note !== 'string' || note.trim().length === 0) {
      hilog.info(0x0000, 'NoteMeter', 'reject reason=EMPTY_NOTE');
      callback.errorByString('EMPTY_NOTE');
      return true;
    }
    const bytes = new util.TextEncoder().encodeInto(note).byteLength;
    hilog.info(0x0000, 'NoteMeter', 'measure bytes=%{public}d', bytes);
    callback.successByString(bytes.toString());
    return true;
  }
}
页面接收成功和错误

HTML 使用模板自带的 Cordova 运行时,脚本绑定页面的样本按钮、输入框和校验结果。下面的 HTML 和 JavaScript 对应截图里实际运行的版本。

entry/src/main/resources/rawfile/www/index.html

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>现场记录</title>
  <link rel="stylesheet" href="css/index.css">
  <script defer src="cordova.js"></script>
  <script defer src="js/index.js"></script>
</head>
<body>
  <main>
    <header>
      <span class="brand-mark" aria-hidden="true">▤</span>
      <div><h1>现场记录</h1><p>UTF-8 字节校验</p></div>
      <span id="bridge" class="status" role="status">正在连接 Cordova</span>
    </header>
    <div class="workspace">
      <aside aria-label="示例记录">
        <h2>示例记录</h2>
        <button class="sample" type="button" data-value="Check OK" aria-pressed="true">
          设备巡检 <small>英文与空格</small>
        </button>
        <button class="sample" type="button" data-value="巡检📝" aria-pressed="false">
          交接速记 <small>中文与表情</small>
        </button>
      </aside>
      <section class="editor" aria-label="记录编辑器">
        <label for="note">记录内容</label>
        <textarea id="note" rows="5" maxlength="2048" spellcheck="false">Check OK</textarea>
        <div class="measurements">
          <div><span>JavaScript 字符串长度</span><strong id="units">8</strong><small>UTF-16 码元</small></div>
          <div><span>鸿蒙插件返回</span><strong id="bytes">—</strong><small>UTF-8 字节</small></div>
        </div>
        <div class="actions">
          <button id="measure" type="button" disabled>校验字节数</button>
          <button id="clear" type="button">清空</button>
        </div>
        <p id="feedback" role="status">连接后可校验当前记录。</p>
      </section>
    </div>
  </main>
</body>
</html>

entry/src/main/resources/rawfile/www/js/index.js

(() => {
  const note = document.querySelector('#note');
  const bridge = document.querySelector('#bridge');
  const units = document.querySelector('#units');
  const bytes = document.querySelector('#bytes');
  const measure = document.querySelector('#measure');
  const feedback = document.querySelector('#feedback');
  const samples = [...document.querySelectorAll('.sample')];
  let ready = false;
  let revision = 0;

  function updateNote() {
    revision += 1;
    units.textContent = note.value.length;
    bytes.textContent = '—';
    feedback.classList.remove('error');
    feedback.textContent = ready ? '等待校验当前记录。' : '连接后可校验当前记录。';
    samples.forEach(button => {
      button.setAttribute('aria-pressed', String(button.dataset.value === note.value));
    });
  }

  function measureNote() {
    if (!ready) return;
    const request = ++revision;
    measure.disabled = true;
    bytes.textContent = '—';
    feedback.classList.remove('error');
    feedback.textContent = '等待鸿蒙插件回传…';
    const timeout = setTimeout(() => finish(null, 'CALLBACK_TIMEOUT'), 4000);
    let settled = false;
    function finish(value, error) {
      if (settled) return;
      settled = true;
      clearTimeout(timeout);
      measure.disabled = false;
      if (request !== revision) return;
      if (error) {
        feedback.classList.add('error');
        feedback.textContent = error === 'EMPTY_NOTE' ? '记录为空,未生成字节结果。' : '插件回传失败:' + error;
        return;
      }
      bytes.textContent = value;
      feedback.textContent = '已收到鸿蒙插件回传。';
    }

    try {
      cordova.exec(value => finish(value, null), error => finish(null, error),
        'NoteMeter', 'measureUtf8', [note.value]);
    } catch {
      finish(null, 'BRIDGE_ERROR');
    }
  }

  document.addEventListener('deviceready', () => {
    ready = true;
    bridge.textContent = 'Cordova 已连接';
    bridge.classList.add('ready');
    measure.disabled = false;
    updateNote();
  }, { once: true });

  note.addEventListener('input', updateNote);
  measure.addEventListener('click', measureNote);
  document.querySelector('#clear').addEventListener('click', () => {
    note.value = '';
    updateNote();
  });
  samples.forEach(button => button.addEventListener('click', () => {
    note.value = button.dataset.value;
    updateNote();
  }));
})();

复现时先核对这两套版本

环境实测配置
Windows 开发机DevEco Studio 6.1.1.300,SDK 包 6.1.1.125
DevEco 设备配置MateBook Pro 2in1,3120 × 2080
模拟器关于本机HarmonyOS 6.1.0,软件版本 6.1.0.125 (SP12DEVC00E47R1P3),API 6.1.1(24)
模拟器命令行2in1、API 24、x86_64、OpenHarmony-6.1.1.125
工程和 Cordova 依赖目标及兼容 SDK 6.1.1(24),hcordova 1.0.7 工程骨架、@cordova-ohos/ohos 14.0.2
安装产物entry-default-unsigned.hap,在这台模拟器上安装、启动

Windows DevEco Studio 原生关于窗口

Windows DevEco Studio 原生关于窗口

同一台 MateBook Pro 2in1 模拟器的关于本机全屏,序列号已遮盖

同一台 MateBook Pro 2in1 模拟器的关于本机全屏,序列号已遮盖

将原 Web 页的 HTML、CSS 和业务脚本放进 entry/src/main/resources/rawfile/www/,使用模板提供的 cordova.js。入口模块设备类型设为 2in1。Cordova 平台模块的 abiFilters 只保留这台模拟器需要的 x86_64,把同一架构的 libssl.so.3、libcrypto.so.3 和头文件放到平台构建脚本指定的目录,再用 DevEco 同步依赖并构建调试 HAP。本文复现所用的依赖见 Cordova 鸿蒙适配仓库 和 OpenSSL 依赖仓库。

第 2 篇 Cordova 工程在 DevEco Studio 编辑器中的 2in1 设备声明

第 2 篇 Cordova 工程在 DevEco Studio 编辑器中的 2in1 设备声明

图中保留了后台 DevEco 截图环境的同步失败提示。实际 HAP 由同一套 DevEco 工具的命令行构建,先用 OHPM 同步依赖,再执行 Hvigor 的 assembleHap。构建日志显示 BUILD SUCCESSFUL,以下安装和启动均使用该产物。

从工程根目录执行下列命令。鸿蒙 PC 模拟器上的应用启动后,按截图顺序各测一次,再查看最后一条命令的输出。

$hdc = Join-Path (Read-Host 'DevEco Studio 安装目录') 'sdk/default/openharmony/toolchains/hdc.exe'
& $hdc list targets -v
$target = Read-Host 'MateBook Pro 模拟器的 HDC 地址'
& $hdc -t $target shell 'param get const.product.devicetype; param get const.ohos.apiversion; uname -m'
$hap = Join-Path $PWD 'entry/build/default/outputs/default/entry-default-unsigned.hap'
& $hdc -t $target install -r $hap
& $hdc -t $target shell 'aa start -b com.aasd23.ugccordovaruntime -a EntryAbility'
& $hdc -t $target shell 'hilog -x -T NoteMeter'

实际卡过的两处

第一次构建时,我更新了 hvigor-config.json5,根目录的 oh-package.json5 仍是模板的 5.0.5。Hvigor 返回 00303027,提示两个 modelVersion 不一致。把两处都对齐到本次工具链使用的 6.1.1 后,构建才继续进入原生模块编译。升级工程时可以先查这两个文件,再看后面滚出来的日志。

接入插件后,ArkTS 又在 const note = args[0] 处报 10605008,提示需要显式类型。最终使用 args[0] as string,并保留 typeof 与空白检查。类型断言约束编译期写法,运行时检查用于判断跨桥传来的值。修正后重新出包、覆盖安装、冷启动,三组结果分别出现在页面和原生日志里。

FAQ

页面能开,校验按钮为什么还是灰色?

先查 cordova.js 能否从包内加载,再看 deviceready 是否触发。页面可以先显示 HTML,按钮会等到桥接就绪。若已显示「Cordova 已连接」却没回调,接着对照页面调用的服务名、动作名与入口注册项,最后查 NoteMeter 日志判断请求是否已经到插件。

Web 里也能编码,为什么这里要经过 Cordova?

只在前端展示一个字节数时,Web 的 TextEncoder 就能完成。这个示例用字节计数做可核对的回调,让页面、Cordova 和鸿蒙插件之间的参数、成功和失败分支都能独立验证。接入实际巡检系统时,字节校验放在最终采用相同编码的那一层更容易对齐后端约束。

模拟器能装未签名 HAP,交付时也这样装吗?

签名安装后的 MateBook 14 也复现了三次插件回调。英文有 8 个码元和 8 个字节;「巡检📝」有 4 个码元和 10 个字节;空白输入不产生字节结果。迁移旧 Cordova 表单时,可以保留这三条样本一起回归。只试英文,容易让按 JavaScript 字符串长度限制 UTF-8 字节的错误漏过去。上文 GIF 记录的是模拟器,真机结果对应独立的全屏图和 NoteMeter 日志。

总结

这次在鸿蒙 PC 的 2in1 模拟器上,Cordova 页面和鸿蒙插件之间的成功、错误两条链路都走通了。用英文样本可以对照两侧是否一致,用中文和表情可以识别码元与字节的差异,清空后再测则能看出错误时旧数字有没有被清掉。迁移别的页面时,先用这样一组可预期的结果验通 Cordova,再接系统能力或业务规则,调试时就能知道该看页面、插件注册,还是构建环境。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐