Skip to content

表单项 (Form Item)

BrFormItem 组件用于封装单个表单字段,管理其标签(Label)、控件(Control)、描述(Description)和校验信息(Message)。它与 BrForm 无缝集成,并为单个字段的布局和状态提供丰富的定制能力。

特性

  • 🚦 校验状态:内置支持成功、警告和错误状态及自定义提示信息
  • 📐 灵活布局:支持独立的标签对齐方式(左、右、上),可覆盖全局表单布局
  • 自定义指示器:完全可定制的必填项星号或文本
  • ♿️ 无障碍访问:自动将标签、描述和错误信息与表单控件关联

校验状态

你可以显式设置 BrFormItemvalidationStatesuccesswarningerror。结合 successMessagewarningMessageerrorMessage 使用以显示相应的反馈信息。

Looks good!

Password is weak.

Email is already taken.

Example

标签对齐方式

当使用水平表单布局(horizontal)时,你可以使用 labelAlign 属性覆盖单个标签的对齐方式。将其设置为 top 会将标签堆叠在控件上方,从而忽略该特定项的水平布局设置。

Overrides horizontal layout.

Example

自定义星号与间距

使用 asterisk 属性定制必填指示器。你可以传入字符串来替换默认的红色星号,或传入 false 来完全隐藏它(即使该字段是必填的)。spacing 属性允许你调整表单项元素之间的间距。

Spacing is increased via spacing prop.

Example

禁用与只读状态

BrFormItem 上设置 disabledreadonly 状态,会自动将这些状态应用到内部控件并调整视觉外观。

Example

API 参考

BrFormItem

属性类型默认值说明
namestring-表单项的字段名,用于校验和数据绑定
requiredbooleanfalse是否必填。也会根据校验规则自动推断
rulesany-原生 vee-validate 的校验规则
validationState'success' | 'warning' | 'error' | 'default''default'显式的校验状态
successMessagestring-状态为 success 时显示的信息
warningMessagestring-状态为 warning 时显示的信息
errorMessagestring-状态为 error 时显示的信息
labelAlign'left' | 'right' | 'top'-标签的对齐方式。设置后将覆盖表单布局
asteriskboolean | stringtrue自定义必填指示器。设为 false 可隐藏
spacingstring-表单项元素之间的自定义间距(例如 '1rem'
disabledbooleanfalse表单项是否禁用
readonlybooleanfalse表单项是否只读

BrFormLabel

基于 BrLabel 封装,自动从 BrFormItem 上下文读取 idrequired 状态。支持继承所有原生 <label> 属性。

BrFormControl

通过 Slot 将上下文中的 idaria-invalidaria-describedbysizeerror 以及表单事件绑定(v-model)传递给子组件。内部只允许包含一个子元素。

BrFormMessage

自动读取并显示当前表单字段的校验错误信息。支持使用默认插槽覆盖显示内容。

BrFormDescription

提供表单项的帮助文本,自动与 BrFormControlaria-describedby 关联。