Przejdź do treści
Biblioteka skilli
Programowanie · Konwersja i formaty

wavedrom-render

/wavedrom-render

Renderuje diagramy czasowe WaveDrom i WaveJSON do SVG lub PNG, także pisze i naprawia kod sygnałów.

Repozytorium
wave_drom_gui ↗
Licencja
MIT
Ostatnia zmiana repozytorium
06.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
14
Skrypty
11
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 06.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 11 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: lib/font-embed.js, lib/meta-embed.js, lib/render-modern.js, lib/render-traditional.js, lib/svg-to-png.js, render.js, scripts/subset_font.py, scripts/svg2png.py, setup.js, vendor/wavedrom.bundle.js, vendor/waveskin.js

Co robi i kiedy

Renderuje diagramy czasowe WaveDrom i WaveJSON do SVG lub PNG, także pisze i naprawia kod sygnałów.

Wyzwalacze z opisu

signal
Oryginalny opis (EN)

当用户需要将时序、周期行为或信号波形可视化, 或需要渲染、预览、编写、修复 WaveDrom / WaveJSON 时使用。 支持 AI 生成或用户手写的 WaveJSON,输出 SVG / PNG。 默认使用与 wavedrom-gui 一致的现代浅色风格, 也支持官方 WaveDrom v3.5.0 的传统风格。 When the user gives WaveDrom / WaveJSON code (e.g. `{ "signal": [...] }`) and wants a waveform picture, timing diagram, 波形图, or to render/preview a signal as SVG/PNG, use this skill. Fully self-contained: needs only Node.js (+ a PNG rasterizer such as Python cairosvg). Does NOT need index.html or a browser. Also use it whenever you are asked to write / fix WaveJSON code: the skill contains a 「WaveJSON 生成指南」(authoring rules — repeated st

Jak działa

  1. 何时使用
  2. WaveJSON 生成指南
  3. 前置条件
  4. 安装 / 初始化(推荐,可选,一次性)
  5. 用法
  6. 两种模式的区别
  7. 宽标签:自动缩放与省略显示
  8. 总线数据块怎么衔接
  9. 支持的 WaveJSON 语法
  10. 字体与字号(可配置)
Sekcje z nagłówków SKILL.md, w oryginale · 273 linii, 1 559 słów
Podgląd SKILL.md
---
name: wavedrom-render
description: >
  当用户需要将时序、周期行为或信号波形可视化,
  或需要渲染、预览、编写、修复 WaveDrom / WaveJSON 时使用。
  支持 AI 生成或用户手写的 WaveJSON,输出 SVG / PNG。
  默认使用与 wavedrom-gui 一致的现代浅色风格,
  也支持官方 WaveDrom v3.5.0 的传统风格。

  When the user gives WaveDrom / WaveJSON code (e.g. `{ "signal": [...] }`) and wants a
  waveform picture, timing diagram, 波形图, or to render/preview a signal as SVG/PNG,
  use this skill. Fully self-contained: needs only Node.js (+ a PNG rasterizer such as
  Python cairosvg). Does NOT need index.html or a browser.
  Also use it whenever you are asked to write / fix WaveJSON code: the skill contains a
  「WaveJSON 生成指南」(authoring rules — repeated states must use continuation dots,
  single-bit signals must not use data-bus chars) that generated code must follow.
---

# WaveDrom Render

把 WaveJSON 渲染为时序波形图片。所有依赖都在本目录内,**不需要 index.html、不需要浏览器**。

## 何时使用

- 用户提供 WaveDrom / WaveJSON,想预览为波形图、时序图,或导出 SVG / PNG。
- 需要把 AI 生成的时序描述可视化检视,并检查周期、边沿、数据框、节点和连线是否符合预期。
- 需要编写或修复 WaveJSON,包括补全 `wave`、`data`、`node`、`edge`、`period`、`phase` 等字段。
- 需要在现代模式和传统 WaveDrom 模式之间选择渲染风格,或调整传统皮肤、节点位置 / 缩放 / 标记形态和 PNG 清晰度。
- 需要在没有浏览器或 `index.html` 的环境中,通过本目录 CLI 独立渲染波形。

## WaveJSON 生成指南

AI 或人工编写 / 修改 WaveJSON 时遵守以下规则与速查表。

### 规则 1:连续相同状态 → 状态字符 + 延续符 `.`

`.` 表示「延续上一拍状态」。连续多拍相同的电平 / 时钟 / 数据值,只在第一拍写状态字符,其后全部用 `.`:

- 高电平 4 拍写 `"1..."`,**不要**写 `"1111"`;低电平同理 `"0..."`。
- 时钟 8 拍写 `"p......."`,**不要**写 `"pppppppp"`(`n`/`P`/`N` 同理)。
- 同一数据值占 3 拍写 `"=.."`(一个数据框横跨 3 拍);值变化时再写一个 `=` 或 `2`–`9`。
- `|`(间隙)表示显式断口。为避免跨间隙产生歧义,`|` 之后建议重新写状态字符,不要直接使用 `.` 延续,如 `"0.1..0|1.0"`。

### 规则 2:单 bit 信号不用多 bit 专用字符

`=` 与 `2`–`9` 是**多 bit 数据总线**专用字符:绘制带边框的数据框、从 `data` 数组依次取标签、按官方八色着色。单 bit 信号(clk、req、ack、en、valid 等控制 / 状态线)只用电平、跳变与时钟字符(`0` `1` `u` `d` `x` `z` `p` `n` 等)。

```jsonc
{ "name": "req",  "wave": "=...." }                                   // ❌ 单 bit 用了数据框字符
{ "name": "req",  "wave": "0.1.....0." }                              // ✅ 电平 + 延续符
{ "name": "data", "wave": "x.==..=x.", "data": ["D0", "D1", "D2"] }   // ✅ 多 bit 总线才用 = / 2–9
```

### 规则 3:使用默认的现代模式渲染时,不使用空白占位行

多利用分组标签,而非空白占位行,因为空白占位行占用高度过高,而分组的所产生的隔离效果要更好。


### 基础常用语法速查

**`wave` 状态字符**(一个字符 = 一拍):

| 字符 | 含义 |
|---|---|
| `0` / `1` | 低电平 / 高电平(与前一拍电平不同时自动画过渡) |
| `p` / `n` | 时钟(上升沿起)/ 反相时钟(下降沿起),之后自动振荡 |
| `P` / `N` | 同 `p` / `n`,另带边沿箭头标记 |
| `u` / `d` | 上升沿(0→1)/ 下降沿(1→0),单次 S 曲线跳变。**没有大写形式**:`U`/`D` 官方无对应砖块,会被画成 `x` 不确定框 |
| `h` / `l` | 高 / 低电平段,跳变处是**垂直沿**(与 `0`/`1` 的斜坡过渡形状不同),可与 `H`/`L` 混搭手工拼时钟,如 `xhlhLHl.` |
| `H` / `L` | 同 `h` / `l`,垂直沿上另带箭头标记 |
| `x` | 不确定 / 无关态(交叉阴影框),多bit数据 “无有效数据” 时推荐使用 |
| `z` | 高阻态 |
| `=` | 多 bit 数据框,标签依次取 `data` 数组, 但颜色固定为默认前景色 |
| `2`–`9` | 多 bit 数据框,各用一种官方配色(白 黄 橙 蓝 青 绿 紫 粉),标签同 `=` ,推荐使用不同配色表示不同的数据|
| `.` | 延续上一拍状态(见规则 1) |
| `\|` | 间隙标记:占一拍、画断口,常用于省略无关时段 |
| `<` `>` | 子周期区段起止:两者之间的字符按半拍宽渲染(亚拍级毛刺 / 跳变) |
| 空格 | 空白拍(该拍不绘制) |

**信号对象字段:**

| 字段 | 含义 |
|---|---|
| `name` | 信号名 |
| `wave` | 波形串(上表字符组成) |
| `data` | 数据标签数组,供 `=` / `2`–`9` 数据框按出现顺序取用 |
| `node` | 与 `wave` 等长的节点字母串(如 `".a....."`),供 `edge` 连线引用 |
| `period` | 周期倍数:该信号每个字符占 `period` 格宽(时钟一个完整周期占 `period` 格,如 DDR 的 CK 用 `2`) |
| `phase` | 相位偏移:波形整体**左移**,`0.5` = 半个本信号周期 |

**文档骨架(其余顶层字段):**

```jsonc
{
  "signal": [                          // 必需;数组元素 = 信号 / 分组 / 占位
    { "name": "clk",  "wave": "p.........", "node": ".a........" },
    { "name": "req",  "wave": "0.1.....0.", "node": "..b......." },
    { "name": "data", "wave": "x.==..x...", "data": ["D0", "D1"] },
    ["分组名",                          // 数组 = 分组,可嵌套子分组
      { "name": "ack", "wave": "1.....01.." }],
  ],
  "edge":   ["a~>b 请求锁存"],         // 节点连线:字母 + 连线符 + 字母 + 标注;
                                       // 常用连线符:-> 直线箭头、~> 曲线箭头、<-> 双向、-| 直角折下、+ 两端圆点
  "head":   { "text": "标题", "tick": 0, "every": 2 },   // 顶部标题 / 刻度
  "foot":   { "text": "图注", "tock": 9 },               // 底部图注 / 刻度
  "config": { "hscale": 1, "skin": "default", "hbounds": [0, 10] },
}
```

> 骨架里的 `//` 注释仅供讲解。粘贴到 wavedrom-gui 代码页和本 skill 的 CLI 可直接渲染;官方 wavedrom.com 编辑器通常也支持这类宽松写法。交给严格 JSON 解析器(如 kroki API)时,请删除注释、未加引号的键、单引号和尾逗号。

## 前置条件

- **Node.js**(渲染 SVG,必需)。
- **PNG 光栅化器**(生成 PNG 时需要,三选一,按优先级自动探测):
  1. Python + `cairosvg`(推荐):`pip install cairosvg`
  2. `rsvg-convert`(librsvg)
  3. ImageMagick(`magick` / `convert`)
- **Python `fontTools`**(可选,用于「把字体内嵌进 SVG」):`pip install fonttools`。见下方「字体」。
- **霞鹜文楷字体下载**(**推荐**,可选):`node setup.js` 一次性下载到 `vendor/fonts/`(两套 TTF 各约 24MB),现代模式获得与 App 一致的字体外观、SVG 可内嵌自包含;**不下载也能正常渲染**(回退系统字体)。见下方「安装 / 初始化」。

只输出 SVG 且不内嵌字体时,只需 Node.js。

## 安装 / 初始化(推荐,可选,一次性)

现代模式默认想用**霞鹜文楷**(与原 App 一致)。首次使用可联网下载一次字体到本地:

```bash
node setup.js
```

- 从 GitHub Releases 下载 `LXGWWenKai-Regular.ttf` 与 `LXGWWenKaiMono-Regular.ttf` 到 `vendor/fonts/`(各约 24MB)。
- 渠道自动:先直连 GitHub,失败再走国内代理 `gh-proxy.org`;也可在 `fonts.config.json` 里把 `mirror` 固定为 `github` / `ghproxy`。
- 已下载则跳过。**下载失败不报错中断**——渲染会静默回退到系统字体名(中文仍显示,只是非霞鹜文楷外观)。
- 不跑这步也能正常渲染,只是拿不到霞鹜文楷外观。

## 用法

在本 skill 目录(`SKILL/wavedrom-render/`)下运行:

```bash
node render.js <input.json> [选项]
node render.js -              # 从 stdin 读取 WaveJSON
```

### 选项

| 选项 | 取值 | 默认 | 说明 |
|---|---|---|---|
| `--mode` | `modern` \| `traditional` | `modern` | 渲染风格 |
| `--format` | `svg` \| `png` \| `both` | `png` | 输出格式 |
| `--out` / `-o` | 路径 | 自动命名(`wavedrom_gui_*`) | 输出路径(扩展名自动补)。不给时按与网页版同一套约定命名:有标题用 `wavedrom_gui_标题`,否则 `wavedrom_gui_日期_序号`;**目录**跟随输入文件(stdin 输入时为当前目录)。父目录需已存在,脚本不会创建它 |
| `--scale` | 数字 | `2` | PNG 缩放倍数(2 = 2×,更清晰) |
| `--skin` | `default` \| `narrow` | 先用文档里的 `config.skin`,缺省 `default` | **仅传统模式**:官方皮肤 |
| `--node-pos` | `lt tm rt lm c rm lb bm rb` | `lm` | **仅现代模式**:节点圆标位置 |
| `--node-scale` | 数字 | `1` | **仅现代模式**:节点圆标缩放 |
| `--node-inset` | `0`–`9` | `4` | **仅现代模式**:节点圆标相对连线端点的内缩像素(0 = 贴住端点) |
| `--node-mode` | `letter` \| `bare` \| `dot` | `bare` | **仅现代模式**:节点标记形态——`letter` 描边圆 + 字母 / `bare` 字母 + 半透明白底(无描边)/ `dot` 实心小圆点 |
| `--bus-join` | `split` \| `joined` | `split` | **仅现代模式**:相邻两个总线数据块怎么接——`split` 各画各的圆角框、中间留一道发丝缝(默认,与网页版编辑区一致)/ `joined` 两端斜切、在拍界上对成一个 X(官方 WaveDrom 的画法)。文档自己写了 `config.busJoin` 时**以文档为准**,这个选项只顶替没钉档的文档 |
| `--auto-scale` | `on` \| `off` | `on` | **仅现代模式**:自动缩放——按最宽的 `data` 标签自动抬高 `hscale`,让标签放得下。只增不减:文档里显式写了更大的 `hscale`(如 `config.hscale: 4`)时以其为准,不被压低 |
| `--auto-scale-max` | `1`–`8` | `2` | **仅现代模式**:自动缩放的倍数上限。到上限仍放不下的标签**改为省略显示**(`开头…末尾字符`,绝不做字距压缩),不会把图拉得极宽 |
| `--no-auto-scale` | — | — | 等价于 `--auto-scale off` |
| `--no-meta` | — | 默认内嵌 | 关闭 WaveJSON 元数据内嵌 |
| `--strict` | — | 宽松解析 | **只接受严格 JSON**:渲染来源不明的文件时务必加上,禁用宽松求值回退 |
| `-h` / `--help` | — | — | 打印用法 |

### 示例

```bash
# 现代模式(默认),生成 PNG
node render.js wave.json

# 现代模式,同时导出 SVG + PNG
node render.js wave.json --format both --out out/mywave

# 传统模式(官方引擎),narrow 皮肤,导出 SVG
node render.js wave.json --mode traditional --skin narrow --format svg

# 从 stdin 读入,写到指定 PNG,3× 清晰度
cat wave.json | node render.js - --out out/w.png --scale 3
```

> `--out` 的父目录需要已存在(脚本不创建目录);上面的 `out/` 请先 `mkdir -p out`。

### WaveJSON 元数据内嵌(默认开启)

导出的 SVG / PNG 都会把本次 WaveJSON 写进图片:SVG 用 `<metadata data-wavedrom>`、PNG 用 `iTXt` 文本块(关键字 `WaveJSON`),与 wavedrom-gui 的导出同规格。**显示完全不受影响**;把图片在 wavedrom-gui 里「打开文件」即可直接还原图表,`--no-meta` 可关闭。

同时写入**导出来源标记**(SVG 的 `data-export` 属性 / PNG 关键字 `WaveDromGui` 的 `iTXt` 块):现代模式写 `skill-modern`、传统模式写 `wavedrom`。VSCode 插件在读图时按它选同一套渲染器重绘写回——skill 导出的图在插件里编辑、保存后不会被换成别的风格(`--no-meta` 会一并省掉,届时插件按指纹判断、判不出时兜底 skill-modern)。

## 两种模式的区别

- **现代模式(modern,默认)**:复刻 wavedrom-gui 编辑区的自绘 SVG —— 浅色主题、每条信号按 `color` 键着色(没写就按调色板轮转)、数据框逐色(官方 2–9 配色)、总线数据块衔接两档(`config.busJoin`,见下)、节点圆标、`period/phase/hscale`、`hbounds` 裁剪、head/foot 文字(含 JsonML 富文本)与 tick 刻度、分组与占位行、节点箭头(`edge`)。几何逻辑逐字移植自 `index.html` 的 `laneSVG` 与网格布局,配色固定为浅色(与 App 的导出一致)。
- **传统模式(traditional)**:直接调用内嵌的**官方 WaveDrom v3.5.0** 渲染引擎(`vendor/` 内),产出官方黑白样式,支持 `default` / `narrow` 两套皮肤。

两种模式吃同一份 WaveJSON。输入既可是严格 JSON,也可是宽松写法:`//` 注释、不带引号的键、尾逗号、单引号(与 App 代码页的宽松解析行为一致)。

> 安全提示:宽松 WaveJSON 解析会使用 JavaScript 表达式求值,以兼容未加引号的键、单引号和尾逗号。求值不是沙箱,恶意构造的输入可以在本进程内执行任意代码——**渲染来源不明的文件或网络内容时必须加 `--strict`**(只接受严格 JSON);仅对可信输入使用默认的宽松解析。

## 宽标签:自动缩放与省略显示

- **宽度按真实字形估**:等宽字体下 ASCII ≈ 0.53em,中文/全角正好是它的**两倍**(1.06em)。估算按全角 2 单位、半角 1 单位计,所以中文标签不会被算窄一半(早前按字符数估算会让中文标签显示溢出或压缩过度)。`—`(破折号)与 `…`(省略号)也按全角计。
- **自动缩放默认开**:渲染前扫描所有 `data` 标签,按「标签自然宽度 + 8px 内边距 ÷ 该数据框的格宽」算出需要的档位,把 `hscale` 抬到够用,**上限默认 2×**(`--auto-scale-max` 可调到 1–8)。只增不减,不会压低文档显式设置的更大 `hscale`。
- **到上限仍放不下 → 省略显示**:标签按字符省略为「开头…末尾字符」(如 `一骑红尘妃子笑` → `一骑…笑`),空间再不够就只留开头,始终在数据框宽度内以正常字距显示尽可能多的字符;不再使用 `textLength` 压缩字距(那样会把汉字挤成一团)。
- 想要标签**完整显示**:把 `--auto-scale-max` 调大(例如中文长标签常用 3–4),或在 WaveJSON 里直接写更大的 `config.hscale`。

## 总线数据块怎么衔接

- **两档**:`split`(默认)相邻两块各画各的圆角框,中间留一道发丝缝;`joined` 两端各收一个斜角、对成一个 X(斜切整段落在这后一块的开头),也就是官方 WaveDrom 的画法。
- **谁说了算**:文档里的 `config.busJoin` > `--bus-join` > 默认 `split`,两边各测过一遍、文档档确实压得住命令行档。App 侧还有第三层「设置 → 外观」的本地偏好,但它不进 JSON——写进文档的只有 `config.busJoin`,所以一份没钉档的 JSON 交给本 skill 就走 `--bus-join`(不给则 `split`),出图与 App 编辑区的默认档一致。
- **只改衔接形状**:框底淡彩、跟随通道色的描边、字号都不动。斜切量**定死 4 CSS px**(= 1× 档一格 40px 的 10%),**不随 `hscale` 放大**——渲染器里只有格宽跟着 hscale 变,斜切要是也等比放大,4× 档每边就得吃掉 16px,长标签白省略。现在斜切整段落在后一块的开头,本格文字带几乎不受影响:实测 1× / 2× / 4× 三档下,`joined` 与 `split` 能完整放下的一格标签最长字符数**完全相同**(2× 都是 10、4× 都是 21),也就是 `joined` 不再多省略任何一个字符;`split` 档的输出与改动前逐字节相同。斜切路径的 `d` 串与编辑区逐条比对一致(24/24)。
- **传统模式不受影响**:官方引擎本来就画斜切相连,`--bus-join` 对 `--mode traditional` 没有意义,`config.busJoin` 这个键官方也不认(按键不存在处理,不报错)。

## 支持的 WaveJSON 语法

`signal`(含嵌套分组数组、`{}` 空白占位)、`wave`(全部状态字符 `01pnPNudxzhlHL=23456789|.` 与 `.` 延续、`<>` 子周期)、`data`、`node` + `edge`(覆盖全部官方箭头写法)、`head`/`foot`(`text`/`tick`/`tock`/`every`)、`config`(`hscale`/`skin`/`hbounds`/`busJoin`)、`period`/`phase`、**`color`**(通道自定义色,wavedrom-gui 写进信号对象的键)。

**`color` 的写法与边界**:只认 `#rgb` / `#rrggbb`(大小写均可),写法不对的(如 `color:"red"`)不猜、按没写处理,回落到调色板轮转——与 App 的判定逐字一致,所以同一份 JSON 两边取到的色一定相同。它管到**现代模式**的整条自绘产物:轨迹与电平线、名称列圆点、数据框描边(`=` 与 `2`–`9` 都用通道色;通道色压在该框自己的淡彩填充上不足 2.5:1 时只往暗压明度、色相不变),数据框**填充**仍是官方逐框淡彩、不跟着变。**传统模式不认这个键**(官方 WaveDrom 没有按通道换色的概念,交给它的图一律回到皮肤色),现代模式也固定浅色画布:App 里的深色主题与「自定义波形底色」不参与,两边都按浅色出图。

**`head`/`foot` 的 `text` 支持官方 JsonML 富文本**:`["tspan", {"class":"h2"}, "标题"]` 这类写法,class 取 `error`/`warning`/`info`/`success`/`muted`/`h1`–`h6`,另支持 `dy`、`baseline-shift`、`font-size`/`font-weight`/`font-style`/`fill` 等内联属性。注意多段富文本要**逐段嵌套**(`["tspan", {}, "前半", ["tspan", {"class":"muted"}, "后半"]]`)——把属性对象直接放在子节点位置(`["tspan", {...}, "a", {...}, "b"]`)不是合法 JsonML,官方引擎会直接报错。现代模式按现代配色映射这些 class(error 红 / warning 橙 / info 蓝 / success 绿 / muted 灰,h1–h6 逐级放大),`baseline-shift` 会转成显式 `y` 位移,任何光栅化器都一致;传统模式交由官方引擎,上下标是否显示取决于光栅化器对 `baseline-shift` 的支持。

## 字体与字号(可配置)

现代模式的字体栈与各处字号都在 **`fonts.config.json` 的 `appearance` 区**(与字体下载/内嵌配置同一个文件)。**想改就改这个 JSON,无需碰任何代码**:

```jsonc
"appearance": {
  "fontFamily": {
    "mono": "\"LXGW WenKai Mono\",\"Cascadia Code\",Consolas,...,monospace",
    "ui":   "\"LXGW WenKai Mono\",\"PingFang SC\",...,sans-serif"
  },
  "size": {
    "dataLabel": 14, "signalName": 16, "groupName": 16, "title": 16,
    "tick": 12, "spacer": 11.5, "ppBadge": 11, "node": 10, "edgeLabel": 11
  }
}
```

| 键 | 作用 | 默认字号 | 字体栈 |
|---|---|---|---|
| `fontFamily.mono` | 等宽字体栈 | — | 首选霞鹜文楷等宽 |
| `fontFamily.ui` | UI 字体栈 | — | 首选霞鹜文楷等宽 |
| `size.dataLabel` | 数据框标签(0x18 / D0…) | **14** | mono |
| `size.signalName` | 信号名(clk / req…) | **16** | mono |
| `size.groupName` | 分组名(▸ ctrl) | **16** | ui |
| `size.title` | 标题 + head/foot 文字 | **16** | ui |
| `size.tick` | 时间轴刻度 / foot 刻度数字 | 12 | mono |
| `size.spacer` | 「空白占位」行 | 11.5 | ui |
| `size.ppBadge` | period/phase 徽标(×2 φ0.5) | 11 | mono |
| `size.node` | 节点圆标字母(再乘 `--node-scale`) | 10 | mono |
| `size.edgeLabel` | 边(箭头)标注 | 11 | mono |

说明:

- 改 `fonts.config.json` 后直接重跑渲染即可生效;配置缺失 / 某项没写 / 文件损坏时,自动回退到内置默认值,渲染不会中断。
- 字号单位为 SVG 用户单位(≈1× 时的 px);PNG 里最终像素 = 字号 × `--scale`(默认 2×);字号不随 `hscale` 变化(`hscale` 只放大横向格宽)。
- 名称列宽度、pp 徽标位置、数据标签换行判定都会随 `signalName`/`dataLabel` 自动缩放,改大字号不会截断。
- 分组行前的折叠三角(▸)是**画出来的 SVG 路径**,不依赖字体,任何渲染器都不会字形错乱。
- **字体内嵌(自包含 SVG)**:若装了 Python `fontTools`(`pip install fonttools`),渲染会把 `fonts.config.json` 中 `fonts` 列表里每个已就位的 TTF **按用到的字符子集化**后内嵌进 SVG —— SVG 自包含(任何机器打开都是同一字体外观),体积仅几百 KB。`fonts` 列表**不限字体**:默认是 `node setup.js` 下载的霞鹜文楷,换用/新增字体只需在 `fonts` 里加一条(`family` + `file`,可选 `github`/`ghproxy` 下载 URL 供 setup.js 下载)并把 TTF 放入 `dir`,同时把 `appearance.fontFamily` 首项改为该 `family`。**内嵌恒为子集化**:没装 fontTools 或子集化失败时**自动不内嵌**(回退字体名),绝不内嵌整份 TTF、不会产生几十 MB 的巨型 SVG。开关在 `fonts.config.json`(`enabled` / `embed` / `mirror` / `dir`)。
- 不内嵌时:SVG 只写字体名,**最终字形由渲染器(浏览器 / cairosvg)能否找到该字体决定**。字体栈末尾附带各平台常见中文字体(Windows 的 Microsoft YaHei、macOS 的 PingFang/Hiragino、Linux 的 Noto/文泉驿),中文一般都能正确回退;若本地已 `setup.js` 下载过霞鹜文楷,cairosvg 生成 PNG 时通常也能直接用上。要固定某字体,改 `appearance.fontFamily.mono` / `appearance.fontFamily.ui` 首项为本机已装字体即可。
- ⚠️ 已知:cairosvg 会静默丢弃**带 `stroke` 的 `<text>`**,故本渲染器所有文字均为纯 `fill`,需要衬底时用背景矩形而非描边光晕。

## 目录结构

```
wavedrom-render/
  render.js                 # 统一 CLI 入口
  setup.js                  # 一次性初始化:下载霞鹜文楷字体到 vendor/fonts/
  fonts.config.json         # 字体配置(可改:enabled / embed / mirror / dir / 下载 URL)
  lib/
    render-modern.js        # 现代模式渲染器(自绘 SVG,移植自 laneSVG + 网格布局)
    render-traditional.js   # 传统模式渲染器(驱动官方引擎,无需浏览器)
    svg-to-png.js           # SVG→PNG(cairosvg / rsvg-convert / ImageMagick 自动探测)
    font-embed.js           # 把子集化后的霞鹜文楷以 @font-face base64 内嵌进 SVG
    meta-embed.js           # SVG <metadata> / PNG iTXt 的 WaveJSON 元数据与导出来源标记(内嵌与回读)
  scripts/
    svg2png.py              # cairosvg 光栅化辅助脚本
    subset_font.py          # fontTools 字体子集化辅助脚本
  vendor/
    wavedrom.bundle.js      # 官方 WaveDrom v3.5.0 引擎(自 index.html 提取 + 两处补丁暴露 renderAny/stringify)
    waveskin.js             # 官方皮肤 default + narrow(自 index.html 提取)
    fonts/                  # setup.js 下载的霞鹜文楷 TTF(不随仓库提交)
```

## 实现说明

- 传统模式在 Node 里**无浏览器**运行:官方 browserify 包只在加载时触碰 `window`,用极小的全局垫片即可;渲染走 `renderAny()`(返回 JsonML 树)→ `onml.stringify()`(转 SVG 字符串),产出的 SVG 已内联皮肤 `<defs>`,自包含可独立打开。
- 现代模式不依赖官方引擎,纯字符串拼 SVG;`laneSVG` 的所有笔画几何(成对状态转换、半拍标记、时钟半砖融合、`x` 交叉阴影、数据框、`.`/`|` 重复器、`u/d/z` 曲线、节点与边)都按 `index.html` 语义复刻。
- 现代模式配色固定浅色主题(与 App 的 SVG/PNG 导出一致)。
Pliki w paczce (14)
  • .gitignore 1 KB
  • SKILL.md 23 KB
  • fonts.config.json 3 KB
  • render.js 12 KB
  • setup.js 5 KB
  • lib/font-embed.js 4 KB
  • lib/meta-embed.js 5 KB
  • lib/render-modern.js 61 KB
  • lib/render-traditional.js 3 KB
  • lib/svg-to-png.js 4 KB
  • scripts/subset_font.py 1 KB
  • scripts/svg2png.py 2 KB
  • vendor/wavedrom.bundle.js 53 KB
  • vendor/waveskin.js 84 KB

Wersje

W bazie nie ma innych skilli o nazwie wavedrom-render.

Migawka bazy z 13.11.2026 · wersja paczki f9f200caa989 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100wavedrom
    Pisze poprawne źródło diagramów WaveDrom dla uml-mcp, czyli przebiegów cyfrowych i diagramów czasowych.
  • 95image
    Renderuje specyfikacje JSON do obrazów SVG i PNG przez Satori w json-render, na przykład obrazy OG i karty społecznościowe z @json-render/image.
  • 100architecture-diagram
    Tworzy ciemne diagramy architektury jako samodzielne pliki HTML z SVG, stylami CSS i paskiem eksportu do PNG i PDF, dla topologii systemowych, chmurowych i sieciowych do udostępnienia.
  • 100run-pele
    Pisze, sprawdza i renderuje diagramy Mermaid do SVG lub HTML przez Pele, także bez przeglądarki, z obsługą motywów i wąskich ekranów.
  • 100beautiful-mermaid
    Renderuje diagramy Mermaid do plików SVG i PNG za pomocą biblioteki Beautiful Mermaid.
  • 100svg-to-raster
    Rasteryzuje pliki SVG do PNG, PDF lub PostScriptu w wybranej rozdzielczości, pojedynczo albo w serii, przy użyciu CairoSVG.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.