Ordo UI
AI助手与对话

StreamingMarkdown

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

streaming-markdown@mox-hub/patternsAI Executioncanonicalsrc/components/streaming-markdown.tsx
变体演示streaming-markdown

验收标准

  • 登录页在 3 秒 内完成首屏
  • 错误提示可读且可关闭
ts
const ok = response.status === 200

Props API

Prop类型默认值说明
content*string——
streaming*booleanfalse—
highlight*booleantrue—
controls*booleantrue—
codeBlockMaxHeight*number400—
tableMaxHeight*number300—
lineNumbers*booleanfalse—
linkSafety*booleantrue—
components*Components——
className*string——

源码

packages/patterns/src/components/streaming-markdown.tsx
import type { ComponentProps } from 'react';
import { createCodePlugin } from '@streamdown/code';
import {
  Streamdown,
  type StreamdownProps,
  type StreamdownTranslations,
} from 'streamdown';

import { cn } from '@mox-hub/ui';

import { ORDO_SHIKI_THEME } from '../lib/highlight-theme';

/**
 * StreamingMarkdown —— 流式 Markdown 渲染(对话平面核心件)。
 *
 * 这是本库唯一允许「直接依赖现成 MIT/Apache 实现」的渲染件:
 * - Streamdown 负责未闭合语法修复、分块流式、代码块/表格控件与外链安全确认;
 * - 主题通过 `ORDO_SHIKI_THEME` 注入,颜色是 CSS 变量,明暗切换自动跟随;
 * - 中文控件文案内聚在本文件,Provider/labels 不介入(Streamdown 自带 35 个槽位,
 *   逐个映射进本库 i18n 会制造两套真相源);
 * - 不在根 barrel 导出:`streamdown` / `@streamdown/code` / `shiki` 都是 optional peer,
 *   只有引 `@mox-hub/patterns/components/streaming-markdown` 的消费方才需要安装。
 *
 * 消费方还需在应用 CSS 里引入一次 Streamdown 的动画样式:
 * `@import "streamdown/styles.css";`
 */
const ordoTranslations: StreamdownTranslations = {
  close: '关闭',
  copied: '已复制',
  copyCode: '复制代码',
  copyLink: '复制链接',
  copyTable: '复制表格',
  copyTableAsCsv: '复制为 CSV',
  copyTableAsMarkdown: '复制为 Markdown',
  copyTableAsTsv: '复制为 TSV',
  downloadDiagram: '下载图表',
  downloadDiagramAsMmd: '下载 Mermaid 源码',
  downloadDiagramAsPng: '下载 PNG',
  downloadDiagramAsSvg: '下载 SVG',
  downloadFile: '下载文件',
  downloadImage: '下载图片',
  downloadTable: '下载表格',
  downloadTableAsCsv: '下载 CSV',
  downloadTableAsMarkdown: '下载 Markdown',
  errorMermaid: '图表渲染失败',
  exitFullscreen: '退出全屏',
  externalLinkWarning: '即将打开外部链接,请确认来源可信。',
  imageNotAvailable: '图片不可用',
  mermaidAriaLabel: 'Mermaid 图表',
  mermaidFormatMmd: 'Mermaid',
  mermaidFormatPng: 'PNG',
  mermaidFormatSvg: 'SVG',
  openExternalLink: '打开外部链接',
  openLink: '打开链接',
  resetView: '重置视图',
  tableFormatCsv: 'CSV',
  tableFormatMarkdown: 'Markdown',
  tableFormatTsv: 'TSV',
  viewFullscreen: '全屏查看',
  zoomIn: '放大',
  zoomOut: '缩小',
};

const ordoCodePlugin = createCodePlugin({
  // token 全部是 CSS 变量,同一份主题同时服务明暗两套配色
  themes: [ORDO_SHIKI_THEME, ORDO_SHIKI_THEME],
});

export interface StreamingMarkdownProps
  extends Omit<ComponentProps<'div'>, 'children'> {
  /** Markdown 原文(流式中可以是未闭合片段) */
  content: string;
  /** 流式中:修复未闭合语法 + 光标 + 动画 */
  streaming?: boolean;
  /** 关闭语法高亮(减少首屏开销) */
  highlight?: boolean;
  /** 代码块/表格的复制、全屏等内建控件;默认开 */
  controls?: boolean;
  /** 代码块最大高度(px);默认 400 */
  codeBlockMaxHeight?: number;
  /** 表格最大高度(px);默认 300 */
  tableMaxHeight?: number;
  /** 代码块显示行号;默认关(对话内更紧凑) */
  lineNumbers?: boolean;
  /** 外链安全确认;默认开 */
  linkSafety?: boolean;
  /** Streamdown 组件覆盖(代码块、表格、链接等) */
  components?: StreamdownProps['components'];
}

