Ordo UI
组件Controls

Field

@mox-hub/ui 组件 · Controls · canonical

field@mox-hub/uiControlscanonicalsrc/components/field.tsx

变体轴

orientation
verticalhorizontalresponsive
变体演示field

用于登录与通知。

Props API

Prop类型默认值说明
className*string——
orientation*"horizontal" | "vertical" | "responsive""vertical"—

源码

packages/ui/src/components/field.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

表单字段布局,由 Field、Label、Description、Error 组合;统一标签、说明与错误间距。