CodeStream 流式代码块
带文件名头部、可流式输出的代码块
用法
流式输出
把目前收到的代码传给 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 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
code | string | — | 源码,必填。 |
lang | string | '' | Shiki 语言 id;留空不高亮,也不加载 Shiki。 |
filename | string | — | 头部文件名,等宽。 |
langLabel | string | — | 文件名旁的语言标签,如 TypeScript。 |
revealedLines | number | — | 显现到第几行,越界时夹取;省略或传 -1 表示全部。 |
streaming | boolean | — | 流式模式:源头仍在输出;false 时直接显示,可用 replay() 回放。 |
reveal | 'aurora' | 'hue' | 'blur' | 'languid' | 'none' | 'aurora' | 流式模式:词的进场方式;代码保持语法颜色,aurora 等同 blur,hue 只是淡入。 |
wordMs | number | 24 | 流式模式:每 wordMs 放出一个词。 |
maxLagMs | number | 600 | 流式模式:任何词都在到达后这段时间内显示。 |
drainMs | number | 320 | 流式模式:streaming 变为 false 后,在这段时间内放完剩余部分。 |
pauseMs | number | 400 | 流式模式:超过这段时间没有新词即报告 paused。 |
reserve | boolean | false | 流式模式:完整代码回放时占住最终高度;streaming 时忽略。 |
paced | boolean | true | 流式模式:为 false 时词一到就显示(仍有进场);TxStreamElement 统一控制节奏时传 false。 |
appear | boolean | false | 流式模式:挂载时已有的代码也播放进场;只在挂载时读取。 |
caret | boolean | true | 逐行模式为末行静止标记,流式模式为 Tuff 光标;关闭即移除。 |
lineNumbers | boolean | true | 显示行号。 |
theme | 'light' | 'dark' | 'auto' | 'auto' | 高亮主题;'auto' 跟随文档根的 data-theme 或 .dark。 |
copyable | boolean | true | 渲染复制按钮。 |
copyLabel | string | 'Copy' | 复制按钮文案;与 copiedLabel 一起本地化。 |
copiedLabel | string | 'Copied' | 复制成功后的文案。 |
previewable | boolean | true | 为 html、svg、xml 代码在停止输出后提供「预览」开关;流式输出中与 diff 模式下不出现。 |
autoPreview | boolean | false | 代码停止输出时直接打开渲染结果;读者可切回源码。 |
previewScripts | boolean | false | 允许预览页运行自带脚本;帧始终是无同源、无网络的沙箱。 |
previewLabel | string | 'Preview' | 开关文案。 |
codeLabel | string | 'Code' | 渲染结果显示时的开关文案。 |
frameLabelFormatter | (lang: string) => string | (lang) => `${lang} preview` | 预览帧的无障碍名称。 |
minHeight | number | string | — | 代码区高度下限;缺省时按完整清单的高度预留。 |
diff | CodeDiffRow[] | — | 统一 diff 行,渲染时附增删计数;复制按钮仍复制 code。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
copy | (code: string) | 复制成功时触发。 |
complete | — | revealedLines 抵达最后一行时触发一次;挂载即完整或流式模式下不触发。 |
state-change | (state: StreamState) | 流式模式:状态变化时触发。 |
done | — | 流式模式:每次播放结束时触发一次。 |
插槽
| 插槽名 | 作用域参数 | 说明 |
|---|---|---|
header | — | 替换文件名与语言标签。 |
actions | — | 复制按钮之前的自定义控件。 |
caret | { state } | 流式模式:替换 Tuff 光标,只在流式进行时渲染。 |
暴露方法
| 名称 | 类型 | 说明 |
|---|---|---|
state | StreamState | 流式模式的状态;其他模式下为 idle。 |
replay | () => void | 流式模式:从第一个词起重播代码。 |
skip | () => void | 流式模式:立即显示全部,不播放进场。 |
类型
CodeDiffRow
| 字段 | 类型 | 说明 |
|---|---|---|
content | string | 该行文本,不带 + / - 标记。 |
kind | 'context' | 'added' | 'removed' | 默认 'context'。 |
number | number | 行号;被删行与替换它的新增行通常共用一个。不传则留空。 |
概述
- 设置了
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