Form 表单

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

跨 shadow 提交入口：oas-form 在 shadow 内包原生 <form>，因此 light DOM 的按钮（含 oas-button）不具备原生 submit 语义。请在按钮点击等时机调用组件公开的 submit() 方法（如 this.closest('oas-form').submit()），它会委托内部 form 的 requestSubmit()，保留 submit 事件语义并触发相同的校验与 oas-submit / oas-validate-fail 派发——不要再穿透 shadowRoot.querySelector('form') 去调内部 form。

数据源是各字段的 value 属性（受控模式）。表单校验的字段范围为带 name 的 oas-input / oas-textarea / oas-select / oas-auto-complete / oas-cascader / oas-tree-select / oas-input-number / oas-radio / oas-radio-group / oas-date-picker / oas-slider / oas-rate / oas-pin-input / oas-dynamic-tags / oas-combobox / oas-picker / oas-transfer（model-value 通道）/ oas-dynamic-input（model-value 通道）/ oas-checkbox / oas-switch（checked 通道）。oas-form 内建监听字段冒泡的 oas-input / oas-change 事件，自动写回该字段的 value 属性（null 写空串），无需逐字段脚本接线。

功能展示

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

基础用法

收集与提交

提交

示例代码

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

多种控件组合

多种控件组合

提交

示例代码

嵌套 name 路径：嵌套 values

字段 name 支持点路径语法：数字段是数组下标，其余段是对象键——profile.city 组装进 { profile: { city } }，users.0.name 与 users[0].name 两种写法等价，组装进 { users: [{ name }] }。提交时 oas-submit 的 detail.values 为嵌套结构；rules 的键用完整路径字符串（如 "users.0.name"）匹配；initial-values 按同样路径嵌套写入，reset() 回嵌套初始值。不含路径语法的普通名组装结果与既有行为完全一致。

嵌套 name 路径提交

提交

示例代码

提交后 values 形如 {"name":"张三","profile":{"city":"杭州"}}——路径段即结构。

动态字段组 form-list

oas-form-list 在表单内维护一组可增删的字段行：在组件内放一个 <template> 作为行模板，克隆出的行内字段 name 自动索引化，两种写法——模板里用 {index} 占位（name="users.{index}.name"），或给组件设 name="users" 并在模板里写裸 name（自动前缀为 users.N.字段名）。min / max 约束行数（不足 min 自动补行；调小 min 不会删已有行，非法 max 按无上限处理），每行带删除按钮，删除后剩余行自动重新编号、已填值随行保留。字段留在 light DOM，校验 / 提交 / oas-values-change 全部随主表；组件派发 oas-add / oas-remove（detail: { index }）。

动态字段组 form-list

提交

示例代码

提交后 values 形如 {"members":[{"name":"张三","role":"本人"},{"name":"李四","role":"家属"}]}；行模板在原生 HTML 里直接写 <template> 即可，md/Vue 编译场景建议用 JS 构造 HTMLTemplateElement 注入（模板内容传透在模板编译下不稳）。

原生表单集成（form-associated）

常用的 15 个表单类组件为 form-associated 自定义元素（formAssociated: true）：可直接放进原生 <form>——<label for> 关联生效（点击 label 聚焦/激活控件、读屏朗读 label 文本），值经标准 FormData 收集（有 name 才提交），form.reset() 回初始值，fieldset[disabled] 联动禁用，required 接入原生校验链（checkValidity() / :invalid 伪类）。

原生 form + label for + FormData + reset

姓名（点击本行 → 聚焦输入框）角色（点击本行 → 聚焦下拉）入职日期接受协议（点击本行 → 勾选）邮件通知（点击本行 → 切换）

读取 FormDataform.reset()

示例代码

支持清单（15 组件）：input / textarea / input-number / checkbox / radio / radio-group / switch / select / combobox / auto-complete / tree-select / mentions / date-picker / time-picker / upload。值语义按原生对齐：多选（select / tree-select / date-picker multiple）提交同名多条；date / time 范围模式提交 name-start / name-end 两条；upload 提交 File；勾选族未勾不提交。与 oas-form 的 collectFields 机制并行可用。

