109k
新建

字段 (Field)

上一页下一页

组合标签、控件和辅助文本，以构建易于访问的表单字段和组合输入项。

Radix UIBase UI
Radix UI - shadcn/ui 组件库
支付方式

所有交易均经过加密处理，安全可靠

输入您的 16 位卡号

账单地址

与您的支付方式关联的账单地址

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

安装

pnpm dlx shadcn@latest add field

用法

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldTitle,
} from "@/components/ui/field"
<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>

结构解析

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

<Field>
  <FieldLabel htmlFor="input-id">Label</FieldLabel>
  {/* Input, Select, Switch, etc. */}
  <FieldDescription>Optional helper text.</FieldDescription>
  <FieldError>Validation message.</FieldError>
</Field>
  • Field 是单个字段的核心包装器。
  • FieldContent 是一个用于组合标签和描述的 flex 列。如果没有描述，则不是必需的。
  • 使用 FieldGroup 包装相关字段，并配合 FieldSet 和 FieldLegend 进行语义化分组。

表单

有关使用 Field 组件结合 React Hook Form 或 Tanstack Form 构建表单的信息，请参阅 表单 (Form) 文档。

示例

输入框

为您的账户选择一个唯一的用户名。

至少需要 8 个字符。

import {
  Field,
  FieldDescription,

文本域 (Textarea)

分享您对我们服务的想法。

import {
  Field,
  FieldDescription,

选择器

选择您的部门或工作领域。

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

Slider 滑块

价格范围

设置您的预算范围 ($200 - 800).

"use client"

import * as React from "react"

字段集 (Fieldset)

地址信息

我们需要您的地址来配送您的订单。

import {
  Field,
  FieldDescription,

复选框

在桌面上显示这些项目

选择您要在桌面上显示的项目。

你的桌面和文稿文件夹正在与 iCloud 云盘同步。你可以从其他设备访问它们。

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

单选框

订阅方案

年度和终身计划可显著节省费用。

import {
  Field,
  FieldDescription,

开关

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

选择卡片

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

计算环境

为您的集群选择计算环境。

import {
  Field,
  FieldContent,

字段组 (Field Group)

使用 FieldGroup 堆叠 Field 组件。添加 FieldSeparator 来进行分隔。

当 ChatGPT 响应耗时请求（如研究或图像生成）时获得通知。

当您创建的任务有更新时接收通知。 管理任务

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

RTL (从右至左)

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

付款方式

所有交易均安全且加密

输入 16 位卡号

账单地址

与您的支付方式关联的账单地址

"use client"

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

响应式布局

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

填写您的个人资料信息。

提供您的全名以供身份识别

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

验证与错误

  • 将 data-invalid 添加到 Field，将整个模块切换为错误状态。
  • 在输入框本身添加 aria-invalid，以支持辅助技术。
  • 在控件之后或在 FieldContent 内直接渲染 FieldError，以保持错误信息与字段对齐。
<Field data-invalid>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" type="email" aria-invalid />
  <FieldError>Enter a valid email address.</FieldError>
</Field>

可访问性

  • FieldSet 和 FieldLegend 将相关的控件组合在一起，方便键盘和辅助技术用户使用。
  • Field 输出 role="group"，因此嵌套的控件在组合时可以继承来自 FieldLabel 和 FieldLegend 的标签信息。
  • 谨慎应用 FieldSeparator，以确保屏幕阅读器能识别清晰的章节边界。

API 参考

FieldSet

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

属性类型默认
classNamestring
<FieldSet>
  <FieldLegend>Delivery</FieldLegend>
  <FieldGroup>{/* Fields */}</FieldGroup>
</FieldSet>

FieldLegend

FieldSet 的图例元素。切换至 label 变体以符合标签大小设置。

属性类型默认
variant (变体)"legend" | "label""legend"
classNamestring
<FieldLegend variant="label">Notification Preferences</FieldLegend>

FieldLegend 有两种变体：legend 和 label。label 变体应用标签大小和对齐方式。如果您有嵌套的 FieldSet，这会非常方便。

FieldGroup

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

属性类型默认
classNamestring
<FieldGroup className="@container/field-group flex flex-col gap-6">
  <Field>{/* ... */}</Field>
  <Field>{/* ... */}</Field>
</FieldGroup>

字段 (Field)

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

属性类型默认
orientation (方向)"vertical" | "horizontal" | "responsive""vertical" (垂直)
classNamestring
data-invalid布尔值
<Field orientation="horizontal">
  <FieldLabel htmlFor="remember">Remember me</FieldLabel>
  <Switch id="remember" />
</Field>

FieldContent

当标签位于控件旁边时，用于组合控件和描述的 Flex 列。如果没有描述，则不是必需的。

属性类型默认
classNamestring
<Field>
  <Checkbox id="notifications" />
  <FieldContent>
    <FieldLabel htmlFor="notifications">Notifications</FieldLabel>
    <FieldDescription>Email, SMS, and push options.</FieldDescription>
  </FieldContent>
</Field>

FieldLabel

为直接输入和嵌套的 Field 子项设置样式的标签。

属性类型默认
classNamestring
asChild (作为子元素)布尔值false
<FieldLabel htmlFor="email">Email</FieldLabel>

FieldTitle

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

属性类型默认
classNamestring
<FieldContent>
  <FieldTitle>Enable Touch ID</FieldTitle>
  <FieldDescription>Unlock your device faster.</FieldDescription>
</FieldContent>

FieldDescription

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

属性类型默认
classNamestring
<FieldDescription>We never share your email with anyone.</FieldDescription>

FieldSeparator

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

属性类型默认
classNamestring
<FieldSeparator>Or continue with</FieldSeparator>

FieldError

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

属性类型默认
errorsArray<{ message?: string } | undefined>
classNamestring
<FieldError errors={errors.username} />

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

FieldError 还接受任何实现 Standard Schema 的验证器所产生的问题，包括 Zod、Valibot 和 ArkType。直接传入来自模式结果的 issues 数组，即可跨库渲染统一的错误列表。