WidgetSettings

本页描述单个超级块实例的配置。插件级共享偏好见插件全局设置。

把配置放在 widgets[].settingsSchema.properties 中。键名就是配置 ID，例如 label 或 step。后台和页面按这个名称读取设置。

#示例

{
  "properties": {
    "label": { "type": "string", "title": "标签", "default": "计数" },
    "step": { "type": "integer", "title": "步长", "default": 1, "minimum": 1, "maximum": 10 }
  }
}

飞块可以根据这些声明生成表单。若组件指定了 configPage，则由配置页使用同一套字段提交值。

#静态和动态候选项

固定列表放在 options 中。列表需要从接口查询时，用 control: "search-select" 与 dynamicOptions: true，并注册 widgetOptions 处理函数。重新编辑时，处理函数可以用 selectedValue 查询已保存项的名称。

#私密字段

API 密钥这类值可用 visibility: "private" 保存。后台的数据提供者会收到它，主页面、配置页和设备布局不会收到。需要密码输入时，可使用 control: "password"；这个控件也采用私密设置处理方式。

#WidgetSettings

清单位置：manifest.contributes.widgets[].settingsSchema。

#WidgetSettings.properties

Record<string, WidgetSetting> · 必填

配置字段映射，最多 16 项。键名以小写字母开头，可包含字母、数字和 _，最多 64 个字符。

#WidgetSetting

清单位置：manifest.contributes.widgets[].settingsSchema.properties.<key>。

#WidgetSetting.type

"string" | "integer" | "boolean" · 必填

配置值的类型。

#WidgetSetting.title

string · 必填

表单标签，最多 80 个字符。

#WidgetSetting.description

string · 可选

字段的填写说明，最多 240 个字符。

#WidgetSetting.default

string | number | boolean · 可选

默认值，与字段类型一致。空字符串在设置归一化时使用默认值。

#WidgetSetting.minimum

integer · integer 可用

最小整数值，包含边界。

#WidgetSetting.maximum

integer · integer 可用

最大整数值，包含边界。

#WidgetSetting.control

"search-select" | "password" | "icon" | "color" · string 可用

搜索选择器、密码输入框、宿主图标选择器或颜色选择器。color 同时保留颜色值输入框，保存值仍为字符串，建议默认值使用 #RRGGBB。password、icon、color 不同时使用 options 或 dynamicOptions。

#WidgetSetting.visibility

"public" | "private" · 可选

默认为 public。私密字段只提供给后台。

#WidgetSetting.options

SettingOption[] · string 可用

静态候选项，1–512 项。保存的值要在列表中。

#WidgetSetting.dynamicOptions

true · string 可用

从后台查询候选项，搭配 search-select，不同时填写 options。

#SettingOption

清单位置：manifest.contributes.widgets[].settingsSchema.properties.<key>.options[]。

#SettingOption.label

string · 必填

显示名称，最多 80 个字符。

#SettingOption.value

string · 必填

保存的值，最多 256 个字符，在候选项中唯一。