组件Controls
Field
@mox-hub/ui 组件 · Controls · canonical
field@mox-hub/uiControlscanonicalsrc/components/field.tsx变体轴
orientationverticalhorizontalresponsive
变体演示field
用于登录与通知。
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| className* | string | — | — |
| orientation* | "horizontal" | "vertical" | "responsive" | "vertical" | — |
源码
import { useMemo } from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "../lib/utils"
import { Label } from "./label"
import { Separator } from "./separator"
function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
return (
<fieldset
data-slot="field-set"
className={cn(
"flex flex-col gap-6 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
className
)}
{...props}
/>
)
}
function FieldLegend({
className,
variant = "legend",
...props
}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
return (
<legend
data-slot="field-legend"
data-variant={variant}
className={cn(
"mb-3 font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base",
className
)}
{...props}
/>
)
}
function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="field-group"
className={cn(
"group/field-group @container/field-group flex w-full flex-col gap-7 has-[>[data-slot=checkbox-group]]:gap-3 *:data-[slot=field-group]:gap-4",
className
)}
{...props}
/>
)
}
/**
* `field-label` 槽的字号档与色调档(E 类批 0 增补,2026-09-27)。
*
* 归因(实测,见交付报告):全库 178 个裸 `<label>` / 49 文件里——
* · 字号:`text-xs` 110 处(28 文件) vs `text-sm` 54 处(17 文件),**多数形态是 12px 标签**,
* 而 `Label` 基线把字号写死成 `text-sm`;
* · 色调:弱色 61 处(`text-muted-foreground` 41 + `text-content-text-secondary` 20),
* 而 `Label` 不设文字色(靠继承)。
* 两者此前都只能由调用方写 className 覆盖来表达。**已具备的「label + 描述 + 错误」
* 三件套未改动**——本文件只补这两根轴。
*
* `FieldLabel`(`<label>`)与 `FieldTitle`(`<div>`)共用 `data-slot="field-label"`,
* 属同一个槽,故两根轴同时给到两者,避免同槽两个出口的 API 不一致。
*/
type FieldLabelProps = {
/** 字号档:`default` = 基线 `text-sm`;`xs` = `text-xs`(中文最小字号,§2.4 D5) */
size?: "default" | "xs"
/** 色调档:`default` = 继承所在容器;`muted` = 弱化(`text-muted-foreground`) */
variant?: "default" | "muted"
}
const fieldVariants = cva(
"group/field flex w-full gap-3 data-[invalid]:text-destructive",
{
variants: {
orientation: {
vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
horizontal:
"flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
responsive:
"flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
},
},
defaultVariants: {
orientation: "vertical",
},
}
)
function Field({
className,
orientation = "vertical",
...props
}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
return (
<div
role="group"
data-slot="field"
data-orientation={orientation}
className={cn(fieldVariants({ orientation }), className)}
{...props}
/>
)
}
function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="field-content"
className={cn(
"group/field-content flex flex-1 flex-col gap-1 leading-snug",
className
)}
{...props}
/>
)
}
function FieldLabel({
className,
size = "default",
variant = "default",
...props
}: React.ComponentProps<typeof Label> & FieldLabelProps) {
return (
<Label
data-slot="field-label"
className={cn(
"group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled]/field:opacity-50 has-data-checked:border-primary/30 has-data-checked:bg-primary/5 has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border has-[>[data-slot=field]]:not-has-[:disabled,[data-disabled]]:hover:bg-muted has-[>[data-slot=field]]:has-[:focus-visible]:border-ring has-[>[data-slot=field]]:has-[:focus-visible]:ring-3 has-[>[data-slot=field]]:has-[:focus-visible]:ring-ring/50 *:data-[slot=field]:p-3 dark:has-data-checked:border-primary/20 dark:has-data-checked:bg-primary/10",
"has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col",
// 批 0 增补:两档默认不生效,既有调用方的类值不变。
// 置于 className 之前,调用方仍可最终覆盖。
//
// ⚠️ `text-xs leading-snug` 不是冗余:twMerge 把 `text-*`(字号)与
// `leading-*`(行高)视为互斥组,后者在前者之后出现才会保留。
// 若只写 `text-xs`,上面的 `leading-snug` 会被**静默丢弃**——
// size="xs" 就变成「同时改了字号和行高」,与「只加字号档」的意图不符。
size === "xs" && "text-xs leading-snug",
variant === "muted" && "text-muted-foreground",
className
)}
{...props}
/>
)
}
function FieldTitle({
className,
size = "default",
variant = "default",
...props
}: React.ComponentProps<"div"> & FieldLabelProps) {
return (
<div
data-slot="field-label"
className={cn(
"flex w-fit items-center gap-2 text-sm leading-snug font-medium group-data-[disabled]/field:opacity-50",
size === "xs" && "text-xs",
variant === "muted" && "text-muted-foreground",
className
)}
{...props}
/>
)
}
function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
return (
<p
data-slot="field-description"
className={cn(
"text-start text-sm leading-normal font-normal text-muted-foreground group-has-data-[orientation=horizontal]/field:text-balance [[data-variant=legend]+&]:-mt-1.5",
"last:mt-0 nth-last-2:-mt-1",
"[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
className
)}
{...props}
/>
)
}
function FieldSeparator({
children,
className,
contentClassName,
...props
}: React.ComponentProps<"div"> & {
children?: React.ReactNode
/** 分隔文字块的底色覆写;用于自定义表面(默认按已知浮层/卡片表面自动跟随) */
contentClassName?: string
}) {
return (
<div
data-slot="field-separator"
data-content={!!children}
className={cn(
"relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2",
className
)}
{...props}
>
<Separator className="absolute inset-0 top-1/2" />
{children && (
<span
className={cn(
// 内容块必须与所在表面同色,否则分隔线会从文字后面穿出。
// 默认页面底色,已知表面(Card / Popover / Sheet / Drawer / Dialog)
// 自动跟随;自定义表面可用 contentClassName 覆写。
"relative mx-auto block w-fit bg-background px-2 text-muted-foreground in-data-[slot=card]:bg-card in-data-[slot=popover-content]:bg-popover in-data-[slot=sheet-content]:bg-popover in-data-[slot=drawer-popup]:bg-popover in-data-[slot=dialog-content]:bg-popover in-data-[slot=alert-dialog-content]:bg-popover",
contentClassName
)}
data-slot="field-separator-content"
>
{children}
</span>
)}
</div>
)
}
function FieldError({
className,
children,
errors,
...props
}: React.ComponentProps<"div"> & {
errors?: Array<{ message?: string } | undefined>
}) {
const content = useMemo(() => {
if (children) {
return children
}
if (!errors?.length) {
return null
}
const uniqueErrors = [
...new Map(errors.map((error) => [error?.message, error])).values(),
]
if (uniqueErrors?.length == 1) {
return uniqueErrors[0]?.message
}
return (
<ul className="ms-4 flex list-disc flex-col gap-1">
{uniqueErrors.map(
(error, index) =>
error?.message && <li key={index}>{error.message}</li>
)}
</ul>
)
}, [children, errors])
if (!content) {
return null
}
return (
<div
role="alert"
data-slot="field-error"
className={cn("text-sm font-normal text-destructive", className)}
{...props}
>
{content}
</div>
)
}
export {
Field,
FieldLabel,
FieldDescription,
FieldError,
FieldGroup,
FieldLegend,
FieldSeparator,
FieldSet,
FieldContent,
FieldTitle,
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
表单字段布局,由 Field、Label、Description、Error 组合;统一标签、说明与错误间距。