# @copse/streaming-markdown 中文文档

规范地址：https://npmcn.com/package/%40copse/streaming-markdown/

版本：1\.8\.1
npm 元数据更新时间：2026-11-10T13:46:33.062Z
中文译文更新时间：2026-11-10T18:41:31.671Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40copse/streaming-markdown
原文对照：https://npmcn.com/package/%40copse/streaming-markdown/?lang=original
项目主页：https://github.com/copse-dev/streaming-markdown#readme
源码仓库：https://github.com/copse-dev/streaming-markdown

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：7.5 MB，213 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：pele ^1\.6\.0，katex ^0\.16\.0 \|\| ^0\.17\.0，react ^18\.0\.0 \|\| ^19\.0\.0，shiki ^4\.3\.1，mermaid ^11\.0\.0，entities ^9\.0\.0，dompurify ^3\.4\.11，react-dom ^18\.0\.0 \|\| ^19\.0\.0，highlight\.js ^11\.11\.1
- 首次发布：2026-07-05T15:23:52.262Z
- 最新版本发布：2026-11-10T13:46:32.412Z
- 近 30 天下载量：5694（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

流能通用马克标记下渲染器(字符串 HTML + 递增 DOM 发射器)

## 安装

```sh
npm install @copse/streaming-markdown
```

也可以使用：`pnpm add @copse/streaming-markdown`、`yarn add @copse/streaming-markdown`、`bun add @copse/streaming-markdown`

## README

# @ copse/ streaming- smarkdown (中文(简体) )

**马克倒地,随着它的到来.** 相同内容的两个发送器 流-纯度 `string→HTML` 函数用于后置渲染,并递增 DOM 渲染器显示部分标记下作为符号到达,而不闪出原始 语法. CommunityMark + GFM,为LLM/代理聊天UIs所建,但主机独立.

