AI助手与对话
ModelSelector
@mox-hub/patterns · AI · 助手与对话 · canonical
model-selector@mox-hub/patternsControlscanonicalsrc/components/model-selector.tsx变体轴
sizesmmd
变体演示model-selector
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| models* | ModelOption[] | — | — |
| value* | string | — | — |
| onValueChange* | (id: string) => void | — | — |
| size* | "sm" | "md" | 'md' | — |
| disabled* | boolean | false | — |
| labels* | Partial<ModelSelectorLabels> | — | — |
| className* | string | — | — |
源码
import { useState, type ReactNode } from 'react';
import { cn } from '@mox-hub/ui';
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from '@mox-hub/ui/components/select';
import { usePatternLabels } from '../lib/i18n';
/**
* ModelSelector —— 模型选择件(W4 B2)。
*
* 只把 `models` 列表呈现成下拉选择:
* - 受控 `value` + `onValueChange`;未传 `value` 时非受控,默认 `models[0]?.id`;
* - 空列表渲染 disabled trigger + empty 文案;
* - 每项可显示 label + description(muted 小字)+ badge;
* - 弹层一律交给 `ui/select`(Base UI),本件不手搓 popover;
* - 不取数、不持久化、不发请求,模型数据与当前值全部由消费方注入。
*/
export interface ModelOption {
id: string;
label: string;
description?: string;
badge?: ReactNode;
disabled?: boolean;
}
export interface ModelSelectorLabels {
placeholder: string;
empty: string;
label: string;
}
export const MODEL_SELECTOR_DEFAULT_LABELS: ModelSelectorLabels = {
placeholder: '选择模型',
empty: '暂无可选模型',
label: '选择模型',
};
export interface ModelSelectorProps {
models: ModelOption[];
value?: string;
onValueChange?: (id: string) => void;
size?: 'sm' | 'md';
disabled?: boolean;
labels?: Partial<ModelSelectorLabels>;
className?: string;
}
export function ModelSelector({
models,
value,
onValueChange,
size = 'md',
disabled = false,
labels,
className,
}: ModelSelectorProps) {
const D = usePatternLabels(
'modelSelector',
MODEL_SELECTOR_DEFAULT_LABELS,
);
const text: ModelSelectorLabels = {
placeholder: labels?.placeholder ?? D.placeholder,
empty: labels?.empty ?? D.empty,
label: labels?.label ?? D.label,
};
const [uncontrolledValue, setUncontrolledValue] = useState<
string | undefined
>(undefined);
const controlled = value !== undefined;
const selectedValue = controlled
? value === ''
? undefined
: value
: (uncontrolledValue ?? models[0]?.id);
// sm → h-control-sm(32px);md → h-control-md(36px)
const triggerSize = size === 'sm' ? 'sm' : 'default';
const triggerClassName = cn('w-fit max-w-full', className);
if (models.length === 0) {
return (
<Select disabled>
<SelectTrigger
size={triggerSize}
aria-label={text.label}
data-ai-component="model.selector"
className={triggerClassName}
>
<span className="truncate text-muted-foreground">{text.empty}</span>
</SelectTrigger>
</Select>
);
}
const handleValueChange = (next: unknown) => {
if (next === null || next === undefined) return;
const id = String(next);
if (!controlled) setUncontrolledValue(id);
onValueChange?.(id);
};
return (
<Select
value={selectedValue}
onValueChange={handleValueChange}
disabled={disabled}
items={models.map((model) => ({
value: model.id,
label: model.label,
}))}
>
<SelectTrigger
size={triggerSize}
aria-label={text.label}
data-ai-component="model.selector"
className={triggerClassName}
>
<SelectValue placeholder={text.placeholder} />
</SelectTrigger>
<SelectContent>
{models.map((model) => (
<SelectItem
key={model.id}
value={model.id}
disabled={model.disabled}
>
<div className="flex min-w-0 max-w-full flex-col items-start gap-0.5 text-start">
<div className="flex min-w-0 max-w-full items-center gap-1.5">
<span className="truncate">{model.label}</span>
{model.badge ? (
<span className="shrink-0">{model.badge}</span>
) : null}
</div>
{model.description ? (
<span className="max-w-full truncate text-2xs text-muted-foreground">
{model.description}
</span>
) : null}
</div>
</SelectItem>
))}
</SelectContent>
</Select>
);
}
可访问性与 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。
用法说明
模型选择器:models 注入、受控/非受控 value、空列表与禁用项;基于 ui/select,不写死模型清单。