BreezeUI

简体中文

English

简体中文

English

Appearance

Form 表单 ​

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

特性 ​

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

基础表单 (水平布局) ​

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

Unique identifier used to log into the system

Example

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

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

Example

栅格布局表单 ​

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

Example

表单项标签对齐方式 ​

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

vue
<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 属性支持自定义必填星号或隐藏星号。

vue
<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 全局修改表单的主题色与校验色：

vue
<script setup>
import { BrConfigProvider, BrForm, BrFormItem, BrFormLabel, BrFormControl, BrInput } from '@breezeui/vue'

const theme = {
  primary: '#8b5cf6',   // 聚焦状态的边框色
  error: '#ef4444',     // 校验失败时的文字与边框色
  radius: 0.5,          // 输入框圆角
}
</script>

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

局部样式覆盖 (TailwindCSS) ​

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

vue
<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 的必填星号颜色、标签文字大小、以及错误提示的背景色等：

vue
<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>

API 说明 ​

BrForm ​

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

BrFormItem ​

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

BrFormLabel ​

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

BrFormControl ​

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

BrFormMessage ​

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

BrFormDescription ​

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