Stream Markdown
面向流式输出的 Markdown 渲染器
用法
基础
流式期间,未闭合的尾部围栏推迟渲染,不会以半截形态闪现。
Loading demo...
最佳实践
- 不要关闭
sanitize:模型输出是不可信内容,这里是它变成 DOM 的地方。 - 生成结束后把
streaming置为false,否则光标一直留在末尾。 - 自定义渲染器在
closed为false时显示加载态,不解析半截内容。 renderers的 key 用围栏首个单词的小写形式(```chart→chart)。- 非英文界面除了图片与表格文案,代码块和图表的文案也要一并传入:内置的块会显示它们,默认是英文。
- 静态 Markdown 用
TxMarkdownView,不需要这套分块与光标机制。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
content | string | — | Markdown 原文,必填。 |
streaming | boolean | false | 仍在输出;控制光标、显影与尾部围栏的延迟渲染。 |
reveal | 'aurora' | 'hue' | 'blur' | 'languid' | 'none' | 'aurora' | 新文字的进场方式,预设同 TxStreamText;languid 只保留缓慢模糊,不上浮。 |
caret | boolean | true | streaming 时在写入位置显示 Tuff 光标;关闭时立即移除。 |
sanitize | boolean | true | 用 DOMPurify 净化 HTML。 |
theme | 'light' | 'dark' | 'auto' | 'auto' | 配色主题;auto 跟随环境。 |
renderers | Record<string, StreamMarkdownBlockRenderer> | — | 按围栏语言替换块渲染组件,组件以 props 接收 StreamMarkdownBlockContext。 |
blockRemoteImages | boolean | true | 远程图片(http(s)://、//)先显示占位块,读者确认后才加载。 |
blockedImageText | string | 'Remote image blocked' | 图片占位块的标题。 |
loadImageOnceText | string | 'Load this image' | 只加载这一张图片的按钮文字。 |
allowSessionImagesText | string | 'Allow for this conversation' | 放行本次会话全部远程图片的按钮文字。 |
copyTableText | string | 'Copy CSV' | 表格「复制为 CSV」按钮的文字。 |
copiedTableText | string | 'Copied' | 复制成功后按钮短暂显示的文字。 |
codePreviewText | string | 'Preview' | 代码块中把 HTML、SVG、XML 渲染出来查看的按钮文字。 |
codeSourceText | string | 'Code' | 预览显示时同一按钮的文字,点击回到源码。 |
inlineCodePreview | boolean | true | 已闭合的 HTML、SVG、XML 围栏默认在代码块下方渲染预览;设为 false 后预览按钮改为发出 code-preview 事件,由宿主决定在哪里显示。 |
codeFrameLabelFormatter | (lang: string) => string | (lang) => `${lang} preview` | 由围栏语言生成预览框的可访问名称。 |
copyCodeText | string | 'Copy' | 代码块复制按钮的文字。 |
copiedCodeText | string | 'Copied' | 复制成功后按钮短暂显示的文字。 |
diagramZoomLabel | string | 'Zoom diagram' | 渲染好的图表(点击打开预览)的可访问名称。 |
diagramPreviewLabel | string | 'Diagram preview' | 图表全屏预览及其中图表滚动区的可访问名称。 |
diagramCloseLabel | string | 'Close preview' | 预览关闭按钮的可访问名称。 |
diagramErrorText | string | 'Diagram failed to render — showing source.' | 图表渲染失败、改为显示源码时,源码上方的提示。 |
diagramDownloadLabel | string | 'Download' | 图表预览里「保存」操作的名称。 |
diagramCopyFailedText | string | 'Could not copy' | 图表预览里复制源码失败时的提示。 |
TxCodeBlock 属性
没有专属渲染器的语言都由它渲染;它也单独导出,可在文档之外展示代码。它以 props 接收 StreamMarkdownBlockContext;在 TxStreamMarkdown 里,文案来自 code* 系列属性与 copyCodeText / copiedCodeText。
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
lang | string | '' | 围栏语言,决定高亮与是否提供预览;留空时显示为纯文本。 |
code | string | '' | 源码文本。 |
closed | boolean | true | 仅在流式中仍在增长的尾部围栏上为 false;为 false 时不提供预览。 |
theme | 'light' | 'dark' | 'light' | 高亮与配色主题。 |
previewable | boolean | true | 已闭合的 HTML、SVG、XML 围栏提供渲染预览。 |
inlinePreview | boolean | true | 设为 false 时不在代码块下方渲染预览,预览按钮改为发出 preview 事件。 |
previewLabel | string | 'Preview' | 切换到渲染预览的按钮文字。 |
codeLabel | string | 'Code' | 预览显示时同一按钮的文字。 |
frameLabelFormatter | (lang: string) => string | (lang) => `${lang} preview` | 由围栏语言生成预览框的可访问名称。 |
copyLabel | string | 'Copy' | 复制按钮的文字。 |
copiedLabel | string | 'Copied' | 复制成功后按钮短暂显示的文字。 |
TxMermaidBlock 属性
内置的 mermaid 渲染器,同样以 props 接收 StreamMarkdownBlockContext;在 TxStreamMarkdown 里,文案来自 diagram* 系列属性与 copyCodeText / copiedCodeText。
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
code | string | '' | 图表源码。 |
closed | boolean | false | 仅在流式中仍在增长的尾部围栏上为 false。 |
theme | 'light' | 'dark' | 'light' | 图表的配色主题。 |
zoomLabel | string | 'Zoom diagram' | 渲染好的图表(点击打开预览)的可访问名称。 |
previewLabel | string | 'Diagram preview' | 全屏预览及其中图表滚动区的可访问名称。 |
closeLabel | string | 'Close preview' | 预览关闭按钮的可访问名称。 |
errorText | string | 'Diagram failed to render — showing source.' | 图表渲染失败、改为显示源码时,源码上方的提示。 |
copyLabel | string | 'Copy' | 渲染失败后所显示源码的复制按钮文字。 |
copiedLabel | string | 'Copied' | 复制成功后按钮短暂显示的文字。 |
downloadLabel | string | 'Download' | 图表预览里「保存」操作的名称。 |
copyFailedText | string | 'Could not copy' | 图表预览里复制源码失败时的提示。 |
maxHeight | number | 480 | 图表绘制的最大高度(px),超出后在框内滚动;放大预览仍显示完整图表。 |
事件
| 事件名 | 来源 | 载荷 | 说明 |
|---|---|---|---|
code-preview | TxStreamMarkdown | StreamMarkdownCodePreview | inlineCodePreview 为 false 时,代码块的预览按钮触发。 |
preview | TxCodeBlock | StreamMarkdownCodePreview | inlinePreview 为 false 时,预览按钮触发;TxStreamMarkdown 把它转发为 code-preview。 |
载荷为 { lang, code, srcdoc }。宿主应把 srcdoc 放进不带 allow-scripts 的 sandbox iframe,与内联预览的隔离方式一致。
概述
- 文档按块渲染:追加文本不会重排整篇。
- 流式中仍在增长的尾部围栏推迟到闭合后再渲染最终形态;渲染器收到的
closed只对它为false。 - 未注册的语言走内置渲染:
mermaid用TxMermaidBlock,其余用TxCodeBlock。 - 点图表打开全屏预览:焦点移到关闭按钮,Tab 留在预览内,在关闭按钮和图表之间切换;图表比屏幕高时,Tab 到图表上再用方向键滚动。Escape 或点空白处关闭,Escape 只在预览位于最上层时生效;关闭后焦点回到图表。预览打开期间,后面的页面不滚动。
- 光标同
TxStreamText:尾部是段落、标题或引用时紧跟末字符,否则单独位于下方一行;减弱动效时不播放进场,光标静止。 - DOMPurify 动态加载;
sanitize开启时,加载完成前或加载失败时不渲染任何内容。净化不能替代服务端的信任边界。 - 图片放行记录是模块级的,所有实例共享;切换会话时调用导出的
resetRemoteImagePolicy()清除。 - 每个实例持有自己的
Marked(gfm、breaks);GitHub Markdown 样式表限定在:where(.tx-md)下,不会改写宿主的.markdown-body。
技术实现
- 内容先由
createBlockStream切分为块,已稳定的块复用缓存的 HTML。 DOMPurify按需动态加载;sanitize开启时,加载完成前不渲染任何内容。每个实例持有自己的Marked。- 源码:
packages/tuffex/packages/components/src/stream-markdown/。
查看源码
packages/tuffex/packages/components/src/stream-markdown/index.ts