表单校验

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

校验规则：{ required, message, minLength, maxLength, pattern, validator, validateTrigger }（validator 为自定义校验函数，函数不可 JSON 序列化，走 rules property 通道；validateTrigger 字段级覆盖表级触发时机）。校验失败时字段被标记 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 切换

示例代码

行内表单

inline 时表单项水平排列：label 在控件左侧（宽度自适应）、控件自动宽度、项之间按 gap 留间距（默认 var(--oas-space-4)），容器放不下时自动换行。与 layout 并存且优先于 layout；此时 label-align 强制 left、label-width 自动。适合登录、搜索等紧凑工具栏场景。

行内登录表单

行内登录表单

登录

示例代码

行内搜索表单

行内搜索表单

搜索

示例代码

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

表单级能力

整表禁用

disabled 属性对齐 config-provider 全局禁用语义：所有字段经字段自身的 form-associated 禁用通道并入生效（内层控件禁用、交互拦截），不回写字段的 disabled 属性（解除后字段完整恢复）；整表禁用时提交跳过全部校验。

整表禁用

提交（禁用时跳过校验）

禁用整表

示例代码

初始值与重置

initial-values 挂载后写入对应字段（input 走 value、switch 走 checked、transfer/dynamic-input 走 model-value）；reset() 回到初始值并清除校验错误态，全程不派发事件（与原生表单 reset 基线语义一致）。也支持 initialValues property 通道（property 优先于 attribute）。

initial-values 与 reset

提交重置

示例代码

自定义校验函数（validator）

validator 在每条规则的既有校验之后执行，返回 true 通过、返回字符串为错误消息、返回 Promise 走异步校验。函数不可 JSON 序列化，通过 rules property 通道设置（脚本赋值 form.rules = {...}）。

自定义校验函数

提交

示例代码

校验触发时机（validate-trigger）

validate-trigger 控制字段级即时校验时机：input（默认，边输入边校验）/ blur / change；字段规则里的 validateTrigger 可覆盖表级。提交时始终全量校验。默认边输入边校验：错误在点击提交前即已结算，避免「点击瞬间错误文案增删 → 布局位移 → 吞掉该次点击」。已出错的字段在输入时实时复校、改对即清。下方示例改为 blur：输入非法手机号后点击别处（失焦）即出现红字，改正后再失焦红字消失。

失焦触发校验

示例代码

滚动定位到首个错误（scroll-to-first-error）

设置 scroll-to-first-error 后，提交校验失败时自动聚焦首个错误字段并平滑滚动进视口（系统开启「减少动态效果」时降级为瞬跳）。下方长表单可滚动，备注字段在最底部——点击提交观察容器自动滚下去。

滚动定位到首个错误

提交（滚动到首个错误）

示例代码

值变化事件（oas-values-change）

任一字段值变化时派发 oas-values-change，detail: { name, value, values }（values 为全表当前值快照）。初始值写入与 reset() 属静默通道，不派发。

oas-values-change

示例代码

脚本接线（受控同步 + 各 demo 事件反馈）：

表级尺寸与标签冒号（size / colon）

size 把表级尺寸档（small / medium / large）下发给表内字段控件，优先级：字段自身显式 size > 表级 size > config-provider 全局注入 > 默认档（表级与全局注入同存时表级生效）；colon 为表内所有 oas-form-item 的标签渲染冒号。点击下方按钮观察字段尺寸与冒号即时变化。

表级 size + colon

勾选框跟随表级尺寸自身 size=medium 优先（不随表级）切到 small切到 large冒号开/关

示例代码

帮助文案与状态图标（help / status-icon）

help 在控件下方渲染常驻帮助文案，与校验错误独立并存；form-item 开启 status-icon 后，校验失败时在错误文本前显示 danger 状态图标（错误清除即隐藏）。

help + status-icon

提交

示例代码

自定义校验文案（validate-messages）

validateMessages（property 通道，推荐）或 validate-messages（JSON 属性）按规则类型覆盖 locale 默认文案，模板支持 ${min} / ${max} / ${value} 占位；rule.message 显式消息优先级最高。

