# Rex 首页 HTML 模块作者指南

本文按 2026-11-20 的客户端源码说明 HTML 卡片的制作、预览和 `.rex` 首页包导入。导入需要包含 HTML 首页支持的 Rex 版本。

内容索引：[快速开始](#快速开始) · [数据](#数据字段) · [图片](#图片如何使用) · [尺寸](#尺寸声明) · [交互](#交互可以做到哪里) · [预算](#性能与硬限制) · [导入首页](#导入首页) · [原生接入](#开发者如何挂载) · [验收](#验收与排错)

## 先分清两种模块

| 层 | 负责什么 | 作者交付什么 |
| --- | --- | --- |
| 数据模块 | 按既有模块协议获取片单、补齐 TMDB 元数据、处理来源参数和分页 | 现有 RexScript JavaScript 数据模块 |
| HTML 展示模块 | 接收当前页元数据和实际卡片尺寸，展示封面、文字和有限交互 | 一个内联 CSS/JS 的 HTML 文件 |
| Rex 宿主 | 数据加载、认证、图片准备、尺寸计算、生命周期、动作鉴权和原生绘制 | App 接线，由开发者维护 |

数据流：`数据模块 / TMDB → 宿主准备元数据与图片 → RexWidget.content/layout → HTML 卡片`。

HTML 不再次访问 TMDB。预告、播放地址和播放器参数不进入展示协议。缺字段时不要编造评分、片名、观看进度或画质标签。

iOS、iPadOS、tvOS、macOS 都有原生运行路径；它不是 WKWebView，也不是完整 Safari。QuickJS 执行作者脚本，DOM/CSS 操作经校验后交给原生 litehtml 后端。浏览器效果成功只证明浏览器排版成功。

## 快速开始

在工作台的「载入示例」选择 [简单封面卡](../assets/widget.html)、[全宽单卡](../assets/full-width.html) 或 [全宽高海报横滑](../assets/rail-item.html)。全宽单卡用一张横向大图配片名和详情按钮，高度从 HTML 声明读取。横滑示例用 2:3 竖海报，宿主负责排成一行并滚动。三份 HTML 都从宿主读取数据。

在 HTML 中声明承载方式与尺寸：

```html
<!-- 网格卡片：宽高各自使用 x1～x4 -->
<meta name="rex-widget" content="type=card; width=x2; height=x2">
```

```html
<!-- 全宽横滑：420 是整个 item 的高度 -->
<meta name="rex-widget" content="type=rail; height=420; item-ratio=2:3">
```

类型、尺寸与材质写在同一个标签中。画布只读显示源码声明，点击「代码声明」可查尺寸示意与用法、复制声明；不会更改源码。缺失、重复或不合法的声明拒绝应用，保留上一版预览。手机服务同样从 HTML 推导尺寸，调用方不能覆盖。原生接线尚需编译与真机验收。

创作顺序：先在 HTML 声明承载方式和尺寸并确定目标平台 → 将宿主字段绑定到自己的 HTML 元素 → 编写 CSS → 接入已开放的按钮动作 → 检查缺数据 → 导出单文件 HTML。网页为源码与画布组成的 IDE 工作台：类型只读显示，平台与测试数据位于画布侧，主界面不展示教学栏。面板独立滚动，分隔条可以拖动，可在「预览 / 源代码 / 并排」间切换，⌘ / Ctrl + Enter 应用源码：粘贴完整 HTML、选择或拖入 HTML 文件，即可用本地样本预览自己的卡片；未连接手机时，文件只在浏览器内读取；显式开启「手机预览」后，源码会发送到当前局域网创作服务，再由手机读取。直接在源码中修改 CSS；「复制我的 HTML 源码」或下载文件包含已应用的 CSS 和固定文案，不包含样本片单、图片或浏览器宿主。若局域网 HTTP 下载被浏览器拦截，可复制源码到编辑器并保存为 `.html`，无需绕过浏览器警告。

1. 复制 [widget.html](../assets/widget.html)，保留一个 HTML 文件，CSS 和 JavaScript 都写在其中。无需 npm 或前端框架。
2. 保留 `RexWidget` 事件接线，修改布局与文字呈现。模板默认显示当前页第一条，空数据给出中性占位；详情按钮按宿主 canOpen 能力启用。
3. 打开 [排版预览器](../assets/preview.html)，选择自己的 HTML，类型从 HTML 声明读取，再选择参考平台，切换合成样本/空列表，或粘贴协议 JSON。网页版本可直接使用；离线使用时保持作者包中的 `preview.html`、[preview.js](../assets/preview.js) 、[preview-layouts.js](../assets/preview-layouts.js) 和 [template.js](../assets/template.js) 同目录，再用浏览器打开 `preview.html`。
4. 可选择一张本地图片，替代预览器自己的 `icon:preview.cover` 样本。该映射仅在工具内有效，成品 token 必须来自宿主。预览器不发网；不要粘贴令牌、账号或原始播放数据。
5. 只检查自己声明支持的尺寸，并在计划支持的平台逐个预览。覆盖长标题、无封面、无评分与数据晚到；不必让每个模板覆盖全部尺寸。预览器的切换与导航都只是 mock；实际开放能力以 App 宿主的绑定为准。
6. 在局域网创作服务打开工作台后，使用同一 Wi-Fi，点网页「手机预览」并用手机相机扫码，在连接页点「在 Rex 中打开」。新版 Debug iOS/iPadOS App 会从当前页面打开独立预览页，直接使用网页当前的 TMDB 样本和封面。修改源码后自动更新，画布使用手机回传的实测尺寸。手机预览里的卡片按钮展示点击目标。网页断开、手机点「关闭」、会话到期或切换环境时，预览结束。这个开发入口仍需原生编译与真机验收。
7. 下载 HTML 后，按下文打包并导入 Rex。

预览器使用独立 iframe 与 mock API；只替换 `img` 上的样本图片 token，不提供完整资源解析器。不执行原生沙箱配额和 CSS 校验，不验证 TV 焦点、合成提升、进程内存或实际帧率。输入宽高是逻辑排版尺寸，不是设备模拟器。

## 运行时 API

| API | 用途 |
| --- | --- |
| `RexWidget.content` | 当前内容 `{items:[...]}` 的副本；初始可能为 `null` |
| `onContentChanged(fn)` / `offContentChanged(fn)` | 订阅/取消内容变化；回调中重新读取快照 |
| `RexWidget.layout` | 当前布局副本，可能为 `null` |
| `onLayoutChanged(fn)` / `offLayoutChanged(fn)` | 宿主改变卡片尺寸或布局环境时通知 |
| `RexWidget.state` | 宿主提供的 JSON 状态；可能为 `null` |
| `onStateChanged(fn)` / `offStateChanged(fn)` | 订阅/取消状态更新 |
| `RexWidget.canOpen(target,id?)` | 查询当前实例是否声明了该导航目标，不能代替点击时校验 |
| `RexWidget.open(target,id?)` | 向宿主打开已绑定的作品、人物或模块列表 |
| `RexWidget.request(action)` | 请求宿主白名单动作，返回 `Promise<string|null>`，可能拒绝 |

修改这些副本不会写回宿主，作者 API 没有 `setState`、`setContent` 或 `setLayout`。局部变量可保存临时 UI 状态，但不要假定它能跨实例、离屏回收或重启保留，也不要依赖持久存储。

先订阅，再初次渲染。内容在作者脚本安装后异步送达，不能只在加载时读一次：

```js
function render() {
  var snapshot = RexWidget.content; // 每次 render 只读一次；getter 会复制整页
  var items = snapshot && snapshot.items ? snapshot.items : [];
  var item = items[0];
  document.getElementById('title').textContent =
    item ? (item.title || '未提供标题') : '暂无内容';
}
RexWidget.onContentChanged(render);
render();
```

不要把标题、简介等模块文本拼入 `innerHTML`。若支持选中项，内容更新后按原始 `id/type` 核对；选中项被删除或列表重排时，回到有效条目。状态索引必须校验范围，不能沿用旧页越界索引。

## 数据字段

根对象为 `items` 数组。下表列出可用的字段，可选字段可能缺失、数组可能为空：

| 字段 | 类型 / 含义 |
| --- | --- |
| `id`、`type` | 字符串，保留来源原始身份；不要把数字猜成 TMDB ID |
| `mediaType` | 可选字符串，媒体类型 |
| `title`、`description` | 可选字符串，片名与简介 |
| `coverUrl` | 可选封面 `icon:` token；名字带 Url 不代表可发网 |
| `coverRatio` | 可选数字，来源封面比例提示 |
| `posterPath`、`detailPoster` | 可选海报 token |
| `backdropPath`、`backdropPaths` | 可选背景 token、背景 token 数组 |
| `releaseDate` | 可选字符串，上映日期；不要假设所有来源格式相同 |
| `rating` | 可选数字。缺失时隐藏 |
| `criticRating`、`audienceRating` | 可选整数，来源提供的媒体评分 |
| `titleLogoPath` | 可选 Logo token |
| `watchProgress` | 可选观看进度，取值 0～1 |
| `genreTitle`、`genreItems` | 可选分类文字；分类数组项为 `{id,title}` |
| `peoples` | 人物数组，项为 `{id,title,avatar?,role?}` |
| `duration`、`durationText` | 可选时长，数值单位秒；也可用来源的可读文案 |
| `season`、`episode` | 可选数字，季/集信息 |
| `language` | 可选字符串 |

合成输入示例（仅供预览，不是 TMDB 身份样例）：

```json
{
  "items": [{
    "id": "preview:one",
    "type": "preview",
    "title": "合成样本 · 长标题排版检查",
    "description": "用于检查缺图、换行和尺寸变化，不代表真实影视数据。",
    "posterPath": "icon:preview.cover",
    "genreTitle": "合成分类",
    "durationText": "样本时长"
  }]
}
```

导入首页包的宿主目前提供片名、简介、年份、类型、评分、海报和横图，部分原生对应模板会提供 Logo。评分扩展字段与观看进度依赖宿主实际提供。不递归提供 `childItems`、`episodeItems`、`relatedItems`。不提供 `videoUrl`、`previewUrl`、`link`、`trailers`、`trailerUrls`、`playerType`、`customHeaders`、`externalSubtitles`。

通用协议每页最多 64 条，JSON ≤64 KiB，超限整页拒绝。当前真实模块实验室只取每页前 **24 条非 text 条目**，原生页头显示展示数/原始数；这不是所有接入场景的统一条数上限。

## 图片如何使用

宿主从既有缓存与认证图片管线准备可信资产，HTML 只收到 `icon:名称`：

```js
var poster = item.posterPath || item.detailPoster || item.coverUrl;
if (poster) image.setAttribute('src', poster);
else image.removeAttribute('src');
```

根据版式选择海报或背景。未映射路径会被省略；缺图时保留占位和标题，不自行补远程地址、data URL、本地路径或猜测 token。

宿主在提供图片 token 前登记资产。导入首页的卡片会先收到元数据，随后随图片到达更新内容。当前协议不承诺作者可动态注册新图片。实验室换数据页由宿主管理相应图片和会话。

通用预算：单张原始资产 ≤48 KiB，展开 data URL ≤64 KiB，实例内全部展开资产合计 ≤2 MiB。当前实验室最多准备 24 张封面和 24 张背景，以 JPEG 最长边 512/384/256 降档、单张原始数据 ≤24 KiB，最多三个图片任务并行。人物文字可用不等于头像一定已准备。

### 使用 Rex 内置取色和渐进模糊

在 HTML 的 `head` 声明要用的效果。可用 `palette` 取色、`bottom-blur` 渐进模糊和 `background-blur` 整图背景柔化。用逗号组合需要的效果。

```html
<meta name="rex-artwork" content="palette,bottom-blur">
```

`RexWidget.artwork(token)` 接收原来的 `icon:` 图片 token。取色返回十六进制的 `background` 和 `foreground`。渐进模糊返回可直接用作图片 `src` 的 `bottomBlur` token。它由宿主在原图上预先处理，从图高 60% 到底部逐渐增强。`background-blur` 返回 `backgroundBlur` 图片 token，适合放在堆叠海报和标题背后。它提供低分辨率柔化底图，透明度和明暗由卡片设置。先显示原图或默认底色，再用 `onArtworkChanged` 接收后台结果。

```js
function render() {
  const token = RexWidget.content?.items[0]?.backdropPath;
  const style = RexWidget.artwork?.(token);
  panel.style.backgroundColor = style?.background || '#151922';
  panel.style.color = style?.foreground || '#ffffff';
  if (token) image.setAttribute('src', style?.bottomBlur || token);
  else image.removeAttribute('src');
}
RexWidget.onContentChanged(render);
RexWidget.onArtworkChanged?.(render);
render();
```

图片未登记、效果尚未就绪或超出实例图片预算时，按缺失字段使用原图或占位。效果只读取宿主已经登记的图片。网页工作台「列表预览 - 超大」可预览浏览器近似效果。离线排版预览器使用原图和默认配色。


## 尺寸声明

参考列表见 [sizes.json](sizes.json)：

| 承载 | 源码声明 | 数据与排版 |
| --- | --- | --- |
| 非全宽卡片 | `type=card; width=x2; height=x2` | 宽高分别为 x1、x2、x3、x4，按宿主网格对齐；接收当前页 |
| 全宽单卡 | `type=full-width; height=420` | 宽度填满宿主可用整行；接收当前页 |
| 全宽横滑 | `type=rail; height=420; item-ratio=2:3` | 宿主负责整行滚动与可见性；每个 HTML 实例只接收自己的 `items[0]` |

非全宽不能填任意像素高度。x 档位包含宿主网格间距；作者不复制计算公式，也不选择原生模板名。宽、高分别选择，例如 `width=x3; height=x2`。示例只做好自己声明的尺寸，不要求覆盖所有组合。

全宽高度使用整数逻辑点。当前宿主默认接受 96～960，再限制为可用容器高度的 85%（最少96），避免占得过高；实际以 `layout.height` 为准。横滑 item 的 `item-ratio` 为宽:高，允许 1:3～3:1，过宽时等比缩小到可用行宽。示例 `420` 配 `2:3` 得到 280×420 的 item。不能在 HTML 内横向滚动或自行抓下一页。

常用 `RexWidget.layout` 字段：

```text
module.id           card / full-width / rail
platform            目标平台
width, height       当前 HTML 实例的实际逻辑宽高
fontScale           字号倍率
cornerRadius        App 指定的外框圆角，只读
```

横滑的 width/height 是单个 item，整行宽度由宿主承担。单卡直接按 width/height 安排内部元素。逻辑 CSS px 对应宿主 pt，不乘 DPR；字号倍率只应用一次。监听 onLayoutChanged，不只在加载时读取尺寸。卡片外框由 App 裁切，不自行覆盖外框圆角。

旧17种原生模板 ID 仅为兼容旧实验资源保留，不作为新作者入口；完整旧推荐卡 [showcase.html](../assets/showcase.html) 继续使用 poster-collage。新声明需包含对应尺寸协议的客户端。浏览器预览不代表原生校验、排版、TV 焦点或性能已验收。

### 卡片背景玻璃

想让整张卡片坐在系统原生玻璃上（和首页其他玻璃卡同一种材质），在 HTML 里声明：

```html
<meta name="rex-widget" content="type=card; width=x2; height=x2; background=glass">
```

- `background=glass` 是标准玻璃，`clear-glass` 更通透。玻璃的形状就是 App 统一的卡片圆角，作者不能指定。
- 卡片位图本身透明，**不要给 html/body 或最外层容器铺不透明底色**，否则玻璃被盖住。需要压暗时用半透明渐变。
- 材质由宿主绘制：iOS/tvOS 26 是 Liquid Glass，更早系统是模糊材质，「减弱视觉效果」时是平涂；明暗跟随宿主主题。它不占 heavy/backdrop 预算，但只采样卡片后面的首页，不采样卡片里的 HTML。
- 浏览器预览器不绘制这层材质，玻璃观感只能在 App 里看。

## 交互可以做到哪里

跨平台动作使用真实 `<button>`，提供可读文字或 `aria-label` 和清楚的焦点样式。tvOS 用方向键移动焦点、确认键激活，不要只做 hover，也不要用可点击 div 替代按钮。任意拖动、长按、输入框、滚轮和卡片内部滚动不是当前跨平台保证；外层滚动与分页归宿主。

`request` 必须源于真实原生用户激活，动作名 1–64 UTF-8 字节且在宿主白名单内，最多一个请求在途。处理拒绝并避免连发。导航目标由当前页宿主绑定。导入后的首页开放作品详情和来源列表。下表也包含真实模块实验室和局域网预览演示的动作：

| 动作 | 含义 |
| --- | --- |
| `previous` | 切到当前数据页的上一条 |
| `next` | 切到当前数据页的下一条 |
| `open('item', item.id)` | 按当前页作品的原始 id 打开原生详情 |
| `open('person', person.id)` | 按人物自身 id 打开人物；适用于人物条目及作品的 peoples 成员 |
| `open('list')` | 用当前数据模块打开完整原生列表 |

该入口状态约定为 `{index:n}`，这不是所有宿主的通用 schema。index 只管理卡片内部当前选中项，导航始终传 id；不把 Promise 返回值当条目数据或播放器结果。

可选按钮接线（需宿主启用这两个动作，并在自己的 render 中校验 state.index）：

```html
<style>button:focus-visible { outline: 3px solid #fff; outline-offset: 2px; }</style>
<button id="next" aria-label="下一张封面">下一张</button>
<script>
var busy = false;
document.getElementById('next').addEventListener('click', function () {
  if (busy) return;
  busy = true;
  RexWidget.request('next').then(function () {
    busy = false;
  }, function () {
    busy = false;
    // 在自己的状态文字区域提示请求未完成，不虚构成功结果。
  });
});
// 将同一个 render 订阅到 onStateChanged；render 的实现见自己的模板。
</script>
```

导航直接使用宿主给的 `item.id` 或 `person.id`，保持原样的非空字符串；不传数组位置，也不把任意数字猜成 TMDB ID。未知 ID 或同一个 ID 对应多个不同导航对象时拒绝。同一人物在多个作品中重复出现、且来源相同时可复用绑定。宿主保留原始作品、人物和模块配置，列表从原模块完整第一页开始加载。模块人物沿用模块的人物来源；数字 ID 不会自动成为 TMDB 人物。缺 ID / 人物名、配置改变、切换首页/环境、过期或已退场的实例会拒绝。更换数据页时重新建立会话和导航绑定。首页宿主渐进填充同一组作品的封面时，原有导航继续有效。

可用 `canOpen` 控制按钮是否启用，但它只是能力提示，点击仍要处理拒绝：

```js
var button = document.getElementById('open-item');
// item 来自当前 RexWidget.content；render() 中同步 disabled
button.disabled = !item || !RexWidget.canOpen('item', item.id);
button.addEventListener('click', function () {
  RexWidget.open('item', item.id).catch(function () {
    document.getElementById('notice').textContent = '无法打开当前条目';
  });
});
// 人物条目或作品中的演员：open('person', person.id)
// 当前模块列表：open('list')
```

网页演示会显示「作品详情 / 人物页 / 模块列表」模拟目标，不执行 App 导航。手机需要包含本次接线的 Debug App；原生事件与各平台目的页尚需运行验收。

原生页面“下一页”请求数据模块的新页；HTML 的 `next` 只切已经加载的封面。本地演示的 `save`、`resume`、`select:*` 是模拟动作，不是正式业务接口。没有任意 URL、`play` 或加入待看能力；`RexWidgetSession` 默认动作白名单仍为空。导航请求使用 `open` 助手，只能提交当前数据中已绑定的原始 ID，不能指定页面类名或任意目标 URL。ID 本身可以包含中文、分隔符或原始 URL 字符串；它仍只用于查找绑定，不直接作为导航地址。

## 性能与硬限制

| 项目 | 当前边界 |
| --- | --- |
| 作者 HTML | ≤32,768 UTF-8 字节、无 NUL；CSS/JS 内联，中文按字节计 |
| JS 堆 | 8 MiB，不代表整个组件或进程总内存 |
| 单任务 / CPU 配额 | 500 ms / 每 1000 ms 最多 300 ms CPU |
| 绘制复杂度 | strict 策略 heavy box ≤16、backdrop box ≤2；按计算样式/效果计数，不等于 DOM 节点数 |
| 内容 / 状态 | 内容 ≤64 条、64 KiB；宿主状态 JSON ≤1024 UTF-8 字节 |
| 有效卡片尺寸 | 内核宽 50…4096、高 50…2048；作者全宽高度另受上述保护策略约束 |

使用简单定位、常见文字/图片样式和小范围渐变，再在原生确认支持。不以完整浏览器 CSS、DOM 或 Web API 为基线，不引入 React/Vue、外部脚本、样式和字体。没有网络、文件、任意导航、播放器或支付能力，不依赖持久存储。

动画优先短暂的 transform/opacity，保持已有 DOM 与图片节点，数据变化时才更新文字。避免逐帧读几何再写布局、持续改 width/height、无限计时器、整页重写，以及多层模糊/阴影/裁剪叠加。不是每个动画都能原生合成；请求 120 Hz 不等于实测达到 120 FPS。

宿主可暂停离屏组件、回收运行时并暂用缓存截图。截图只是在准备时占位，不赋予交互能力。不要用动画时钟驱动数据加载，不要为通过演示取消校验或调高配额。30 卡滚动页是独立压力场景，首帧准备、峰值内存与呈现帧率仍须实测。

## 导入首页

工作台的「下载 HTML」保存一张卡的源码。Rex 的「导入首页列表」接收整个 `.rex` 首页包。可以用[默认首页 HTML 示例](https://assets.rexnow.tv/home-examples/default-home-zjgiqmt3/Rex-Default-Home-HTML.rex)验证导入入口。

1. 从 Rex 导出已有的首页配置作为基础，导出时关闭包含账号的选项，保留待绑定卡片的数据来源和查询参数。
2. 解开归档，把模板放到 `rex-html/`，例如 `rex-html/my-card.html`。在 `rex-layout.json` 的对应卡片添加 `"htmlTemplate": "my-card.html"`，并对齐下表中的配置。
3. 把 `rex-manifest.json` 中的 `version` 改为 `2`，保留原有 `format`。重新打成 ZIP，使用 `.rex` 文件扩展名。manifest、布局和首页信息仍须位于归档根目录。
4. 在支持 HTML 首页的 Rex 中打开「导入首页列表」。选择文件或粘贴首页包直链。导入会新增一套首页，切换到它即可查看真实数据。再次导出时会带上 HTML 模板。

| HTML 声明 | 布局中的卡片配置 |
| --- | --- |
| `type=card; width=x2; height=x2` | `style: "cover"` 和 `gridSize: [2, 2]`。同一行的 HTML 卡片须使用相同宽高档位 |
| `type=full-width; height=420` | 行内一张卡，`style: "cover"`，`gridSize` 的宽度为 `-1` |
| `type=rail; height=420; item-ratio=2:3` | 行内一张卡，`style: "fullWidthPoster"`，`gridSize` 的宽度为 `-1` |

全宽高度和横滑比例以 HTML 声明为准。工作台目前只有单卡 HTML 导出，导入前需要打包步骤。向现有首页直接追加 HTML 卡片尚无操作入口。

## 开发者如何挂载

这一节需要 App 源码接入，不是普通用户操作入口。

1. 将 HTML 加入 `RexWidgets` 包资源，通过包内资源加载。当前真实实验室固定使用 `LiveCovers.html`；选数据源不会更换模板。
2. 沿既有模块链加载 `[MediaItem]` 并补齐 TMDB，准备 `RexWidgetImageAsset` 与原路径到资产名的映射，不把认证/播放字段交给 HTML。
3. 用首页尺寸适配器得到 `RexWidgetLayout`，用 `RexModuleWidgetContent` 投影字段，再创建并持有 session。以下是示意，变量由宿主准备，需要在既有 MainActor 页面内接线：

```swift
let content = try RexModuleWidgetContent.makeContent(
    from: moduleItems, imageNames: [posterURL: "poster.0"])
let session = try RexWidgetSession(
    html: authorHTML,
    layout: hostLayout,
    content: content,
    imageAssets: ["poster.0": preparedPoster])
```

4. 默认只读。交互需声明 `allowedActions` 并实现 `onRequest`，用宿主 `setState` 更新状态；内容/尺寸用 `setContent`/`setLayout` 更新。新图超出现有登记集时由宿主管理新会话。
5. 使用现有宿主视图安装、可见性和销毁接线，不只创建 session 就认为已展示。快速换来源时取消旧加载，防止晚到数据覆盖。

Debug 验收入口：**设置 → 实验室 → 真实模块卡片**。它读取当前首页已配置的脚本模块；先在首页加数据模块，再切来源/数据页看真实封面。原演示和“30 张卡片 · 滚动测试”保留，不能用演示正常代替真实数据验收。

Debug 局域网实时预览使用一张临时卡片，关闭即结束。需要保留卡片时，使用上文的首页包导入流程。

## 验收与排错

静态检查与原生验收分开记录，未运行的写“待验收”。不要把浏览器视觉正确或源码接线完成说成全平台通过。

| 检查 | 预期 |
| --- | --- |
| 首次 content 为 null，随后送达 | 有中性加载/空态，数据到达自动显示 |
| 空页、缺图、缺评分、超长标题 | 不串旧图、不编造数据、不溢出 |
| 替换/重排/移除选中项 | 目标按原始 id 绑定，无旧条目或错误导航残留 |
| 声明支持的尺寸、平台和字号变化 | 布局清楚、不裁掉主标题；不要求覆盖所有尺寸 |
| iOS 首张点击、滚离再返回 | 有授权动作时，首次和回看都响应 |
| Mac 点击、窗口缩放、跨屏 | 命中与视觉一致，尺寸更新正确 |
| TV 方向键/确认 | 焦点可见、按钮可达、动作发生一次 |
| 快速换来源/翻页/返回 | 数据、封面不被晚到请求覆盖 |
| 30 卡滚动 | 分别观察准备长帧、滚动、内存和回看交互，不仅看请求刷新率 |

常见问题：

- **黑屏/停更**：核对 HTML 字节、JS 错误和原生配额/校验诊断，去掉新增复杂效果定位，不取消限制。
- **网页与 Duo 大小不同**：对齐实际 width/height、字号、当前内容与模板版本，不把视口/参考尺寸当卡片尺寸。
- **有标题没封面**：检查图片是否准备、token 是否登记，HTML 不自行发网补图。
- **按钮无效**：核对白名单/handler 和原生准备状态，再看首张/回看差异，不以延迟或伪造用户激活解决。
- **卡顿**：分测首帧准备与持续动画，减少重排、DOM 重建与高开销绘制。浏览器 FPS 不代表原生 FPS。

## 维护者实现入口

以下是源码仓库相对路径，可分享包不包含这些文件：

- `docs/logic-contracts/html-widgets.md`：内核与平台契约。
- `Packages/RexWidgets/Sources/RexWidgets/Resources/RexWidget.js`：公开 JS API。
- `Packages/RexWidgets/Sources/RexWidgets/RexWidgetContent.swift`：展示字段与内容预算。
- `Packages/RexHome/Sources/RexHomeCore/RexModuleWidgetContent.swift`：原始模块到展示数据的投影。
- `Packages/RexWidgets/Sources/RexWidgets/RexWidgetLayout.swift`、`Resources/WidgetModules.json`：布局与预设。
- `Packages/RexWidgets/Sources/RexWidgets/RexWidgetSession.swift`、`RexWidgetImageAsset.swift`：HTML、动作、状态与图片限制。
- `Packages/RexWidgets/Sources/RexWidgets/RexWidgetLiveLabViewController.swift`、`Resources/LiveCovers.html`：实验入口与当前模板。
