WireViz 官方教程精讲:从零开始用 YAML 绘制线束接线图与物料清单
WireViz 官方教程精讲:从零开始用 YAML 绘制线束接线图与物料清单
导读
本文是 WireViz 官方教程(tutorial/readme.md)的完整精讲。WireViz 是一个通过 YAML 描述文件自动生成接线图(Graphviz SVG/PNG)、HTML 预览与 BOM(物料清单,TSV)的开源工具。教程由 8 个递进式示例构成,从最小可用接线图开始,逐步覆盖参数与颜色、引脚定义(pinout)、屏蔽、模板复用、线束(bundle)、端子(ferrule)、菊花链(daisy chain)以及零件号与附加物料。读完本文,你将掌握 WireViz 全部核心语法,并能独立写出可生成专业线束图纸与 BOM 的 YAML 文件。
每个示例的源码 YAML、生成的图(PNG/SVG)与 BOM(TSV)都保存在仓库的 tutorial/ 目录下,示例 tutorialNN.yml、tutorialNN.bom.tsv 与本文代码块一一对应,可随时对照验证。
01 - 最小可用示例(Bare-bones)
目标与要点
- 最小可用示例(Minimum working example);
- 仅使用 1 对 1 的顺序接线(1-to-1 sequential wiring)。
完整代码
connectors:
X1:
pincount: 4
X2:
pincount: 4
cables:
W1:
wirecount: 4
length: 1
connections:
-
- X1: [1-4]
- W1: [1-4]
- X2: [1-4]
逐段解读
connectors:定义所有用到的连接器。X1、X2各有一个pincount: 4,表示 4 引脚。WireViz 会自动为引脚编号为 1、2、3、4(详见 docs/syntax.md 中pins的说明:"if omitted, is autofilled with [1, 2, ..., pincount]")。cables:定义电缆。W1有 4 根导线(wirecount: 4),长度 1(单位默认为米,length的数值默认以米为单位,详见 docs/syntax.md)。connections:定义接线。每一条-是一个"连接组(connection set)",组内元素必须在connectors与cables之间交替出现。本示例将X1的引脚 1-4 依次接到W1的导线 1-4,再接到X2的引脚 1-4。
注意 [1-4] 这种写法:<int>-<int> 会自动展开为范围,例如 1-4 展开为 1,2,3,4;反向写 9-7 也会展开为 9,8,7(见 docs/syntax.md 的 "Multiple parallel connections" 一节)。
输出

生成的 BOM
运行后生成的 tutorial01.bom.tsv 内容如下:
Id Description Qty Unit Designators
1 Cable, 4 wires 1 m W1
2 Connector, 4 pins 2 X1, X2
可以看到:电缆按 1 米计(Unit 为 m),两个同规格连接器合并为一行(Designators 列为 X1, X2)。
02 - 添加参数与颜色(Parameters and colors)
新增能力
- 为连接器和电缆添加参数;
- 从 mm² 自动换算等效 AWG 线规;
- 非顺序接线(non-sequential wiring)。
完整代码
connectors:
X1:
pincount: 4
# More connector parameters:
type: Molex KK 254
subtype: female
X2:
pincount: 4
type: Molex KK 254
subtype: female
cables:
W1:
wirecount: 4
# more cable parameters:
length: 1
gauge: 0.25 mm2
show_equiv: true # auto-calculate AWG equivalent
colors: [WH, BN, GN, YE]
connections:
-
- X1: [1-4]
- W1: [1-4]
# non-sequential wiring:
- X2: [1,2,4,3]
解读
type/subtype:连接器的型号与子型号(如 Molex KK 254 母头),会显示在图中并进入 BOM 描述。gauge: 0.25 mm2:线规。WireViz 支持的格式(见 docs/syntax.md):<int/float> mm2按平方毫米理解;<int> AWG按 AWG 理解;裸数字默认按 mm²;字符串则使用自定义单位且不参与自动换算。show_equiv: true:显示等效线规。默认值为false;设为true后,WireViz 会在 mm² 与 AWG 之间自动换算并在图中展示结果。colors: [WH, BN, GN, YE]:为 4 根导线分别指定颜色(白、棕、绿、黄)。颜色使用两个大写字母的短代码,完整颜色表见 docs/syntax.md 与 src/wireviz/wv_colors.py(如BK黑、RD红、OG橙、YE黄、GN绿、BU蓝、VT紫、BN棕等)。多色(条纹)导线可直接拼接短码,如GNYE表示绿黄。- 非顺序接线:
X2: [1,2,4,3]让 X2 的第 4、3 引脚与 X1 的第 3、4 引脚交叉连接,图中会如实画出交叉关系。
输出

