组件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 | — | — |
源码
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/translatorprops,其次用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)。