组件/CodeStream 流式代码块

CodeStream 流式代码块

带文件名头部、可流式输出的代码块

Verified自 0.3.9

用法

流式输出

把目前收到的代码传给 code 并设置 streaming,组件逐词匀速放出。

Loading demo...

逐行显现

宿主推进 revealedLines,组件负责过渡与光标。

Loading demo...

完整清单

不传 revealedLines 与 streaming 时显示完整清单。

Loading demo...

渲染预览

html、svg、xml 代码停止输出后,头部出现「预览」开关,在沙箱 iframe 中渲染,再点回源码;流式与 diff 模式下不出现,auto-preview 则在代码结束时直接显示渲染结果。

Loading demo...

统一 Diff

传 diff 渲染统一 diff;被删行与替换它的新增行共用行号,所以行号逐行给出。

Loading demo...

最佳实践

  • 代码来自模型时用 streaming,交给组件控制节奏;宿主掌握节奏(脚本回放、逐行日志)时才用 revealedLines。
  • 流式模式下代码框随行数长高;下方不能挪动时,把 minHeight 设为最终高度,完整代码回放时用 reserve。
  • 语言不确定时不传 lang:纯文本总是正确的。
  • 长代码配合外层滚动容器:代码区只横向滚动,高度随内容。
  • 需要与 TxStreamMarkdown 的围栏统一观感时用 TxCodeBlock;需要文件名头部、行号与逐行显现时用本组件。
  • 预览页默认不运行脚本。只有宿主确认页面可信时才设 preview-scripts;即便如此,页面仍在无同源、无网络的沙箱里,只能绘制,碰不到宿主。
  • 模型要求「给我一个页面」时,用 auto-preview;只是展示片段时不要开,读者先看到的应是源码。

API 参考

属性

属性名类型默认值说明
codestring—源码,必填。
langstring''Shiki 语言 id;留空不高亮,也不加载 Shiki。
filenamestring—头部文件名,等宽。
langLabelstring—文件名旁的语言标签,如 TypeScript。
revealedLinesnumber—显现到第几行,越界时夹取;省略或传 -1 表示全部。
streamingboolean—流式模式:源头仍在输出;false 时直接显示,可用 replay() 回放。
reveal'aurora' | 'hue' | 'blur' | 'languid' | 'none''aurora'流式模式:词的进场方式;代码保持语法颜色,aurora 等同 blur,hue 只是淡入。
wordMsnumber24流式模式:每 wordMs 放出一个词。
maxLagMsnumber600流式模式:任何词都在到达后这段时间内显示。
drainMsnumber320流式模式:streaming 变为 false 后,在这段时间内放完剩余部分。
pauseMsnumber400流式模式:超过这段时间没有新词即报告 paused。
reservebooleanfalse流式模式:完整代码回放时占住最终高度;streaming 时忽略。
pacedbooleantrue流式模式:为 false 时词一到就显示(仍有进场);TxStreamElement 统一控制节奏时传 false。
appearbooleanfalse流式模式:挂载时已有的代码也播放进场;只在挂载时读取。
caretbooleantrue逐行模式为末行静止标记,流式模式为 Tuff 光标;关闭即移除。
lineNumbersbooleantrue显示行号。
theme'light' | 'dark' | 'auto''auto'高亮主题;'auto' 跟随文档根的 data-theme 或 .dark。
copyablebooleantrue渲染复制按钮。
copyLabelstring'Copy'复制按钮文案;与 copiedLabel 一起本地化。
copiedLabelstring'Copied'复制成功后的文案。
previewablebooleantrue为 html、svg、xml 代码在停止输出后提供「预览」开关;流式输出中与 diff 模式下不出现。
autoPreviewbooleanfalse代码停止输出时直接打开渲染结果;读者可切回源码。
previewScriptsbooleanfalse允许预览页运行自带脚本;帧始终是无同源、无网络的沙箱。
previewLabelstring'Preview'开关文案。
codeLabelstring'Code'渲染结果显示时的开关文案。
frameLabelFormatter(lang: string) => string(lang) => `${lang} preview` 预览帧的无障碍名称。
minHeightnumber | string—代码区高度下限;缺省时按完整清单的高度预留。
diffCodeDiffRow[]—统一 diff 行,渲染时附增删计数;复制按钮仍复制 code。

事件

事件名参数说明
copy(code: string)复制成功时触发。
complete—revealedLines 抵达最后一行时触发一次;挂载即完整或流式模式下不触发。
state-change(state: StreamState)流式模式:状态变化时触发。
done—流式模式:每次播放结束时触发一次。

插槽

插槽名作用域参数说明
header—替换文件名与语言标签。
actions—复制按钮之前的自定义控件。
caret{ state }流式模式:替换 Tuff 光标,只在流式进行时渲染。

暴露方法

名称类型说明
stateStreamState流式模式的状态;其他模式下为 idle。
replay() => void流式模式:从第一个词起重播代码。
skip() => void流式模式:立即显示全部,不播放进场。

类型

CodeDiffRow

字段类型说明
contentstring该行文本,不带 + / - 标记。
kind'context' | 'added' | 'removed'默认 'context'。
numbernumber行号;被删行与替换它的新增行通常共用一个。不传则留空。

概述

  • 设置了 streaming(true 或 false),且没有 revealedLines 和非空的 diff 时进入流式模式;节奏、状态与增量显影同 StreamText。
  • revealedLines 模式下,光标只在显现过程中(0 < revealedLines < 总行数)出现在最后一行末尾,且保持静止。
  • 删除行用斜纹槽标、新增行用实心槽标,不只靠红绿两种色调区分。
  • 只有 Shiki 生成的标记进入 v-html,其中代码文本已转义;未高亮时走普通插值。
  • 预览帧是 sandbox 的 iframe,没有 allow-same-origin;它的文档写在外层 srcdoc 里,策略 <meta> 放在外层,被预览的代码作为转义后的内层 srcdoc 嵌入,所以代码里的 " 或 <head> 改不了策略。策略为 default-src 'none',仅放行内联样式、data:/blob: 图片与媒体;script-src 默认 'none',设 previewScripts 才为 'unsafe-inline'。
  • 减弱动效时不播放行或词的进场:revealedLines 照常显现,流式模式直接显示,光标静止。

技术实现

  • 高亮复用 TxCodeBlock 的 Shiki 懒加载单例:先渲染纯文本,颜色异步叠加。TxStreamCode 是同一组件的别名。
  • 移植自 Beautiful UI(© 2026 Shane Levine,MIT)。
  • 源码:packages/tuffex/packages/components/src/code-stream/。
查看源码
packages/tuffex/packages/components/src/code-stream/index.ts