鸿蒙 PC 上迁移 Cordova 巡检页:同一条记录为什么是 4 个码元、10 个字节
框架与适配: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 OK | 8 | 成功回调 8 | 显示 8 字节 |
巡检📝 | 4 | 成功回调 10 | 显示 10 字节 |
| 清空后点击校验 | 0 | 错误回调 EMPTY_NOTE | 字节栏显示横线,页面提示记录为空 |

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

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

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

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

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

MateBook 14 真机全屏,清空后没有字节结果,页面提示输入为空
MateBook 14 真机全屏录屏。先校验 Check OK(8 个码元、8 个字节),拖窗后切到「巡检📝」(4 个码元、10 个字节),最后清空并再次校验,页面提示记录为空。原始 MP4 为 2880 × 1920,拖窗期间测得一秒内 60 个不同画面,整段平均约 18 fps。
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 原生关于窗口

同一台 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 设备声明
图中保留了后台 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,再接系统能力或业务规则,调试时就能知道该看页面、插件注册,还是构建环境。
更多推荐



所有评论(0)