Ordo UI
AI助手与对话

ReasoningBlock

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

reasoning-block@mox-hub/patternsAI Executioncanonicalsrc/components/reasoning-block.tsx
变体演示reasoning-block
先确认登录页现状: 1. 表单字段 3 个 2. 无验证码 再拆验收标准。

Props API

Prop类型默认值说明
content*string——
streaming*booleanfalse—
durationMs*number——
defaultOpen*boolean——
open*boolean——
onOpenChange*(open: boolean) => void——
renderContent*(content: string) => ReactNode——
labels*Partial<ReasoningBlockLabels>——
className*string——

源码

packages/patterns/src/components/reasoning-block.tsx
import { useId, useState, type ComponentProps, type ReactNode } from 'react';
import { Brain, ChevronDown } from 'lucide-react';

import { cn } from '@mox-hub/ui';
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from '@mox-hub/ui/components/collapsible';
import { formatLiveDuration } from '@mox-hub/ui/format';

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

/**
 * ReasoningBlock —— 推理过程折叠块(对话平面)。
 *
 * 承载模型的 chain-of-thought / thinking 段:
 * - 流式期间自动展开并显示「思考中…」,结束后自动收起并显示「思考了 N 秒」
 *   (与 AI Elements 的行为契约一致;受控 `open` 时不再自动干预);
 * - 内容默认纯文本;消费方可经 `renderContent` 注入 Markdown 渲染器,
 *   保持本库「不依赖 Markdown 实现」的架构裁决;
 * - 折叠面板用 Base UI Collapsible,键盘与 aria-expanded 由底座保证。
 */
export interface ReasoningBlockLabels {
  /** 流式中标题 */
  thinking: string;
  /** 完成且有耗时 */
  thoughtFor: (duration: string) => string;
  /** 完成但无耗时 */
  thought: string;
  /** 展开/收起无障碍名 */
  toggle: string;
}

export const REASONING_BLOCK_DEFAULT_LABELS: ReasoningBlockLabels = {
  thinking: '思考中…',
  thoughtFor: (duration) => `思考了 ${duration}`,
  thought: '思考过程',
  toggle: '展开或收起思考过程',
};

export interface ReasoningBlockProps
  extends Omit<ComponentProps<'div'>, 'children'> {
  /** 推理文本 */
  content: string;
  /** 是否仍在流式输出 */
  streaming?: boolean;
  /** 已完成推理耗时(ms);仅非流式时显示 */
  durationMs?: number;
  /** 非受控初始展开态;缺省流式时展开 */
  defaultOpen?: boolean;
  /** 受控展开态;传入后流式结束不再自动收起 */
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
  /** 内容渲染器;缺省 whitespace-pre-wrap 纯文本 */
  renderContent?: (content: string) => ReactNode;
  labels?: Partial<ReasoningBlockLabels>;
}

export function ReasoningBlock({
  content,
  streaming = false,
  durationMs,
  defaultOpen,
  open,
  onOpenChange,
  renderContent,
  labels,
  className,
  ...props
}: ReasoningBlockProps) {
  const D = usePatternLabels('reasoningBlock', REASONING_BLOCK_DEFAULT_LABELS);
  const text: ReasoningBlockLabels = {
    thinking: labels?.thinking ?? D.thinking,
    thoughtFor: labels?.thoughtFor ?? D.thoughtFor,
    thought: labels?.thought ?? D.thought,
    toggle: labels?.toggle ?? D.toggle,
  };

  const controlled = open !== undefined;
  const [innerOpen, setInnerOpen] = useState(() => defaultOpen ?? streaming);
  const currentOpen = controlled ? open : innerOpen;

  // 流式结束自动收起(渲染期调整 state,避免 effect 级联渲染);受控时不干预
  const [prevStreaming, setPrevStreaming] = useState(streaming);
  if (prevStreaming !== streaming) {
    setPrevStreaming(streaming);
    if (!controlled && prevStreaming && !streaming) {
      setInnerOpen(false);
    }
  }

  const panelId = useId();
  const heading = streaming
    ? text.thinking
    : durationMs !== undefined
      ? text.thoughtFor(formatLiveDuration(durationMs))
      : text.thought;

  const handleOpenChange = (next: boolean) => {
    if (!controlled) setInnerOpen(next);
    onOpenChange?.(next);
  };

  return (
    <div
      data-ai-component="reasoning.block"
      data-state={streaming ? 'streaming' : 'done'}
      className={cn(
        'w-full rounded-lg border border-content-border bg-content-bg-secondary/60',
        className,
      )}
      {...props}
    >
      <Collapsible open={currentOpen} onOpenChange={handleOpenChange}>
        <CollapsibleTrigger
          aria-label={text.toggle}
          className="group/reasoning flex w-full items-center gap-2 rounded-lg px-3 py-2 text-start text-xs text-content-text-secondary outline-none transition-colors duration-fast hover:text-content-text focus-visible:ring-2 focus-visible:ring-ring/50"
        >
          <Brain
            aria-hidden
            className={cn(
              'size-3.5 shrink-0',
              streaming ? 'text-accent-purple' : 'text-content-text-muted',
            )}
          />
          <span className="flex-1">{heading}</span>
          <ChevronDown
            aria-hidden
            className={cn(
              'size-3.5 shrink-0 text-content-text-muted transition-transform duration-fast',
              currentOpen && 'rotate-180',
            )}
          />
        </CollapsibleTrigger>
        <CollapsibleContent
          id={panelId}
          className="border-t border-content-border px-3 py-2"
        >
          <div className="max-h-72 overflow-y-auto overscroll-contain text-xs whitespace-pre-wrap break-words text-content-text-secondary">
            {renderContent ? renderContent(content) : content}
          </div>
        </CollapsibleContent>
      </Collapsible>
    </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。

用法说明

推理过程折叠块:流式自动展开、结束自动收起(受控 open 不干预);内容缺省纯文本,renderContent 可注入 Markdown。