Field

控件周围的配套部分：标签、一行说明文字，以及带小斜切标记、滑入显示的错误信息。校验沿用 Base UI 的机制。

安装

terminal

# once per project: where @zzzui items come frompnpm dlx shadcn@latest registry add @zzzui=https://zzzui.catforest.dev/r/{name}.jsonpnpm dlx shadcn@latest add @zzzui/field

示例

输入时校验

Callsign

Shown on every job you take.

field-validation.tsx

import {  Field,  FieldDescription,  FieldError,  FieldLabel,} from "@/components/zero/field";import { Input } from "@/components/zero/input";export default function FieldValidation() {  return (    <Field      className="w-full max-w-xs"      validationMode="onChange"      validate={(value) =>        typeof value === "string" && value.length > 0 && value.length < 3          ? "At least three characters."          : null      }    >      <FieldLabel>Callsign</FieldLabel>      <Input placeholder="Three or more characters" />      <FieldDescription>Shown on every job you take.</FieldDescription>      <FieldError />    </Field>  );}

由外部标记为无效

Drop point

That pier closed last season.

field-invalid.tsx

import { Field, FieldError, FieldLabel } from "@/components/zero/field";import { Input } from "@/components/zero/input";export default function FieldInvalid() {  return (    <Field invalid className="w-full max-w-xs">      <FieldLabel>Drop point</FieldLabel>      <Input defaultValue="Pier 0" />      <FieldError match>That pier closed last season.</FieldError>    </Field>  );}

行为

放在 Field 内的 Input 或 Select 即为该 Field 的控件：标签作为控件的可访问名称；Field 无效时，控件描边与标签一同变为危险色。

错误信息在 240 ms 内滑入，消失更快，只需 140 ms。校验在别处完成时，为 FieldError 设置 match，字段一旦无效即显示错误信息。

属性

Field

属性	类型	默认值	说明
validate	(value) => string \| string[] \| null	—	根据值返回错误信息，无错误时返回 null。
validationMode	"onSubmit" \| "onBlur" \| "onChange"	"onSubmit"	validate 的执行时机。
invalid	boolean	—	从外部将字段标记为无效。

另可传入 Base UI Field.Root 的全部属性。

FieldLabel

另可传入 Base UI Field.Label 的全部属性。

FieldDescription

另可传入 Base UI Field.Description 的全部属性。

FieldError

属性	类型	默认值	说明
match	boolean \| keyof ValidityState	—	为 true 时，字段无效即显示；传入 validity 键名时，仅在该项校验失败时显示。

另可传入 Base UI Field.Error 的全部属性。