# Schema

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

## 示例

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

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

## 类型

| type | 对应的 JavaScript 值 |
| --- | --- |
| `string` | 文本，例如 `"hello"` |
| `number` | 有限数字，例如 `1.5` |
| `integer` | 整数，例如 `3` |
| `boolean` | `true` 或 `false` |
| `array` | 列表，例如 `[1, 2, 3]` |
| `object` | 对象，例如 `{ "count": 3 }` |

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

以下属性是飞块支持的 Schema 结构。参数编辑器的具体表现见[参数编辑器](./editors.md)。

## 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 仅用于显示。用法见[动作动态候选项](../guides/actions.md#动态候选项)。

### `Schema.format`

`string` · string 可用

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

### `Schema.allowedSchemes`

`string[]` · uri 可用

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

### `Schema.filePicker`

`FilePicker` · 文件格式可用

文件选择器筛选规则，见 [FilePicker](./editors.md#filepicker)。

## SchemaOption

清单位置：`Schema.options[]`。

### `SchemaOption.label`

`string` · 必填

候选项显示名称。

### `SchemaOption.value`

`string` · 必填

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