欢迎加入鸿蒙 PC 开发者社区,也欢迎在 AtomGit 鸿蒙 PC 社区 申请新建项目。

Cordova OpenHarmony 框架仓

前言

交接人员拿到一批巡检记录时,想知道少的是哪一份。校验进度走到三分之一后停在那里,可能是第三份迟迟没有返回,也可能是前两份已经通过、第三份对不上。两种情况都可以显示「二比六」,接下来要做的事却不同。这个页面把分片计数和最后一条回执留在一起,方便交班时把停下的原因说清楚。

我在鸿蒙 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 鸿蒙适配源码。

Logo

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

更多推荐