表单组件版本 0.1.0

Field 表单字段

把标签、表单控件、帮助文字与错误消息关联为完整字段。

使用概览

适合使用

输入控件需要统一表达必填、禁用、说明或校验错误时。

不建议使用

内容不是表单字段，或内部没有可关联的输入控件时。

真实示例

工作邮箱

用于接收邀请。

正在加载示例…

安装

本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。

pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/field.json

基础用法

导入

import { Field, FieldLabel, FieldDescription, FieldMessage } from "@richardqiu/quartz/field";

JSX

<Field controlId="email" descriptionIds="email-help" required><FieldLabel>工作邮箱</FieldLabel><input id="email" name="email" type="email" /><FieldDescription id="email-help">用于接收邀请。</FieldDescription><FieldMessage id="email-error" /></Field>

状态与控制摘要

默认

已禁用

无效

label · textactive · boolean

API 参考

属性	类型	默认值	说明
`controlId`	`string`	`必填`	提供标签与输入控件共享的稳定标识。
`invalid`	`boolean`	`false`	同步字段及其消息的无效状态语义。

组合结构

01Field
02FieldLabel
03FieldDescription
04FieldMessage

键盘约定

Field 不添加额外键盘行为，焦点顺序由内部原生控件决定。

可访问性契约

controlId 统一关联标签与控件，说明和消息 ID 统一组成 aria-describedby。
校验逻辑仍由使用方负责。