Ordo UI
AI助手与对话

ModelSelector

@mox-hub/patterns · AI · 助手与对话 · canonical

model-selector@mox-hub/patternsControlscanonicalsrc/components/model-selector.tsx

变体轴

size
smmd
变体演示model-selector

Props API

Prop类型默认值说明
models*ModelOption[]——
value*string——
onValueChange*(id: string) => void——
size*"sm" | "md"'md'—
disabled*booleanfalse—
labels*Partial<ModelSelectorLabels>——
className*string——

源码

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

用法说明

模型选择器:models 注入、受控/非受控 value、空列表与禁用项;基于 ui/select,不写死模型清单。