# FlyonDeckWidgetConfig

在清单中填写 `configPage` 后，飞块会在编辑器中打开你的配置 HTML。这个页面加载专用 SDK：

```html
<script src="/api/plugin-sdk/widget-config-page-v1.js"></script>
```

页面修改的是当前编辑草稿。用户保存块时，飞块才会把配置应用到实例。字段定义见 [WidgetSettings](./settings.md)。

## version

只读值 `1`，表示配置页面协议版本。

## onSettings()

监听配置变化。已有配置时，注册后立即回放。调用 `update()` 后，会立即通知合并后的本地设置，适合根据模式显示和隐藏字段；宿主校验后还会回传规范化的草稿。如果宿主拒绝修改，则回传上一份有效草稿。监听器应更新界面，不要在回调中无条件再次调用 `update()`。

```ts
FlyonDeckWidgetConfig.onSettings(
  listener: (settings: Readonly<Record<string, string | number | boolean>>) => void
): () => void
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `listener` | `function` | 接收当前公开配置。 |

### 返回值

返回取消订阅函数。

### 示例

```js
FlyonDeckWidgetConfig.onSettings(settings => {
  document.querySelector("#step").value = settings.step;
});
```

## getSettings()

同步读取当前公开配置。

```ts
FlyonDeckWidgetConfig.getSettings():
  Readonly<Record<string, string | number | boolean>> | null
```

### 返回值

首份配置到达前返回 `null`，之后返回配置对象。

## update()

把修改交给飞块编辑器。只传入这次改动的字段即可。

```ts
FlyonDeckWidgetConfig.update(changes: Record<string, string | number | boolean>): void
```

### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `changes` | `Record<string, string \| number \| boolean>` | 字段名来自 `settingsSchema.properties`，值符合对应定义。 |

### 返回值

无返回值。编辑器校验后更新草稿，并通过 `onSettings()` 回传配置。

### 示例

```js
document.querySelector("#step").onchange = event => {
  FlyonDeckWidgetConfig.update({ step: Number(event.target.value) });
};
```

## getLocale()

返回当前宿主传来的语言，值为 `zh-CN` 或 `en-US`。Web Client 的语言可独立于桌面端；收到后续语言快照时更新。

## t()

`t(key, values?)` 使用当前插件的包内词典翻译语义键并格式化 ICU 参数。先加载 `/api/plugin-sdk/i18n-v1.js`；资源由宿主在页面脚本执行前自动提供。缺失消息依次回退到插件默认语言和原始键，不查询宿主词典。详见[国际化](./i18n.md)。