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 | — | — |
源码
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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
消息版本切换:index 0-based + count 总数,首尾禁用不隐藏;计数 aria-live 播报,方向图标 RTL 镜像;不持有分支数据。