鸿蒙 PC 的 Cordova 校验任务,一次调用怎样陆续收到分片回执
欢迎加入鸿蒙 PC 开发者社区,也欢迎在 AtomGit 鸿蒙 PC 社区 申请新建项目。
前言
交接人员拿到一批巡检记录时,想知道少的是哪一份。校验进度走到三分之一后停在那里,可能是第三份迟迟没有返回,也可能是前两份已经通过、第三份对不上。两种情况都可以显示「二比六」,接下来要做的事却不同。这个页面把分片计数和最后一条回执留在一起,方便交班时把停下的原因说清楚。
我在鸿蒙 PC 做了一个 Cordova 校验任务台。任务里有六个内置分片,原生插件按分片计算记录数,和交接单上的数字比对。每次算完就回给页面一条结果。样例之间留了固定间隔,便于演示中途取消和数量不符;这个间隔只控制演示节奏,校验进度来自原生回执。应用只使用测试数据,复现时不需要导入实际巡检记录。
到底停在第三片之前,还是第三片之后
在 1.0.1 的真机复测中,第一轮快一点过了第三片。点击取消后屏幕停在 3/6,前三片的通过回执完整保留。多等了一会儿,第四片仍没出来。任务的最后一行是「已取消」,负责接班的人可以直接看出它停在什么地方。旧版录像曾在通过两片时取消。这两个数分别对应按下按钮的时点,取消没有约定必须停在第几片。
第二轮我勾上「使用少一条的样例」。第三片收到实计 22、预期 23,前两片仍是通过,界面停在 2/6。这时第三格有独立的差异提示。它确实收到了第三片的结果,只是这片没有计入通过数。若只把通过数放出来,用户很难分辨任务是暂停等待、被主动取消,还是已因数量不符结束。回执里保留状态和实计、预期,交班时才有具体内容可查。


