模板类型

表单文档 FormDocument 的全部类型，按 @xihan-form/core 的源码列出。当前结构版本 FORM_SCHEMA_VERSION 为 1。

各种类的属性包里有哪些属性见种类与属性。

文档、节点与规则

PropertyBag

属性包：一组按名字存放的 JSON 值。

类型：Readonly<Record<string, JsonValue>>

ExtensionData

扩展数据：扩展 id → 这个扩展自己的 JSON 对象。只给扩展用，与业务属性分开；编辑与复制粘贴原样带着走。

类型：Readonly<Record<string, JsonObject>>

PropertyGroup

节点的属性分组：基础、数据、外观。校验与联动另以规则列表存放。

类型：'basic' | 'data' | 'appearance'

RequiredRule

必填：值为空时不通过，空值判定取 @xihan-ui/headless 的 isEmptyFormValue：null、只含空白的字符串、空列表与元素全为空的列表算空，false 与 0 不算空。

字段	类型	必填	说明
id	string	是	规则 id，在所在规则列表里唯一；设计器编辑与问题定位都按它找规则。
kind	'required'	是	规则种类。
message	string	可省	不通过时给最终用户看的提示；不写时由运行时按问题码给出缺省文案。

AcceptedRule

必须为 true：用于「必须勾选同意」，值为 false 或空时都不通过。只适用于布尔值字段。

字段	类型	必填	说明
id	string	是	规则 id，在所在规则列表里唯一；设计器编辑与问题定位都按它找规则。
kind	'accepted'	是	规则种类。
message	string	可省	不通过时给最终用户看的提示；不写时由运行时按问题码给出缺省文案。

LengthRule

长度：字符串按字素计（@xihan-ui/headless 的 graphemeLength，与文本框的字数一致）、列表按元素个数，闭区间。

字段	类型	必填	说明
id	string	是	规则 id，在所在规则列表里唯一；设计器编辑与问题定位都按它找规则。
kind	'length'	是	规则种类。
min	number	可省	最少多少个字符或元素。
max	number	可省	最多多少个字符或元素。
message	string	可省	不通过时给最终用户看的提示；不写时由运行时按问题码给出缺省文案。

RangeRule

数值范围，闭区间。

字段	类型	必填	说明
id	string	是	规则 id，在所在规则列表里唯一；设计器编辑与问题定位都按它找规则。
kind	'range'	是	规则种类。
min	number	可省	下限。
max	number	可省	上限。
message	string	可省	不通过时给最终用户看的提示；不写时由运行时按问题码给出缺省文案。

PatternRule

正则：flags 只允许 i、m、s、u，整串不匹配即不通过。

字段	类型	必填	说明
id	string	是	规则 id，在所在规则列表里唯一；设计器编辑与问题定位都按它找规则。
kind	'pattern'	是	规则种类。
pattern	string	是	正则的源码，不带两边的斜杠。
flags	string	可省	正则标志。
message	string	可省	不通过时给最终用户看的提示；不写时由运行时按问题码给出缺省文案。

ExpressionRule

表达式：结果为 false 时不通过，为 true 或 null 时通过。

字段	类型	必填	说明
id	string	是	规则 id，在所在规则列表里唯一；设计器编辑与问题定位都按它找规则。
kind	'expression'	是	规则种类。
expression	string	是	受限表达式，$value 是字段自己的值。
message	string	可省	不通过时给最终用户看的提示；不写时由运行时按问题码给出缺省文案。

ValidationRule

声明式校验规则。message 是模板作者写给最终用户的提示，缺省时由运行时按规则种类给出。

取其一：RequiredRule、AcceptedRule、LengthRule、RangeRule、PatternRule、ExpressionRule。

ValidationKind

校验规则的种类。

类型：ValidationRule['kind']

LinkageAction

联动动作：条件成立时生效，不成立时回到节点的静态设定。

• show / hide：显示 / 隐藏。
• enable / disable：可用 / 禁用。
• require / optional：设为必填 / 取消必填。
• assign：把 value 表达式的结果赋给字段。

类型：'show' | 'hide' | 'enable' | 'disable' | 'require' | 'optional' | 'assign'

LinkageRule

声明式联动规则；when 缺省表示总是成立。同一状态有多条规则成立时，排在后面的生效。