03 - 引脚定义、屏蔽与模板(Pinouts, shielding, templates, I)
新增能力
- 连接器引脚定义(pinout):
pinlabels隐式决定引脚数(pincount implicit in pinout); - 电缆颜色编码(color code);
- 电缆屏蔽与屏蔽层接线;
- 模板(YAML anchor / alias 复用)。
完整代码
connectors:
X1: &template1 # define a template for later use
pinlabels: [GND, VCC, RX, TX] # pincount implicit in pinout
type: Molex KK 254
subtype: female
X2:
<<: *template1 # reuse template
cables:
W1:
wirecount: 4
length: 1
gauge: 0.25 mm2
show_equiv: true
color_code: DIN # auto-assign colors based on DIN 47100
shield: true # add cable shielding
connections:
-
- X1: [1-4]
- W1: [1-4]
- X2: [1,2,4,3]
- # connect the shielding to a pin
- X1: 1
- W1: s
解读
- 模板(Template):
X1: &template1定义 YAML 锚点(anchor),X2: <<: *template1通过 YAML 合并键(merge key)继承全部属性。这样同规格连接器只需定义一次。若需覆盖个别参数,只需在继承后重新赋值(见示例 04)。 - 引脚定义:
pinlabels: [GND, VCC, RX, TX]有 4 个标签,引脚数自动取列表长度(pincount隐式)。此后既可用引脚号(1),也可用唯一标签(如RX)来引用引脚。 - 颜色编码:
color_code: DIN根据 DIN 47100 标准自动为 4 根导线分配颜色。WireViz 内置的颜色编码定义在 src/wireviz/wv_colors.py 的COLOR_CODES中,支持DIN(DIN 47100)、IEC(IEC 60757)、TEL/TELALT(25 对颜色码)、T568A/T568B(以太网线序)与BW(黑白交替),详见 docs/syntax.md 的 "Cable color codes" 一节。 - 屏蔽(Shield):
shield: true为电缆添加屏蔽层,图中以细黑线表示;也支持用颜色值(如shield: BN)渲染屏蔽层颜色。屏蔽层在接线时以特殊导线 IDs引用:本例第二条连接组把X1的引脚 1 接到W1的屏蔽层s。
输出

04 - 模板进阶、注释、美式标准与线性菊花链(Templates II, notes, American standards, daisy chaining I)
新增能力
- 覆盖模板参数(overriding template parameters);
- 为连接器和电缆添加注释节点(notes);
- 美式标准:直接使用 AWG 线规与 IEC 颜色编码;
- 线性菊花链(linear daisy chain):适合较短的链式连接。
完整代码
connectors:
X1: &template_con
pinlabels: [GND, VCC, SCL, SDA]
type: Molex KK 254
subtype: male
notes: to microcontroller # add notes
X2:
<<: *template_con # use template
subtype: female # but override certain parameters
notes: to accelerometer
X3:
<<: *template_con
subtype: female
notes: to temperature sensor
cables:
W1: &template_cbl
wirecount: 4
length: 0.3
gauge: 24 AWG # specify gauge in AWG directly
color_code: IEC # IEC 62 colors also supported
notes: This cable is a bit longer
W2:
<<: *template_cbl
length: 0.1
notes: This cable is a bit shorter
connections:
-
- X1: [1-4]
- W1: [1-4]
- X2: [1-4]
- # daisy chain connectors (in line)
- X2: [1-4]
- W2: [1-4]
- X3: [1-4]
解读
- 覆盖模板参数:
X2、X3继承X1的模板后将subtype改为female,notes改为各自的去向(accelerometer / temperature sensor)。W2继承电缆模板后缩短长度并改写注释。这正是模板的典型用法:共享共性、覆盖差异。 - 注释(notes):连接器与电缆都支持
notes字段,显示在对应节点框中(见 docs/syntax.md 的 Connector/Cable attributes)。notes还支持多行字符串(|块或"\n"转义,见 docs/syntax.md 的 "Multiline strings" 一节)。 - AWG 直接指定:
gauge: 24 AWG表示直接在 AWG 体系下指定线规,无需 mm² 换算。WireViz 同时支持美制 AWG 与公制 mm² 两种表述。 - IEC 颜色编码:
color_code: IEC按 IEC 60757 标准分配颜色("ROY G BIV":棕、红、橙、黄、绿、蓝、紫、灰、白、黑,见 src/wireviz/wv_colors.py 的COLOR_CODES["IEC"])。 - 线性菊花链:第二个连接组
X2 -> W2 -> X3把三个器件串联成一条直线链。连接组内元素不限数量("The maximum number of items is unlimited",见 docs/syntax.md),因此一条链可串联任意多个器件。这种写法对短链最直观。
输出