最后撤掉故障选项再开始。新的回执列表从「开始」出现,任务编号换为 3。六片检查依次经过,第六片和最终「完成」各占一行。原先的差异回执没有混入这一轮。这样一组连贯操作,分别验到了取消后静止、哪片的数量不符、以及收尾能否让下一轮重新开始。
为什么同一次调用能刷新多次
页面启动任务只调用一次 cordova.exec。原生侧收到的是动作、参数和这次调用对应的回调对象。后面每次处理的分片仍然通过这一个对象发回,网页没有另外发轮询请求。回调里带有任务编号、状态、已通过数量和总量。必要时还补实计和预期,页面据此生成状态文字和回执列表。调试时从这个编号向下找,可以把一次点击和一串进度联系起来。
重要的参数是 keepCallback。开始通知和普通进度把它设为真,让 Cordova 保留 JavaScript 的回调。最后一次消息把它设为假。取消和数量不符也会关闭这次回调。这里的「成功回调」表示插件成功送达结构化结果,收到它之后还有一步要读业务状态。某个分片比预期少一条,依然能用这个回调把真实差异告诉页面。启动动作被拒绝则走错误回调。
第六个分片通过之后,插件先报告该分片的具体数字,再发一条「完成」。这个设计乍看像多发了一次,回执里两行分别有用。第六片那条保留核对结果,完成那条让页面恢复开始按钮。页面上进度达到六的时候仍按消息类型处理。如果拿百分比来决定回调是否结束,界面很容易比原生更早恢复按钮。样例里的状态能让读者立刻分清两条消息属于同一轮,但作用不同。
取消还有第二个回调。点击「取消本次」是新的一次桥接请求,它的回调收的是取消确认。真正的结束通知依旧回到启动任务的那条通道上。原生侧先清除计时器和当前任务,再用旧通道发 cancelled,最后确认取消请求。若启动请求和取消请求共用一个页面状态变量,必须以任务结束消息为准,否则可能把请求确认误当作进度已经完整收尾。
把回执从原生插件读到页面
鸿蒙 PC 工程将 VerifyBatch 注册到 Cordova 容器。插件的任务记录握住当前索引和回调上下文,每次只安排一个定时步骤。下一步开始先核对任务身份,取消后即使旧步骤已排进事件队列,也无法再给当前任务写入进度。页面就绪前,开始按钮保持禁用。运行后,页面只读最新回执里的计数来更新格子,所以它展示的是已经完成的核对,而非预计耗时。
一轮任务结束时清除原生的活动记录,下一轮才能进入。当旧任务进行中再次发出开始动作,原生会返回忙,页面也在已有任务运行期间禁用开始。两层分别面对普通用户输入和桥接请求。关闭页面时原生清掉定时器,样例没有设计跨会话续跑。这让任务生命周期和页面回调归属一致,读者复刻后能用关闭、再打开来区分新的会话。
下面两个文件分别是 ArkTS 插件和页面脚本。桥接的名字在容器注册和页面调用里都用 VerifyBatch。其中的计数输入属于内置样例,换成实际巡检来源时,校验和读取应带着具体分片标识一起向下传递。
import { hilog } from '@kit.PerformanceAnalysisKit';
import { CallbackContext, CordovaPlugin } from '@cordova-ohos/ohos/Index';
const TAG = 'UgcCordovaVerify';
const MANIFEST: number[][] = [[4, 12, 6], [9, 18], [7, 5, 11], [24, 3], [12, 26], [20, 19]];
const TOTALS: number[] = [22, 27, 23, 27, 38, 39];
interface Run {
id: number;
cursor: number;
insertMismatch: boolean;
callback: CallbackContext;
}
interface Update {
runId: number;
state: string;
checked: number;
total: number;
actual: number;
expected: number;
}
export class VerifyBatch extends CordovaPlugin {
private nextId: number = 1;
private active: Run | null = null;
private timer: number = -1;
execute(action: string, args: ESObject[], callback: CallbackContext): boolean {
if (action === 'cancel') {
const run = this.active;
if (!run) {
callback.errorByString('NO_ACTIVE_RUN');
return true;
}
this.finish(run, 'cancelled', 0, 0);
callback.successByString('CANCEL_ACK');
return true;
}
if (action !== 'start') return false;
if (this.active) {
callback.errorByString('BUSY');
return true;
}
const run: Run = {
id: this.nextId++, cursor: 0, insertMismatch: args[0] === true, callback: callback
};
this.active = run;
this.send(run, 'started', 0, 0, true);
this.schedule(run);
return true;
}
private schedule(run: Run): void {
this.timer = setTimeout(() => { this.step(run); }, 460);
}
private step(run: Run): void {
if (this.active !== run) return;
const index = run.cursor;
const expected = TOTALS[index];
let actual = MANIFEST[index].reduce((sum: number, value: number) => sum + value, 0);
if (run.insertMismatch && index === 2) actual -= 1;
if (actual !== expected) {
this.finish(run, 'mismatch', actual, expected);
return;
}
run.cursor++;
this.send(run, 'progress', actual, expected, true);
if (run.cursor < MANIFEST.length) {
this.schedule(run);
} else {
this.finish(run, 'done', actual, expected);
}
}
private finish(run: Run, state: string, actual: number, expected: number): void {
clearTimeout(this.timer);
this.timer = -1;
this.active = null;
this.send(run, state, actual, expected, false);
}
private send(run: Run, state: string, actual: number, expected: number, keep: boolean): void {
const update: Update = {
runId: run.id, state: state, checked: run.cursor, total: MANIFEST.length,
actual: actual, expected: expected
};
hilog.info(0, TAG, 'run=%{public}d state=%{public}s checked=%{public}d actual=%{public}d expected=%{public}d keep=%{public}s',
run.id, state, run.cursor, actual, expected, keep ? 'true' : 'false');
run.callback.successByString(JSON.stringify(update), keep);
}
onDestroy(): void {
clearTimeout(this.timer);
this.active = null;
this.timer = -1;
}
}
'use strict';
const start = document.querySelector('#start');
const cancel = document.querySelector('#cancel');
const useMismatch = document.querySelector('#fault');
const receipts = document.querySelector('#receipts');
const message = document.querySelector('#message');
const count = document.querySelector('#count');
const run = document.querySelector('#run');
const ticks = Array.from({length: 6}, () => {
const tick = document.createElement('span');
tick.className = 'tick';
document.querySelector('#ticks').append(tick);
return tick;
});
function busy(running) {
start.disabled = running;
cancel.disabled = !running;
useMismatch.disabled = running;
}
function addReceipt(label, result) {
const entry = document.createElement('li');
const kind = document.createElement('span');
kind.textContent = label;
entry.append(kind, document.createTextNode(result));
receipts.append(entry);
}
function update(result) {
const data = JSON.parse(result);
count.textContent = data.checked + ' / ' + data.total;
ticks.forEach((tick, i) => {
tick.classList.toggle('passed', i < data.checked);
tick.classList.toggle('failed', data.state === 'mismatch' && i === data.checked);
});
switch (data.state) {
case 'started':
run.textContent = '任务 #' + data.runId;
message.textContent = '正在等待分片回执…';
addReceipt('开始', '校验插件已接收任务');
return;
case 'progress':
message.textContent = '已核对 ' + data.checked + ' 个分片';
addReceipt('分片 ' + data.checked, '实计 ' + data.actual + ',与交接单一致');
return;
case 'mismatch':
message.textContent = '分片 ' + (data.checked + 1) + ' 数量不符,任务已结束。';
addReceipt('数量不符', '实计 ' + data.actual + ',预期 ' + data.expected);
break;
case 'cancelled':
message.textContent = '已取消,后续分片未执行。';
addReceipt('取消', '保留已完成的 ' + data.checked + ' 条回执');
break;
case 'done':
message.textContent = '六个分片全部核对通过。';
addReceipt('完成', '收到最后一条回执');
break;
default:
message.textContent = '未知回应 ' + data.state;
}
busy(false);
}
document.addEventListener('deviceready', () => {
busy(false);
message.textContent = '准备开始。';
start.addEventListener('click', () => {
receipts.replaceChildren();
busy(true);
cordova.exec(update, (reason) => {
message.textContent = '启动失败。' + reason;
busy(false);
}, 'VerifyBatch', 'start', [useMismatch.checked]);
});
cancel.addEventListener('click', () => {
cancel.disabled = true;
cordova.exec(() => {}, (reason) => {
message.textContent = '取消请求返回。' + reason;
}, 'VerifyBatch', 'cancel', []);
});
}, {once: true});
最后的两条日志为什么都显示 6/6
这次从同一签名包的 UgcCordovaVerify 日志里摘出结束处,三个任务使用独立的运行编号。取消和差异都释放回调。正常任务到第六片时继续保留,紧接着发最终回执才释放。
run=1 state=cancelled checked=3 keep=false
run=2 state=mismatch checked=2 actual=22 expected=23 keep=false
run=3 state=progress checked=6 actual=39 expected=39 keep=true
run=3 state=done checked=6 actual=39 expected=39 keep=false
调试时如果先收到 6/6,仍要等 done 才算这轮结束。第六片的回执说明该片发生了什么,最终回执说明这一轮还能否继续接收消息。两条都保留时,用户可以检查具体数据,页面也能在正确时点恢复按钮。若把它们合并为单一百分比,取消和失败的收尾处理也很容易写成另一套逻辑。代码中的最后一条结构化回执把这三种情况留在同一次启动调用里。

