Ordo UI
组件Controls

SelectField

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

select-field@mox-hub/uiControlscanonicalsrc/components/select-field.tsx
变体演示select-field

Props API

Prop类型默认值说明
className*string——
size*"default" | "sm""default"—
children*ReactNode——
value*string | number | readonly string[]——
defaultValue*string | number | readonly string[]——
name*string——
id*string——
disabled*boolean——
required*boolean——
onChange*(event: ChangeEvent<HTMLSelectElement, Element>) => void——

源码

packages/ui/src/components/select-field.tsx
import * as React from "react"

import { cn } from "../lib/utils"
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "./select"

/**
 * SelectField 的 `required` 只映射到 trigger 的 `aria-required`(可访问性提示);
 * 内部 `<input type="hidden">` 不参与 HTML 约束校验,普通 `<form>` 提交不会被浏览器拦截。
 * 短期支持路径:react-hook-form 的 `rules: { required: ... }` + `<FormMessage />`;
 * Base UI Root 的原生 `name/required` 委托仍待 owner 裁决(见 PLAN §5 #12)。
 */
type SelectFieldProps = Omit<React.ComponentPropsWithoutRef<"select">, "size" | "onChange"> & {
  size?: "sm" | "default"
  onChange?: (event: React.ChangeEvent<HTMLSelectElement>) => void
}

const EMPTY_SENTINEL = "__select_field_empty__"

type ParsedOption = {
  value: string
  disabled?: boolean
  label: React.ReactNode
}

type ParsedGroup = {
  label?: React.ReactNode
  options: ParsedOption[]
}

function normalizeValue(value: unknown): string {
  if (value === undefined || value === null) return ""
  return String(value)
}

function parseOptions(children: React.ReactNode): ParsedGroup[] {
  const groups: ParsedGroup[] = []
  const rootOptions: ParsedOption[] = []

  const parseOptionNode = (node: React.ReactNode): ParsedOption | null => {
    if (!React.isValidElement(node)) return null
    const nodeType = node.type
    if (nodeType !== "option" && nodeType !== SelectFieldOption) {
      return null
    }
    return {
      value: normalizeValue((node.props as { value?: unknown }).value),
      disabled: Boolean((node.props as { disabled?: boolean }).disabled),
      label: (node.props as { children?: React.ReactNode }).children,
    }
  }

  React.Children.forEach(children, (child) => {
    if (!React.isValidElement(child)) return
    const childType = child.type

    if (childType === "option" || childType === SelectFieldOption) {
      const parsed = parseOptionNode(child)
      if (parsed) rootOptions.push(parsed)
      return
    }

    if (childType === "optgroup" || childType === SelectFieldOptGroup) {
      const options: ParsedOption[] = []
      React.Children.forEach(
        (child.props as { children?: React.ReactNode }).children,
        (optionNode) => {
          const parsed = parseOptionNode(optionNode)
          if (parsed) options.push(parsed)
        },
      )
      if (options.length > 0) {
        groups.push({
          label: (child.props as { label?: React.ReactNode }).label,
          options,
        })
      }
    }
  })

  if (rootOptions.length > 0) {
    groups.unshift({ options: rootOptions })
  }
  return groups
}

