# @block-ml/viewer 中文文档

规范地址：https://npmcn.com/package/%40block-ml/viewer/

版本：0\.4\.3
npm 元数据更新时间：2026-10-30T07:49:18.672Z
中文译文更新时间：2026-11-08T07:09:38.519Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40block-ml/viewer
原文对照：https://npmcn.com/package/%40block-ml/viewer/?lang=original
项目主页：https://github.com/Roiocam/blockml#readme
源码仓库：https://github.com/Roiocam/blockml

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

- 包体积（解压后）：442 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-10-29T11:27:43.235Z
- 最新版本发布：2026-10-30T07:49:18.305Z
- 近 30 天下载量：1901（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

交互式 BlockML 画布: 渲染、拖放、导出

## 安装

```sh
npm install @block-ml/viewer
```

也可以使用：`pnpm add @block-ml/viewer`、`yarn add @block-ml/viewer`、`bun add @block-ml/viewer`

## README

# @block-ml/viewer

BlockML 交互画布：渲染、拖拽（回写源码）、图层开关、导出 SVG，以及把整张图内联成可双击的单文件 HTML。 渲染质量（共享端口、法线出线、标签避让、避障与跳弧）由这一层统一保证，不依赖文档里的样式键。

`@block-ml/cli` 的 `blockml render` 和 BlockML 桌面端用的就是这一份实现。

## 安装

```bash
npm i @block-ml/viewer @block-ml/core
```

## 用法（ESM）

```ts
import { mount } from "@block-ml/viewer";

const handle = mount(document.getElementById("canvas")!, {
  source: text,                 // .blockml 源码
  theme: "light",               // light | dark
  mode: "presentation",         // 嵌入编辑器时可用 editing
  route: "orthogonal",          // 初始走线：curve（默认）| orthogonal；可用 handle.setRoute() 切换
  onSourceChange: (next) => save(next), // 拖动后回写
});

handle.fit();
const svg = handle.toSVG();
```

`viewer` 默认 `editing` 以保持嵌入编辑器行为；单文件 HTML 与 CLI 交付默认 `presentation`， 只保留选择、详情、缩放与平移，顶部可切到编辑态。`mount()` 返回的 `ViewerHandle` 还提供 `setMode` / `getMode`、`zoomTo`、`layout`、`toggleLayers`、`setHiddenNodes`、 `setCollapsedGroups`、`showAll`、`getVisibility` 等方法。

## 用法（普通 HTML）

IIFE 构建会把 API 挂到 `globalThis.BlockML`：

```html
<link rel="stylesheet" href="node_modules/@block-ml/viewer/dist/styles.css" />
<script src="node_modules/@block-ml/viewer/dist/viewer.iife.js"></script>
<script>
  BlockML.mount(document.getElementById("canvas"), { source: "diagram \"demo\" {}" });
</script>
```

## 单文件 HTML

把 CSS 与 IIFE 内联进一个文件，双击即可打开——这正是 CLI 在做的事：

```ts
import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
import { renderStandaloneHTML } from "@block-ml/viewer";

const require = createRequire(import.meta.url);
const read = (id: string) => readFileSync(require.resolve(id), "utf8");

const html = renderStandaloneHTML({
  source: text,
  viewerScript: read("@block-ml/viewer/iife"),
  viewerCss: read("@block-ml/viewer/styles.css"),
  title: "订单平台",
  theme: "light",
});
```

也可以直接用命令行：`blockml render your.blockml -o your.html`（默认演示态，`--route` 只设初始走线风格，阅读器工具条可随时切换，`--readonly` 隐藏编辑切换）。

## 相关包

-   [`@block-ml/core`](https://www.npmjs.com/package/@block-ml/core)：解析与规范化
-   [`@block-ml/cli`](https://www.npmjs.com/package/@block-ml/cli)：命令行

文档与语言规范：[Roiocam/blockml](https://github.com/Roiocam/blockml)

## License

MIT

## 常见问题

### @block-ml/viewer 是什么？

交互式 BlockML 画布: 渲染、拖放、导出

### 如何安装 @block-ml/viewer？

在项目目录运行 npm install @block-ml/viewer，或使用 pnpm add / yarn add / bun add。

### @block-ml/viewer 支持 TypeScript 吗？

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

### @block-ml/viewer 支持 ESM 还是 CommonJS？

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

### @block-ml/viewer 可以商用吗？

@block-ml/viewer 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @block-ml/viewer 的下载量有多少？

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

### @block-ml/viewer 还在维护吗？

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