我喜欢那些紧邻其所解释代码的图表。导出的图片容易被遗忘,难以审查,并且在经过几次更改后通常会过时。
这就是我构建 @schemd/core 的原因,这是一个零依赖的编译器,可以将一种小型文本格式转换为可访问的可缩放矢量图形(SVG)。
斯凯姆德(Schemd)目前支持常见的电路元件、经典和量子逻辑门、可配置的集成电路,以及我最常用的统一建模语言(UML)图表:类图、序列图、状态图和用例图。它在服务器端或构建过程中运行,因此浏览器不需要编译器或 Markdown 包。
快速示例
安装软件包:
npm install @schemd/core
然后编译图表:
import { compileSchematic, parseSchematicFence } from "@schemd/core";
const fence = parseSchematicFence(
'schemd bounds="640x260" title="传感器输入"',
)!;
const { svg } = compileSchematic(
`
port:VIN "输入" at (120, 130) #blue
resistor:R1 "10 k\\Omega" at (300, 130) #amber
capacitor:C1 "100 nF" at (500, 130) #cyan
VIN.out -> R1.in #blue [ortho]
R1.out -> C1.in #amber [ortho]
`,
fence,
);
结果是确定性的内联可缩放矢量图形(SVG),包含标题、描述、固有尺寸和安全的文本输出。正交连线会避开元件主体,并在交叉处生成桥接弧。
统一建模语言(UML)使用相同的语法:
class:User "用户" at (160, 120) #slate [attributes="- id: UUID" operations="+ save(): void"]
class:Admin "管理员" at (460, 120) #blue
Admin.left -> User.right #blue [ortho generalization]
为什么需要另一个图表工具?
我想要一个职责单一的编译器:
- 无运行时依赖;
- 无文档对象模型(DOM)或浏览器布局过程;
- 通过一次函数调用即可生成有用的可缩放矢量图形(SVG);
- 源代码在拉取请求中易于阅读;
- 工作量有界且输出可预测;
- 提供足够的样式钩子,适用于文档和模拟。
编译器入口点在持续集成(CI)中的 gzip 压缩大小硬性限制为 20 KiB。当前构建版本约为 18 KiB。此外,语句、分支、函数和行的代码覆盖率也强制要求达到 100%。
斯凯姆德(Schemd)不包含 Markdown 解析器。宿主环境可以使用 Marked、markdown-it、unified 或其自有解析器检测 schemd 代码块,然后仅将代码块主体传递给核心模块。这保持了软件包的小巧,并让每个应用程序能够保留其现有的 Markdown 处理流程。