表单项 (Form Item)
BrFormItem 组件用于封装单个表单字段,管理其标签(Label)、控件(Control)、描述(Description)和校验信息(Message)。它与 BrForm 无缝集成,并为单个字段的布局和状态提供丰富的定制能力。
特性
- 🚦 校验状态:内置支持成功、警告和错误状态及自定义提示信息
- 📐 灵活布局:支持独立的标签对齐方式(左、右、上),可覆盖全局表单布局
- ✨ 自定义指示器:完全可定制的必填项星号或文本
- ♿️ 无障碍访问:自动将标签、描述和错误信息与表单控件关联
校验状态
你可以显式设置 BrFormItem 的 validationState 为 success、warning 或 error。结合 successMessage、warningMessage 或 errorMessage 使用以显示相应的反馈信息。
Example
标签对齐方式
当使用水平表单布局(horizontal)时,你可以使用 labelAlign 属性覆盖单个标签的对齐方式。将其设置为 top 会将标签堆叠在控件上方,从而忽略该特定项的水平布局设置。
Example
自定义星号与间距
使用 asterisk 属性定制必填指示器。你可以传入字符串来替换默认的红色星号,或传入 false 来完全隐藏它(即使该字段是必填的)。spacing 属性允许你调整表单项元素之间的间距。
Example
禁用与只读状态
在 BrFormItem 上设置 disabled 或 readonly 状态,会自动将这些状态应用到内部控件并调整视觉外观。
Example
API 参考
BrFormItem
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| name | string | - | 表单项的字段名,用于校验和数据绑定 |
| required | boolean | false | 是否必填。也会根据校验规则自动推断 |
| rules | any | - | 原生 vee-validate 的校验规则 |
| validationState | 'success' | 'warning' | 'error' | 'default' | 'default' | 显式的校验状态 |
| successMessage | string | - | 状态为 success 时显示的信息 |
| warningMessage | string | - | 状态为 warning 时显示的信息 |
| errorMessage | string | - | 状态为 error 时显示的信息 |
| labelAlign | 'left' | 'right' | 'top' | - | 标签的对齐方式。设置后将覆盖表单布局 |
| asterisk | boolean | string | true | 自定义必填指示器。设为 false 可隐藏 |
| spacing | string | - | 表单项元素之间的自定义间距(例如 '1rem') |
| disabled | boolean | false | 表单项是否禁用 |
| readonly | boolean | false | 表单项是否只读 |
BrFormLabel
基于 BrLabel 封装,自动从 BrFormItem 上下文读取 id 和 required 状态。支持继承所有原生 <label> 属性。
BrFormControl
通过 Slot 将上下文中的 id、aria-invalid、aria-describedby、size、error 以及表单事件绑定(v-model)传递给子组件。内部只允许包含一个子元素。
BrFormMessage
自动读取并显示当前表单字段的校验错误信息。支持使用默认插槽覆盖显示内容。
BrFormDescription
提供表单项的帮助文本,自动与 BrFormControl 的 aria-describedby 关联。