配置用户参数

字段结构见数据模型 · 用户字段。用户侧的配置方式见用户指南 · 管理。

只有 widget 和 search 可以声明 params 表单。detail / playback 不声明额外字段，但从 widget 实例进入时，会在同一 runtime 中接收该实例的输入：input.params 包含实例配置，input.instanceId 是实例 ID。当前版本的 subtitle / danmu 不与实例绑定。包级共享配置仍应使用包上的 settings，详见设置。

instanceId 由 App 生成，位于 input 顶层。请勿在 params 中重复声明名为 instanceId 的字段。需要按实例使用 ctx.storage 时，应以 input.instanceId 区分。

声明

在扩展声明中定义，不应放入 load / search 的返回值。

{
  type: "widget",
  id: "grid",
  title: "Demo Grid",
  template: "poster-grid",
  params: [
    {
      name: "showSecond",
      title: "Show second title",
      type: "boolean",
      default: true,
    },
  ],
  load: async function (ctx, input) {
    var items = catalog;
    if (input.params && input.params.showSecond === false) {
      items = items.slice(0, 1);
    }
    return { items: items };
  },
}

name 是 JavaScript 中读取的键，title 是用户添加或编辑 widget 实例时看到的标签。

search 的处理方式相同：声明 params，并在 search 中读取 input.params。关键词仅通过 input.query 提供，不应重复放入 params。

支持的控件

type 仅支持以下四种类型。完整协议见数据模型 · 用户字段。

type	界面控件	传入值
text	单行文本框	string
number	数字框	number
boolean	开关	true / false
select	单选	string，取 options[].value

请勿使用 file、date 或 password。当前版本会将未知 type 按文本框渲染，但扩展不应依赖此回退行为。

boolean 的 default 应使用 true / false，而不是字符串 "true"。读取时应使用 === true / === false，不应与 "yes" / "no" 比较。

select 必须包含 options: { title, value }[]。text 也可以包含 options，但在协议中仅表示建议值；当前版本的界面尚未渲染建议列表。visibleWhen 见下文。对于 boolean 字段，visibleWhen.in 应写为 ["true"] 或 ["false"]。

必填

required 为可选字段，默认表示选填。设为 true 后，扩展详情页会在标签旁及空文本框或数字框中显示 Required；开关和单选控件也会在标题旁显示该提示。

{
  name: "token",
  title: "Token",
  type: "text",
  required: true,
}

该设置仅影响配置页和扩展列表中的提示。即使用户未填写，App 仍会调用 load / search，对应键可能不存在或为空字符串。设置 default 后，即使用户尚未修改，也可以读取默认值，列表也不会显示提醒。空白字符串视为未填写。被 visibleWhen 隐藏的必填字段不会显示提示，也不会计入列表提醒。handler 不应假设该字段一定存在值。

调用时参数值的来源

App 按以下顺序合并并生成 input.params：

1. 每个字段的 default
2. 用户在这块 widget 实例上填的值
3. 扩展上的 constants（作者固定，覆盖同名键）

即使用户从未打开详情页，也可以读取 default。不应假设某个键一定存在，读取前应先检查其类型或是否存在。

var limit = input.params && input.params.limit;
if (typeof limit !== "number") {
  limit = 20;
}

constants 用于定义由开发者固定且不向用户开放的输入参数，例如固定的站点 ID。用户可修改的选项不应放入 constants。

和 settings 的区别

写在哪	谁填	JS 里读
扩展 params	添加或编辑对应的 widget（或 search）实例	input.params
包 settings	包详情页，每个包一份	ctx.settings

两者使用相同的字段结构。Emby 服务器和账号应存放在 widget 实例的 params 中，而不是 settings 中。仅包级共享配置（例如脚本语言、全局开关）应存放在 settings 中。详见设置。

可见条件

visibleWhen: { field, in } 根据另一个字段的当前值控制显示或隐藏。用户无法修改被隐藏的字段，但其 default 或此前填写的值仍可能出现在 input.params 中。因此，handler 不应将“不可见”视为“未传入”。