Payment Method

All transactions are secure and encrypted

Name on Card

Card Number

Enter your 16-digit card number

Month

Year

CVV

Billing Address

The billing address associated with your payment method

Same as shipping address

Comments

安装

pnpm dlx shadcn-vue@latest add field

使用

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldTitle,
} from "@/components/ui/field"
</script>

<template>
  <FieldSet>
    <FieldLegend>个人资料</FieldLegend>
    <FieldDescription>此信息将显示在发票和邮件中。</FieldDescription>
    <FieldGroup>
        <Field>
        <FieldLabel for="name">全名</FieldLabel>
        <Input id="name" autoComplete="off" placeholder="邪恶兔子" />
        <FieldDescription>此信息将显示在发票和邮件中。</FieldDescription>
        </Field>
        <Field>
        <FieldLabel for="username">用户名</FieldLabel>
        <Input id="username" autoComplete="off" aria-invalid />
        <FieldError>请选择其他用户名。</FieldError>
        </Field>
        <Field orientation="horizontal">
        <Switch id="newsletter" />
        <FieldLabel for="newsletter">订阅新闻通讯</FieldLabel>
        </Field>
    </FieldGroup>
 </FieldSet>
</template>

结构

Field 组件族旨在构建可访问的表单。

典型字段结构如下：

<template>
  <Field>
    <FieldLabel for="input-id">标签</FieldLabel>
    <!-- Input, Select, Switch, 等等 -->
    <FieldDescription>可选帮助文本。</FieldDescription>
    <FieldError>验证消息。</FieldError>
  </Field>
</template>

• Field 是单个字段的核心包装器。
• FieldContent 是一个弹性列布局，在标签旁边聚集标签和说明。若无说明，则不必使用。
• 将相关字段用 FieldGroup 包装，并使用带有 FieldLegend 的 FieldSet 进行语义分组。

示例

输入框

Username

Choose a unique username for your account.

Password

Must be at least 8 characters long.

文本域

Feedback

Share your thoughts about our service.

下拉框

Department

Select your department or area of work.

滑块

Price Range

Set your budget range ($ 200 - 800).

字段集

Address Information

We need your address to deliver your order.

Street Address

City

Postal Code

复选框

Show these items on the desktop

Select the items you want to show on the desktop.

Hard disks

External disks

CDs, DVDs, and iPods

Connected servers

Sync Desktop & Documents folders

Your Desktop & Documents folders are being synced with iCloud Drive. You can access them from other devices.

单选按钮

Subscription Plan

Yearly and lifetime plans offer significant savings.

Monthly ($9.99/month)

Yearly ($99.99/year)

Lifetime ($299.99)

切换开关

Multi-factor authentication

Enable multi-factor authentication. If you do not have a two-factor device, you can use a one-time code sent to your email.

选择卡片

将 Field 组件嵌套在 FieldLabel 内可创建可选的字段组。这适用于 RadioItem、Checkbox 和 Switch 组件。

Compute Environment

Select the compute environment for your cluster.

Kubernetes

Run GPU workloads on a K8s configured cluster.

Virtual Machine

Access a VM configured cluster to run GPU workloads.

字段组

堆叠 Field 组件，并使用 FieldGroup。添加 FieldSeparator 可将它们分隔开。

Responses

Get notified when ChatGPT responds to requests that take time, like research or image generation.

Push notifications

Tasks

Get notified when tasks you've created have updates.{" "} Manage tasks

Push notifications

Email notifications

响应式布局

如果你使用 Tailwind CSS v3，需要安装 @tailwindcss/container-queries。

• 垂直字段： 默认方向将标签、控件和辅助文本堆叠，适合移动优先布局。
• 水平字段： 设置 orientation="horizontal" 在 Field 以将标签和控件并排对齐。与 FieldContent 配合使用可保持说明对齐。
• 响应式字段： 将 orientation="responsive" 设置为自动列布局，并在容器感知父级内使用。通过在 FieldGroup 上应用 @container/field-group 类，在特定断点切换方向。

Profile

Fill in your profile information.

Name

Provide your full name for identification

Message