字段	类型	必填	说明
id	string	是	规则 id，在所在规则列表里唯一。
action	LinkageAction	是	条件成立时做什么。
when	string	可省	条件，受限表达式，结果为 true 时成立；缺省总是成立。
value	string	可省	assign 的取值，受限表达式；其它动作不用。

FieldNode

字段：有数据键与值。

字段	类型	必填	说明
type	'field'	是	节点类型。
id	string	是	节点 id，在整份文档里唯一。
kind	string	是	种类，如 text、select，决定渲染方式与可用的属性。
key	string	是	数据键：字段的值在表单数据里的键，在所在作用域里唯一。
basic	PropertyBag	是	基础属性，如标签、提示、初始值、隐藏与禁用。
data	PropertyBag	是	数据属性，如选项、精度、数据来源。
appearance	PropertyBag	是	外观属性，如尺寸、前后缀。
validation	readonly ValidationRule[]	是	校验规则。
linkage	readonly LinkageRule[]	是	联动规则。
extensions	ExtensionData	可省	各扩展放在这个节点上的数据。

Region

区域：容器里放子节点的一格，如栅格的一列、标签页的一页、表格布局的一个单元格。

字段	类型	必填	说明
id	string	是	区域 id，在整份文档里唯一。
props	PropertyBag	是	区域属性，如栅格的列宽、标签页的标题、表格布局单元格的位置。
children	readonly FormNode[]	是	放在这一格里的节点。

ContainerNode

容器：子节点放在区域里。列表作用域的容器（子表单、子表）带 key，它的值是行对象的列表，区域里字段的键相对于行对象。

字段	类型	必填	说明
type	'container'	是	节点类型。
id	string	是	节点 id，在整份文档里唯一。
kind	string	是	种类，如 grid、subform，决定渲染方式与可用的属性。
key	string	可省	数据键：只有列表容器有，值是行对象的列表。
basic	PropertyBag	是	基础属性，如标签、提示、初始值、隐藏与禁用。
data	PropertyBag	是	数据属性，如选项、精度、数据来源。
appearance	PropertyBag	是	外观属性，如尺寸、前后缀。
validation	readonly ValidationRule[]	是	校验规则：只对列表容器的整份列表生效。
linkage	readonly LinkageRule[]	是	联动规则。
regions	readonly Region[]	是	区域，按顺序排列。
extensions	ExtensionData	可省	各扩展放在这个节点上的数据。

StaticNode

静态元素：只展示，没有值，如分隔线、说明文字。

字段	类型	必填	说明
type	'static'	是	节点类型。
id	string	是	节点 id，在整份文档里唯一。
kind	string	是	种类，如 divider、paragraph，决定渲染方式与可用的属性。
basic	PropertyBag	是	基础属性，如正文、标题文字与隐藏。
data	PropertyBag	是	数据属性。
appearance	PropertyBag	是	外观属性，如级别、宽度。
linkage	readonly LinkageRule[]	是	联动规则：只有显示与隐藏。
extensions	ExtensionData	可省	各扩展放在这个节点上的数据。

FormNode

表单节点。

取其一：FieldNode、ContainerNode、StaticNode。

NodeType

节点类型。

类型：FormNode['type']

FormDocument

表单文档：纯 JSON，不含任何代码。

字段	类型	必填	说明
schemaVersion	typeof FORM_SCHEMA_VERSION	是	结构版本，当前是 FORM_SCHEMA_VERSION。
settings	PropertyBag	是	表单设置，如标签位置、尺寸、整表禁用与只读。
children	readonly FormNode[]	是	顶层节点，按顺序排列。
extensions	ExtensionData	可省	各扩展放在文档上的数据。

选项

选项：选项列表用 designer-kit 的内建编辑方式 options，选项树用 treeOptions，都要求 label。每项是 { value: string, label: string, disabled?: boolean, tone?: Tone, description?: string }，选项树的项另可带 children（下一层的选项）与 hasChildren（有子项但还没给出，首次展开时向宿主要）。按 @xihan-ui/core/options 的 findOptionViolation 严格检查：不许多余的键，value 不为空、同一层里不重复，选项树最多 32 层；问题落在那一项的那个键上，如 [2, "value"]、[0, "children", 1, "label"]。