widget

widget 是首页 Dashboard 中的小组件。用户可以添加实例并填写参数。UI 仅支持 runtime 中已注册的模板，JavaScript 扩展不能绘制自定义视图。

字段

字段	必填	含义
`type`	是	`"widget"`
`id` / `title`	是	包内唯一；添加到桌面时的名称
`template`	是	runtime 模板 ID，见下文
`families`	否	支持的尺寸：`small` / `medium` / `large` / `extraLarge`。默认使用模板支持的全部尺寸
`params`	否	用户配置这块小组件时的字段
`constants`	否	由开发者指定且用户无法修改的输入参数
`cache`	否	默认 `ttlSeconds: 3600`
`load`	是	protocol 方法
`placeholderData`	否	字面量示例数据。安装时写入清单，不执行 JavaScript
`placeholder`	否	示例数据函数。实现后优先于 `placeholderData`

Protocol

load(ctx, input) => Promise<WidgetContent>

input: {
  instanceId?: string;               // 该实例的稳定 ID，由 App 生成，不属于 params
  params: Record<string, unknown>;   // 该实例用户配置 + constants
  family: "small" | "medium" | "large" | "extraLarge";
  page?: PageToken;                  // 仅在“展开全部”时提供
}

placeholder?(ctx, input) => Promise<WidgetContent>

input: {
  family: "small" | "medium" | "large" | "extraLarge";
}

WidgetContent: {
  items: ListItem[];
  next?: PageToken;
}

placeholderData 和 placeholder 均为可选项，仅用于 Widget Picker 的预览渲染，不属于首页时间线。其结构与 load 返回的 WidgetContent 相同。预览数据不对应具体实例，也不包含用户 params；应使用本地示例数据，不应发起网络请求。如果两者均未提供，安装阶段将跳过预览数据采集，Picker 仅显示标题。App 会在安装或包版本发生变化时获取一次预览数据：如果实现了 placeholder，则调用该方法（可根据 ctx.settings 调整标题）；否则使用清单中的 placeholderData。结果将写入磁盘，并在卸载时清除。

Dashboard 仅展示模板可容纳的前 N 个条目。N 由模板和 family（即 WidgetSize：small / medium / large / extraLarge）决定。用户选择“展开全部”时，App 会继续调用同一个 load，改用全屏列表模板，并通过 page 实现分页。无需为展开功能实现额外方法。

params 的字段结构与包 settings 相同，见数据模型 · 用户字段。locale / userId 只在 ctx 里。

模板

模板属于 runtime，不在扩展中定义。扩展仅声明 template ID。对于无法识别的 ID，App 将拒绝添加对应小组件。

当前已注册的模板：

ID	适用尺寸	交互行为
`poster-grid`	small / medium / large	每张海报默认打开 detail，可选显示播放按钮
`poster-ranked`	small / medium / large	前三张海报呈扇形叠放：第 1 名居中、第 2 名在左、第 3 名在右；点击海报进入详情；仅第 1 名显示播放按钮
`poster-pager`	extraLarge	横向分页大海报：中间显示一张完整卡片，两侧显示上一张和下一张的局部内容；底部叠加标题与 `releaseDate · genre`；点击卡片进入详情
`ranked-rail`	extraLarge	横向滚动的排行海报：约显示三张完整卡片及右侧下一张的局部内容；左上角显示排名，底部叠加标题与 `genre`；点击卡片进入详情
`backdrop-hero`	medium / large	主卡片 detail；播放按钮
`ranked-list`	medium / large	每行 detail
`schedule-day`	medium / large	每行 detail

条目与点击

load 返回 ListItem[]，每个条目必须包含 ref。点击事件不由 widget 处理，详见架构 · 点击解析。

字段	作用
`intent`	卡片主体的默认行为。省略时视为 `"detail"`。`"play"` 适用于点击卡片后直接播放的模板，但仍需满足播放条件
`episode`	已确定的季、集。仅提供此字段时，才允许从小组件直接播放剧集

widget 不提供 loadDetail 或 sources。如需支持详情或播放，应在同一包中提供对应 type 的扩展。

widget ​

字段 ​

Protocol ​

模板 ​

条目与点击 ​

字段

Protocol

模板

条目与点击