You can write your message here. Keep it short, preferably under 100 characters.

验证与错误

• 在 Field 上添加 data-invalid 可将整个块切换为错误状态。
• 在输入本身添加 aria-invalid 以支持辅助技术。
• 在控件之后或 FieldContent 内立即渲染 FieldError，以保持错误消息与字段对齐。

<template>
  <Field data-invalid>
    <FieldLabel for="email">电子邮件</FieldLabel>
    <Input id="email" type="email" aria-invalid />
    <FieldError>请输入有效的电子邮件地址。</FieldError>
  </Field>
<template>

可访问性

• FieldSet 与 FieldLegend 将相关控件组合在一起，方便键盘和辅助技术用户使用。
• Field 输出 role="group"，使嵌套控件继承 FieldLabel 与 FieldLegend 的标签。
• 谨慎使用 FieldSeparator，以确保屏幕阅读器识别清晰的段落边界。

API 参考

FieldSet

容器，渲染语义化的 fieldset 并带有间距预设。

Prop	Type	Default
class	string

<template>
  <FieldSet>
    <FieldLegend>交付</FieldLegend>
    <FieldGroup>
        <!-- Fields -->
    </FieldGroup>
  </FieldSet>
</template>

FieldLegend

FieldSet 的图例元素。切换到 label 变体以与标签尺寸对齐。

Prop	Type	Default
variant	"legend" | "label"	"legend"
class	string

<FieldLegend variant="label">通知偏好</FieldLegend>

FieldLegend 有两个变体：legend 和 label。label 变体应用标签尺寸与对齐，若你有嵌套 FieldSet，非常方便。

FieldGroup

布局包装器，堆叠 Field 组件，并启用容器查询以实现响应式方向。

Prop	Type	Default
class	string

<template>
  <FieldGroup class="@container/field-group flex flex-col gap-6">
    <Field><!-- Fields --></Field>
    <Field><!-- Fields --></Field>
  </FieldGroup>
</template>

Field

单个字段的核心包装器。提供方向控制、无效状态样式和间距。

Prop	Type	Default
orientation	"vertical" | "horizontal" | "responsive"	"vertical"
class	string
data-invalid	boolean

<Field orientation="horizontal">
  <FieldLabel for="remember">记住我</FieldLabel>
  <Switch id="remember" />
</Field>

FieldContent

弹性列布局，在标签旁边聚集控件和说明。若无说明，则不必使用。

Prop	Type	Default
class	string

<Field>
  <Checkbox id="notifications" />
  <FieldContent>
    <FieldLabel for="notifications">通知</FieldLabel>
    <FieldDescription>电子邮件、SMS 和推送选项。</FieldDescription>
  </FieldContent>
</Field>

FieldLabel

标签，样式适用于直接输入和嵌套 Field 子组件。

Prop	Type	Default
class	string
asChild	boolean	false

<FieldLabel for="email">电子邮件</FieldLabel>

FieldTitle

在 FieldContent 内渲染一个带标签样式的标题。

Prop	Type	Default
class	string

<FieldContent>
  <FieldTitle>启用指纹识别</FieldTitle>
  <FieldDescription>更快解锁设备。</FieldDescription>
</FieldContent>

FieldDescription

辅助文本插槽，自动平衡水平布局中的长行。

Prop	Type	Default
class	string

<FieldDescription>我们永远不会将您的电子邮件与任何人共享。</FieldDescription>

FieldSeparator

可视分隔符，用于分隔 FieldGroup 内的段落。接受可选的内联内容。

Prop	Type	Default
class	string

<FieldSeparator>或者继续使用</FieldSeparator>

FieldError

可访问错误容器，接受子元素或 errors 数组（例如来自 vee-validate）。

Prop	Type	Default
errors	Array<{ message?: string } | undefined>
class	string

<FieldError :errors="errors.username" />

当 errors 数组包含多个消息时，组件会自动渲染列表。
FieldError 还接受任何实现了 Standard Schema，包括 Zod、Valibot 和 ArkType 的校验器。将模式结果的 issues 数组直接传给它即可跨库统一显示错误列表。