05 - 端子(Ferrule)、线束(Bundle)与自定义导线颜色
新增能力
- 端子(ferrule):
- 比连接器更简单;
- 图形表示紧凑;
- 只有一个引脚、只能有一根连接、没有编号(designator)的自动生成端子;
- 定义一次,按需自动生成多个实例。
- 线束(wire bundle):
- 内部按电缆处理;
- BOM 中每条导线单独列出(different treatment in BOM: each wire is listed individually);
- 图中以虚线轮廓(dashed outline)表示。
- 自定义导线颜色:导线数可隐含在颜色列表长度中(wirecount implicit in color list)。
完整代码
connectors:
X1:
pinlabels: [+12V, GND, GND, +5V]
type: Molex 8981
subtype: female
F1:
style: simple
type: Crimp ferrule
subtype: 0.5 mm²
color: OG # optional color
cables:
W1:
category: bundle # bundle
length: 0.3
gauge: 0.5 mm2
colors: [YE, BK, BK, RD] # custom colors, wirecount is implicit
connections:
-
- F1. # a new ferrule is auto-generated for each of the four wires
- W1: [1-4]
- X1: [1-4]
解读
- 端子:
F1使用style: simple(单引脚连接的紧凑样式,见 docs/syntax.md 的style: <style>,simple 样式默认不显示名称与引脚数)。type: Crimp ferrule表示压接端子,color: OG为端子着色(可选)。 - 自动生成(autogeneration):连接组中写
F1.——设计符后跟.触发自动生成(template_separator默认字符,见 docs/syntax.md 的 "Autogeneration of items" 一节)。本例连接组有 4 条并联连接(W1: [1-4]与X1: [1-4]),因此 WireViz 为每条连接自动生成一个同规格端子实例,无需手工命名。 - 线束(bundle):
category: bundle把W1声明为线束。语法上它与电缆相同("Internally treated as cables"),区别在于:- BOM 中每条导线单独成行(下例 BOM 可验证),而非整根电缆一行;
- 图中以虚线轮廓渲染(对应 src/wireviz/Harness.py 中的
("filled,dashed", self.options.bgcolor_bundle)渲染逻辑,且cable.category == "bundle"分支生效)。
- 导线数隐式确定:
colors: [YE, BK, BK, RD]有 4 个颜色,wirecount自动取 4,无需再写wirecount。WireViz 对颜色与导线数的组合规则见 docs/syntax.md:"colors only: wirecount is inferred from list length"。 - 重复标签:
pinlabels: [+12V, GND, GND, +5V]中GND出现两次,WireViz 允许标签重复(引用引脚时需用引脚号,因为重复标签不唯一,见 docs/syntax.md 的<pin>引用规则)。
输出

