FlyonDeckwidgets
声明超级块页面、尺寸、状态订阅和实例操作。
Documentation content is currently available in Simplified Chinese.
contributes.widgets 中的每一项对应一种可放置的超级块。完整开发过程见创建超级块。
#页面与配置
page 相对插件根目录，configPage 相对主页面所在目录。配置字段使用 WidgetSettings，它与动作的 Schema分开定义。
#手势与页面交互
如果组件是一个只读显示界面，可以通过 customizableGestures 让用户配置点击、长按等动作。如果页面自己处理按钮或滑块交互，使用 instanceActions 向后台提交操作。
#Widget
清单位置：manifest.contributes.widgets[]。
#Widget.id
string · 必填
超级块类型 ID，在本插件的 widgets 中唯一。
#Widget.title
string · 必填
目录中显示的名称。
#Widget.description
string · 可选
组件用途说明，最多 240 个字符。
#Widget.category
string · 可选
超级块目录分类，最多 48 个字符。
#Widget.page
string · 必填
主页面路径，例如 pages/counter/index.html。页面放在独立资源目录中。
#Widget.configPage
string · 可选
配置页面相对主页面目录的路径，例如 settings.html，最多 128 个字符。
#Widget.defaultSize
WidgetSize · 必填
默认占用的网格大小。
#Widget.allowedSizes
WidgetSize[] · 可选
用户可选的大小，最多 16 项，并包含 defaultSize。省略时只允许默认大小。每个规格都应验证实际页面内容区的排版；网格占位不等于 iframe 宽高，详见响应式布局最佳实践。
#Widget.stateSource
string · 可选
页面订阅的状态来源 ID，该来源应允许超级块读取。
#Widget.customizableGestures
string[] · 可选
可配置的手势：click、doubleClick、swipeLeft、swipeRight、longPress。填写非空、不重复的列表。
#Widget.instanceActions
WidgetInstanceAction[] · 可选
页面提交给后台的操作，最多 16 项。
#Widget.settingsSchema
WidgetSettings · 可选
每个放置实例的配置字段，见 WidgetSettings。
#WidgetSize
清单位置：manifest.contributes.widgets[].defaultSize。
#WidgetSize.cols
integer · 必填
横向占用的网格数，1–16。
#WidgetSize.rows
integer · 必填
纵向占用的网格数，1–16。
#WidgetInstanceAction
清单位置：manifest.contributes.widgets[].instanceActions[]。
#WidgetInstanceAction.id
string · 必填
实例动作 ID，使用小写字母开头，可包含小写字母、数字和 -，最多 32 个字符。
#WidgetInstanceAction.title
string · 可选
流程选择器显示的名称，最多 64 个字符。
#WidgetInstanceAction.argsSchema
Schema · 可选
实例动作参数，根 type 为 object。省略时只接收空对象。
#WidgetInstanceAction.execution
ActionExecution · 可选
使用与普通动作相同的超时、并发和资源声明。默认与同插件普通动作共用串行队列；可显式声明 resource、hostResource 或 concurrency。
#可复用的数值控件
#Widget.valueControl
true · 可选
声明此页面是由用户绑定目标的数值控件。要求宿主能力 widgets.valueControl v1。用户在“编辑超级块 → 控制目标”中选择显式声明 Action.valueControl 的数值设置动作；参数由声明确定，范围和默认反馈自动填入，用户可调整范围、更换或清除反馈。其他必需参数在同一界面填写；目标可以属于任何已安装、兼容的平台插件，无需双向依赖。控制目标也可以是可写入的数字类型自定义状态，要求宿主能力 widgets.stateControl v1；宿主按状态 Schema 校验范围与步长，状态不可用或超出可见范围时绑定无效。
页面先通过 window.FlyonDeckWidget.getControlValue() 获取 {minimum,maximum,step,value,available,title,icon?,updatedAt?,message?}；value 为 null 表示尚无可用反馈。调用 setValue(number) 提交目标单位中的实际值。用户绑定保存在宿主布局，页面不能传入目标插件、动作、反馈路径或固定参数。设备布局也不包含绑定详情。
首版支持显式开放的普通动作顶层 number/integer 参数，不支持枚举数值、流程输入、跨实例私有状态。反馈必须是全局可见、允许小组件读取的全局数值字段；没有反馈也可只写。目标停止、状态缺失或配置无效会显示不可用，不自动替换目标。
框架保留 set-value 实例动作和 control-value 数据查询名称；声明 valueControl 后不能再为同一小组件声明这些端点。宿主重新读取真实布局并走统一动作执行器；旧的排队请求在绑定改变后失效。
内置“通用控件 → 通用滑块”使用此协议，拖动只改变预览，松手或键盘提交时执行；每 1.5 秒读取反馈，宿主合并同一实例的待执行数值。它不依赖音量、天气等业务插件。
动作反馈绑定可选保存 state.availabilityPath，由动作的默认反馈声明初始化，用户可以更换或清除。该路径必须指向反馈来源中已声明的布尔字段；值为 true 才使用数值，缺失或为 false 时反馈不可用。没有声明时不检查可用性，宿主不会对 available 等业务字段名作特殊处理。
绑定策略集中在独立的 WidgetControlBindings 模块，通过布局、动作目录、状态和执行入口工作；它不依赖 Electron、HTTP、WebSocket 或具体控件插件。通信层仅识别框架端点并转交。不可用标题取自控件声明，无法取得声明时使用“数值控件”。