**▶ [现场演示](https://copse-dev.github.io/streaming-markdown/)** ——看两个发报员的相并发内容相同.

```bash
npm install @copse/streaming-markdown
```

## 快开始

**安静** —— 说 `renderMarkdown` 是安全、默认的切入点:它的输出有 已经通过水槽的消毒器, 所以它直接掉入 `innerHTML` (或 `setSanitizedHtml`类型安全:

```ts
import { renderMarkdown, setSanitizedHtml } from '@copse/streaming-markdown'

setSanitizedHtml(el, renderMarkdown('# Hi\n\n**bold** and ~~strike~~'))
// el.innerHTML = renderMarkdown('…') is also safe — the output is sanitized.
```

因为消毒造出DOM, `renderMarkdown` 需要一个消毒器后端( 浏览器默认为本地的 Sanitizer API, 或者一个注册的, 例如 [`…/sanitizers/dompurify`](https://npmcn.com/package/%40copse/streaming-markdown/docs/EXTENDING.md))),两者皆无 **掷出** 而不是返回不安全的 HTML.

与字符串端对端工作( SSR, 快照, 非 DOM 管道) 无 后端吗? 使用 `renderMarkdownUnsafe` ——"零依赖","DOM"无路径. 这个 返回时 **无信任** HTML,通过它 `sanitizeRenderedMarkdown` 在此之前 它到达任何 `innerHTML` 沉入水中,你管理自己.

**流线** ——喂每个符上生长的串. 字符串发射器是 最简单的; DOM 发射补丁递增而不是替换 `innerHTML`数字 :

```ts
import { StreamingMarkdownRenderer } from '@copse/streaming-markdown'

const renderer = new StreamingMarkdownRenderer(el)
for await (const chunk of stream) {
  accumulated += chunk
  renderer.update(accumulated) // incremental DOM patch, pending blocks styled while they form
}
renderer.finish() // end of stream: release held text, close an unclosed fence, render at rest
```

中流 渲染器挡住下一个字符仍然会改变的 (跟踪) `~~run`,最后一个表格行或列表项目). `finish()` 告诉它 没有什么了: `.stream-complete` 然后匹配 `renderMarkdown` 会 议 日 程 和 议 程 其最后一行的同文案文结束(与 `renderMarkdown(text)` 除外 在三个形状中,它暂时解析时没有新线;见 `finish()`A级 待会 `update()` 恢复流线。 用弦放电器,制造出 端流框架的相同方式: `renderMarkdown(accumulated)`,带有最终 `\n` 如果缺少附件,则附上附件.

## 要点

-   **流畅而安全.** 待定区块状态显示部分结构(表、清单、, 代码,图,数学),不闪出原始语法;重新进行升级到位.
-   **通用马克+ GFM** - 表格、任务清单、罢工、自动链接、, 脚注`[^1]`), GitHub 警报(`> [!NOTE]`),收缩和栅栏编码. 追踪到Spec的套房.
-   **一等数学.** ` ```math ` 栅栏, `$$…$$` 财务报告和审定财务报表 `\[…\]` 显示 块( OpenAI 分隔器样式),以及 `$…$` 编号 : `\(…\)` 内置数学 货币警卫(`$20 and $30` ——通过KaTeX懒惰地进行, 流中没有分隔符闪光。 传道词的分界符是每个渲染物选入的 通过 `{ mathSyntax: true }`; 在此之前,输出将保持字节与 无数学建构( ` ```math ` 栅栏是任意的). 见 [数学在 `docs/EXTENDING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/EXTENDING.md#math-katex)。 。 。 .
-   **洗个澡.** 渲染的 HTML 被视为不可信,链接为 计划验证;水槽消毒器是安全门。 Raw HTML 是 (原始内容存档于) **默认通过** (单位:千美元)`htmlPolicy: 'passthrough'`和水槽 消毒器是唯一的仲裁者——允许列出的标签作为元素渲染,一切 其他(包括 `<script>`剥去/未包装;通过 `htmlPolicy: 'escape'` 在渲染配置中将原始 HTML 字化取而代之,例如: 变形器串到水槽中而不进行消毒。 选入 **链接/图像来源允许列表** (单位:千美元)`linkImagePolicy`上面的分层—— 限制哪些来源链接/图像可能指向,修改/中和其余部分, 和脱衣舞基地64 `data:` 图像——默认关闭, 字节相同, 直到设定 这个 见 [链接/图像来源政策 `docs/EXTENDING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/EXTENDING.md#linkimage-origin-policy)。 。 。 . 完整的安全模型 威胁模型 和坚固的把手 [`docs/SECURITY.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/SECURITY.md)。 。 。 .
-   **零运行时间依赖关系.** 核心不需依赖。 HTML 语言 字符引用对内置集的解码( 252 经典 HTML4 已命名) 参考文献加所有数字参考文献),基本上涵盖所有真实事物 标记下出; 完整的 ~2 100- 输入 HTML5 表格 (~23 KB gzip) 选择通过 `browserEntityDecoder` (DOM零捆绑成本)或 `@copse/streaming-markdown/entities/full` 条目-见 [实体解码于 `docs/EXTENDING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/EXTENDING.md#entity-decoding)。 。 。 . higrant.js(或Shiki-作为后端的两艘船)、DOMPurify、美人鱼和KaTeX 为: **可选而懒惰** -除非你选择加入 否则从不加入 见 [`docs/LAZY-LOADING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/LAZY-LOADING.md)。 。 。 .
-   **所有东西都插上** ——消毒剂,语法突出显示器,美人鱼和数学 & 自定义有栅栏的块、自定义内在语法(引用、突出语法),以及 `<a>` 线路均可注射. Emoji 短码(`:smile:` 作为一艘船舶 可选内行后传 `@copse/streaming-markdown/inline/emoji` a 包括: GitHub/ gemoji相通地图, 除非导入, 否则您的捆绑中为零 字节 .
-   **可选的显示平滑.** 选入助手 (单位:千美元)`@copse/streaming-markdown/smoothing`斯地克多的标志性到达 平滑的字符卡通通过节奏显示 _投入_ 提供给 `renderer.update()` ——按固定速率,或适应地跟随溪流 本身的速率——并且从不停止用半满分的马克下语法来设置帧. 离开 默认和零字节,除非导入;荣誉 `prefers-reduced-motion`, (中文(简体) ), 或短短地排出(`finish`或立即释放 (单位:千美元)`flush`) (中文(简体) ). 见 [输入平滑 `docs/LAZY-LOADING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/LAZY-LOADING.md#input-smoothing--an-opt-in-reveal-cadence-84)。 。 。 .

## 扩展

消毒器、语法亮点、图/栅栏块渲染器、自定义内线 语法、链接路由和原始图像处理都是插件点——注册 a 后端一次,它不从你的捆绑,直到你做到这一点。 整个指南,与 每个代码,在 **[`docs/EXTENDING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/EXTENDING.md)**数字 :

```ts
import { renderMarkdown } from '@copse/streaming-markdown'
import { dompurifyBackend } from '@copse/streaming-markdown/sanitizers/dompurify'

// Pass the backend in the per-render config — e.g. for Node/jsdom/SSR.
renderMarkdown(md, { sanitizerBackend: dompurifyBackend })
```

执行的页 [信任类型](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) (单位:千美元)`require-trusted-types-for 'script'`)在框外加上任何 后端 — 见 [信任类型 `docs/EXTENDING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/EXTENDING.md#trusted-types) 政策名称和 `trustedTypesPolicy` 配置场.

中文 / 日文 / 韩文输出也有选入条目: 分布 `cjkFriendlyConfig` 从 `@copse/streaming-markdown/cjk` 转换为 使强调和赤裸的自动链接行为 绕起全宽平分线(`**「強調」**`, (中文(简体) ), `https://example.com。`页:1 选项 `styles/cjk.css` 搭载主机拥有的换行/间隔 CSS—— 见 [CJK / 东亚文本](https://npmcn.com/package/%40copse/streaming-markdown/docs/EXTENDING.md#cjk--east-asian-text)两者都是 默认关闭; 拉丁语输出为同字节.

## 反应

第三方 将船舶装订为 `@copse/streaming-markdown/react` 子路径。 反应是一种 _选项_ 同伴依赖,所以它不在你的捆绑之内 直到你导入子路径。 两个组件映射核心的两个渲染 路径 - 无 `useEffect`编号 :`useRef` 锅炉板和无 `dangerouslySetInnerHTML` 内 您的代码, 因为每个组件都拥有它的节点和路径 每个 DOM 写入 通过内部消毒器:

```tsx
import { Markdown, StreamingMarkdown } from '@copse/streaming-markdown/react'

// At rest — a complete document. SSR-safe; every DOM write is sanitized.
<Markdown markdown={content} />

// Streaming — feed the growing text; the incremental DOM renderer patches only
// the settled tail per token, not a re-render of the whole document (the thing
// that makes naive react-markdown-in-a-loop janky).
<StreamingMarkdown markdown={accumulatedText} />
```

两人都做个平手 `config` 道具(html/化学政策, `linkDecorator`, (中文(简体) ), `fenceHandlers`,数学/CJK切换,.),a `as` 选择容器的道具 和转发标准容器属性`className`(见A/C.5/49/70,附件)。 全数 指南——安全部门改革和水分化 `onUpdate` 数学/图表后端的钩子和 a `react-markdown` 移民情况 **[`docs/REACT.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/REACT.md)**。 。 。 .

## 样式

制造器释放出记录级钩,但船舶默认没有样式. 提供了可选样式表(`styles/core.css`,仅结构; `styles/default.css`,包括电池在内的主题; `styles/cjk.css`选择 东亚-亚洲分界线/间距;每个范围 `.streaming-markdown` 类 :

```ts
import '@copse/streaming-markdown/styles/default.css'
el.classList.add('streaming-markdown')
```

通过 `--sm-*` 自定义属性。 详细情况——班级合同,CSS 变量和去除原生的音符在 [`docs/EXTENDING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/EXTENDING.md#styling)。 。 。 .

## 文档

-   **[`docs/REACT.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/REACT.md)** ——使用来自React:at-rest并 增流组件、安全部门改革和从 `react-markdown`。 。 。 .
-   **[`docs/EXTENDING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/EXTENDING.md)** ——每一个接头(sanitizer, 突出显示器,自定义有栅栏的块,链接路由,图像,方案允许列表)和样式.
-   **[`docs/RECIPES.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/RECIPES.md)** ——UI食谱:如何添加副本 按钮(和相近的部件)改为代码块,而不与流出形态相对抗.
-   **[`docs/LAZY-LOADING.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/LAZY-LOADING.md)** - 为什么重道士是 可选和懒惰,以及密码分解加载是如何工作的.
-   **[`docs/ARCHITECTURE.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/ARCHITECTURE.md)** - 设计变化性 两单元流体结构, 和回归/相容套件.
-   **[`docs/BENCHMARKS.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/BENCHMARKS.md)** ——跨图书馆流出 基准(vs 向下流,反应-标记, smd, Incremark):方法, 说明和最新公布的结果.
-   **[`docs/SECURITY.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/SECURITY.md)** - 隔离安全 模型,一个威胁模型,信任边界, 和硬化的把手.
-   **[`docs/GITHUB-PARITY.md`](https://npmcn.com/package/%40copse/streaming-markdown/docs/GITHUB-PARITY.md)** - 副设计 与 github.com 渲染的相差 注释 HTML,并通过配置关闭哪些空白.

## 稳定性和版本

套装如下 [铸造](https://semver.org/)合同包括:

-   **主入口的出口** (单位:千美元)`src/index.ts`——每个符号都稳定 预加1.0 `@experimental` 级( 环境配置内观获取器和 低水平渲染器内部)从条目中去除后为1.0.
-   **子路径条目** (单位:千美元)`/sanitizers/*`, (中文(简体) ), `/highlighters/*`, (中文(简体) ), `/math/katex`, (中文(简体) ), `/diagrams`, (中文(简体) ), `/diagrams/mermaid`, (中文(简体) ), `/inline/emoji`, (中文(简体) ), `/cjk`, (中文(简体) ), `/entities/full`, (中文(简体) ), `/smoothing`, (中文(简体) ), `/react`, (中文(简体) ), `/host/workspace`)和CSS的切入点.
-   **默认输出稳定性 .** 通用市场/通用市场管理设施兼容性基线和 属性“ 字节- 相同, 直到您选择 ” (math 语法、 链接/ 图像) 政策,实体表)是合同的一部分——更改默认产出 正在打破更改 .

流线 _待定状态_ 标值( e)`stream-pending-*` 课程和瞬间 结构)是一种渲染行为,而不是有线格式:其活性(无生) 语法闪存; 与 rest 渲染的趋同) 稳定, 精确 瞬间DOM不是.

## 发展

拉动请求可以接受咨询 [警察审查](https://npmcn.com/package/%40copse/streaming-markdown/docs/COPSE-REVIEWER.md)运行 完全在这个寄存器的 GitHub 动作与正常的 CI .

```bash
npm install
npm run typecheck   # tsc (strict, exactOptionalPropertyTypes)
npm test            # node:test via tsx — unit + CommonMark & GFM conformance
npm run build       # emit dist/ (ESM JS + .d.ts)
npm run test:e2e    # Trusted Types enforcement e2e in real Chromium (skips without a browser)
npm run bench:browser  # sink-path throughput in real Chromium, incl. a TT-enforced page
```

### 图表渲染

[Pele 是默认的图后端](https://npmcn.com/package/%40copse/streaming-markdown/docs/DIAGRAMS.md),通过 `diagrams` (另见: `diagrams/pele`) (中文(简体) ). 它使美人鱼语法和负载只打开 第一个水分。 通过 SVG 消毒器 `transformSvg`; 演示使用 DOMPurify. (英语). 美人鱼.j仍然通过明确 `diagrams/mermaid` 适配器. 核心释放惰性图源,直到主机配置后端.

### 孤立的美人鱼制作

对于带有散列式CSP的不透明执行框架,使用可选 [`diagrams/mermaid/isolated` 适配器](https://npmcn.com/package/%40copse/streaming-markdown/docs/ISOLATED-MERMAID.md)它经营美人鱼 完全在母文档之外。 服务预建框架文档 (单位:千美元)`diagrams/mermaid/frame.html`)或构建自己的;主题、标签字体和框架 可访问名称为每个递归选项。 主机保留了导航/本地API执行. 现有的文档适配器不变. 对于缩放、平板、重置和全屏幕,可选 `diagrams/mermaid/viewer` 添加纯 DOM 控制器(`styles/diagram-viewer.css` 风格.

## 常见问题

### @copse/streaming-markdown 是什么？

流能通用马克标记下渲染器\(字符串 HTML \+ 递增 DOM 发射器\)

### 如何安装 @copse/streaming-markdown？

在项目目录运行 npm install @copse/streaming-markdown，或使用 pnpm add / yarn add / bun add。

### @copse/streaming-markdown 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @copse/streaming-markdown 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @copse/streaming-markdown 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @copse/streaming-markdown 可以商用吗？

@copse/streaming-markdown 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @copse/streaming-markdown 的下载量有多少？

根据 npm 官方下载统计，@copse/streaming-markdown 在 2026/10/11 – 2026/11/09 这 30 天内被下载 5,694 次，日均约 190 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @copse/streaming-markdown 还在维护吗？

最新版本 1\.8\.1 发布于 2026/11/10（今天）；至今共发布 30 个版本，其中过去 12 个月发布了 30 个；首次发布于 2026/07/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。