function SelectField({
  className,
  size = "default",
  children,
  value,
  defaultValue,
  name,
  id,
  disabled,
  required,
  onChange,
  ...restProps
}: SelectFieldProps) {
  const optionGroups = React.useMemo(() => parseOptions(children), [children])
  const options = React.useMemo(
    () => optionGroups.flatMap((group) => group.options),
    [optionGroups],
  )
  const firstValue = options[0]?.value ?? ""
  const isControlled = value !== undefined

  const [internalValue, setInternalValue] = React.useState<string>(
    normalizeValue(defaultValue ?? firstValue),
  )

  React.useEffect(() => {
    if (!isControlled && internalValue === "" && firstValue !== "") {
      setInternalValue(firstValue)
    }
  }, [firstValue, internalValue, isControlled])

  const currentValue = isControlled
    ? normalizeValue(value)
    : internalValue

  const selectValue = currentValue === "" ? EMPTY_SENTINEL : currentValue

  /**
   * 交给 base-ui `Select.Root` 的 `items` —— **trigger 显示名称而非 value 的唯一开关**。
   *
   * base-ui 的 `Select.Value` 只在 Root 拿到 `items`(或 `itemToStringLabel`)时才能把
   * value 映射成 label,否则回退 `String(value)`,于是下拉框全部显示原始 value(id)。
   * 它无法从 `SelectItem` 反推:弹层关闭时 item **根本不挂载**(已实证),
   * 所以必须在 Root 这一层显式给出数据(2026-09-11 修复)。
   */
  const selectItems = React.useMemo(() => {
    const items = options.map((option) => ({
      value: option.value === "" ? EMPTY_SENTINEL : option.value,
      label: option.label,
    }))
    // 调用方未提供空选项、但当前值为空时,给哨兵补一个空 label,
    // 避免 `__select_field_empty__` 这个内部标记被当作文本渲染到 trigger 上
    if (!items.some((item) => item.value === EMPTY_SENTINEL)) {
      items.unshift({ value: EMPTY_SENTINEL, label: "" })
    }
    return items
  }, [options])

  const handleValueChange = (nextValue: string) => {
    const normalized = nextValue === EMPTY_SENTINEL ? "" : nextValue
    if (!isControlled) {
      setInternalValue(normalized)
    }
    if (onChange) {
      onChange({
        target: { value: normalized, name },
        currentTarget: { value: normalized, name },
      } as React.ChangeEvent<HTMLSelectElement>)
    }
  }

  return (
    <div
      className={cn(
        // 禁用态只由 SelectTrigger 自己降透明度;wrapper 再叠一层会变成 ~0.25(审计 P2-27)。
        "group/select-field relative w-full",
      )}
      data-slot="select-field-wrapper"
      data-size={size}
    >
      {name ? <input type="hidden" name={name} value={currentValue} /> : null}
      <Select
        value={selectValue}
        onValueChange={handleValueChange}
        disabled={disabled}
        items={selectItems}
      >
        <SelectTrigger
          id={id}
          data-select-field=""
          data-size={size}
          className={cn(
            "w-full min-w-0 data-[size=sm]:h-control-sm",
            className,
          )}
          aria-required={required}
          {...(restProps as unknown as React.ButtonHTMLAttributes<HTMLButtonElement>)}
        >
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {optionGroups.map((group, groupIndex) => (
            <SelectGroup key={groupIndex}>
              {group.label ? <SelectLabel>{group.label}</SelectLabel> : null}
              {group.options.map((option) => {
                const optionValue = option.value === "" ? EMPTY_SENTINEL : option.value
                return (
                  <SelectItem
                    key={`${groupIndex}-${optionValue}`}
                    value={optionValue}
                    disabled={option.disabled}
                  >
                    {option.label}
                  </SelectItem>
                )
              })}
            </SelectGroup>
          ))}
        </SelectContent>
      </Select>
    </div>
  )
}

function SelectFieldOption({ ...props }: React.ComponentProps<"option">) {
  return <option data-slot="select-field-option" {...props} />
}

function SelectFieldOptGroup({
  className,
  ...props
}: React.ComponentProps<"optgroup">) {
  return (
    <optgroup
      data-slot="select-field-optgroup"
      className={cn(className)}
      {...props}
    />
  )
}

export { SelectField, SelectFieldOptGroup, SelectFieldOption }

可访问性与 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。

用法说明

表单场景的 select 封装:受控/非受控 value + onChange 与 size 档;label/description/error 由 field 组合提供,不在本组件 props 内。

必填与校验(短期约定)

required 只会在 trigger 上输出 aria-required,用于告诉辅助技术该字段必填。组件内部的 <input type="hidden"> 不参与 HTML 约束校验,因此普通 <form> 提交空值不会被浏览器拦截, 也不会出现原生的 valueMissing 提示。

当前受支持的校验路径是 react-hook-form:

<FormField
  control={form.control}
  name="status"
  rules={{ required: '请选择状态' }}
  render={({ field }) => (
    <FormItem>
      <FormLabel>状态</FormLabel>
      <FormControl>
        <SelectField {...field} required>
          <SelectFieldOption value="open">进行中</SelectFieldOption>
          <SelectFieldOption value="done">已完成</SelectFieldOption>
        </SelectField>
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>

把 name/required 下放给 Base UI Select.Root 可以获得原生约束校验,但会改变空值提交语义, 属于公共表单契约变更,需 owner 裁决后再实施(见 PLAN §5 #12)。