Ordo UI
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*booleantrue—
labels*Partial<ThinkingLoaderLabels>——
className*string——

源码

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

用法说明

等待首包/推理中/工具执行中的活性行:role=status + aria-live;startedAt 传入才有计时,now 可注入时钟。