WebView 沙箱摸不到 HMS kits,实况窗在 Cordova 里还有没有得做?——有:把 payload 构造层和预览器做成纯 JS,把边界写清楚。这篇文章讲这条"零原生"路线能做到哪一步、边界在哪里,以及一个 DOM 预览器的 0.5ms 渲染耗时是怎么来的。

仓库地址:https://atomgit.com/oh-tpc/live-view-cordova
版本地址:https://atomgit.com/CPF-Cordova
三方库框架:https://atomgit.com/oh-tpc

0. 环境与实测设备

项版本/型号
DevEco Studio26.0.0.851(HarmonyOS SDK 26.0.0 Release / API 26)
Cordovahcordova 1.0.7 宿主 + Cordova-ohos 14.0.2(ArkWeb WebView)
插件形态纯 JS(esbuild 打包,UMD clobber window.LiveViewKit,零原生代码)
实测设备Mate 90 Pro 镜像模拟器,OpenHarmony 7.0.0.107(API 26,ohos-x64)
测量通道hilog ARKWEB-CONSOLE(页面 console.log 直达)+ vitest/jsdom
插件live-view-cordova 1.0.0(本仓库,本地注入)

1. WebView 沙箱的能力边界

系列分工排到实况窗的 Cordova 位时,问题就摆在那了:实况窗是系统服务,liveViewManager 挂在 HMS kits 里,而 ArkWeb 的 WebView 沙箱不把 HMS kits 暴露给页面 JS。Cordova 的插件体系在鸿蒙上能挂 ArkTS 原生模块吗?试过就知道:hcordova 1.0.7 连 file 型插件都拒(File-based plugins not yet supported),JS 模块要靠手工注入三步才能进宿主——原生插件注入这条路在这个工具链版本上走不通。

第一个念头是"那就等工具链",第二个念头是先想清楚实况窗这件事里,哪些部分可以直接放在网页里。答案有两层:

  • payload 构造层:外卖、打车、比分三条场景链路的状态机,产出与 kit 字段一字不差的 spec——这是纯数据工作,天然属于 JS;
  • 预览器:把 spec 渲染成与系统模板同构的胶囊和卡片——这部分由 DOM 完成。

至于系统发布(start/update/stop),这部分由原生侧完成,WebView 里访问不到,probe() 直接返回 supported:false 和原因。三件套里 Flutter / RN 两个原生实现负责发布,Cordova 端把 payload 备好,交给任意一个原生桥即可上屏。分工和边界都写清楚。

所以这道题拆成三件事:

  • payload 构造层(三场景状态机的纯 JS 实现,vitest 逐字段锚定);
  • 应用内预览器(胶囊 / 卡片三区 / 26.0.0 左滑分享交互模拟);
  • 边界与测量(probe 如实、deviceready 与浏览器直开双兼容、0.5ms 渲染预算)。

下面是干完之后的完整记录。

2. 效果展示

先看效果。Demo 是一页 ArkWeb 应用:deviceready ✓ 徽标后面跟着 “预览模式(沙箱不暴露 HMS kits)”,这是 probe() 的返回值,页面用绿框把它标出来:

Cordova 实验室:外卖场景与 payload 全文

页面从上到下:场景切换(外卖 / 打车 / 比分)、胶囊态预览(状态栏胶囊的 DOM 等价物)、卡片态预览(固定区 + 辅助区 + 扩展区三段式)、步骤指示器、操作按钮、payload JSON 全文,最底下是 probe() 的边界说明全文。

徽标是这套页面里信息量最大的一行:deviceready ✓ 说明 Cordova 运行时正常(手工注入的 cordova.js 与插件脚本都加载成功),括号里的"预览模式(沙箱不暴露 HMS kits)“则是 probe() 的原文——这两句话同时成立,就是这条"零原生"路线的全部前提。再往下点"下一步”,payload JSON 面板里的 sequence 会 +1,胶囊里的迷你进度条与卡片的大进度条同步走——同一份数据的两种投影,这是三端同构在页面上的直接体现。

打车场景切过去,卡片扩展区变成强调文本模板:大号车牌"京A·8P9X2"带蓝色下划线(underlineColor),胶囊是文本形态"车牌 + 距离"——这一屏可以直接看到三段式结构:

