---
title: "CodeStream 流式代码块"
description: "带文件名头部、可流式输出的代码块"
category: AiReasoning
status: beta
since: 0.3.9
tags: [ai, code, streaming, highlight]
syncStatus: reviewed
verified: true
---

## 用法

### 流式输出
把目前收到的代码传给 `code` 并设置 `streaming`，组件逐词匀速放出。
:::TuffDemoWrapper{demo="CodeStreamLiveDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  const code = ref('')
  const busy = ref(true)

  onMounted(async () => {
    for await (const delta of stream)
      code.value += delta
    busy.value = false
  })
  </script>

  <template>
    <TxCodeStream :code="code" :streaming="busy" lang="ts" filename="churn.ts" />
  </template>
---
:::

### 逐行显现
宿主推进 `revealedLines`，组件负责过渡与光标。
:::TuffDemoWrapper{demo="CodeStreamStreamingDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCodeStream
      :code="code"
      lang="ts"
      filename="churn.ts"
      lang-label="TypeScript"
      :revealed-lines="revealed"
      @complete="onComplete"
    />
  </template>
---
:::

### 完整清单
不传 `revealedLines` 与 `streaming` 时显示完整清单。
:::TuffDemoWrapper{demo="CodeStreamStaticDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCodeStream
      :code="code"
      lang="ts"
      filename="inventory.ts"
      lang-label="TypeScript"
    />
  </template>
---
:::

### 渲染预览
`html`、`svg`、`xml` 代码停止输出后，头部出现「预览」开关，在沙箱 `iframe` 中渲染，再点回源码；流式与 diff 模式下不出现，`auto-preview` 则在代码结束时直接显示渲染结果。
:::TuffDemoWrapper{demo="CodeStreamPreviewDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCodeStream
      :code="html"
      lang="html"
      filename="pelican.html"
      lang-label="HTML"
      auto-preview
    />
  </template>
---
:::

### 统一 Diff
传 `diff` 渲染统一 diff；被删行与替换它的新增行共用行号，所以行号逐行给出。
:::TuffDemoWrapper{demo="CodeStreamDiffDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  const CODE = `...新版全文，供复制按钮使用...`

  const diff = [
    { number: 3, content: '  const base = await dairy.fetch({ flavor })' },
    { number: 4, kind: 'removed', content: '  await freezer.store(base, { temp: "-14C" })' },
    { number: 4, kind: 'added', content: '  await freezer.store(base, { temp: "-16C" })' },
    { number: 5, kind: 'added', content: '  if (!base.approved) return null' },
  ]
  </script>

  <template>
    <TxCodeStream :code="CODE" :diff="diff" lang="ts" filename="churn.ts" />
  </template>
---
:::

### 最佳实践

- 代码来自模型时用 `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](./stream-text.zh.mdc)。
- `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](https://www.beautifului.dev)（© 2026 Shane Levine，MIT）。
- 源码：`packages/tuffex/packages/components/src/code-stream/`。

<TuffDocSourceLink />
