BreezeUI
  • 简体中文

    • 校验状态

    你可以显式设置 BrFormItem 的 validationState 为 success、warning 或 error。结合 successMessage、warningMessage 或 errorMessage 使用以显示相应的反馈信息。

    <script setup lang="ts">
import {
  BrForm,
  BrFormItem,
  BrFormLabel,
  BrFormControl,
  BrFormMessage,
  BrInput,
  BrFlex
} from '@breezeui/vue'
</script>

<template>
  <BrForm layout="vertical">
    <BrFlex class="gap-6 w-full flex-col sm:flex-row">
      <BrFormItem name="default" class="flex-1">
        <BrFormLabel>Default State</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="Normal input" />
        </BrFormControl>
      </BrFormItem>

      <BrFormItem name="success" validation-state="success" success-message="Looks good!" class="flex-1">
        <BrFormLabel>Success State</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="Valid input" model-value="john_doe" />
        </BrFormControl>
        <BrFormMessage />
      </BrFormItem>

      <BrFormItem name="warning" validation-state="warning" warning-message="Password is weak." class="flex-1">
        <BrFormLabel>Warning State</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="Warning input" type="password" model-value="123" />
        </BrFormControl>
        <BrFormMessage />
      </BrFormItem>

      <BrFormItem name="error" validation-state="error" error-message="Email is already taken." class="flex-1">
        <BrFormLabel>Error State</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="Error input" model-value="test@test" />
        </BrFormControl>
        <BrFormMessage />
      </BrFormItem>
    </BrFlex>
  </BrForm>
</template>

    标签对齐方式

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

    <script setup lang="ts">
import {
  BrForm,
  BrFormItem,
  BrFormLabel,
  BrFormControl,
  BrFormDescription,
  BrInput
} from '@breezeui/vue'
</script>

<template>
  <BrForm layout="horizontal" class="max-w-md">
    <BrFormItem name="leftAlign" label-align="left" required>
      <BrFormLabel>Left Align</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Label aligns to the left" />
      </BrFormControl>
    </BrFormItem>

    <BrFormItem name="rightAlign" label-align="right" required>
      <BrFormLabel>Right Align</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Label aligns to the right" />
      </BrFormControl>
    </BrFormItem>

    <BrFormItem name="topAlign" label-align="top" required>
      <BrFormLabel>Top Align</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Label is stacked on top" />
      </BrFormControl>
      <BrFormDescription>Overrides horizontal layout.</BrFormDescription>
    </BrFormItem>
  </BrForm>
</template>

    自定义星号与间距

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

    <script setup lang="ts">
import {
  BrForm,
  BrFormItem,
  BrFormLabel,
  BrFormControl,
  BrFormDescription,
  BrInput
} from '@breezeui/vue'
</script>

<template>
  <BrForm layout="vertical" class="max-w-md">
    <BrFormItem name="customAst" asterisk="(Required)" required spacing="1.5rem">
      <BrFormLabel>Custom Asterisk</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Asterisk is replaced with text" />
      </BrFormControl>
      <BrFormDescription>Spacing is increased via spacing prop.</BrFormDescription>
    </BrFormItem>

    <BrFormItem name="noAst" :asterisk="false" required>
      <BrFormLabel>Hidden Asterisk</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Asterisk is hidden despite being required" />
      </BrFormControl>
    </BrFormItem>
  </BrForm>
</template>

    禁用与只读状态

    在 BrFormItem 上设置 disabled 或 readonly 状态，会自动将这些状态应用到内部控件并调整视觉外观。

    <script setup lang="ts">
import {
  BrForm,
  BrFormItem,
  BrFormLabel,
  BrFormControl,
  BrInput
} from '@breezeui/vue'
</script>

<template>
  <BrForm layout="horizontal" class="max-w-md">
    <BrFormItem name="disabled" disabled>
      <BrFormLabel>Disabled</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Cannot interact" />
      </BrFormControl>
    </BrFormItem>

    <BrFormItem name="readonly" readonly>
      <BrFormLabel>Readonly</BrFormLabel>
      <BrFormControl>
        <BrInput model-value="Read-only value" readonly />
      </BrFormControl>
    </BrFormItem>
  </BrForm>
</template>

    表单项 (Form Item)

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

    组件特性

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

    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 上下文读取 id 和 required 状态。支持继承所有原生 <label> 属性。

    BrFormControl

    通过 Slot 将上下文中的 id、aria-invalid、aria-describedby、size、error 以及表单事件绑定（v-model）传递给子组件。内部只允许包含一个子元素。

    BrFormMessage

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

    BrFormDescription

    提供表单项的帮助文本，自动与 BrFormControl 的 aria-describedby 关联。