Cordova 实验室:打车车牌卡

比分场景推到 2:1:扩展区是比分模板(主客队 / 比分 / 赛事描述 / 比赛时间),胶囊标题"2:1"按 6.0.0(20) 的语义会被系统渲染成队徽样式——预览器忠实还原字段的去向,payload 面板里能看到 "event": "SCORE" 与逐字段的 sequence:

Cordova 实验室:比分 2:1 与 payload

26.0.0 的左滑分享也在这页模拟:向左拖动卡片露出绿色分享面板,松手过阈值(-55px)触发回调,横幅亮出 shareUrl:
Cordova 实验室:左滑分享

比分的胶囊标题"2:1"还有一个细节值得单独说:按 kit 的 6.0.0(20) 语义,“数字:数字"格式的标题会触发系统把扩展区的队徽与比分提取到胶囊上,胶囊从"文本形态"升级成"队徽形态”。预览器里它是一条普通文本胶囊——预览器渲染的是 payload 字段的忠实投影,系统侧的加成(队徽、天气背景、归档动画)只会比预览更多,不会更少。这条判断是三端预览器共同遵守的规则。

渲染预算是页面里 performance.now 打点实测的:每推进一步,胶囊 + 卡片两个 DOM 子树全量重建只要 0.5~0.6ms(LVK-ADVANCE scene=score step=3 seq=4 renderMs=0.5,经 console.log 直达 hilog 的 ARKWEB-CONSOLE 通道采集)。对预览器来说,这个开销可以忽略,用来调 payload 足够。

以外卖为例,把"每一步预览器长什么样"完整走一遍——设计 payload 层时逐字段对照官方模板文档核出来的表(三端状态机逐字对齐):

步骤扩展区模板胶囊形态胶囊文案关键字段变化
已下单ProgressLayout(10%,虚线)ProgressCapsule“等待商家接单”progress=10/max=100
商家接单ProgressLayout(25%)ProgressCapsule“商家出餐中”辅助区"预计 35 分钟送达"
骑手取餐ProgressLayout(60%)ProgressCapsule“骑手取餐中”辅助区切"取餐码 8829"
配送中ProgressLayout(85%)ProgressCapsule“距您 1.2km”辅助区"骑手 王师傅"
已送达ProgressLayout(100%,实线)ProgressCapsule“已送达”keepTime=600 归档

打车与比分同理会走各自的形态切换:打车从 TimerCapsule(呼叫计时)切 TextCapsule(车牌 + 距离)再切 ProgressCapsule(行程),比分全程 ScoreLayout、只动 hostScore/guestScore/competitionTime 与胶囊标题。这套"模板与胶囊随步骤推进切换"的规则,是状态机层复用价值最高的部分——预览器的 0.5ms 让你可以在页面上把这些切换连着点一遍,肉眼核对每一步的字段去向。

3. 原理:构造、渲染、边界三层

写代码之前先定三层的职责,也包括每层不做什么:

构造层(payload):三条场景状态机(外卖 5 步、打车 6 步、比分 5 步)产出与 kit 字段一字不差的 spec。枚举值是协议(LayoutType 进度 3 / 接送 4 / 航班 5 / 比分 7,CapsuleType 文本 1 / 计时 2 / 进度 3),sequence 严格递增的不变量由状态机持有,shareUrl(26.0.0 左滑分享)做 HTTPS 与长度校验。这一层零 DOM、零 Cordova 依赖——vitest 在 jsdom 之外的纯环境里就能把契约钉死。

状态机的类型层也有讲究:spec 的接口用字面量判别联合建模(TextCapsuleJson 的 type: typeof CapsuleType.TEXT……),而不是一律 type: number。这样 if (cap.type === CapsuleType.TEXT) 才能真正收窄类型,四个模板分支各自拿到精确的字段集;写错字段名在 tsc --noEmit 就会报错,而不是等到运行时渲染出一张空卡。noUncheckedIndexedAccess 同时开着——步骤表取值全部 ?? 兜底,"步骤表少一行"这类低级错误也进不了产物。