下方原录像记录了 1.0.0 的取消、失配和正常完成。旧真机素材整段平均 3.54 帧每秒。本次 1.0.1 的验收依据是新采集的全屏图和本机日志。

MateBook Pro 模拟器校验实录。无音轨。整段平均 1.88 帧每秒,1.5 至 10.0 秒区间每秒 2.00 个不同解码画面。
先让两侧的服务名碰面
在鸿蒙电脑的「文档」解开完整的 CordovaProgress 源码。用鸿蒙版 DevEco Studio 打开含 build-profile.json5 的根目录,等同步结束后,在编辑区先找 VerifyBatch.ets 和页面里调用 cordova.exec 的位置。入口页还要把服务名 VerifyBatch 注册给适配容器。三个地方对上,才能把一次点击和后面多条回执关联起来。项目源码归档保留了 Web 页面、ArkTS、原生容器和工程配置;完整项目公开版本直链仍待补。 Cordova OpenHarmony 适配仓
| 层级 | 本次使用 |
| 鸿蒙电脑开发与装机 | HUAWEI MateBook 14(MNTXM-24B),HarmonyOS 7.0.0,软件 7.0.0.115(SP11C00E103R12P2patch01),API 26.0.0,aarch64 |
| IDE 与工程 | 鸿蒙版 DevEco Studio 26.0.0.220,Stage 2in1,Cordova OpenHarmony 14.0.2,目标与兼容 SDK 6.1.1(24) |
| 旧版模拟器对照 | MateBook Pro 2in1,HarmonyOS 6.1.0,软件 6.1.0.125(SP12DEVC00E47R1P3),API 24,x86_64 |
下面两条在鸿蒙电脑的 DevEco 终端执行,当前位置是本篇工程根目录。本机同时编译了项目 ArkTS 代码和 Cordova 宿主,完成 43 项任务,耗时 16 秒 252 毫秒。未签名 HAP 为 23,167,297 字节,位于 entry/build/default/outputs/default/。
ohpm install --all
hvigorw --mode module -p product=default -p module=entry@default -p buildMode=debug assembleHap --no-daemon
运行目标选择「此电脑」。在鸿蒙版 DevEco Studio 的「项目结构 → 签名配置」为 com.aasd23.ugccordovaprogress 自动生成调试签名,再运行 entry-default-signed.hap。本机安装后核对版本 1.0.1、版本代码 1000001。等 Cordova 页面报告就绪才开始复测,窗口已经弹出还不足以判断桥接是否正常。签名文件由复现者在自己的鸿蒙电脑上生成。 华为 DevEco Studio 签名说明


