# WidgetSettings

本页描述单个超级块实例的配置。插件级共享偏好见[插件全局设置](./plugin-settings.md)。

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

## 示例

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

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

## 静态和动态候选项

固定列表放在 `options` 中。列表需要从接口查询时，用 `control: "search-select"` 与 `dynamicOptions: true`，并注册 [widgetOptions 处理函数](./node-sdk.md#widgetoptionshandler)。重新编辑时，处理函数可以用 `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 个字符，在候选项中唯一。