渲染层(预览器):renderCapsule(el, spec) 与 renderCard(el, spec) 把 spec 翻译成 DOM。结构上严格对齐系统模板:胶囊 = 状态点 + 主文本 + 副文本 +(进度胶囊的)迷你比例条;卡片 = 固定区(标题 + 内容行)+ 辅助区(扩展文本 chip)+ 扩展区(按 layoutType 分派四种模板)。渲染是纯函数式的:每次调用先清空容器再重建子树,不维护增量状态——0.5ms 的渲染耗时就是这么来的;它渲染的是 payload 本身,中间没有缓存或默认值。

边界层(probe):probe() 永远返回 supported:false + 原因全文。这一层的作用是把边界直接告诉调用方:WebView 沙箱不暴露 HMS kits 是结构性事实,与其让调用方猜"发布失败是网络问题还是能力问题",不如一开始就把答案写在类型里。

胶囊有三种形态,行为分别是:TextCapsule 最常用,标题+副文本,传"2:1"这种"数字:数字"标题且扩展区是比分模板时(6.0.0(20) 起)系统自动渲染成队徽样式;TimerCapsule 自带秒级时钟(time 起始 + isCountdown 方向 + isPaused 暂停),打车呼叫"已等待 0:37"适合用它;ProgressCapsule 传 progress/max,indeterminate 决定显示比例还是百分比。构造层把形态写进 spec,渲染层把形态画成 DOM,两层之间没有第三个信息源。

还有一个只有 Cordova 才会遇到的问题:payload 如何上屏? 答案写在 specJson(spec) 里——它产出一条与 Flutter / RN 成员的桥协议字节级同构的 JSON 字符串。这条字符串在本次提交里被 flutter_live_view 的桥真实发布成功(start result 0 success.,系统级实拍见 flutter 成员仓库);Cordova 端只欠一个原生桥,欠的原因(工具链版本不支持原生插件注入)如实写进 verification.md。

specJson 与 probe 的实现都很短,可以全文贴出来:

// live-view.ts(节选)
/** Serialize a spec for the bridge (one JSON string, all three ends agree). */
export function specJson(spec: LiveViewSpecJson): string {
  return JSON.stringify(spec);
}

/** Honest capability probe: the ArkWeb sandbox never exposes the kit. */
export function probe(): ProbeOutcome {
  return {
    supported: false,
    detail: 'ArkWeb 沙箱不暴露 HMS kits:本插件负责 payload 构造与应用内预览;' +
            '系统发布请将 specJson 交给宿主原生桥(flutter_live_view / live-view-rn 同协议)。',
  };
}

probe() 返回的对象会被实验室页渲染成徽章与边界说明——页面加载时第一眼看到的就是它。预览模式下 payload 仍然完整构造,specJson 随时可以拿去真机验证;这个顺序(先构造、后上屏)也反过来保证了:预览器看到的和系统收到的,永远是同一份数据。

"字节级同构"指的是:三端对同一步骤产出的 JSON,字段名、枚举值、嵌套结构完全一致,差异只在无关紧要的键序。这一点由三端测试保证:Flutter 13 个、RN 15 个、Cordova 18 个测试里,有一批是逐字段值断言('京A·8P9X2'、'2:1'、progress: 85),另一批直接断言 JSON 子串('"layoutType":3'、'"subEvent":"FOOD"')。两层测试下来,三端的"公共语义"由这些断言保证。

4. 工程怎么搭:插件、产物、宿主三层

live-view-cordova/
├─ src/types.ts          # 线上协议类型(字面量枚举判别联合)
├─ src/payload.ts        # 场景构造层(与 Flutter/RN 成员同语义)
├─ src/live-view.ts      # probe / specJson / DOM 预览器 / 左滑分享
├─ www/live-view-kit.js  # esbuild IIFE 产物,clobber window.LiveViewKit
├─ types/index.d.ts      # tsc 类型输出
├─ example/
│  ├─ www/               # 实验室页(deviceready + 浏览器直开双兼容)
│  └─ harmonyos/         # hcordova 宿主(手工注入,见坑一)
└─ __tests__/            # 18 个 vitest(jsdom:payload 契约 + 预览 DOM + 左滑)

插件产物是 IIFE,footer 里手工 clobber 全局:

// scripts/build.mjs 的 footer(节选)
'var __LVK__ = LiveViewKitBundle;',
'if (typeof module !== "undefined" && module.exports) { Object.assign(module.exports, __LVK__); }',
'if (typeof window !== "undefined") { window.LiveViewKit = __LVK__; }',

