基础表单 (水平布局)

使用 layout="horizontal" 快速搭建企业级常见的水平表单。

<script setup lang="ts">
import { toTypedSchema } from '@vee-validate/zod'
import * as z from 'zod'
import { 
  BrForm, BrFormItem, BrFormLabel, BrFormControl, BrFormMessage, BrFormDescription,
  BrInput, BrButton 
} from '@breezeui/vue'

const formSchema = toTypedSchema(z.object({
  username: z.string().min(2, 'Username requires at least 2 characters'),
}))

const onSubmit = (values: any) => {
  console.log('Submitted data:', values)
}
</script>

<template>
  <BrForm layout="horizontal" :validation-schema="formSchema" @submit="onSubmit">
    <BrFormItem name="username" required>
      <BrFormLabel>Username</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Please enter username" />
      </BrFormControl>
      <BrFormDescription>Unique identifier used to log into the system</BrFormDescription>
      <BrFormMessage />
    </BrFormItem>

    <BrFormItem>
      <div class="col-start-2 mt-4">
        <BrButton type="submit">Submit</BrButton>
      </div>
    </BrFormItem>
  </BrForm>
</template>

带有复杂校验规则的表单

结合 vee-validate 与 zod，轻松实现异步校验与多字段校验。

<script setup lang="ts">
import { toTypedSchema } from '@vee-validate/zod'
import * as z from 'zod'
import { 
  BrForm, BrFormItem, BrFormLabel, BrFormControl, BrFormMessage,
  BrInput, BrButton 
} from '@breezeui/vue'

const formSchema = toTypedSchema(z.object({
  password: z.string().min(8, 'Password length cannot be less than 8 characters'),
  confirmPassword: z.string()
}).refine(data => data.password === data.confirmPassword, {
  message: "Passwords do not match",
  path: ["confirmPassword"],
}))

const onSubmit = (values: any) => {
  console.log(values)
}
</script>

<template>
  <BrForm layout="vertical" :validation-schema="formSchema" @submit="onSubmit">
    <BrFormItem name="password" required>
      <BrFormLabel>Password</BrFormLabel>
      <BrFormControl>
        <BrInput type="password" placeholder="Please enter password" />
      </BrFormControl>
      <BrFormMessage />
    </BrFormItem>

    <BrFormItem name="confirmPassword" required>
      <BrFormLabel>Confirm Password</BrFormLabel>
      <BrFormControl>
        <BrInput type="password" placeholder="Please enter password again" />
      </BrFormControl>
      <BrFormMessage />
    </BrFormItem>

    <BrButton type="submit" class="mt-4">Register</BrButton>
  </BrForm>
</template>

栅格布局表单

在复杂表单场景下，结合 BrGrid 实现多列响应式排版。

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

const onSubmit = (values: any) => {
  console.log(values)
}
</script>

<template>
  <BrForm layout="vertical" @submit="onSubmit">
    <BrGrid :cols="2" gap="4">
      <BrGridItem>
        <BrFormItem name="firstName">
          <BrFormLabel>First Name</BrFormLabel>
          <BrFormControl>
            <BrInput placeholder="First Name" />
          </BrFormControl>
          <BrFormMessage />
        </BrFormItem>
      </BrGridItem>
      
      <BrGridItem>
        <BrFormItem name="lastName">
          <BrFormLabel>Last Name</BrFormLabel>
          <BrFormControl>
            <BrInput placeholder="Last Name" />
          </BrFormControl>
          <BrFormMessage />
        </BrFormItem>
      </BrGridItem>
    </BrGrid>

    <BrButton type="submit" class="mt-4">Submit</BrButton>
  </BrForm>
</template>

表单项标签对齐方式

BrFormItem 支持 labelAlign 属性独立控制单个表单项的标签对齐方式，包括 left、right 和 top。在小屏下，水平布局的表单项会自动响应式堆叠。

<template>
  <BrForm layout="horizontal">
    <BrFormItem name="leftAlign" labelAlign="left" required>
      <BrFormLabel>左对齐标签</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="标签向左对齐" />
      </BrFormControl>
    </BrFormItem>

    <BrFormItem name="rightAlign" labelAlign="right" required>
      <BrFormLabel>右对齐标签</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="标签向右对齐" />
      </BrFormControl>
    </BrFormItem>

    <BrFormItem name="topAlign" labelAlign="top" required>
      <BrFormLabel>顶部对齐标签</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="强制在顶部显示" />
      </BrFormControl>
    </BrFormItem>
  </BrForm>
</template>

自定义校验提示与必填标记

通过 BrFormItem 的 validationState、errorMessage、successMessage、warningMessage 属性可快速绑定自定义校验状态。同时，asterisk 属性支持自定义必填星号或隐藏星号。

<template>
  <BrForm layout="vertical">
    <BrFormItem 
      name="customAst" 
      asterisk="(必填)" 
      required 
      spacing="1.5rem"
    >
      <BrFormLabel>自定义星号与间距</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="星号被替换为文字，间距变大" />
      </BrFormControl>
      <BrFormDescription>通过 spacing 属性自定义表单项内部间距。</BrFormDescription>
    </BrFormItem>

    <BrFormItem 
      name="success" 
      validationState="success" 
      successMessage="用户名可用！"
    >
      <BrFormLabel>成功状态</BrFormLabel>
      <BrFormControl>
        <BrInput modelValue="BreezeUI_User" />
      </BrFormControl>
      <BrFormMessage />
    </BrFormItem>
  </BrForm>