06 - 自定义端子(Custom ferrules)
新增能力
- 自定义端子(custom ferrule):
- 允许一个端子接入多根导线(attaching more than one wire to a ferrule);
- 需将其定义为带唯一编号的普通连接器,并添加
category: ferrule参数。
完整代码
connectors:
X1:
pinlabels: [+12V, GND, GND, +5V]
type: Molex 8981
subtype: female
F_10: # this is a unique ferrule
style: simple
type: Crimp ferrule
subtype: 1.0 mm²
color: YE # optional color
F_05: # this is a ferrule that will be auto-generated on demand
style: simple
type: Crimp ferrule
subtype: 0.5 mm²
color: OG
cables:
W1:
category: bundle # bundle
length: 0.3
gauge: 0.5 mm2
colors: [YE, BK, BK, RD] # custom colors, wirecount is implicit
connections:
-
- [F_05., F_10.F1, F_10.F1, F_05.]
- W1: [1-4]
- X1: [1-4]
解读
- 示例 05 的端子只有一个引脚,只能接一根导线;当需要把多根导线并到一个端子(例如同规格的
BK、BK两根线合并压接)时,就要用自定义端子。 F_10是带唯一编号F1的自定义端子(内部标注F_10.F1,即"模板F_10生成实例F1"),F_05则保留为按需自动生成的模板(写F_05.触发)。- 连接组第一项是一个列表
[F_05., F_10.F1, F_10.F1, F_05.]:第 2、3 条连接都指向同一个命名实例F_10.F1,从而让两根BK导线共用一个 1.0 mm² 端子;第 1、4 条连接各自自动生成一个 0.5 mm² 端子F_05.。这对应 docs/syntax.md 中"specify multiple simple connectors to attach in parallel"与"these may be unique, auto-generated, or a mix of both"的语法。 - 实现层面,端子/线束的
category由 src/wireviz/Harness.py 处理:对bundle,逐线生成 BOM 项(if cable.category == "bundle":分支),而ferrule类别在语法上同样通过category参数声明。
输出

07 - 菊花链进阶(Daisy chaining II):之字形链
新增能力
- 之字形菊花链(zig-zag daisy chain):
- 适合更长的链(convenient for longer chains)。
完整代码
connectors:
X1: &template_con
type: Molex KK 254
subtype: female
pinlabels: [GND, VCC, SCL, SDA]
X2:
<<: *template_con
X3:
<<: *template_con
X4:
<<: *template_con
X5:
<<: *template_con
X6:
<<: *template_con
cables:
W1: &template_wire
gauge: 0.25 mm2
length: 0.2
colors: [TQ, PK, YE, VT]
category: bundle
W2:
<<: *template_wire
W3:
<<: *template_wire
W4:
<<: *template_wire
W5:
<<: *template_wire
connections:
-
- X1: [1-4]
- W1: [1-4]
- X2: [1-4]
-
- X3: [1-4]
- W2: [1-4]
- X2: [1-4]
-
- X3: [1-4]
- W3: [1-4]
- X4: [1-4]
-
- X5: [1-4]
- W4: [1-4]
- X4: [1-4]
-
- X5: [1-4]
- W5: [1-4]
- X6: [1-4]
解读
- 当链很长时,线性连接组会变得又长又乱;之字形(zig-zag)写法把每段连接拆成独立的连接组,如
X1-W1-X2、X3-W2-X2、X3-W3-X4、X5-W4-X4、X5-W5-X6,相邻连接组共享中间器件(X2、X3、X4、X5都出现在两个连接组中)。 - 这种写法让长链在图中呈折叠的"之"字形排布,可读性更好,也便于增删中间节点。
- 模板在此发挥最大价值:6 个连接器共享一个模板,5 根线束共享一个模板,整张图只需定义两次共性参数。注意线束模板中省略了
wirecount与length之外的重复项,颜色列表[TQ, PK, YE, VT]隐式给出 4 根导线。
输出

