AI助手与对话
ThinkingLoader
@mox-hub/patterns · AI · 助手与对话 · canonical
thinking-loader@mox-hub/patternsAI Executioncanonicalsrc/components/thinking-loader.tsx变体演示thinking-loader
正在思考…
执行中…已用 12.5s
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| state* | "working" | "thinking" | 'thinking' | — |
| startedAt* | number | — | — |
| now* | number | — | — |
| showElapsed* | boolean | true | — |
| labels* | Partial<ThinkingLoaderLabels> | — | — |
| className* | string | — | — |
源码
import { useEffect, useState, type ComponentProps } from 'react';
import { cn } from '@mox-hub/ui';
import { Spinner } from '@mox-hub/ui/components/spinner';
import { formatLiveDuration } from '@mox-hub/ui/format';
import { usePatternLabels } from '../lib/i18n';
/**
* ThinkingLoader —— 等待首包 / 推理中 / 工具执行中的活性行(对话平面)。
*
* 它是「AI 正在做事」的最小可感知单元,替代各页面各写一套 spinner + 文案:
* - 状态经 role="status" + aria-live="polite" 播报(§22.5 活性可感知);
* - 计时只对传入 `startedAt` 的调用方生效,历史消息补不回时间就不显示(不造假数);
* - `now` 时钟注入供测试与跨组件对齐,缺省自跑 1s tick;
* - 不在根 barrel 导出——体积无关,但它是对话件族的私有原件。
*
* 与 `AssistantMessageList` 的分工:消息流内部缺省用本件渲染 pending 行,
* 消费方也可以独立使用(例如工具卡头部、面板空态)。
*/
export interface ThinkingLoaderLabels {
thinking: string;
working: string;
/** 计时前缀;参数是已格式化的时长 */
elapsed: (duration: string) => string;
}
export const THINKING_LOADER_DEFAULT_LABELS: ThinkingLoaderLabels = {
thinking: '正在思考…',
working: '执行中…',
elapsed: (duration) => `已用 ${duration}`,
};
export interface ThinkingLoaderProps extends Omit<ComponentProps<'div'>, 'children'> {
/** thinking = 等首包/推理中;working = 工具执行中 */
state?: 'thinking' | 'working';
/** 开始时间(服务端毫秒时间戳);传入后显示实时计时 */
startedAt?: number;
/** 外部时钟注入(毫秒时间戳);传入后组件不再自跑 tick */
now?: number;
/** 是否显示计时(默认 startedAt 存在即显示) */
showElapsed?: boolean;
/** 文案覆写(Provider 的 thinkingLoader section 优先于默认值,labels 又优先于 Provider) */
labels?: Partial<ThinkingLoaderLabels>;
}
export function ThinkingLoader({
state = 'thinking',
startedAt,
now,
showElapsed = true,
labels,
className,
...props
}: ThinkingLoaderProps) {
const D = usePatternLabels('thinkingLoader', THINKING_LOADER_DEFAULT_LABELS);
const text: ThinkingLoaderLabels = {
thinking: labels?.thinking ?? D.thinking,
working: labels?.working ?? D.working,
elapsed: labels?.elapsed ?? D.elapsed,
};
const [clock, setClock] = useState(() => Date.now());
const running = startedAt !== undefined && showElapsed && now === undefined;
useEffect(() => {
if (!running) return;
const timer = setInterval(() => setClock(Date.now()), 1000);
return () => clearInterval(timer);
}, [running]);
const current = now ?? clock;
const elapsed =
startedAt !== undefined && showElapsed
? Math.max(0, current - startedAt)
: undefined;
const label = state === 'working' ? text.working : text.thinking;
return (
<div
role="status"
aria-live="polite"
data-ai-component="thinking.loader"
data-state={state}
className={cn(
'inline-flex items-center gap-1.5 rounded-lg bg-content-bg-secondary px-3 py-2 text-sm text-content-text-secondary',
className,
)}
{...props}
>
<Spinner
size="sm"
aria-hidden
className="size-3.5 shrink-0 text-accent-purple"
/>
<span>{label}</span>
{elapsed !== undefined ? (
<span className="text-2xs tabular-nums text-content-text-muted">
{text.elapsed(formatLiveDuration(elapsed))}
</span>
) : null}
</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。
用法说明
等待首包/推理中/工具执行中的活性行:role=status + aria-live;startedAt 传入才有计时,now 可注入时钟。