宿主注入是 hcordova 1.0.7 下的手工三步:模板的 cordova.js 保留;插件产物拷到 rawfile/www/js/live-view-kit.js;index.html 加一行 <script src="js/live-view-kit.js"></script>。UMD 自己 clobber 全局,不依赖 cordova_plugins 机制——deviceready 照常,浏览器直开也照常(window.cordova 不存在时直接走 load 事件)。

构建管线分三步:tsc --noEmit(strict + noUncheckedIndexedAccess)先做类型检查,esbuild 打 IIFE 包(target es2018,覆盖 ArkWeb 的解析能力),最后 tsc -p tsconfig.types.json 给 npm 消费方产出 types/index.d.ts。

页面侧(example/www/js/index.js)的结构也可以直接用,它演示了双兼容启动和测量打点的写法:

// example/www/js/index.js(节选)
function boot() {
  if (window.cordova) {
    document.addEventListener('deviceready', start, false);  // Cordova 环境等 deviceready
  } else {
    window.addEventListener('load', start);                  // 浏览器直开直接走 load
  }
}

function advance(next) {
  const ms = mark('advance');
  step = next;
  render();
  console.log('LVK-ADVANCE scene=' + current + ' step=' + step +
    ' seq=' + spec.sequence + ' renderMs=' + (mark('advance') - ms).toFixed(1));
}

LVK-* 前缀的打点经 console.log 直达 hilog(ARKWEB-CONSOLE 标签),advance 的渲染耗时、分享触发、就绪探测全在 hilog 里可查——发布前清掉非打点的杂散 log 即可。

使用方 API 全部挂在 window.LiveViewKit 下:

const machine = new LiveViewKit.TaxiScenario();
const spec = machine.specFor(0);            // sequence 自增
LiveViewKit.renderCapsule(capsuleHost, spec);
LiveViewKit.renderCard(cardHost, spec);
const off = LiveViewKit.onSwipeShare(cardHost, (url) => console.log('share', url));
LiveViewKit.specJson(spec);                 // 桥就绪的 JSON,交给原生桥即可上屏

5. 把代码讲透

5.1 状态机:在纯 JS 里实现 kit 的约束

三条场景链路(外卖 5 步、打车 6 步、比分 5 步)与 Flutter / RN 成员逐字段同构——同一套步骤文案、同一套枚举值、同一条 sequence 递增规则。基类只干两件事:

// payload.ts(节选)
export class ScenarioMachine {
  private sequence = 0;
  /** Strictly monotonic: start gets 1, every update bumps by one. */
  nextSequence(): number { return ++this.sequence; }
}

打车场景的分支最能体现"一个场景多种模板":呼叫段是 PickupLayout + TimerCapsule,接单段切车牌强调 + TextCapsule,行程段再切 ProgressLayout + ProgressCapsule——

// payload.ts - TaxiScenario.build(节选)
protected override build(step: number): LiveViewSpecJson {
  const trip = step >= 4;
  const capsule: CapsuleJson = step === 0
    ? { type: CapsuleType.TIMER, status: 1,
        content: TAXI_CAPSULE_CONTENT[0], time: 0, isCountdown: false }
    : trip
      ? { type: CapsuleType.PROGRESS, status: 1,
          progress: step === 4 ? 45 : 100, max: 100,
          content: TAXI_CAPSULE_CONTENT[step] }
      : { type: CapsuleType.TEXT, status: 1,
          title: TAXI_CAPSULE_TITLE[step], content: TAXI_CAPSULE_CONTENT[step] };
  return {
    id: this.id, event: this.event, subEvent: this.subEvent,
    sequence: this.nextSequence(), isMute: this.isMute,
    shareUrl: this.shareUrl,
    lifeCycleMode: LifeCycleMode.AUTO_STOP_WHEN_APP_TERMINATE,
    liveViewData: { primary: { title: TAXI_TITLES[step],
      /* ... content / extensionData / layoutData ... */ }, capsule },
  };
}

vitest 直接断言 JSON 字符串里的字段名与枚举值:expect(specJson(...)).toContain('"layoutType":3')。这一层是三件套的公共语义,任何一个字段漂移都应该在测试阶段失败,而不是等到真机上的卡片渲染错了才发现。