08 - 零件号与附加物料(Part numbers and additional components)
新增能力
- 为零件添加零件号信息(part number information):
- 只有填写的字段才会进入图纸与 BOM(only provided fields will be added to the diagram and BOM);
- 线束可逐线指定零件信息(bundles can have part information specified by wire);
- 可向器件追加附加组件,或直接追加到 BOM(additional parts can be added to components or just to the BOM);
- 附加组件的数量可按父连接器/电缆的特征成倍计算(quantities can be multiplied by features from parent connector or cable)。
完整代码
options:
mini_bom_mode: false
connectors:
X1: &template1 # define a template for later use
type: Molex KK 254
pincount: 4
subtype: female
manufacturer: '<a href="https://www.molex.com/">Molex</a>' # set manufacter name
mpn: '<a href="https://www.molex.com/molex/products/part-detail/crimp_housings/0022013047">22013047</a>' # set manufacturer part number
supplier: Digimouse
spn: 1234
# add a list of additional components to a part (shown in graph)
additional_components:
- type: Crimp # short identifier used in graph
subtype: Molex KK 254, 22-30 AWG # extra information added to type in bom
qty_multiplier: populated # multipier for quantity (number of populated pins)
manufacturer: Molex # set manufacter name
mpn: 08500030 # set manufacturer part number
- type: Test
qty: 1
pn: ABC
manufacturer: Molex
mpn: 45454
supplier: Mousikey
spn: 9999
X2:
<<: *template1 # reuse template
pn: CON4 # set an internal part number for just this connector
X3:
<<: *template1 # reuse template
cables:
W1:
wirecount: 4
length: 1
gauge: 0.25 mm2
color_code: IEC
manufacturer: CablesCo
mpn: ABC123
supplier: Cables R Us
spn: 999-888-777
pn: CAB1
W2:
category: bundle
length: 1
gauge: 0.25 mm2
colors: [YE, BK, BK, RD]
manufacturer: [WiresCo, WiresCo, WiresCo, WiresCo] # set a manufacter per wire
mpn: [W1-YE, W1-BK, W1-BK, W1-RD]
supplier: [WireShack, WireShack, WireShack, WireShack]
spn: [1001, 1002, 1002, 1009]
pn: [WIRE1, WIRE2, WIRE2, WIRE3]
# add a list of additional components to a part (shown in graph)
additional_components:
- type: Sleve # short identifier used in graph
subtype: Braided nylon, black, 3mm # extra information added to type in bom
qty_multiplier: length # multipier for quantity (length of cable)
unit: m
pn: SLV-1
connections:
- - X1: [1-4]
- W1: [1-4]
- X2: [1-4]
- - X1: [1-4]
- W2: [1-4]
- X3: [1-4]
additional_bom_items:
- # define an additional item to add to the bill of materials (does not appear in graph)
description: Label, pinout information
qty: 2
designators:
- X2
- X3
manufacturer: '<a href="https://www.bradyid.com">Brady</a>'
mpn: '<a href="https://www.bradyid.com/wire-cable-labels/bmp71-bmp61-m611-tls-2200-nylon-cloth-wire-general-id-labels-cps-2958789">B-499</a>'
pn: Label-ID-1
解读
- 零件信息字段:连接器与电缆都支持
pn(内部零件号)、manufacturer(制造商)、mpn(制造商零件号)、supplier(供应商)、spn(供应商零件号)。这些字段全部可选,只有填写的字段才会出现在图与 BOM 中。字段值支持 HTML 链接,例如把mpn包成<a href="...">即可生成可点击的零件号(HTML 输出中生效)。 options: mini_bom_mode: false:全局选项。默认值为true,此时图中只显示附加组件的 BOM 条目引用与基本信息;设为false后,图中完整显示附加组件信息(见 docs/syntax.md 的 "Options" 一节)。示例通过该选项展示附加组件在图纸节点内的完整呈现。- 附加组件(additional_components):挂在连接器/电缆下,会显示在图中,同时进入 BOM。
type是图中的短标识,subtype是 BOM 中追加到 type 的补充信息。 - 数量倍增器(qty_multiplier):按父器件的特征自动计算数量。可选值(见 docs/syntax.md):
- 用于连接器:
pincount(引脚数)、populated(已插装引脚数)、unpopulated(未插装引脚数); - 用于电缆/线束:
wirecount(导线数)、terminations(端接数)、length(电缆长度)、total_length(线束各导线长度之和)。 - 本例中
Crimp的qty_multiplier: populated使端子数量等于已插装引脚数(3 个连接器共 12 个),Sleve的qty_multiplier: length使护套数量等于电缆长度(1 m)。
- 用于连接器:
- 线束逐线零件信息:
W2是 bundle,其manufacturer、mpn、supplier、spn、pn均以列表形式逐线指定(列表长度与导线数一致)。对应 src/wireviz/Harness.py 中的注释 "for bundles, individual wires can have part information" 及if cable.category == "bundle":的分支处理。 - 直接加 BOM 的条目(additional_bom_items):只进 BOM、不进图。支持
description、qty、unit、designators(设计符列表)以及 pn/manufacturer/mpn/supplier/spn 等字段(见 docs/syntax.md 的 "BOM items" 一节)。
生成的 BOM
tutorial08.bom.tsv 展示了本示例的完整输出:
Id Description Qty Unit Designators P/N Manufacturer MPN Supplier SPN
1 Cable, 4 x 0.25 mm² 1 m W1 CAB1 CablesCo ABC123 Cables R Us 999-888-777
2 Connector, Molex KK 254, female, 4 pins 2 X1, X3 Molex 22013047 Digimouse 1234
3 Connector, Molex KK 254, female, 4 pins 1 X2 CON4 Molex 22013047 Digimouse 1234
4 Crimp, Molex KK 254, 22-30 AWG 12 X1, X2, X3 Molex 08500030
5 Label, pinout information 2 X2, X3 Label-ID-1 Brady B-499
6 Sleve, Braided nylon, black, 3mm 1 m W2 SLV-1
7 Test 3 X1, X2, X3 ABC Molex 45454 Mousikey 9999
8 Wire, 0.25 mm², BK 2 m W2 WIRE2 WiresCo W1-BK WireShack 1002
9 Wire, 0.25 mm², RD 1 m W2 WIRE3 WiresCo W1-RD WireShack 1009
10 Wire, 0.25 mm², YE 1 m W2 WIRE1 WiresCo W1-YE WireShack 1001
对照解读:
X2因为单独设置了pn: CON4而与X1、X3分成两行(Designators 分别为X1, X3与X2);Crimp数量 12 = 3 个连接器 × 4 个已插装引脚(qty_multiplier: populated);Sleve数量 1、单位 m,等于W2长度(qty_multiplier: length);- 线束
W2的每条导线单独成行(Wire, 0.25 mm², BK等),各自的 MPN/供应商零件号/内部零件号逐行列出; Label, pinout information来自additional_bom_items,只出现在 BOM 中。
运行方法:从 YAML 到图纸与 BOM
教程各示例都配有对应的 .gv、.svg、.png、.html 与 .bom.tsv 产物。要亲自生成这些输出,可使用 WireViz 命令行工具(入口为 src/wireviz/wv_cli.py):
python -m wireviz tutorial01.yml
默认输出格式为 hpst,即同时生成 HTML(h)、PNG(p)、SVG(s)与 TSV BOM(t)。-f/--format 支持以下格式码(详见 wv_cli.py 中的 format_codes):
| 格式码 | 输出 | 说明 |
|---|---|---|
g |
GV | Graphviz 点脚本(中间产物) |
h |
HTML | 带内嵌图的 HTML 预览 |
p |
PNG | 位图图片 |
s |
SVG | 矢量图片 |
t |
TSV | 物料清单(BOM) |
常用选项还包括 -o/--output-dir(指定输出目录)、-O/--output-name(指定输出文件名)、-p/--prepend(预置 YAML,可叠加多个,适合共享公共定义)与 -V/--version(打印版本)。
延伸阅读
- WireViz 语法参考:连接器/电缆/连接组/选项/颜色/附加组件的完整参数表;
- WireViz 综合示例:
demo*.yml与ex*.yml展示了更多真实场景(如 demo02.yml 演示 YAML 锚点继承,见 docs/syntax.md 的 "Inheritance" 一节); - HTML 输出模板:了解
metadata如何注入 HTML 模板; - 图片使用进阶:连接器/电缆节点内嵌图片的精细控制。