应用启动后,打开过滤 UgcCordovaVerify 的运行日志。窗口初次渲染只证明 Web 资源存在。出现第一条带任务编号的 started 才说明桥接已经进入原生;后续 progress 的条数用于判断这个调用有没有保留回调,最后的 keep=false 对应收尾。排查时把日志和界面视图对照,定位到启动、分片和结束中的一个阶段,再去改对应一侧的代码。
FAQ
为什么取消后数字不归零? 已完成的分片对解释这次交接有用。取消保留当前计数和已出现的回执。下一轮开始时才清掉上一轮的列表,计数从新任务的开始消息更新。核对实现时,可以看取消之后有没有同一任务编号的下一条进度,有的话就需要回插件检查计时器和当前任务的判断。
为什么不用一个定时器给进度条做动画? 固定间隔可以用来模拟等待,页面上的数字仍必须由校验结果决定。如果第三片内容不符,任务应停在前两片通过,界面能给第三片单独着色。用动画把格子填满会掩盖这个差异。
数量不符之后还能用同一个回调重试吗? 上一轮已发终态并释放回调,重试要重新发起开始动作。这样每个编号有自己的起点和终点。用日志核对时,应当看到新编号从零开始,上一轮的错误停在原位置。
总结
校验台最有用的两行输出,一行说明有多少片已经通过,另一行说明任务为什么停下。真机和模拟器都复现了主动取消、第三片失败和正常完成,所以页面能清楚区分三条路径。串起它们的是一次 Cordova 调用里的多条真实回执。开始与进度保留连接,三种终态释放连接,重试时才打开一条新的调用通道。
原生插件注册方式可查 Cordova 鸿蒙适配源码。
更多推荐

所有评论(0)