export function StreamingMarkdown({
  content,
  streaming = false,
  highlight = true,
  controls = true,
  codeBlockMaxHeight = 400,
  tableMaxHeight = 300,
  lineNumbers = false,
  linkSafety = true,
  components,
  className,
  ...props
}: StreamingMarkdownProps) {
  return (
    <div
      data-ai-component="streaming.markdown"
      data-streaming={streaming ? 'true' : 'false'}
      dir="auto"
      className={cn(
        'w-full text-sm break-words text-content-text',
        '[&_a]:text-accent-blue [&_a]:underline-offset-2 [&_a:hover]:underline',
        '[&_h1]:mt-4 [&_h1]:mb-2 [&_h1]:text-lg [&_h1]:font-semibold',
        '[&_h2]:mt-3 [&_h2]:mb-2 [&_h2]:text-base [&_h2]:font-semibold',
        '[&_h3]:mt-3 [&_h3]:mb-1 [&_h3]:text-sm [&_h3]:font-semibold',
        '[&_p]:my-2 [&_p:first-child]:mt-0 [&_p:last-child]:mb-0',
        '[&_ul]:my-2 [&_ul]:list-disc [&_ul]:ps-5',
        '[&_ol]:my-2 [&_ol]:list-decimal [&_ol]:ps-5',
        '[&_li]:my-1 [&_blockquote]:border-s-2 [&_blockquote]:border-content-border [&_blockquote]:ps-3 [&_blockquote]:text-content-text-secondary',
        '[&_:not(pre)>code]:rounded-sm [&_:not(pre)>code]:bg-muted [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:py-0.5 [&_:not(pre)>code]:font-mono [&_:not(pre)>code]:text-xs',
        // 表格圆角外壳:border-separate + 单元格仅保留内部分隔线,四角随外框圆角
        '[&_table]:my-2 [&_table]:w-full [&_table]:border-separate [&_table]:border-spacing-0 [&_table]:overflow-hidden [&_table]:rounded-md [&_table]:border [&_table]:border-content-border [&_table]:text-xs',
        '[&_th]:border-b [&_th]:border-e [&_th]:border-content-border [&_th]:bg-content-bg-secondary [&_th]:px-2 [&_th]:py-1 [&_th]:text-start [&_th]:font-semibold [&_th:last-child]:border-e-0 [&_th:first-child]:rounded-ss-md [&_th:last-child]:rounded-se-md',
        '[&_td]:border-b [&_td]:border-e [&_td]:border-content-border [&_td]:px-2 [&_td]:py-1 [&_td]:align-top [&_td:last-child]:border-e-0 [&_tr:last-child_td]:border-b-0 [&_tr:last-child_td:first-child]:rounded-es-md [&_tr:last-child_td:last-child]:rounded-ee-md',
        '[&_hr]:my-4 [&_hr]:border-content-border',
        className,
      )}
      {...props}
    >
      <Streamdown
        mode={streaming ? 'streaming' : 'static'}
        dir="auto"
        parseIncompleteMarkdown={streaming}
        isAnimating={streaming}
        caret="block"
        lineNumbers={lineNumbers}
        codeBlockMaxHeight={codeBlockMaxHeight}
        tableMaxHeight={tableMaxHeight}
        shikiTheme={[ORDO_SHIKI_THEME, ORDO_SHIKI_THEME]}
        plugins={highlight ? { code: ordoCodePlugin } : undefined}
        controls={
          controls
            ? {
                code: { copy: true, download: false },
                table: { copy: true, download: false, fullscreen: false },
                image: { download: false },
              }
            : false
        }
        linkSafety={linkSafety ? { enabled: true } : undefined}
        translations={ordoTranslations}
        components={components}
      >
        {content}
      </Streamdown>
    </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。

用法说明

流式 Markdown 渲染:Streamdown 负责未闭合语法修复、代码/表格控件与外链确认;中文文案内聚;streamdown/@streamdown/code/shiki 均为 optional peer,只能按子路径引入。