Rex

首页卡片

官网 ↗
读取源码…
测试数据
数据集
图片
内容
最近事件等待点击…目标 ID—
示例卡片
为你推荐
正在准备模板…
全宽高海报 · 每张 2:3,左右滚动查看。浏览器参考预览
查看宿主传入的数据

卡片尺寸

在首页怎么摆?

查看声明

复制后替换源码里的尺寸声明。

卡片开发文档

需要查接口时,再打开这里。字段、图片、交互与性能预算

协议快照:2026-11-18,实验内核及真实模块数据接口(源码基线 78eb2890)。本文面向卡片作者;这是一套实验协议,尚未作为正式用户导入格式发布。

内容索引:快速开始 · 数据 · 图片 · 尺寸 · 交互 · 预算 · 原生接入 · 验收

先分清两种模块

层 负责什么 作者交付什么
数据模块 按既有模块协议获取片单、补齐 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 后端。浏览器效果成功只证明浏览器排版成功。

快速开始

在工作台的「载入示例」选择 简单封面卡、全宽单卡 或 全宽高海报横滑。全宽单卡用一张横向大图配片名和详情按钮,高度从 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,无需绕过浏览器警告。

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

预览器使用独立 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 状态,但不要假定它能跨实例、离屏回收或重启保留,也不要依赖持久存储。

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

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 个字段,可选字段可能缺失、数组可能为空:

字段 类型 / 含义
id、type 字符串,保留来源原始身份;不要把数字猜成 TMDB ID
mediaType 可选字符串,媒体类型
title、description 可选字符串,片名与简介
coverUrl 可选封面 icon: token;名字带 Url 不代表可发网
coverRatio 可选数字,来源封面比例提示
posterPath、detailPoster 可选海报 token
backdropPath、backdropPaths 可选背景 token、背景 token 数组
releaseDate 可选字符串,上映日期;不要假设所有来源格式相同
rating 可选数字;没有就隐藏,0 不应被真假值判断误当成缺失
genreTitle、genreItems 可选分类文字;分类数组项为 {id,title}
peoples 人物数组,项为 {id,title,avatar?,role?}
duration、durationText 可选时长,数值单位秒;也可用来源的可读文案
season、episode 可选数字,季/集信息
language 可选字符串

合成输入示例(仅供预览,不是 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:

承载 源码声明 数据与排版
非全宽卡片 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 字段:

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 字节且在宿主白名单内,最多一个请求在途。处理拒绝并避免连发。真实模块实验室及手机首页临时预览支持以下动作;导航目标必须由当前页的宿主绑定:

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

该入口状态约定为 {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 字符串;它仍只用于查找绑定,不直接作为导航地址。

性能与硬限制

项目 当前边界
作者 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 卡滚动页是独立压力场景,首帧准备、峰值内存与呈现帧率仍须实测。

开发者如何挂载

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

  1. 将 HTML 加入 RexWidgets 包资源,通过包内资源加载。当前真实实验室固定使用 LiveCovers.html;选数据源不会更换模板。
  2. 沿既有模块链加载 [MediaItem] 并补齐 TMDB,准备 RexWidgetImageAsset 与原路径到资产名的映射,不把认证/播放字段交给 HTML。
  3. 用首页尺寸适配器得到 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])
  1. 默认只读。交互需声明 allowedActions 并实现 onRequest,用宿主 setState 更新状态;内容/尺寸用 setContent/setLayout 更新。新图超出现有登记集时由宿主管理新会话。
  2. 使用现有宿主视图安装、可见性和销毁接线,不只创建 session 就认为已展示。快速换来源时取消旧加载,防止晚到数据覆盖。

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

目前没有生产版 HTML 用户导入、组件包 manifest、线上分发、生产首页模板替换、任意业务动作注册接口。Debug 局域网实时预览只添加临时卡片,不属于这些发布能力。不要自行承诺 .rexwidget 等格式。上游框架授权尚有待解决项,正式分发内核前需确认许可;分享作者 HTML/skill 不代表获得内核分发授权。

验收与排错

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

检查 预期
首次 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: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:实验入口与当前模板。

手机预览