Form 表单

原生 <form> 增强，支持按 rules 规则对内部字段做校验与提交。

数据源是各字段的 value 属性（受控模式）。表单校验的字段范围为带 name 的 oas-input / oas-textarea / oas-select / oas-auto-complete / oas-cascader / oas-tree-select / oas-input-number / oas-checkbox / oas-radio（组容器不参与）。oas-input / oas-textarea / oas-input-number 输入时不会自动写回 value 属性，需在脚本中监听 oas-input / oas-change 事件同步；oas-select / oas-cascader / oas-tree-select 选中时自带回写。

功能展示

功能展示区只演示表单的字段收集与提交，不配置校验规则。

基础用法

收集与提交

提交

示例代码

不配置 rules 时提交不做任何校验，直接派发 oas-submit，detail.values 携带所有带 name 字段的收集结果。

多种控件组合

多种控件组合

提交

示例代码

表单校验

校验区演示 rules 声明的校验规则与失败反馈。

校验规则：{ required, message, minLength, maxLength, pattern }。校验失败时字段被标记 aria-invalid（输入框红边），字段下方显示红字错误提示，并派发 oas-validate-fail。

必填与格式校验

必填与格式校验

提交

示例代码

长度校验

minLength 校验

提交

示例代码

禁用字段跳过校验

禁用字段不参与校验

提交

示例代码

提交与校验失败事件

submit / validate-fail

提交

示例代码

栅格表单布局

layout="grid" 时 form 元素变为 24 列栅格，oas-form-item 按 span 占列（默认 24 即整行）；gap 控制栅格间距，label-align 控制标签位置（left / right / top，默认 top），label-width 设置 left/right 时标签列宽。校验失败的错误提示会收编进 oas-form-item 的错误位（role="alert"）。

两列栅格 + 校验

两列栅格布局

提交

示例代码

label-align 与 label-width

label-align 切换

示例代码

受控同步与事件监听（一个 <script> 块统一挂接）：

API

oas-form

属性	说明	类型	默认值
gap	grid 模式栅格间距（token 值，如 var(--oas-space-4)）	string	0
label-align	标签对齐：left / right / top（grid 模式默认 top）	string	top
label-width	label-align 为 left/right 时的标签列宽	—	—
layout	布局模式：vertical（默认，竖排）/ grid（24 列栅格）；非枚举值回退 vertical	string	vertical
rules	校验规则 JSON：{ 字段名: [{ required, message, minLength, maxLength, pattern }] }	Rules | string	{}

事件	说明
oas-submit	校验通过，detail: { values }
oas-validate-fail	校验失败，detail: { errors, values }

名称	说明
默认	—

oas-form-item

属性	说明	类型	默认值
label	标签文本（缺省不渲染标签行）	string	—
name	字段名（透传校验关联）	—	—
required	必填星号（仅视觉标记，校验规则仍由 form 的 rules 驱动）	boolean	—
span	24 栅格占列数（仅 form layout="grid" 生效；非 1-24 整数按 24）	string	24

名称	说明
默认	字段控件

校验失败时失败字段被标记 aria-invalid；可通过 form.getErrors() 获取错误信息。被 oas-form-item 包裹的字段，错误文本写入 form-item 的错误位（role="alert"）。