</template>

主题定制示例

BrForm 完全接入了 BrConfigProvider 的设计 Token 系统，你可以通过全局配置或 Tailwind 类名进行定制。

全局配置 (BrConfigProvider)

通过 BrConfigProvider 全局修改表单的主题色与校验色：


<template>
  <BrConfigProvider :theme="theme">
    <BrForm>
      <BrFormItem name="demo" required>
        <BrFormLabel>全局主题表单</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="聚焦或报错时将展示自定义颜色" />
        </BrFormControl>
      </BrFormItem>
    </BrForm>
  </BrConfigProvider>
</template>

局部样式覆盖 (TailwindCSS)

你可以通过传入 class 或局部 CSS 变量，轻松覆盖单个表单的默认样式：

<template>
  <BrForm 
    layout="horizontal" 
    class="[--br-form-label-width:150px]" <!-- 自定义水平表单的 Label 宽度 -->
  >
    <BrFormItem name="email">
      <BrFormLabel class="text-blue-500 text-base">自定义标签</BrFormLabel>
      <BrFormControl>
        <BrInput class="bg-gray-50 border-gray-300" />
      </BrFormControl>
    </BrFormItem>
  </BrForm>
</template>

BrFormItem 专属样式定制

可以通过传递 style 或者修改 CSS 变量，定制 BrFormItem 的必填星号颜色、标签文字大小、以及错误提示的背景色等：

<template>
  <BrFormItem 
    name="custom" 
    required
    validationState="error"
    errorMessage="此项配置存在错误"
    class="
      /* 自定义必填星号颜色 */
      [&_.br-form-label::after]:!text-purple-500 
      /* 全局配置标签文字大小 */
      [&_.br-form-label]:text-lg 
      /* 错误提示背景色 */
      [&_.br-form-message]:bg-red-50 [&_.br-form-message]:p-2 [&_.br-form-message]:rounded-md
    "
  >
    <BrFormLabel>高级定制项</BrFormLabel>
    <BrFormControl>
      <BrInput />
    </BrFormControl>
    <BrFormMessage />
  </BrFormItem>
</template>

Form 表单

基于 BrConfigProvider 实现全局主题配置，支持校验、布局、联动与无障碍访问的企业级表单组件。底层集成 vee-validate 与 @vee-validate/zod，提供极致的类型安全与校验体验。

组件特性

🔒 类型安全：基于 Zod 的 Schema 校验。
🎨 主题配置：通过 BrConfigProvider 统一管理表单颜色、尺寸与间距。
📐 多种布局：支持垂直（vertical）、水平（horizontal）、行内（inline）与栅格布局。
📦 表单项容器：核心容器，支持标签对齐方式切换、必填星号自定义、多状态校验联动及响应式堆叠。
♿️ 无障碍：自动生成 aria-describedby 与 aria-invalid 属性。
⚡ 状态反馈：自动处理错误提示与输入框高亮。

API 说明

BrForm

属性	类型	默认值	说明
layout	`'vertical' \| 'horizontal' \| 'inline'`	`'vertical'`	表单布局方式
size	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`	`'md'`	表单控件的全局尺寸
hideRequiredAsterisk	`boolean`	`false`	是否隐藏必填项的红色星号
showMessage	`boolean`	`true`	是否全局显示错误提示信息
keepValues	`boolean`	`false`	组件卸载时是否保留表单值

BrFormItem

属性	类型	默认值	说明
name	`string`	-	表单域的字段名，用于校验与数据绑定
required	`boolean`	`false`	是否必填（也会根据校验规则自动推导）
asterisk	`boolean \| string`	`true`	是否显示必填星号。传入字符串可自定义必填标记，传入 `false` 可隐藏
rules	`any`	-	`vee-validate` 原生校验规则
labelAlign	`'left' \| 'right' \| 'top'`	-	表单项标签的对齐方式，覆盖全局布局默认行为
validationState	`'success' \| 'error' \| 'warning' \| 'default'`	`'default'`	强制绑定特定的校验状态，控制组件颜色
spacing	`string \| number`	-	自定义表单项内元素间距，支持像素或 CSS 单位
disabled	`boolean`	`false`	禁用表单项（禁用内层控件交互及置灰）
readonly	`boolean`	`false`	表单项处于只读状态
errorMessage	`string`	-	自定义错误提示文案
successMessage	`string`	-	自定义成功提示文案
warningMessage	`string`	-	自定义警告提示文案

BrFormLabel

基于 BrLabel 封装，自动读取 FormItem 上下文的 id 与 required 状态。支持继承所有原生 <label> 属性。

BrFormControl

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

BrFormMessage

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

BrFormDescription

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

#基础表单 (水平布局)

#带有复杂校验规则的表单

#栅格布局表单

#表单项标签对齐方式

#自定义校验提示与必填标记

#主题定制示例

#全局配置 (BrConfigProvider)

#局部样式覆盖 (TailwindCSS)

#BrFormItem 专属样式定制

#Form 表单

#组件特性

#API 说明

#BrForm

#BrFormItem

#BrFormLabel

#BrFormControl

#BrFormMessage

#BrFormDescription