组件/Stream Markdown

Stream Markdown

面向流式输出的 Markdown 渲染器

Verified自 0.3.9

用法

基础

流式期间,未闭合的尾部围栏推迟渲染,不会以半截形态闪现。

Loading demo...

最佳实践

  • 不要关闭 sanitize:模型输出是不可信内容,这里是它变成 DOM 的地方。
  • 生成结束后把 streaming 置为 false,否则光标一直留在末尾。
  • 自定义渲染器在 closed 为 false 时显示加载态,不解析半截内容。
  • renderers 的 key 用围栏首个单词的小写形式(```chart → chart)。
  • 非英文界面除了图片与表格文案,代码块和图表的文案也要一并传入:内置的块会显示它们,默认是英文。
  • 静态 Markdown 用 TxMarkdownView,不需要这套分块与光标机制。

API 参考

属性

属性名类型默认值说明
contentstring—Markdown 原文,必填。
streamingbooleanfalse仍在输出;控制光标、显影与尾部围栏的延迟渲染。
reveal'aurora' | 'hue' | 'blur' | 'languid' | 'none''aurora'新文字的进场方式,预设同 TxStreamText;languid 只保留缓慢模糊,不上浮。
caretbooleantruestreaming 时在写入位置显示 Tuff 光标;关闭时立即移除。
sanitizebooleantrue用 DOMPurify 净化 HTML。
theme'light' | 'dark' | 'auto''auto'配色主题;auto 跟随环境。
renderersRecord<string, StreamMarkdownBlockRenderer>—按围栏语言替换块渲染组件,组件以 props 接收 StreamMarkdownBlockContext。
blockRemoteImagesbooleantrue远程图片(http(s)://、//)先显示占位块,读者确认后才加载。
blockedImageTextstring'Remote image blocked'图片占位块的标题。
loadImageOnceTextstring'Load this image'只加载这一张图片的按钮文字。
allowSessionImagesTextstring'Allow for this conversation'放行本次会话全部远程图片的按钮文字。
copyTableTextstring'Copy CSV'表格「复制为 CSV」按钮的文字。
copiedTableTextstring'Copied'复制成功后按钮短暂显示的文字。
codePreviewTextstring'Preview'代码块中把 HTML、SVG、XML 渲染出来查看的按钮文字。
codeSourceTextstring'Code'预览显示时同一按钮的文字,点击回到源码。
inlineCodePreviewbooleantrue已闭合的 HTML、SVG、XML 围栏默认在代码块下方渲染预览;设为 false 后预览按钮改为发出 code-preview 事件,由宿主决定在哪里显示。
codeFrameLabelFormatter(lang: string) => string(lang) => `${lang} preview`由围栏语言生成预览框的可访问名称。
copyCodeTextstring'Copy'代码块复制按钮的文字。
copiedCodeTextstring'Copied'复制成功后按钮短暂显示的文字。
diagramZoomLabelstring'Zoom diagram'渲染好的图表(点击打开预览)的可访问名称。
diagramPreviewLabelstring'Diagram preview'图表全屏预览及其中图表滚动区的可访问名称。
diagramCloseLabelstring'Close preview'预览关闭按钮的可访问名称。
diagramErrorTextstring'Diagram failed to render — showing source.'图表渲染失败、改为显示源码时,源码上方的提示。
diagramDownloadLabelstring'Download'图表预览里「保存」操作的名称。
diagramCopyFailedTextstring'Could not copy'图表预览里复制源码失败时的提示。

TxCodeBlock 属性

没有专属渲染器的语言都由它渲染;它也单独导出,可在文档之外展示代码。它以 props 接收 StreamMarkdownBlockContext;在 TxStreamMarkdown 里,文案来自 code* 系列属性与 copyCodeText / copiedCodeText。

属性名类型默认值说明
langstring''围栏语言,决定高亮与是否提供预览;留空时显示为纯文本。
codestring''源码文本。
closedbooleantrue仅在流式中仍在增长的尾部围栏上为 false;为 false 时不提供预览。
theme'light' | 'dark''light'高亮与配色主题。
previewablebooleantrue已闭合的 HTML、SVG、XML 围栏提供渲染预览。
inlinePreviewbooleantrue设为 false 时不在代码块下方渲染预览,预览按钮改为发出 preview 事件。
previewLabelstring'Preview'切换到渲染预览的按钮文字。
codeLabelstring'Code'预览显示时同一按钮的文字。
frameLabelFormatter(lang: string) => string(lang) => `${lang} preview`由围栏语言生成预览框的可访问名称。
copyLabelstring'Copy'复制按钮的文字。
copiedLabelstring'Copied'复制成功后按钮短暂显示的文字。

TxMermaidBlock 属性

内置的 mermaid 渲染器,同样以 props 接收 StreamMarkdownBlockContext;在 TxStreamMarkdown 里,文案来自 diagram* 系列属性与 copyCodeText / copiedCodeText。

属性名类型默认值说明
codestring''图表源码。
closedbooleanfalse仅在流式中仍在增长的尾部围栏上为 false。
theme'light' | 'dark''light'图表的配色主题。
zoomLabelstring'Zoom diagram'渲染好的图表(点击打开预览)的可访问名称。
previewLabelstring'Diagram preview'全屏预览及其中图表滚动区的可访问名称。
closeLabelstring'Close preview'预览关闭按钮的可访问名称。
errorTextstring'Diagram failed to render — showing source.'图表渲染失败、改为显示源码时,源码上方的提示。
copyLabelstring'Copy'渲染失败后所显示源码的复制按钮文字。
copiedLabelstring'Copied'复制成功后按钮短暂显示的文字。
downloadLabelstring'Download'图表预览里「保存」操作的名称。
copyFailedTextstring'Could not copy'图表预览里复制源码失败时的提示。
maxHeightnumber480图表绘制的最大高度(px),超出后在框内滚动;放大预览仍显示完整图表。

事件

事件名来源载荷说明
code-previewTxStreamMarkdownStreamMarkdownCodePreviewinlineCodePreview 为 false 时,代码块的预览按钮触发。
previewTxCodeBlockStreamMarkdownCodePreviewinlinePreview 为 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