配置包级设置

字段结构见数据模型 · 用户字段。控件类型、required 和 visibleWhen 与参数一致，本文不再重复定义。用户侧的配置方式见用户指南 · 管理。

settings 应声明在包上，而不是某个扩展上。六种 type 的 handler 均通过 ctx.settings 读取。请勿将其与 widget / search 的 params 混淆；后者通过 input.params 读取。

声明

在 definePackage 中声明，不应放入 load / search 的返回值。

definePackage({
  id: "conflux.demo",
  title: "Demo",
  version: "1.0.0",
  engine: 1,
  permissions: { network: [] },
  settings: [
    {
      name: "tag",
      title: "Title tag",
      type: "text",
      default: "",
      description: "Prefixed on every title from this package.",
    },
    {
      name: "uppercase",
      title: "Uppercase titles",
      type: "boolean",
      default: false,
    },
  ],
  extensions: [ /* ... */ ],
});

name 是 JavaScript 中读取的键，title 是包详情页 Settings 区域中显示的标签。

读取

所有 handler 的第一个参数均为 ctx。包级配置仅通过 ctx.settings 提供，不应从 input.params 中读取。

load: async function (ctx, input) {
  var title = "Demo Movie";
  var tag = ctx.settings && ctx.settings.tag;
  if (typeof tag === "string") {
    tag = tag.replace(/^\s+|\s+$/g, "");
    if (tag) {
      title = tag + " " + title;
    }
  }
  if (ctx.settings && ctx.settings.uppercase === true) {
    title = String(title).toUpperCase();
  }
  return { items: [{ ref: ref, title: title }] };
}

detail.load、playback.sources、subtitle.match / search / file 以及 danmu.match / search / comments 同样通过 ctx.settings 读取配置。本仓库的 Demo 使用 tag / uppercase 调整 widget、search 和详情标题。

不应假设某个键一定存在。即使用户尚未修改配置，也可以读取字段的 default 值。

var tag = ctx.settings && ctx.settings.tag;
if (typeof tag !== "string") {
  tag = "";
}

值的来源

App 按以下顺序合并并生成 ctx.settings：

1. 每个字段的 default
2. 用户在包详情页填的值

包级 settings 不支持 constants。对于固定且不向用户开放的值，可以直接写入脚本，或使用扩展 params 中的 constants。

和 params 的区别

	包 settings	扩展 params
写在哪	definePackage({ settings })	widget / search 的 params
谁填	用户在包详情页填写，每个包一份	用户在对应扩展实例的详情页填写
JS 里读	ctx.settings	input.params
谁能用	六种 type	仅 widget / search 可声明；同源 detail / playback 可读取来源实例的值
constants	没有	有，覆盖同名键

包级共享配置应放入 settings，例如脚本默认语言和全局开关。服务器和账号属于 widget 实例的 params。detail / playback 应从本次调用的 input.params 读取这些值，不应将其写入 settings。showSecond 等实例专属选项也应存放在实例 params 中。

两类配置可以包含同名键，且彼此独立。例如，ctx.settings.tag 与 input.params.tag 表示两个不同的值。

必填

设置 required: true 后，包详情页的 Settings 控件会显示 Required。当可见的必填字段仍为空时，包列表会显示“Required settings missing”。此提示不会阻止任何 handler 执行。空白字符串视为未填写；存在 default 时，列表不会显示提醒。

被 visibleWhen 隐藏的必填字段不会显示提示，也不会计入包列表提醒。handler 不应假设该字段一定存在值。