Schema

Schema 告诉飞块一个值是什么类型，以及可以取哪些值。同一套结构用于动作参数、动作结果、状态和数据提供者。

#示例

下面描述一个包含 items 和 mode 的对象。items 是必填的文本列表；mode 是可选的枚举文本。

{
  "type": "object",
  "required": ["items"],
  "additionalProperties": false,
  "properties": {
    "items": { "type": "array", "items": { "type": "string" }, "maxItems": 100 },
    "mode": { "type": "string", "enum": ["fast", "safe"], "enumLabels": ["快速", "安全"], "default": "safe" }
  }
}

#类型

飞块按实际类型检查值。"3" 是文本，不能作为数字参数传入；如果数据来自文本输入，需要先转换成数字。

以下属性是飞块支持的 Schema 结构。参数编辑器的具体表现见参数编辑器。

#Schema

清单位置：Schema。

#Schema.type

string · 必填

使用上表中的一种类型。当前不提供 null 类型。

#Schema.title

string · 可选

字段在参数表单中显示的名称。

#Schema.description

string · 可选

帮助用户填写的说明，例如“单位为秒”。

#Schema.properties

Record<string, Schema> · object 可用

子字段的名称和 Schema。字段名非空，最多 128 个字符。

#Schema.required

string[] · object 可用

必须传入的字段名，名称要在 properties 中声明。

#Schema.additionalProperties

boolean · object 可用

设为 false 时拒绝未声明的字段。动作根参数默认拒绝未知字段；嵌套对象需要单独设置。

#Schema.items

Schema · array 可用

列表元素的 Schema。省略时不限制元素类型。

#Schema.enum

JSON[] · 可选

允许的值，实际值应与 type 一致。

#Schema.enumLabels

string[] · 可选

与 enum 按顺序对应的显示名称，不改变存储的值。

#Schema.minimum

number · number / integer 可用

允许的最小值，包含这个边界。

#Schema.maximum

number · number / integer 可用

允许的最大值，包含这个边界。

#Schema.maxLength

integer · string 可用

文本的最大长度，按 JavaScript string.length 计算。省略时为 65536。

#Schema.maxItems

integer · array 可用

列表最多包含多少项。省略时为 1000。

#Schema.default

JSON · 可选

参数编辑器的初始值。处理函数中的可选参数仍应设置自己的默认值。

#Schema.options

SchemaOption[] · string 可用

字符串候选项。选中的 value 作为实际参数传入。

#Schema.dynamicOptions

true · 仅普通动作 argsSchema 的顶层 string 参数可用

由插件 actionOptions[actionId][fieldKey] 返回动态候选项，宿主使用搜索选择器。不能与 options、enum 或 format 同时声明；不支持嵌套参数、动作结果、超级块实例动作或其他数据 Schema。超级块设置继续使用自己的 dynamicOptions 与 widgetOptions。

此属性只提供配置界面提示，不将候选列表变成运行时枚举。保存 value，label 仅用于显示。用法见动作动态候选项。

#Schema.format

string · string 可用

选择参数编辑器，例如 application、file、uri 或 multiline。

#Schema.allowedSchemes

string[] · uri 可用

允许的 URI 协议，每项包含冒号，例如 ["https:", "mailto:"]。

#Schema.filePicker

FilePicker · 文件格式可用

文件选择器筛选规则，见 FilePicker。

#SchemaOption

清单位置：Schema.options[]。

#SchemaOption.label

string · 必填

候选项显示名称。

#SchemaOption.value

string · 必填

选择该项时传给后台的值。