buttonPresets

一个预设把动作和按钮外观组合起来，让用户直接创建常用按钮。实现示例见提供按钮预设。

#多状态按钮

引用插件状态时，填写 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 路径，见插件图标与资源。

#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。