# bananamark-tikz 中文文档

规范地址：https://npmcn.com/package/bananamark-tikz/

版本：0\.2\.1
npm 元数据更新时间：2026-11-03T02:36:46.938Z
中文译文更新时间：2026-11-03T05:30:46.179Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/bananamark-tikz
原文对照：https://npmcn.com/package/bananamark-tikz/?lang=original
项目主页：https://github.com/banana-space/banana/tree/main/packages/bananamark-tikz#readme
源码仓库：https://github.com/banana-space/banana

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

- 包体积（解压后）：50.9 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：3 个
- peer 依赖：bananamark ~0\.2\.0
- 首次发布：2026-10-28T03:03:10.847Z
- 最新版本发布：2026-11-03T02:36:46.759Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

用于bananark的TikZ图表：在工作线程中使用Node -tikzjax编译为SVG（仅限Node）

## 安装

```sh
npm install bananamark-tikz
```

也可以使用：`pnpm add bananamark-tikz`、`yarn add bananamark-tikz`、`bun add bananamark-tikz`

## README

# bananamark-tikz

TikZ图 [bananamark](https://github.com/banana-space/banana/tree/main/packages/bananamark#readme)． 用TikZ打开（方言的） `tikz: true`)、TikZ图(` ```tikz ` 块, `tikzcd` 和 `tikzpicture` （公式中的环境）是bananark的HTML中的占位符，包含其源的元素；这个包使用node-tikzjax （WebAssembly中的一个TeX引擎）在工作线程中编译它们，并将SVG放在它们的位置。节点。

## 状态

版本0.2，发布于 `bananamark` (见其 [状态](https://github.com/banana-space/banana/tree/main/packages/bananamark#status))：在1.0之前，小版本可能会改变接口。同行的依赖: `bananamark` 相同的小版本。仅限ES模块；麻省理工学院的执照。

```sh
npm install bananamark bananamark-tikz
```

## 使用

作为处理器的插件：

```js
import { createProcessor, defineDialect } from 'bananamark';
import { tikz } from 'bananamark-tikz';

const diagrams = tikz({
  cache: 'cache/tikz',                  // compiled diagrams are kept here (a JSON file each); without it, in memory only
  fonts: { directory: 'site/fonts' },   // the fonts of diagrams' text are copied here
});
const processor = createProcessor({ dialect: defineDialect({ tikz: true }), plugins: [diagrams] });
const page = await processor.renderAsync(source, { file: 'groups.md', outputPath: 'site/groups/index.html' });
await processor.close();   // closes the plugin: stops its worker
```

或者在HTML上（比如从网站的模板中截取整个页面）：

```js
const diagrams = tikz({ cache: 'cache/tikz', fonts: { directory: 'site/fonts' } });
const html = await diagrams.render(pageHTML, { outputPath: 'site/groups/index.html' });
await diagrams.close();
```

`render(html, page)` （`postprocess`（作为一个插件）给出了带有图表的HTML。 `page` 是 `{ outputPath, file, locale, messages }`： `outputPath`，页面的HTML文件，字体的地址是相对于它的； `file`，文件错误名称(默认为 `outputPath`); `locale` 和 `messages`，有关错误(请参阅 [错误](https://npmcn.com/package/bananamark-tikz/#readme-errors);处理器赋予它自己的插件。当图表有文本时 `@font-face` 它的字体规则之前 `</head>` 在整个页面上，或者在HTML的开头没有 `<head>` （一个页面的主体，作为插件看到它）。

一旦每个页面被渲染， `prune()` 删除缓存不再需要的内容； `close()` 阻止工人。

## 选项

| 选项 | 意义 | 默认的 |
| --- | --- | --- |
| `cache` | 编译图保存在目录中 | 仅在内存中 |
| `fonts` | `{ directory }`：一个页面的图表使用的字体在那里被复制（带有他们的许可），并且该页面从其HTML文件中引用他们的路径；或 `{ href(font, outputPath) }`：字体地址 | 无：带有文本的图表是错误的 |
| `timeout` | 一个图表最长的编译时间，以毫秒为单位。一个图表用完后会被记住10分钟：没有时间允许的实例会立即失败 | 15000 |
| `totalTimeout` | 时间，以毫秒为单位，这个实例可能花费在编译上（一个预览：一个有许多慢图的草稿不能占用队列）；失败后的图表 | 没有限制 |
| `workerIdleTimeout` | 以毫秒为单位，实例共享一个工作线程（大约0.5秒启动，370 MB），在最后一个工作线程关闭后保持这么长时间 | 每个实例都有自己的worker |
| `locale`， `messages` | 错误的语言和调用者的消息，作为bananark的选项(这个包自己的消息： `tikz_failed`， `tikz_command`， `tikz_unsafe`， `tikz_timeout`， `tikz_total_timeout`， `tikz_worker_exit`)，翻过这一页 | 页面的;否则 `'en'` |

## 输出

占位符(`bm-tikz-source`,他的 `code.bm-tikz-code` 显示编译前的源代码)变为 `bm-tikz-rendered`，保持SVG `span.bm-tikz-body` （`svg.bm-tikz-svg`;汉字 `bm-tikz-cjk`）. 有编号的图表 `span.bm-tikz-layout`，它的数量在 `span.bm-tikz-tag`, `--bm-tikz-tag-space` 数字的宽度。

## 可以使用哪些图表

-   特克斯包 `tikz-cd`， `amsmath`， `amssymb` 和 `array`;TikZ库加载一个图表 `\usetikzlibrary{…}`.
-   的命令 `\coloneqq`， `\eqqcolon`， `\bra`， `\ket`， `\braket`， `\set`， `\Set` 和 `\bm`，以及Unicode数学符号、希腊字母和直接输入的重音拉丁字母，如KaTeX。
-   汉字，用页面的字体绘制。
-   不是bananamark `katex` 宏：除KaTeX外，图表由TeX编译。目前还没有来电者的序言选项。
-   不 `\special`，在图的源代码的任何地方（也有注释）：它按原样写入SVG。这个图表是错误的。`tikz_command`)，当它在缓存中时也是如此。
-   只有一幅画出来了：如果一个图的SVG有一个TikZ没有使用的元素（链接、脚本、动画、嵌入内容）、一个事件处理程序、一个图片外的引用或一个标记声明，那么这个图就是一个错误(`tikz_unsafe`)，不管TeX是怎么写的。SVG中没有删除任何内容；检查在使用每个图时运行，也从缓存运行。

## 图表是如何绘制的？

-   一个图表的公式是由TeX编写的：几个图表， `\left…\right` 或1附近的分数是由TeX布置的，遵循LaTeX而不是KaTeX （KaTeX自己的命令不在那里）。一个 `\tag` 它的周围是分开编译的，放在右边，所以数字和参考文献保留了下来。内联一行 `tikzcd` 在其细胞的基线上对齐；一个 `tikzpicture` 像往常一样 `baseline=(node.base)`.
-   SVG是TeX引擎自己的绘图，校正了上游转换器的偏移量（0.27 pt），使其与公式框对齐。页面只显示它：浏览器中没有测量或移动任何东西，而且它显示时没有使用JavaScript。
-   中文：引擎没有中文字体。每个汉字和全宽标点符号被声明为TeX，作为一个1 em宽的方框（在文本的大小上：公式的放大，1.1，无效），高85%，深15%；TeX在这些框周围放置节点、标签和箭头，SVG将字符写入 `<text>` 我把他们接到哪儿去了 `dvisvgm:raw`)，用页面的字体绘制， `textLength` 保持它们的宽度。一行中的字符为一个 `<text>`，所以一个单词在一行上复制。尺寸遵循数学风格，粗体和斜体遵循TeX的字体，颜色和旋转遵循TikZ的字体。
-   这不是CTeX或xeCJK：宽度是假设的，而不是从读者的字体中测量的（是否显示稀有字符取决于它们），中文文本没有断行，行尾没有标点符号规则，也没有垂直文本。用ASCII写节点名；中文是用来展示的。
-   重音拉丁字母被声明为TeX的重音，所以 `\text{Möbius}` 和 `\mathsf{Ét}` 可以直接输入。
-   抄写使汉字原封不动；西方的数学是在引擎的BaKoMa字体中，其希腊字母、符号和大括号可以作为其他字符复制。图没有MathML。

## 缓存

编译后的图由输入（源，显示，模式），编译器代码，引擎版本和它得到的序言（上面的可选行只有在图使用它们时才在其中）的散列保存：更改一个命令只会再次编译使用它的图。

-   `prune({ maxAge })`：在渲染每个页面后，删除此实例未使用的缓存文件，并且其中没有使用任何文件 `maxAge` （ms，默认一周：在线编辑的草稿保留他们的）。返回已删除的号码。
-   TeX失败的图被记住（最近的200次失败），不再编译；一场没有时间的演讲，持续了十分钟 `timeout` 不再是。几页同时需要的图表只编译一次。

## 错误

当图表无法编译时， `render` 扔一个香蕉马克 `BananamarkError`：它的消息是文件和原因("groups。md: TikZ编译失败：…"和TeX的错误)， `error.file` 这个文件, `error.code` 和 `error.params` 消息的键和值(`tikz_failed`，其中TeX的误差为 `params.message`； `tikz_command`，使用 `\special`，命令为 `params.command`； `tikz_unsafe`，一个不仅仅是绘图的SVG，它被发现为 `params.found`； `tikz_timeout` 和 `tikz_total_timeout`, `seconds`； `tikz_worker_exit`，工人的退出 `code`), `error.cause` 下面的误差。单词在实例中 `locale` 和 `messages`或者页面的（处理器会给它自己的插件）默认是英文的；没有这些键的呼叫者的区域设置使用英语。

## 贡献

测试:看 [CONTRIBUTING.md](https://github.com/banana-space/banana/blob/main/packages/CONTRIBUTING.md).

## 常见问题

### bananamark-tikz 是什么？

用于bananark的TikZ图表：在工作线程中使用Node -tikzjax编译为SVG（仅限Node）

### 如何安装 bananamark-tikz？

在项目目录运行 npm install bananamark-tikz，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：bananamark（~0\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### bananamark-tikz 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bananamark-tikz 是否存在。

### bananamark-tikz 支持 ESM 还是 CommonJS？

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

### bananamark-tikz 需要什么版本的 Node\.js？

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

### bananamark-tikz 可以商用吗？

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

### bananamark-tikz 还在维护吗？

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