Ordo UI
AI助手与对话

StreamError

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

stream-error@mox-hub/patternsFeedbackcanonicalsrc/components/stream-error.tsx
变体演示stream-error

Props API

Prop类型默认值说明
title*string——
message*string——
detail*string——
onRetry*() => void——
retrying*booleanfalse—
onDismiss*() => void——
labels*Partial<StreamErrorLabels>——
className*string——

源码

packages/patterns/src/components/stream-error.tsx
import { useState } from 'react';
import { ChevronDown, RefreshCw, TriangleAlert, X } from 'lucide-react';

import { cn } from '@mox-hub/ui';
import {
  Alert,
  AlertAction,
  AlertDescription,
  AlertTitle,
} from '@mox-hub/ui/components/alert';
import { Button } from '@mox-hub/ui/components/button';
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from '@mox-hub/ui/components/collapsible';

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

/**
 * StreamError —— 流式 / AI 请求错误块(对话平面,W4 P1 / B15)。
 *
 * 覆盖限流、断流、上下文超限等可恢复错误:标题 + 主消息 + 可选可折叠详情,
 * 以及重试 / 关闭两个由回调决定是否出现的动作。
 *
 * 边界:
 * - 纯展示 / 受控件——不取数、不发请求;`retrying` 只负责禁用与文案切换,
 *   真实请求状态由消费方维护;
 * - `detail` 折叠收纳原始错误(限流阈值、provider 返回等),默认收起;
 * - a11y:根节点为 `role="alert"`(ui/alert 底座保证),折叠触发器由
 *   Base UI Collapsible 提供 `aria-expanded` / `aria-controls`,按钮均带可访问名。
 */
export interface StreamErrorLabels {
  /** 缺省标题 */
  title: string;
  /** 重试按钮 */
  retry: string;
  /** 重试进行中的按钮文案 */
  retrying: string;
  /** 关闭按钮无障碍名 */
  dismiss: string;
  /** 详情折叠触发器文案 */
  detail: string;
}

export const STREAM_ERROR_DEFAULT_LABELS: StreamErrorLabels = {
  title: '生成中断',
  retry: '重试',
  retrying: '重试中…',
  dismiss: '关闭',
  detail: '错误详情',
};

export interface StreamErrorProps {
  /** 覆写标题(缺省 labels.title) */
  title?: string;
  /** 主消息(必填) */
  message: string;
  /** 原始错误详情,传入则可折叠展开 */
  detail?: string;
  /** 未传则不渲染重试按钮 */
  onRetry?: () => void;
  /** 重试进行中:按钮禁用并切换文案 */
  retrying?: boolean;
  /** 未传则不渲染关闭按钮 */
  onDismiss?: () => void;
  labels?: Partial<StreamErrorLabels>;
  className?: string;
}

export function StreamError({
  title,
  message,
  detail,
  onRetry,
  retrying = false,
  onDismiss,
  labels,
  className,
}: StreamErrorProps) {
  const D = usePatternLabels('streamError', STREAM_ERROR_DEFAULT_LABELS);
  const text: StreamErrorLabels = {
    title: labels?.title ?? D.title,
    retry: labels?.retry ?? D.retry,
    retrying: labels?.retrying ?? D.retrying,
    dismiss: labels?.dismiss ?? D.dismiss,
    detail: labels?.detail ?? D.detail,
  };
  const [detailOpen, setDetailOpen] = useState(false);

  return (
    <Alert
      variant="destructive"
      data-ai-component="stream.error"
      className={cn('text-start', className)}
    >
      <TriangleAlert aria-hidden className="size-4" />
      <AlertTitle>{title ?? text.title}</AlertTitle>
      <AlertDescription className="flex flex-col items-start gap-2">
        <p className="text-sm text-balance break-words">{message}</p>
        {detail ? (
          <Collapsible open={detailOpen} onOpenChange={setDetailOpen}>
            <CollapsibleTrigger className="group/detail inline-flex items-center gap-1 rounded-sm text-xs text-destructive/80 outline-none transition-colors duration-fast hover:text-destructive focus-visible:ring-2 focus-visible:ring-ring/50">
              <ChevronDown
                aria-hidden
                className={cn(
                  'size-3 transition-transform duration-fast',
                  detailOpen && 'rotate-180',
                )}
              />
              <span>{text.detail}</span>
            </CollapsibleTrigger>
            <CollapsibleContent>
              <pre className="mt-1.5 max-h-40 overflow-auto overscroll-contain rounded-md bg-muted/50 p-2 font-mono text-2xs whitespace-pre-wrap break-words text-content-text-secondary">
                {detail}
              </pre>
            </CollapsibleContent>
          </Collapsible>
        ) : null}
        {onRetry ? (
          <Button
            type="button"
            variant="outline"
            size="xs"
            disabled={retrying}
            onClick={onRetry}
            // 卡片操作区贴右下:操作按钮不占左侧阅读起始位
            className="self-end"
          >
            <RefreshCw
              aria-hidden
              className={cn(retrying && 'animate-spin')}
            />
            {retrying ? text.retrying : text.retry}
          </Button>
        ) : null}
      </AlertDescription>
      {onDismiss ? (
        <AlertAction>
          <Button
            type="button"
            variant="ghost"
            size="icon-xs"
            aria-label={text.dismiss}
            title={text.dismiss}
            onClick={onDismiss}
          >
            <X aria-hidden />
          </Button>
        </AlertAction>
      ) : null}
    </Alert>
  );
}

可访问性与 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=alert,重试中禁用。