比分场景还有一个跨端共享的设计点:胶囊标题传"数字:数字"('1:0'、'2:1'),6.0.0(20) 起 kit 会自动提取两侧数字渲染成队徽样式——payload 层只保证标题与 hostScore/guestScore 逐字一致(测试里两者锁死在同一个用例里),样式的事交给系统。hostScore 按协议是 string 不是 number,"10:9"这种两位数比分用数字传会在转换器处被拒。

5.2 DOM 预览器:0.5ms 的全量重建

renderCard 每次先 clear(container) 再从 spec 重建整棵子树。样式全部内联(不依赖页面 CSS,jsdom 测试里也能断言到具体样式值),类名留了 lvk-* 钩子给测试与定制:

// live-view.ts(节选)
export function renderCard(container: HTMLElement, spec: LiveViewSpecJson): void {
  clear(container);
  const card = el('div', 'lvk-card');
  card.style.cssText =
    'background:#fff;border-radius:20px;padding:14px 16px;color:#111;' +
    'border:1px solid rgba(0,0,0,.08);box-shadow:0 8px 24px rgba(0,0,0,.10);';
  const primary = spec.liveViewData.primary;
  // ... 固定区 -> 辅助区 -> 扩展区(按 layoutType 分派)
  container.appendChild(card);
}

胶囊渲染器 renderCapsule 是同一个模式的迷你版,三种胶囊类型各走一支——进度胶囊要在胶囊里内嵌一条迷你比例条,这与卡片的大进度条共享同一份 progress/max 数据:

// live-view.ts(节选)
} else {
  const p = cap as ProgressCapsuleJson;
  const ratio = (p.progress ?? 0) / (p.max ?? 100);
  const cEl = el('span', 'lvk-capsule-content',
    p.content ?? `${p.progress ?? 0}/${p.max ?? 100}`);
  pill.appendChild(cEl);
  const barWrap = el('span', 'lvk-capsule-bar');          // 34px 迷你条
  const bar = el('span', 'lvk-capsule-bar-fill');
  bar.style.cssText =
    `display:block;height:4px;width:${Math.round(ratio * 100)}%;background:#fff;`;
  barWrap.appendChild(bar);
  pill.appendChild(barWrap);
}

几个写的时候才意识到的地方:

比分要成对更新。 ScoreLayout 的主客比分是两个独立字段,但语义上永远成对——预览器一次重渲染天然保证一致性,这也是"全量重建优于增量更新"的又一个论据。

jsdom 的颜色归一化。 测试里断言下划线颜色时,jsdom 会把 #FF007DFF 归一化成 rgb(255, 0, 125)——断言写 hex 会永远失败。这是测试代码迁就运行时的小例子,注释里写明白。

detach 也要有。 detach(container) 清空容器——预览器是库不是页面,生命周期得让调用方自己掌握。

5.3 左滑分享:触摸与鼠标双通道

onSwipeShare(card, cb) 返回解绑函数,内部同时挂 touch(真机/模拟器)与 mouse(浏览器预览)两套事件,dataset.lvkShareUrl 携带目标链接,-55px 阈值 + 30px 纵向容差判定:

// live-view.ts(节选)
const end = (x: number, y: number) => {
  if (!dragging) return;
  dragging = false;
  const dx = x - startX, dy = y - startY;
  card.style.transform = '';
  if (dx <= -55 && Math.abs(dy) < 30 && !fired) {
    fired = true;
    const url = card.dataset.lvkShareUrl ?? '';
    if (url) onShared(url);            // 26.0.0 shareUrl 透传
    setTimeout(() => { fired = false; }, 600);
  }
};

vitest 里用 MouseEvent 精确复现了"过阈值触发 / 小拖动不触发"两个用例——这两个用例就是交互规格的可执行版本。

onSwipeShare 返回解绑函数(内部六个监听器成对卸载)——库不是页面,生命周期由调用方管理。这一条和 5.2 的 detach 是同一条规则:渲染可以全量重建,监听必须成对卸载。

5.4 probe:在类型里声明能力不可用

