n-form 表单容器
纵向堆叠 n-form-item 表单行，统一管理标签布局（位置 / 对齐 / 宽度）与校验规则。页面自持数据对象（model 只读取值参与校验，不回写），提交前经组件 ref 调用 validate 整表校验，首个错误按条目在模板中的顺序返回。
- 数据归页面：表单不复制、不回写 model，输入控件照常
:model-value+@update:model-value受控使用- 校验规则两处可放：表单级
rules（Map，按字段名索引）与条目级rules（同名字段条目级优先）- 已有错误的字段在值变化后自动重校验（纠错即清），未触发过校验的字段不主动报错
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
API
属性
| 参数 | 说明 | 类型 | 默认值 | 可选值 |
|---|---|---|---|---|
| model | 表单数据对象（只读取值参与校验，不回写）；字段值变化后已有错误的字段自动重校验。支持 a.b 点路径取嵌套值 | UTSJSONObject | null | - |
| rules | 表单级校验规则表（键 = 条目 prop 名）；同名字段的条目级 rules 优先于本表 | Map<string, NFormRule[]> | null | - |
| label-position | 标签位置：left 水平排在控件左侧，top 堆叠在控件上方 | String | left | left / top |
| label-align | 水平排列时标签文字对齐 | String | left | left / center / right |
| label-valign | 水平排列时标签相对控件的纵向对齐（控件为多行内容时生效） | String | center | top / center / bottom |
| label-width | 标签宽度 px（水平排列时生效，top 时标签占满整行） | Number | 80 | - |
| label-style | 标签行内样式（表单级默认，条目非空 label-style 覆盖），如 "font-weight:600" | String | "" | 与 css 相同 |
| border-bottom | 条目行底分隔线（条目可覆盖） | Boolean | true | - |
| show-asterisk | 显示必填星号（条目 required 或规则含 required 时渲染） | Boolean | true | - |
| asterisk-position | 必填星号位置 | String | left | left / right |
| show-message | error-type 为 message 时显示条目错误文字（条目可覆盖） | Boolean | true | - |
| error-type | 错误展示通道：message 控件下方错误文字 / toast 轻提示（校验首个错误）/ border-bottom 行底红线 / none 只回调不展示 | String | message | message / toast / border-bottom / none |
| disabled | 整表禁用：透明遮罩盖住表单拦截全部交互（已聚焦的输入框到失焦才收键盘） | Boolean | false | - |
| custom-class | 挂到根节点的额外 class（类需定义在组件样式表内） | String | "" | - |
| custom-style | 根节点行内样式，如 "margin:0 15px" 用于表单两侧留白 | String | "" | 与 css 相同 |
事件
无（校验结果经 validate 回调返回，见下方方法）。
方法（经组件 ref 调用）
| 方法名 | 说明 | 参数 |
|---|---|---|
| validate | 整表校验：按条目模板顺序逐字段校验，error-type 为 toast 时轻提示首个错误 | callback: (valid: boolean, errors: Array<NFormError>) => void |
| validateField | 校验单个字段，返回错误信息（null = 通过） | prop: string |
| clearValidate | 清除校验错误；传空数组清除全部 | props: string[] |
插槽
| 插槽名 | 说明 |
|---|---|
| default | 表单行内容（通常是若干 n-form-item） |
规则类型 NFormRule
| 字段 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| required | 必填：值为 null、空串或空数组时未通过 | Boolean | false |
| message | 未通过时的错误信息；留空用内置文案（走语言包） | String | "" |
| min | 数值比大小、字符串与数组比长度 | Number | - |
| max | 数值比大小、字符串与数组比长度 | Number | - |
| pattern | 正则校验（对值转字符串后匹配） | RegExp | - |
| validator | 自定义校验函数：返回 true 通过；返回字符串即错误信息；返回 false 取 message 或内置文案 | (value) => boolean | string | - |
逐条按序执行，首条未通过即终止；值为空且未声明 required 时跳过其余校验（非必填字段允许留空）。
实现说明
机制对照（参考源并集 → 本库实现）：
- 规则模型取类型化方案（required / message / min / max / pattern / validator），字符串规则名（正则集合写死在库内）不收——正则与函数在 uts 下一等支持，用户自写
pattern即等价表达- 错误展示通道为并集：message 条目下方文字（默认）/ toast 轻提示（整表校验时 uni.showToast，全端可用零依赖）/ border-bottom 行底红线 / none 只回调；参考源自绘的错误提示浮层不收（toast 通道已覆盖其场景）
- 整表禁用用透明遮罩（常驻节点 + v-show）：对任意插槽内容立即生效、零耦合；"成员控件读表单上下文自行禁用"的路线要求全部控件配合注入，跨组件耦合不收
- 条目点击事件不提供：行内通常内嵌输入控件，App 端父容器交互绑定会拦截子控件触摸、输入法唤不起（行组件零交互绑定为库内既定纪律）；点击语义由行内控件（如选择器触发器）自行承载
- 滚动到首个错误不内置：页面滚动容器归页面管（本库页面骨架不提供滚动 API），validate 回调的 errors 按模板顺序排列，
errors[0]即第一个错误，页面可据此自行滚动定位- 原生 form 提交联动（behaviors 注入聚合组件值）不收：uni-app x 不支持 behaviors，表单提交走 validate 回调拿全量 model
- 值变化重校验：仅对已有错误的字段生效（纠错即清），不给未触发过校验的字段主动报错；model 传响应式对象（ref / computed / reactive）即生效