协议快照:2026-11-18,实验内核及真实模块数据接口(源码基线 78eb2890)。本文面向卡片作者;这是一套实验协议,尚未作为正式用户导入格式发布。
内容索引:快速开始 · 数据 · 图片 · 尺寸 · 交互 · 预算 · 原生接入 · 验收
先分清两种模块
数据流:数据模块 / TMDB → 宿主准备元数据与图片 → RexWidget.content/layout → HTML 卡片。
HTML 不再次访问 TMDB。预告、播放地址和播放器参数不进入展示协议。缺字段时不要编造评分、片名、观看进度或画质标签。
iOS、iPadOS、tvOS、macOS 都有原生运行路径;它不是 WKWebView,也不是完整 Safari。QuickJS 执行作者脚本,DOM/CSS 操作经校验后交给原生 litehtml 后端。浏览器效果成功只证明浏览器排版成功。
快速开始
在工作台的「载入示例」选择 简单封面卡、全宽单卡 或 全宽高海报横滑。全宽单卡用一张横向大图配片名和详情按钮,高度从 HTML 声明读取。横滑示例用 2:3 竖海报,宿主负责排成一行并滚动。三份 HTML 都从宿主读取数据。
在 HTML 中声明承载方式与尺寸:
<!-- 网格卡片:宽高各自使用 x1~x4 -->
<meta name="rex-widget" content="type=card; width=x2; height=x2">
<!-- 全宽横滑: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,无需绕过浏览器警告。
- 复制 widget.html,保留一个 HTML 文件,CSS 和 JavaScript 都写在其中。无需 npm 或前端框架。
- 保留
RexWidget 事件接线,修改布局与文字呈现。模板默认显示当前页第一条,空数据给出中性占位;详情按钮按宿主 canOpen 能力启用。
- 打开 排版预览器,选择自己的 HTML,类型从 HTML 声明读取,再选择参考平台,切换合成样本/空列表,或粘贴协议 JSON。网页版本可直接使用;离线使用时保持作者包中的
preview.html、preview.js 、preview-layouts.js 和 template.js 同目录,再用浏览器打开 preview.html。
- 可选择一张本地图片,替代预览器自己的
icon:preview.cover 样本。该映射仅在工具内有效,成品 token 必须来自宿主。预览器不发网;不要粘贴令牌、账号或原始播放数据。
- 只检查自己声明支持的尺寸,并在计划支持的平台逐个预览。覆盖长标题、无封面、无评分与数据晚到;不必让每个模板覆盖全部尺寸。预览器的切换与导航都只是 mock;实际开放能力以 App 宿主的绑定为准。
- 同一 Wi-Fi 下,点网页「手机预览」并用手机相机扫码,在连接页点「在 Rex 中打开」。新版 Debug iOS/iPadOS App 会从当前页面打开独立预览页,直接使用网页当前的 TMDB 样本和封面。修改源码后自动更新,画布使用手机回传的实测尺寸。手机预览里的卡片按钮展示点击目标。网页断开、手机点「关闭」、会话到期或切换环境时,预览结束。这个开发入口仍需原生编译与真机验收。
- 正式接入仍把 HTML 交给接入开发者。当前没有生产版用户导入或作者发布服务;接入后的原生验收见后文。
预览器使用独立 iframe 与 mock API;只替换 img 上的样本图片 token,不提供完整资源解析器。不执行原生沙箱配额和 CSS 校验,不验证 TV 焦点、合成提升、进程内存或实际帧率。输入宽高是逻辑排版尺寸,不是设备模拟器。
运行时 API
修改这些副本不会写回宿主,作者 API 没有 setState、setContent 或 setLayout。局部变量可保存临时 UI 状态,但不要假定它能跨实例、离屏回收或重启保留,也不要依赖持久存储。
先订阅,再初次渲染。内容在作者脚本安装后异步送达,不能只在加载时读一次:
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 数组。每条允许以下 21 个字段,可选字段可能缺失、数组可能为空:
合成输入示例(仅供预览,不是 TMDB 身份样例):
{
"items": [{
"id": "preview:one",
"type": "preview",
"title": "合成样本 · 长标题排版检查",
"description": "用于检查缺图、换行和尺寸变化,不代表真实影视数据。",
"posterPath": "icon:preview.cover",
"genreTitle": "合成分类",
"durationText": "样本时长"
}]
}
没有 originalTitle、Logo、4K/HDR、待看或观看进度字段;尺寸预设名中有“继续观看”也不会提供这些数据。不递归提供 childItems、episodeItems、relatedItems。不提供 videoUrl、previewUrl、link、trailers、trailerUrls、playerType、customHeaders、externalSubtitles。
通用协议每页最多 64 条,JSON ≤64 KiB,超限整页拒绝。当前真实模块实验室只取每页前 24 条非 text 条目,原生页头显示展示数/原始数;这不是所有接入场景的统一条数上限。
图片如何使用
宿主从既有缓存与认证图片管线准备可信资产,HTML 只收到 icon:名称:
var poster = item.posterPath || item.detailPoster || item.coverUrl;
if (poster) image.setAttribute('src', poster);
else image.removeAttribute('src');
根据版式选择海报或背景。未映射路径会被省略;缺图时保留占位和标题,不自行补远程地址、data URL、本地路径或猜测 token。
图片映射在创建 session 时登记,后续内容更新只能引用该实例已经登记的 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 整图背景柔化。用逗号组合需要的效果。
<meta name="rex-artwork" content="palette,bottom-blur">
RexWidget.artwork(token) 接收原来的 icon: 图片 token。取色返回十六进制的 background 和 foreground。渐进模糊返回可直接用作图片 src 的 bottomBlur token。它由宿主在原图上预先处理,从图高 60% 到底部逐渐增强。background-blur 返回 backgroundBlur 图片 token,适合放在堆叠海报和标题背后。它提供低分辨率柔化底图,透明度和明暗由卡片设置。先显示原图或默认底色,再用 onArtworkChanged 接收后台结果。
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:
非全宽不能填任意像素高度。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 字段:
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 继续使用 poster-collage。新声明需新版 Debug App。浏览器预览不代表原生校验、排版、TV 焦点或性能已验收。
卡片背景玻璃
想让整张卡片坐在系统原生玻璃上(和首页其他玻璃卡同一种材质),在 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 字节且在宿主白名单内,最多一个请求在途。处理拒绝并避免连发。真实模块实验室及手机首页临时预览支持以下动作;导航目标必须由当前页的宿主绑定:
该入口状态约定为 {index:n},这不是所有宿主的通用 schema。index 只管理卡片内部当前选中项,导航始终传 id;不把 Promise 返回值当条目数据或播放器结果。
可选按钮接线(需宿主启用这两个动作,并在自己的 render 中校验 state.index):
<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 / 人物名、配置改变、切换首页/环境、过期或已退场的实例会拒绝。切换内容页需重新建立会话和目标绑定;同一实例 setContent 改变内容后导航失效。
可用 canOpen 控制按钮是否启用,但它只是能力提示,点击仍要处理拒绝:
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 字符串;它仍只用于查找绑定,不直接作为导航地址。
性能与硬限制
使用简单定位、常见文字/图片样式和小范围渐变,再在原生确认支持。不以完整浏览器 CSS、DOM 或 Web API 为基线,不引入 React/Vue、外部脚本、样式和字体。没有网络、文件、任意导航、播放器或支付能力,不依赖持久存储。
动画优先短暂的 transform/opacity,保持已有 DOM 与图片节点,数据变化时才更新文字。避免逐帧读几何再写布局、持续改 width/height、无限计时器、整页重写,以及多层模糊/阴影/裁剪叠加。不是每个动画都能原生合成;请求 120 Hz 不等于实测达到 120 FPS。
宿主可暂停离屏组件、回收运行时并暂用缓存截图。截图只是在准备时占位,不赋予交互能力。不要用动画时钟驱动数据加载,不要为通过演示取消校验或调高配额。30 卡滚动页是独立压力场景,首帧准备、峰值内存与呈现帧率仍须实测。
开发者如何挂载
这一节需要 App 源码接入,不是普通用户操作入口。
- 将 HTML 加入
RexWidgets 包资源,通过包内资源加载。当前真实实验室固定使用 LiveCovers.html;选数据源不会更换模板。
- 沿既有模块链加载
[MediaItem] 并补齐 TMDB,准备 RexWidgetImageAsset 与原路径到资产名的映射,不把认证/播放字段交给 HTML。
- 用首页尺寸适配器得到
RexWidgetLayout,用 RexModuleWidgetContent 投影字段,再创建并持有 session。以下是示意,变量由宿主准备,需要在既有 MainActor 页面内接线:
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])
- 默认只读。交互需声明
allowedActions 并实现 onRequest,用宿主 setState 更新状态;内容/尺寸用 setContent/setLayout 更新。新图超出现有登记集时由宿主管理新会话。
- 使用现有宿主视图安装、可见性和销毁接线,不只创建 session 就认为已展示。快速换来源时取消旧加载,防止晚到数据覆盖。
Debug 验收入口:设置 → 实验室 → 真实模块卡片。它读取当前首页已配置的脚本模块;先在首页加数据模块,再切来源/数据页看真实封面。原演示和“30 张卡片 · 滚动测试”保留,不能用演示正常代替真实数据验收。
目前没有生产版 HTML 用户导入、组件包 manifest、线上分发、生产首页模板替换、任意业务动作注册接口。Debug 局域网实时预览只添加临时卡片,不属于这些发布能力。不要自行承诺 .rexwidget 等格式。上游框架授权尚有待解决项,正式分发内核前需确认许可;分享作者 HTML/skill 不代表获得内核分发授权。
验收与排错
静态检查与原生验收分开记录,未运行的写“待验收”。不要把浏览器视觉正确或源码接线完成说成全平台通过。
常见问题:
- 黑屏/停更:核对 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:21 字段与内容预算。
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:实验入口与当前模板。