Ordo UI
AI助手与对话

BranchPicker

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

branch-picker@mox-hub/patternsAI Executioncanonicalsrc/components/branch-picker.tsx
变体演示branch-picker
2/3第 2 / 3 个版本

Props API

Prop类型默认值说明
index*number——
count*number——
onChange*(index: number) => void——
labels*Partial<BranchPickerLabels>——
className*string——

源码

packages/patterns/src/components/branch-picker.tsx
import { ChevronLeft, ChevronRight } from 'lucide-react';
import type { ComponentProps } from 'react';

import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';

import { usePatternLabels } from '../lib/i18n';

/**
 * BranchPicker —— 消息版本切换器(对话平面)。
 *
 * AI 对同一条输入生成多个候选回答时,在消息下方显示 `‹ 2/3 ›`:
 * - `index` 为 0-based,`count` 为分支总数;
 * - 到边界时对应按钮 disabled(不隐藏,保持布局稳定);
 * - 计数经 aria-live 播报,方向键图标在 RTL 下镜像;
 * - 只做切换,不持有分支数据——分支内容由消费方按 index 取。
 */
export interface BranchPickerLabels {
  region: string;
  previous: string;
  next: string;
  position: (index: number, total: number) => string;
}

export const BRANCH_PICKER_DEFAULT_LABELS: BranchPickerLabels = {
  region: '消息分支',
  previous: '上一个版本',
  next: '下一个版本',
  position: (index, total) => `第 ${index} / ${total} 个版本`,
};

export interface BranchPickerProps
  extends Omit<ComponentProps<'div'>, 'children' | 'onChange'> {
  /** 当前分支索引(0-based) */
  index: number;
  /** 分支总数 */
  count: number;
  onChange: (index: number) => void;
  labels?: Partial<BranchPickerLabels>;
}

export function BranchPicker({
  index,
  count,
  onChange,
  labels,
  className,
  ...props
}: BranchPickerProps) {
  const D = usePatternLabels('branchPicker', BRANCH_PICKER_DEFAULT_LABELS);
  const text: BranchPickerLabels = {
    region: labels?.region ?? D.region,
    previous: labels?.previous ?? D.previous,
    next: labels?.next ?? D.next,
    position: labels?.position ?? D.position,
  };

  const safeCount = Math.max(count, 1);
  const safeIndex = Math.min(Math.max(index, 0), safeCount - 1);

  return (
    <div
      role="group"
      aria-label={text.region}
      data-ai-component="branch.picker"
      className={cn('inline-flex items-center gap-0.5', className)}
      {...props}
    >
      <Button
        type="button"
        variant="ghost"
        size="icon-xs"
        aria-label={text.previous}
        title={text.previous}
        disabled={safeIndex <= 0}
        onClick={() => onChange(safeIndex - 1)}
      >
        <ChevronLeft aria-hidden className="rtl:-scale-x-100" />
      </Button>
      <span
        aria-live="polite"
        className="min-w-10 text-center text-2xs tabular-nums text-content-text-muted"
      >
        {safeIndex + 1}/{safeCount}
      </span>
      <Button
        type="button"
        variant="ghost"
        size="icon-xs"
        aria-label={text.next}
        title={text.next}
        disabled={safeIndex >= safeCount - 1}
        onClick={() => onChange(safeIndex + 1)}
      >
        <ChevronRight aria-hidden className="rtl:-scale-x-100" />
      </Button>
      <span className="sr-only">{text.position(safeIndex + 1, safeCount)}</span>
    </div>
  );
}

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

用法说明

消息版本切换:index 0-based + count 总数,首尾禁用不隐藏;计数 aria-live 播报,方向图标 RTL 镜像;不持有分支数据。