Form Field 表单字段

基于 BrConfigProvider 实现全局主题配置，支持多控件集成、状态联动、布局自定义的企业级表单字段组件，可无缝集成 BrForm 和 BrTable 内联表单。

组件特性

🎨 主题配置：通过 BrConfigProvider 自动继承全局主题设置（颜色、圆角、尺寸等）。
🔄 状态联动：根据字段状态（如错误、成功）自动联动标签、边框和提示文本的颜色。
📐 灵活布局：支持标签顶部、左侧或右侧对齐，并可自定义标签宽度。
🛠️ 高度定制：可轻松使用 TailwindCSS 或传入自定义类名覆盖默认样式。

基础用法

展示一个包含标签、控件和描述的基础表单字段。

<script setup lang="ts">
import { ref } from 'vue'
import { BrFormField } from '@breeze-ui/vue'

const value = ref('')
</script>

<template>
  <div class="max-w-sm">
    <BrFormField 
      label="Username" 
      description="This is your public display name."
      name="username"
    >
      <template #default="{ id, disabled, readonly, state }">
        <input 
          :id="id" 
          v-model="value" 
          :disabled="disabled"
          :readonly="readonly"
          class="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50"
          :class="{ 'border-[var(--destructive)]': state === 'error' }"
          placeholder="Enter username"
        />
      </template>
    </BrFormField>
  </div>
</template>

错误状态

展示在校验失败时，标签、边框和提示文本的联动变色效果。

<script setup lang="ts">
import { ref } from 'vue'
import { BrFormField } from '@breeze-ui/vue'

const email = ref('invalid-email')
</script>

<template>
  <div class="max-w-sm">
    <BrFormField 
      label="Email Address" 
      required
      error="Please enter a valid email address."
      state="error"
    >
      <template #default="{ id, state }">
        <input 
          :id="id" 
          v-model="email"
          class="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 transition-colors"
          :class="state === 'error' ? 'border-[var(--destructive)] focus-visible:ring-[var(--destructive)]' : ''"
        />
      </template>
    </BrFormField>
  </div>
</template>

自定义布局

支持标签在左侧或右侧显示，以及定制标签宽度。

<script setup lang="ts">
import { ref } from 'vue'
import { BrFormField } from '@breeze-ui/vue'

const notification = ref(false)
const agreement = ref(false)
</script>

<template>
  <div class="space-y-6 max-w-sm">
    <!-- Label on the left -->
    <BrFormField 
      label="Push Notifications" 
      description="Receive updates via email."
      label-position="left"
      label-width="120px"
    >
      <template #default="{ id }">
        <input :id="id" v-model="notification" type="checkbox" class="w-4 h-4" />
      </template>
    </BrFormField>

    <!-- Label on the right -->
    <BrFormField 
      label="I have read and agree to the terms." 
      label-position="right"
    >
      <template #default="{ id }">
        <input :id="id" v-model="agreement" type="checkbox" class="w-4 h-4" />
      </template>
    </BrFormField>
  </div>
</template>

状态联动

展示禁用 (disabled)、只读 (readonly) 和加载中 (loading) 状态。标签和描述文本会自动调整样式以匹配当前状态。

<script setup lang="ts">
import { ref } from 'vue'
import { BrFormField } from '@breeze-ui/vue'

const value1 = ref('Some value')
const value2 = ref('Cannot edit this')
const value3 = ref('')
</script>

<template>
  <div class="space-y-6 max-w-sm">
    <!-- Disabled State -->
    <BrFormField 
      label="Disabled Field" 
      description="This field and its label are disabled."
      disabled
    >
      <template #default="{ id, disabled }">
        <input 
          :id="id" 
          v-model="value1" 
          :disabled="disabled"
          class="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50"
        />
      </template>
    </BrFormField>

    <!-- Readonly State -->
    <BrFormField 
      label="Readonly Field" 
      description="This field cannot be modified."
      readonly
    >
      <template #default="{ id, readonly }">
        <input 
          :id="id" 
          v-model="value2" 
          :readonly="readonly"
          class="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 read-only:bg-muted read-only:cursor-default"
        />
      </template>
    </BrFormField>

    <!-- Loading State -->
    <BrFormField 
      label="Loading Field" 
      description="Verifying availability..."
      loading
    >
      <template #default="{ id }">
        <input 
          :id="id" 
          v-model="value3" 
          placeholder="Checking..."
          class="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 pr-10"
        />
      </template>
    </BrFormField>
  </div>
</template>

API 说明

BrFormField

属性	类型	默认值	说明
`name`	`string`	`-`	字段名称，用于表单校验绑定
`label`	`string`	`-`	标签文本
`description`	`string`	`-`	描述信息
`error`	`string`	`-`	错误信息，设置后会自动进入错误状态
`state`	`'default' \| 'error' \| 'success' \| 'warning'`	`'default'`	自定义状态
`disabled`	`boolean`	`false`	是否禁用
`readonly`	`boolean`	`false`	是否只读
`required`	`boolean`	`false`	是否必填（显示红星）
`hideRequiredAsterisk`	`boolean`	`false`	是否隐藏必填星号
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`	`'md'`	尺寸，继承自 ConfigProvider
`labelPosition`	`'top' \| 'left' \| 'right'`	`'top'`	标签位置
`labelWidth`	`string \| number`	`-`	标签宽度（仅左/右位置生效）
`loading`	`boolean`	`false`	是否显示加载态占位
`isolated`	`boolean`	`false`	是否启用 Shadow DOM 样式隔离
`zIndex`	`number`	`-`	层级，默认由 FormFieldManager 自动分配递增

BrFormFieldLabel / BrFormFieldDescription / BrFormFieldMessage

通用属性：支持传入 class 进行样式覆盖，自动从 formFieldContext 注入状态。

FormFieldManager (工具类)

管理全局表单字段层级的单例工具。

import { formFieldManager } from '@breeze-ui/vue/form-field'
// 获取下一个自增的 z-index
const zIndex = formFieldManager.nextZIndex()

// 重置 z-index 基数
formFieldManager.resetZIndex()

#Form Field 表单字段

#组件特性

#基础用法

#错误状态

#自定义布局

#状态联动

#API 说明

#BrFormField

#BrFormFieldLabel / BrFormFieldDescription / BrFormFieldMessage

#FormFieldManager (工具类)