字段

import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import {

安装

🌐 Installation

pnpmnpmyarnbun
pnpm dlx shadcn@latest add field
Copy

用法

🌐 Usage

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

Copy<FieldSet>
  <FieldLegend>Profile</FieldLegend>
  <FieldDescription>This appears on invoices and emails.</FieldDescription>
  <FieldGroup>
    <Field>
      <FieldLabel htmlFor="name">Full name</FieldLabel>
      <Input id="name" autoComplete="off" placeholder="Evil Rabbit" />
      <FieldDescription>This appears on invoices and emails.</FieldDescription>
    </Field>
    <Field>
      <FieldLabel htmlFor="username">Username</FieldLabel>
      <Input id="username" autoComplete="off" aria-invalid />
      <FieldError>Choose another username.</FieldError>
    </Field>
    <Field orientation="horizontal">
      <Switch id="newsletter" />
      <FieldLabel htmlFor="newsletter">Subscribe to the newsletter</FieldLabel>
    </Field>
  </FieldGroup>
</FieldSet>

剖析

🌐 Anatomy

Field 系列旨在用于创建可访问的表单。一个典型的字段结构如下:

🌐 The Field family is designed for composing accessible forms. A typical field is structured as follows:

Copy<Field>
  <FieldLabel htmlFor="input-id">Label</FieldLabel>
  
  <FieldDescription>Optional helper text.</FieldDescription>
  <FieldError>Validation message.</FieldError>
</Field>

• Field 是单个字段的核心封装器。
• FieldContent 是一个弹性列，用于组合标签和描述。如果没有描述，则不是必需的。
• 用 FieldGroup 封装相关字段，并使用 FieldSet 和 FieldLegend 进行语义分组。

表单

🌐 Form

请参阅 Form 文档，以使用 Field 组件以及 React Hook Form 或 Tanstack Form 构建表单。

🌐 See the Form documentation for building forms with the Field component and React Hook Form or Tanstack Form.

示例

🌐 Examples

输入

🌐 Input

import {
  Field,
  FieldDescription,

文本区域

🌐 Textarea

import {
  Field,
  FieldDescription,

选择

🌐 Select

import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import {
  Select,

滑块

🌐 Slider

"use client"

import * as React from "react"

字段集

🌐 Fieldset

import {
  Field,
  FieldDescription,

复选框

🌐 Checkbox

import { Checkbox } from "@/components/ui/checkbox"
import {
  Field,

单选框

🌐 Radio

import {
  Field,
  FieldDescription,

切换

🌐 Switch

import { Field, FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"

选择卡

🌐 Choice Card

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

🌐 Wrap Field components inside FieldLabel to create selectable field groups. This works with RadioItem, Checkbox and Switch components.

import {
  Field,
  FieldContent,

字段组

🌐 Field Group

将 Field 组件与 FieldGroup 堆叠。添加 FieldSeparator 来分隔它们。

🌐 Stack Field components with FieldGroup. Add FieldSeparator to divide them.

import { Checkbox } from "@/components/ui/checkbox"
import {
  Field,

从右到左

🌐 RTL

要在 shadcn/ui 中启用 RTL 支持，请参阅 RTL 配置指南。

🌐 To enable RTL support in shadcn/ui, see the RTL configuration guide.

"use client"

import { Button } from "@/examples/radix/ui-rtl/button"

响应式布局

🌐 Responsive Layout

• 垂直字段： 默认方向将标签、控件和辅助文本垂直堆叠——非常适合移动优先布局。
• 水平字段： 在 Field 上设置 orientation="horizontal" 以使标签和控件并排对齐。与 FieldContent 配合使用以保持描述对齐。
• 响应字段: 在容器感知的父元素内部设置 orientation="responsive" 以实现自动列布局。在 FieldGroup 上应用 @container/field-group 类以在特定断点切换方向。

import { Button } from "@/components/ui/button"
import {
  Field,

验证与错误

🌐 Validation and Errors

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

Copy<Field data-invalid>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" type="email" aria-invalid />
  <FieldError>Enter a valid email address.</FieldError>
</Field>

可访问性

🌐 Accessibility

• FieldSet 和 FieldLegend 让相关控件保持分组，以便键盘和辅助技术用户使用。
• Field 输出 role="group"，因此嵌套控件在组合时继承 FieldLabel 和 FieldLegend 的标签。
• 谨慎使用 FieldSeparator，以确保屏幕阅读器能遇到清晰的章节边界。

API参考

🌐 API Reference

FieldSet

用于渲染带有间距预设的语义 fieldset 的容器。

🌐 Container that renders a semantic fieldset with spacing presets.

Copy<FieldSet>
  <FieldLegend>Delivery</FieldLegend>
  <FieldGroup></FieldGroup>
</FieldSet>

FieldLegend

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

🌐 Legend element for a FieldSet. Switch to the label variant to align with label sizing.

Copy<FieldLegend variant="label">Notification Preferences</FieldLegend>

FieldLegend 有两个变体：legend 和 label。label 变体适用于标签大小和对齐。如果你有嵌套的 FieldSet，这很方便。

🌐 The FieldLegend has two variants: legend and label. The label variant applies label sizing and alignment. Handy if you have nested FieldSet.

FieldGroup

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

🌐 Layout wrapper that stacks Field components and enables container queries for responsive orientations.

Copy<FieldGroup className="@container/field-group flex flex-col gap-6">
  <Field></Field>
  <Field></Field>
</FieldGroup>

字段

🌐 Field

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

🌐 The core wrapper for a single field. Provides orientation control, invalid state styling, and spacing.

Copy<Field orientation="horizontal">
  <FieldLabel htmlFor="remember">Remember me</FieldLabel>
  <Switch id="remember" />
</Field>

FieldContent

当标签位于控件旁边时，将控件和描述分组的弹性列。如果没有描述，则不需要。

🌐 Flex column that groups control and descriptions when the label sits beside the control. Not required if you have no description.

Copy<Field>
  <Checkbox id="notifications" />
  <FieldContent>
    <FieldLabel htmlFor="notifications">Notifications</FieldLabel>
    <FieldDescription>Email, SMS, and push options.</FieldDescription>
  </FieldContent>
</Field>

FieldLabel

标签样式适用于直接输入和嵌套的 Field 子项。

🌐 Label styled for both direct inputs and nested Field children.

Copy<FieldLabel htmlFor="email">Email</FieldLabel>

FieldTitle

在 FieldContent 内以标签样式呈现标题。

🌐 Renders a title with label styling inside FieldContent.

Copy<FieldContent>
  <FieldTitle>Enable Touch ID</FieldTitle>
  <FieldDescription>Unlock your device faster.</FieldDescription>
</FieldContent>

FieldDescription

帮助文本槽，可在水平布局中自动平衡长行。

🌐 Helper text slot that automatically balances long lines in horizontal layouts.

Copy<FieldDescription>We never share your email with anyone.</FieldDescription>

FieldSeparator

用于在 FieldGroup 内部分隔部分的视觉分隔符。可接受可选的内联内容。

🌐 Visual divider to separate sections inside a FieldGroup. Accepts optional inline content.

Copy<FieldSeparator>Or continue with</FieldSeparator>

FieldError

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

🌐 Accessible error container that accepts children or an errors array (e.g., from react-hook-form).

Copy<FieldError errors={errors.username} />

当 errors 数组包含多个消息时，该组件会自动渲染一个列表。

🌐 When the errors array contains multiple messages, the component renders a list automatically.

FieldError 也接受由任何实现了 标准模式 的验证器产生的问题，包括 Zod、Valibot 和 ArkType。将 schema 结果中的 issues 数组直接传递，以在各个库之间呈现统一的错误列表。