// live-view.ts(节选)
export function probe(): ProbeOutcome {
  return {
    supported: false,
    detail: 'ArkWeb 沙箱不暴露 HMS kits:本插件负责 payload 构造与应用内预览;' +
            '系统发布请将 specJson 交给宿主原生桥(flutter_live_view / live-view-rn 同协议)。',
  };
}

这个函数没有业务逻辑,作用是把能力边界写进返回值。调用方拿到 supported:false 就知道该走预览路径,不会对着一个永远失败的 start 排查半天。

6. 我踩过的坑(每一条都有真实出处)

这一节是 Cordova 端的坑清单,外加这条路线必须面对的边界记录。

坑一:hcordova 拒绝 file 型插件。

File-based plugins not yet supported

plugin add ../ 与绝对路径都触发。JS 模块的手工注入三步(cordova.js / js/ 目录 / script 标签)是唯一通路——这也直接决定了本插件必须 JS-only。

坑二:ArkWeb 白屏过渡帧。 WebView 的 FCP 与合成器上屏之间有间隙,截图可能截到白屏。视觉验证以 uitest dumpLayout 控件树为准(文字在树里再截图),截图时机跟着 hilog 的 PageFirstContentfulPaint 走。

坑三:console.log 会常驻 hilog。 页面的 console.log 直达 hilog(ARKWEB-CONSOLE 标签)——这是测量通道,也是发布前的清理项。保留 LVK-* 前缀的打点,其余清掉。

坑四:jsdom 颜色归一化。 测试断言 borderBottom 包含 #FF007DFF 永远失败——jsdom 归一化成 rgb(255, 0, 125)。断言跟着运行时的规范化走。

坑五:宿主应用名要全局改。 AppScope/app.json5 的 bundleName、AppScope 与 entry 两处 string.json 的 label——改了 config.xml 不会跟着变(坑的变体:改了一处漏三处)。

坑五点五:OneDrive 目录里的构建产物。 工作区在 OneDrive 下,整树拷贝构建副本会慢到怀疑人生(回灌几十分钟);构建只拷需要的子树(宿主的 entry / AppScope / 配置文件),node_modules 千万别用 robocopy 的 /XD build 排除——那会把依赖里所有同名 build 目录一起杀掉,症状是运行时 Cannot find module。

坑六(边界记录,非缺陷):系统发布在 WebView 里结构性不可达。 probe() 如实回答 supported:false。同一次提交里,同一份 payload 语义在 flutter 成员侧真实发布成功(start result 0 success.,状态栏胶囊 / 锁屏卡片实拍在 flutter 成员仓库的 docs 里)——payload 契约是系统可用形态,Cordova 端只欠一个原生桥,欠的原因写在这条记录里。

欠的这个原生桥可以很短。任何一个 Cordova-ohos 宿主,只要在 EntryAbility 里加十行 ArkTS 胶水,把页面的 specJson 接到 kit 上,预览的那条实况窗就真的上屏了:

// 宿主原生桥示意(伪代码级,API 均真实存在)
import { liveViewManager } from '@kit.LiveViewKit';
import { wantAgent } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

// 页面侧:window.LiveViewKit.specJson(spec) -> 任意通道 -> 这里
async function publish(op: string, specJson: string): Promise<Object> {
  const spec = parseSpec(specJson);        // 与 flutter 成员的 LiveViewCodec 同款逐字段装配
  spec.liveViewData.primary.clickAction =  // 运行时必传(见 401 清单)
    await wantAgent.getWantAgent({ wants: [{ bundleName: '宿主包名',
      abilityName: 'EntryAbility' }], operationType: wantAgent.OperationType.START_ABILITY });
  const r = op === 'start'
    ? await liveViewManager.startLiveView(spec)
    : await liveViewManager.updateLiveView(spec);
  hilog.info(0x0000, 'LVKBridge', '%{public}s -> %{public}d', op, r.resultCode);
  return r;
}

这样分层之后,payload 层一行不改,桥接层补上即可。层与层之间的契约(specJson)已经用 18 个测试钉死,桥的成败只取决于桥自己。
再回答三个被问得最多的问题:

问:既然摸不到系统服务,这个库的价值是什么? 答:两件事。payload 契约是三端公共语义的 JS 参照实现(React/Vue/任何 Web 技术栈都能直接用它产出合规 spec);预览器让"实况窗会渲染成什么样"在任何一个能跑网页的地方变成可见的——包括 CI 里的无头浏览器。

