#内置字段组件

A3S Form 的字段由两部分组成：JSON Schema 负责值类型与校验，UI 节点负责控件、文案和展示方式。Renderer 只回传受控值，不保存业务数据，也不会替宿主执行网络请求。

交互示例直接渲染仓库里的 FormRenderer，字段修改结果会以实际回传的 JSON 显示。

#通用属性

所有字段节点都使用 kind: "field"，并通过 schemaPath 绑定 Schema。下列属性由 Renderer、Designer、Vue 适配器和 Web Component 共用。

UiOption 的结构为 { label, value, disabled? }。value 只能是 JSON 基础类型，不能放函数或组件实例。

const node = {
  id: 'name',
  kind: 'field',
  label: '任务名称',
  widget: 'text',
  schemaPath: '/properties/name',
  width: 6,
};

#组件速查

#文本输入

#单行文本 text

适合名称、标识和短标题。长度、格式和正则约束都放在 Schema 中。

{
  "value": "同步客户数据"
}

#多行文本 textarea

适合备注和说明。长文本应设置合理的 maxLength，避免把大段文件内容塞进表单值。

{
  "value": "失败时保留现场，并通知流程负责人。"
}

#数字 number

输入为空时回传 null，有值时回传 JavaScript number。范围约束以 Schema 为准。

{
  "value": 3
}

#邮箱 email

使用原生邮箱输入能力，并由 Schema Profile 的 email 格式完成一致校验。

{
  "value": "ops@a3s.dev"
}

#密码 password

只负责遮挡输入，不等于加密。不要把长期凭证写入表单文档、默认值、日志或截图。

{
  "value": ""
}

#日期 date

只表示日历日期，不带时区。

{
  "value": "2026-08-09"
}

#网址 url

适合回调地址、资料链接和服务端点。浏览器输入类型为 url，Schema 使用 uri 格式。

{
  "value": "https://a3s.dev/form"
}

{
  "schema": { "type": "string", "format": "uri" },
  "ui": { "widget": "url", "placeholder": "https://example.com" }
}

#电话 tel

电话格式因国家和业务场景不同，组件不擅自改写号码。需要固定格式时，在 Schema 中加入 pattern。

{
  "value": "+86 138 0000 0000"
}

#时间

#日期时间 date-time

控件明确显示 UTC。带偏移量的受控值会先换算到 UTC，用户修改后写回带 Z 后缀的值。

{
  "value": "2026-08-09T09:30:00Z"
}

#时间 time

适合只关心一天中某个 UTC 时间点的配置，例如跨地区统一调度。带偏移量的值会换算到 UTC。

{
  "value": "09:15:00Z"
}

#选择与集合

#下拉选择 select

选项较多、用户只选一项时使用。静态 options 和 Schema enum 应保持一致；动态选项通过 dataSource 交给宿主加载。

{
  "value": "staging"
}

#单选项 radio

选项少且需要直接比较时使用。每项保留原生 radio 语义，方向键行为由浏览器提供。

{
  "value": "review"
}

#复选框 checkbox

用于确认一个独立布尔状态。

{
  "value": true
}

#开关 switch

用于立即表达启用或关闭状态，语义为 role="switch"。如果切换会产生不可逆副作用，应改用明确的操作按钮和确认流程。

{
  "value": true
}

#多选 multi-select

使用可扫描的复选选项面板，不依赖原生 select[multiple]。达到 maxItems 后，未选项会禁用；已选项仍可取消。

{
  "value": [
    "human",
    "agent"
  ]
}

{
  "schema": {
    "type": "array",
    "items": { "type": "string", "enum": ["human", "agent", "reviewer"] },
    "minItems": 1,
    "maxItems": 2,
    "uniqueItems": true
  },
  "ui": {
    "widget": "multi-select",
    "options": [
      { "label": "人类成员", "value": "human" },
      { "label": "Agent", "value": "agent" }
    ]
  }
}

选项值通过严格相等比较，数字 1 与字符串 "1" 不会混为一项。

#标签 tags

输入后按 Enter、逗号或“添加”提交。重复标签不会写入值；达到 minItems 时保留项的移除按钮会禁用。

{
  "value": [
    "Rust",
    "TypeScript"
  ]
}

#数值与业务展示

#金额 currency

货币代码作为输入前缀展示，受控值仍是普通 number。它适合配置预算、阈值和报价，不替代财务系统的十进制定点数。

{
  "value": 1280.5
}

{
  "schema": { "type": "number", "minimum": 0, "maximum": 1000000 },
  "ui": {
    "widget": "currency",
    "customProps": { "currency": "CNY", "step": 0.01 }
  }
}

#评分 rating

默认从 1 分开始，最高分读取 Schema maximum，支持 1–10。组件使用原生 radio，因此键盘和读屏语义与普通单选组一致。

{
  "value": 4
}

#滑块 slider

适合有清晰上下界、允许近似选择的数值。需要精确录入时应使用 number 或 currency。

{
  "value": 65
}

滑块显示当前值，并提供 aria-valuetext。方向键、Page Up、Page Down、Home 和 End 沿用浏览器原生行为。

#隐藏值 hidden

隐藏字段保留在受控值和 DOM 的 input[type="hidden"] 中，但不渲染标题或可见字段外壳。适合宿主已经掌握、又需要随配置一起提交的稳定标识。

{
  "value": "org-a3s-lab"
}

不要把密钥、访问令牌或权限判断放在隐藏字段中。

#计算结果 calculated

以只读 output 展示宿主值或 computed 规则结果。数字按当前 locale 格式化，原始受控值不会改变。

{
  "value": 2561
}

{
  "ui": {
    "id": "total",
    "kind": "field",
    "widget": "calculated",
    "readOnly": true,
    "schemaPath": "/properties/total"
  },
  "rule": {
    "id": "calculate-total",
    "target": "total",
    "kind": "computed",
    "expression": {
      "op": "multiply",
      "left": { "op": "field", "path": "quantity" },
      "right": { "op": "field", "path": "unitPrice" }
    }
  }
}

#React 中使用

字段组件不单独维护值。宿主编译一次文档，将完整表单值作为受控属性传入。

import { assertCompiled } from '@a3s-lab/form/core';
import { FormRenderer } from '@a3s-lab/form/react';
import '@a3s-lab/form/styles.css';

const plan = assertCompiled(document);

function NodeSettings() {
  const [value, setValue] = useState({
    endpoint: 'https://api.example.com',
    roles: ['agent'],
    budget: 1000,
  });

  return <FormRenderer plan={plan} value={value} onChange={setValue} />;
}

Vue 使用 v-model，Web Component 监听 value-change。三种适配器都调用同一个 React Renderer，因此字段值、校验、locale、只读状态和宿主错误保持一致。

#校验与错误状态

• required 来自父对象 Schema 的 required 数组，不在 UI 节点重复配置。
• minimum、maximum、minItems、maxItems 等约束由 Schema 提供。
• 宿主错误通过 errors 传入，并以稳定的字段路径绑定。
• readOnly 表单会禁用所有可编辑控件；计算结果仍保持可读。
• 空选项、数据源加载失败、重复标签和集合上限都有可见且可读屏的状态文案。

矩阵字段的行列契约、交互示例和嵌入边界见矩阵字段。重复字段组、数据表格和多步向导分别见重复字段组、数据表格和多步向导。