validate-messages

提交

示例代码

API

方法

方法	说明
submit()	公开提交入口：委托内部 form 的 requestSubmit()（保留 submit 事件与 submitter 语义），经校验后派发 oas-submit / oas-validate-fail。跨 shadow 边界时 light DOM 按钮无原生提交语义，统一用此方法（如 this.closest('oas-form').submit()）
validate()	公开校验入口：校验全部字段并同步错误态（aria-invalid + 错误文案），返回 Promise<boolean>。纯校验——不派发 oas-submit / oas-validate-fail、不做 scroll-to-first-error；供分步容器等外部门控复用校验内核（异步 validator 聚合等待、禁用字段跳过、无 rules 默认放行）
getValues()	公开取值入口：全表当前值快照（嵌套结构），与 submit() 派发的 detail.values 同口径——不做校验、不过滤禁用字段，零交互字段的 value 属性预填同样计入。返回 Record<string, unknown>

oas-form

属性

属性	说明	类型	默认值
colon	表内所有 form-item 标签渲染冒号（CSS ::after，不进 DOM 文本）	—	—
disabled	整表禁用：字段经 form-associated 禁用通道并入生效（不回写字段 disabled 属性，防自锁）；禁用时提交跳过全部校验	boolean	—
gap	间距（grid 模式栅格间距；inline 模式项间距），token 值如 var(--oas-space-4)；grid 默认 0，inline 默认 var(--oas-space-4)	string	0
initial-values	表单初始值 JSON（property initialValues 优先）：挂载后写入对应字段；reset() 回到初始值	Record<string, unknown> | string	—
inline	行内布局：表单项水平排列（label 在控件左侧、控件自动宽度、可换行），项间距取 gap（默认 var(--oas-space-4)）；与 layout 并存且优先于 layout；此时 label-align 强制 left、label-width 自动	boolean	—
label-align	标签对齐：left / right / top（grid 模式默认 top；inline 模式强制 left）	string	top
label-width	label-align 为 left/right 时的标签列宽（inline 模式自动，不生效）	—	—
layout	布局模式：vertical（默认，竖排）/ grid（24 列栅格）；非枚举值回退 vertical；存在 inline 属性时优先	string	vertical
rules	校验规则 JSON：{ 字段名: [{ required, message, minLength, maxLength, pattern }] }	Rules | string	—
scroll-to-first-error	校验失败后聚焦首个错误字段并平滑滚动进视口（prefers-reduced-motion 时瞬跳）	boolean	—
size	表级尺寸档：经 data-form-size 通道下发表内全部字段（字段自身显式 size 优先，form-associated 字段动态跟随）	—	—
validate-messages	按规则类型覆盖 locale 默认校验文案（property/JSON 双通道，支持 ${min}/${max}/${value} 插值，default 兜底）	ValidateMessages | string	—
validate-trigger	字段级即时校验触发时机：input（默认，边输入边校验）/ blur / change；规则 validateTrigger 可逐字段覆盖；提交始终全量校验	string	input

事件

事件	说明
oas-submit	校验通过，detail: { values }
oas-validate-fail	校验失败，detail: { errors, values }
oas-values-change	任一字段值变化时派发，detail: { name, value, values }（values 为全表快照；initial-values 写入与 reset() 静默）

插槽

名称	说明
默认	表单内容（oas-form-item 等）

oas-form-item

属性

属性	说明	类型	默认值
help	控件下方常驻帮助文案，与校验错误独立并存	string	—
label	标签文本（缺省不渲染标签行）	string	—
name	字段名（透传校验关联）	—	—
required	必填星号（仅视觉标记，校验规则仍由 form 的 rules 驱动）	boolean	—
span	24 栅格占列数（仅 form layout="grid" 生效；非 1-24 整数按 24）	string	24
status-icon	校验失败时在错误文本前显示 danger 状态图标（修正后隐藏）	boolean	—

插槽

名称	说明
默认	字段控件

CSS 变量

CSS 变量	默认值
--oas-form-label-width	96px

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