问:specJson 的输出未来会不会变? 答:它跟随 kit 的 d.ts 演进,新增字段只会向后兼容地追加(26.0.0 加的 shareUrl/subEvent/lifeCycleMode 就是这么进来的);既有字段名与枚举值被 18 个测试钉死,破坏性变更会在 major 版本里做。

问:想在 Cordova 里直接发布,现在最快的多久能通? 答:写一个十行的 ArkTS 原生桥(见上文示意)把 specJson 递给 kit——payload 层不用改,401 清单(运行时必传字段)照着核一遍即可。工具链的 file 插件限制只挡"插件分发形态",不挡"宿主内自己写桥"。

坑七:生成脚本的转义错位。 build 脚本里用 join('\n') 拼 footer 时,若被写成了真实换行,产物直接 SyntaxError。生成完立刻 node --check 一次,能省掉十分钟排查。

坑七点五:把"系统不可达"写成类型而不写成弹窗。 最早的版本在 probe() 失败时弹过一个 alert——调用方(页面)根本没机会决定怎么呈现。改成返回 ProbeOutcome 后,页面把它渲染成徽章、渲染成说明文字、或者干脆静默,都是页面的事。库只返回数据,怎么显示由页面决定。

坑八:跨用例的缓存残留。 预览/探测类库做单例缓存时,vitest 的用例间残留会让"第二次 probe"命中第一次的缓存——要么提供 dispose() 归零,要么测试里显式重置。本插件的 probe() 是纯函数(无缓存),天然免疫;renderCapsule/renderCard 是纯重建,同理。纯函数没有缓存,测试不用额外清理。

7. 现在怎么用:从 三方库 到依赖

npm 形态(files 里带 www/types/plugin.xml),file / git 依赖直接用:

npm install ../live-view-cordova
# 宿主注入(hcordova 1.0.7 手工三步):
#   1) cordova.js 保留在 rawfile/www/
#   2) www/live-view-kit.js -> rawfile/www/js/
#   3) index.html 加 <script src="js/live-view-kit.js"></script>

specJson(spec) 的输出与 flutter_live_view / live-view-rn 的桥协议字节级同构——找一个原生桥(哪怕是自己写十行的 ArkTS 胶水)把它递给 liveViewManager.startLiveView,网页里预览的那条实况窗就真的上屏了。三条场景的 TypeScript 类型(types/index.d.ts)随包分发,React/Vue/任何 Web 技术栈照着类型拼 spec,同样能产出合规 payload。这个库的产物可以当三种东西用:Cordova 页面的插件、Web 工程的实况窗构造器、以及跨端团队的对齐文档——三个身份共享同一套 18 个测试。完整 API、测试清单与排错说明在仓库文档里:
实况窗路径文档(技术路线分工)、包检查记录(结构与注入核对)、
验证记录(实测记录与边界);三库对照的系列总览在
HarmonyOS 新能力实况窗/docs/ 的统一篇里。

下一步:onSwipeShare 的阈值与回弹可配置化、预览器支持 TimerCapsule 的
秒级走针(当前是静态时钟渲染)、以及等 hcordova 的原生插件注入通路打通后,
把"payload 构造 + 原生发布"闭环也搬进 Cordova——payload 层一行都不用改,
这就是把构造和发布分层的好处。

最后附自检清单——本文所有环节的浓缩,接手的人按这六条走一遍,
交付是否健康一目了然:

  1. deviceready ✓ 徽标亮起,probe() 如实显示"预览模式(沙箱不暴露
    HMS kits)",绝无假装支持;
  2. 三场景(外卖 / 打车 / 比分)步骤推进,胶囊与卡片 DOM 同步重渲染,
    每步 0.5~0.6ms(ARKWEB-CONSOLE 打点可见);
  3. payload JSON 面板逐字段可核对(event / subEvent / sequence /
    layoutType / capsule.type 与 kit 枚举对得上);
  4. 左滑分享交互可用,shareUrl 为 HTTPS 且 <128 字符;
  5. specJson(spec) 与三端桥协议字节级同构(vitest 断言 "layoutType":3
    等 18 条);
  6. 浏览器直开与 deviceready 双兼容,宿主包名与 label 全局改净。
Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