# buttonPresets

一个预设把动作和按钮外观组合起来，让用户直接创建常用按钮。实现示例见[提供按钮预设](../guides/presets.md)。

## 多状态按钮

引用插件状态时，填写 `multiState.sourceId`。来源应为允许超级块读取的全局字符串枚举；`states` 覆盖所有枚举值，并提供 `unknown` 作为尚未收到状态时的外观。

按钮自身轮换时，填写 `sourceKind: "local"` 和 `initialState`。这种配置包含 2–16 个状态，用 `nextState` 指定执行后切换到哪一项。

## ButtonPreset

清单位置：`manifest.contributes.buttonPresets[]`。

### `ButtonPreset.id`

`string` · 必填

预设 ID，小写字母开头，可包含小写字母、数字、`_` 和 `-`，最多 64 个字符。

### `ButtonPreset.title`

`string` · 必填

预设名称，最多 80 个字符。

### `ButtonPreset.description`

`string` · 可选

解释预设用途，最多 240 个字符。

### `ButtonPreset.category`

`string` · 可选

引用 `categories` 中的分类 ID。

### `ButtonPreset.icon`

`string` · 可选

预设目录中的图标库 ID 或包内 SVG 路径，见[插件图标与资源](./icons.md)。

### `ButtonPreset.actionId`

`string` · 必填

本插件的动作 ID。

### `ButtonPreset.button`

`ButtonAppearance` · 必填

默认按钮外观。

### `ButtonPreset.multiState`

`MultiState` · 可选

根据来源状态或本地轮换切换外观和动作。

## ButtonAppearance

清单位置：`manifest.contributes.buttonPresets[].button`。

### `ButtonAppearance.title`

`string` · 必填

按钮名称，最多 50 个字符。

### `ButtonAppearance.titleFrom`

`ButtonTitleFrom` · 可选

根据动作的字符串参数生成名称。

### `ButtonAppearance.icon`

`ButtonIcon` · 必填

按钮图标，见下方类型。

### `ButtonAppearance.backgroundColor`

`string` · 可选

背景颜色，格式为 `#RRGGBB` 或 `#RRGGBBAA`。

### `ButtonAppearance.foregroundColor`

`string` · 可选

前景颜色，格式同背景颜色。

### `ButtonAppearance.showTitle`

`boolean` · 可选

是否在块下方显示名称。

### `ButtonAppearance.size`

`string` · 可选

按钮大小，例如 `1x1`、`2x1`。每边为 1–8，放置时还受设备网格限制。

## ButtonTitleFrom

清单位置：`manifest.contributes.buttonPresets[].button.titleFrom`。

### `ButtonTitleFrom.arg`

`string` · 必填

用于生成名称的字符串参数名。

### `ButtonTitleFrom.transform`

`string` · 必填

`application-name`、`basename`、`hostname`、`hotkey` 或 `screen-name`。`hostname` 对应 URI 参数，`hotkey` 对应热键，`screen-name` 对应屏幕参数。

## ButtonIcon

清单位置：`manifest.contributes.buttonPresets[].button.icon`。

### `ButtonIcon.kind`

`string` · 必填

`emoji`、`application`、`icon-pack` 或 `none`。

### `ButtonIcon.text`

`string` · emoji 必填

emoji 内容，最多 3 个 Unicode 码点。

### `ButtonIcon.arg`

`string` · application 必填

应用参数名，该参数使用 `format: "application"`。

### `ButtonIcon.id`

`string` · icon-pack 必填

图标包 ID，例如 `host:outline/Globe` 或 `host:filled/Globe`。

## MultiState

清单位置：`manifest.contributes.buttonPresets[].multiState`。

### `MultiState.sourceId`

`string` · 插件状态必填

全局字符串枚举来源 ID。

### `MultiState.sourceKind`

`"local"` · 本地状态必填

表示状态由按钮自身轮换。

### `MultiState.initialState`

`string` · 本地状态必填

初始状态，引用 `states[].id`。

### `MultiState.persistent`

`boolean` · 本地状态可选

是否保存本地状态。

### `MultiState.states`

`ButtonState[]` · 必填

每个状态对应的外观和动作。插件状态由后台发布，本地状态由 `nextState` 轮换。

## ButtonState

清单位置：`manifest.contributes.buttonPresets[].multiState.states[]`。

### `ButtonState.id`

`string` · 必填

对应枚举值或本地状态 ID。

### `ButtonState.actionId`

`string` · 可选

在这个状态下执行的动作；省略时该状态不绑定点击动作。

### `ButtonState.nextState`

`string` · 本地状态可选

执行后切换到的状态 ID。

### `ButtonState.button`

`ButtonAppearance` · 必填

这一状态的外观。状态图标使用 `emoji`、`icon-pack` 或 `none`。

预设的 `category` 引用 `contributes.categories`，与动作共用分类目录，但不会自动继承所引用动作的分类；未指定时归入“其他”。公共分组和两种视图见 [Category.group](./actions.md#categorygroup)。