Unicode 图表
使用Unicode框线字符以纯文本形式绘制图表,风格统一。
务必使用下面的 textdiagram.py 网格引擎构建图表。请勿手工绘制:手工绘制的图表会逐渐错位。
风格规则
- 纯文本,放在围栏代码块中。禁止使用 Mermaid、SVG、图片或表情符号。
- 宽度:默认为 80 列。若要更改,向构造函数传递
max_width,例如D(max_width=100)。引擎在遇到更长的行时会报错。 - 所有文本均为大写。 引擎会自动处理:在脚本中按正常文本书写即可。
例外:含义随大小写变化的单位,当你严格按照如下格式书写时,其大小写保持不变:
Hz kHz MHz GHz、kB MB GB TB KiB MiB GiB TiB、kb Mb Gb Tb kbps Mbps Gbps、ms µs ns。其他单词(如 NGINX 或 K8S)均为大写。 - 组件框(系统的一部分:服务、客户端、数据库、队列、工作者):
细线
┌─┐ │ └─┘加上一个细░阴影,位于右侧一列和下方一行。 为了对部件进行分组,将一个框拆分为多个部分:细分隔线├───┤,一个边框,一个阴影。 - 标题框(文档的主标题,每个图表一个):双线
╔═╗ ║ ╚═╝,无阴影。 每行一项(名称、文档类型、版本),每行在框内居中。使用d.header(...)创建:引擎会将框在整个图表上居中。可选:左侧的元框(公司、RFC、日期)和右侧的印章框(状态)。三者高度相同;标题框的填充行包含一个居中点·。 箭头不能始于或止于标题框。 - 框架框(节标题、注释、标注):细线,无阴影。
注释/标注:将名称放在顶部边框,如
┌─ 注释 ───┐。 请勿添加图例:每个图表的风格都相同。 - 自由文本(
d.annotate):图表旁边的简短说明,无框。请谨慎使用。线条不得穿过它。 - 水平箭头:标签在线条内部,两侧各一个空格:
── HTTPS ──▶。 两端均接触框:线条始于发送框的阴影列,箭头头部接触接收框。 - 垂直箭头:线条从底部边框的
┬开始,以▼结束。标签放在线条右侧,位于阴影下方一行。或者将标签切入线条内部(inline=True):线条、空白行、标签行在线条上居中、空白行、线条。 - 弯曲箭头(
d.route):任意数量的弯曲,任意方向(▲ ▼ ◀ ▶)。标签放在一个水平段内部,或者放在垂直段的旁边(或者,使用inline=True,切入垂直段)。交叉或汇合的线条形成连接点(┼ ├ ┤ ┬ ┴)。线条永远不会穿过框。 - 总线(
d.fan_out):从一个框出发的一条线,分散为指向每个目标的箭头。标签放在共享线上。 - 箭头头部:实心
▶ ◀ ▲ ▼用于主流。空心▷ ◁ △ ▽用于第二种关系(异步、可选、事件)。仅当图表需要两种类型时才使用空心,并在标签或注释中说明其含义,不要在单独的图例中说明。 - 为每个箭头标记流经的内容(协议、事件、数据)。
- 如果不清楚某个框的角色:系统部件用组件框,主标题用标题框,其他所有用框架框。
工作流程
- 在绘制之前,先列出组件、框架和箭头。
- 将引擎写入
/tmp/textdiagram/textdiagram.py(完整源代码位于本文档末尾,请精确复制)。每次会话都重新写入,以确保不使用旧版本。 - 编写一个简短的 Python 脚本,导入引擎并构建图表。使用布局辅助函数来放置框(不要猜测坐标):
Diagram.x_right_of(a, label)— 下一个框在a右侧的 x 坐标,为箭头标签留出空间。Diagram.x_left_of(a, lines, label)— 新框在a左侧的 x 坐标,为标签留出空间。Diagram.y_below(a)—a下方一个框的 y 坐标。带内联标签时:Diagram.y_below(a, lines=N)。Diagram.x_centered_under(a, lines)— 使框在a下方居中的 x 坐标(arrow_v需要)。- 对于路由通道,使用框的边缘:
a.right + 4、a.bottom + 2。
- 运行脚本。如果引发
DiagramError,请按照消息中的说明修复布局并重新运行。 - 将输出完全按照打印结果粘贴到代码块中。请勿手动编辑。如需更改,请编辑脚本并重新运行。
示例 1:标题、节、路由
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D() # max_width=80 是默认值
t = d.header(["Order Platform", "Architecture"],
left=["Acme Inc", "RFC 9000", "Nov 2026"],
right=["*~~~~~~~~~*", "Deep Dive", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Client"]) # role="component" 是默认值
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Gateway"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2, # 节:一个框,一个阴影
[["Auth"], ["Orders"], ["Billing"]], title="Services")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Calls") # S 形
cache = d.box(D.x_left_of(svc, ["Cache"], "Reads"), svc.rows[1] - 1, ["Cache"])
d.arrow_h(svc, cache, "Reads", row=svc.rows[1]) # 连接到一个节
aud = d.box(svc.right + 9, y, ["Audit"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Events") # 一个弯曲
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2], # 环绕:3 个弯曲
via=[svc.right + 4, svc.bottom + 2], label="Retry")
print(d.render())
输出:
┌────────────┐ ╔══════════════════╗ ┌───────────────┐
│ ACME INC │ ║ ORDER PLATFORM ║ │ *~~~~~~~~~* │
│ RFC 9000 │ ║ ARCHITECTURE ║ │ DEEP DIVE │
│ NOV 2026 │ ║ · ║ │ *~~~~~~~~~* │
└────────────┘ ╚══════════════════╝ └───────────────┘
┌──────────┐ ┌───────────┐ ┌─────────┐
│ CLIENT │── HTTPS ──▶│ GATEWAY │░ │ AUDIT │░
└──────────┘░ └─────┬─────┘░ └─────────┘░
░░░░░▲░░░░░░ ░░░░░│░░░░░░░ ░░░░▲░░░░░░
│ │ │
│ │ │
│ └───── CALLS ─────┐ │
│ │ │
│ ▼ │
│ ┌─ SERVICES ────┐ │
│ │ AUTH │─── EVENTS ───┘
│ ┌─────────┐ ├───────────────┤░
│ │ CACHE │◀─ READS ───│ ORDERS │░
│ └─────────┘░ ├───────────────┤░
│ ░░░░░░░░░░░ │ BILLING │────┐
│ └───────────────┘░ │
│ ░░░░░░░░░░░░░░░░░ │
│ │
└─────────────────────── RETRY ────────────────────────┘
示例 2:总线、空心箭头头部、内联标签、自由文本
import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D
d = D()
t = d.header(["Event Bus", "Design"], left=["Acme Inc", "ADR 12", "Nov 2026"],
right=["*~~~~~~~*", "Draft", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publisher"])
s1 = d.box(36, y - 2, ["Billing"])
s2 = d.box(36, y + 4, ["Audit"])
s3 = d.box(36, y + 10, ["Search"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Events", head="hollow") # 总线,空心箭头
arc = d.box(D.x_centered_under(pub, ["Archive"]), D.y_below(pub, lines=2), ["Archive"])
d.arrow_v(pub, arc, "Nightly\nbackup", inline=True) # 标签切入线条
d.annotate(46, y + 16, ["At-least-once", "delivery"]) # 自由文本,无框
print(d.render())
输出:
┌────────────┐ ╔═════════════╗ ┌─────────────┐
│ ACME INC │ ║ EVENT BUS ║ │ *~~~~~~~* │
│ ADR 12 │ ║ DESIGN ║ │ DRAFT │
│ NOV 2026 │ ║ · ║ │ *~~~~~~~* │
└────────────┘ ╚═════════════╝ └─────────────┘
┌───────────┐
┌──────▷│ BILLING │░
┌─────────────┐ │ └───────────┘░
│ PUBLISHER │── EVENTS ───┤ ░░░░░░░░░░░░░
└──────┬──────┘░ │
░░░░░░│░░░░░░░░ │
│ ┌─────────┐
NIGHTLY ├──────▷│ AUDIT │░
BACKUP │ └─────────┘░
│ ░░░░░░░░░░░
│ │
▼ │
┌───────────┐ │ ┌──────────┐
│ ARCHIVE │░ └──────▷│ SEARCH │░
└───────────┘░ └──────────┘░
░░░░░░░░░░░░░ ░░░░░░░░░░░░
AT-LEAST-ONCE
DELIVERY
API 参考
D(max_width=80)— 创建一个图表;max_width是列限制。d.box(x, y, lines, role="component"|"frame"|"title", title=None, w=None, align="left")→Box(.x .y .w .h .right .bottom .cx .rows;right/bottom包含阴影)。lines是一个行列表,或者是一个节列表(行的列表)用于拆分框。box.rows保存每个节的箭头行。align="center"使文本居中。d.header(title, left=None, right=None, y=0)→ 标题Box。每个参数都是一个行列表。 这些框的最终x在渲染时确定。每个图表一个标题。d.arrow_h(a, b, label="", row=None, head="filled")—a和b并排放置;双向均可。row选择一个节的行(a.rows[i])。head是"filled"或"hollow"。d.arrow_v(a, b, label="", head="filled", inline=False)—b在a下方,居中对齐。 标签可以有多行("\n")。使用inline=True时,请使用Diagram.y_below(a, lines=N)留出空间。d.route(a, a_side, b, b_side, via=(), label="", label_seg=None, a_row=None, b_row=None, head="filled", inline=False)— 侧面为"left""right""top""bottom"。线条从a的a_side侧离开,进入b的b_side侧。 它有len(via) + 2个线段,交替水平方向和垂直方向,从离开a_side的方向开始。每个via值是一个中间段的通道:垂直段用 x 坐标,水平段用 y 坐标。via=[]是一个弯曲,一个值是两个弯曲(S 形或 U 形),两个值是三个弯曲(环绕)。a_row/b_row选择一个节的行。label_seg选择携带标签的线段(从 0 开始)。d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False)— 一条总线。trunk是共享线的通道:左右侧用 x 坐标,顶部/底部用 y 坐标。d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled")— 一个弯曲,是route的简写形式。vh:离开a的底部,转向进入b的侧面。hv:离开a的侧面,向下转向进入b的顶部。方向遵循b的位置。d.annotate(x, y, lines, align="left")→Box(角色"text")— 自由文本,大写。lines是一个字符串("\n"开始新行)或一个列表。d.text(x, y, s)— 原始文本(不大写)。d.render()— 返回图表;放置标题;检查宽度和宽字符。- 引擎在遇到重叠、间距过小、通道值错误或行超出最大宽度时引发
DiagramError。
如果没有可用的 Shell
使用相同的规则手工绘制。然后计算每行的列数并检查:右侧阴影位于框的右侧一列;底部阴影行从框左边缘的右侧一列开始,到阴影列结束;所有框边缘对齐。
引擎源代码:textdiagram.py
"""textdiagram:在字符网格上绘制对齐的 Unicode 框线图表。
风格:
所有文本均为大写,KEEP 中的单位除外。
组件框:细线 + 细阴影(░),位于右侧一列、下方一行。
标题框:双线,无阴影,在图表上居中(在渲染时放置)。
框架框:细线,无阴影(注释、标注)。
标题:标题框,带有可选的元框(左侧)和印章框(右侧);
标题框的填充行包含一个居中点。
节:一个框由细分隔线拆分,整个框有一个阴影。
水平箭头:标签在线条内部,两端均接触框:── 标签 ──▶
垂直箭头:标签位于线条右侧,位于阴影下方一行。
路由:具有任意数量弯曲的箭头,由通道坐标(via)设置。
箭头头部:实心(▶)或空心(▷)。fan_out:一条线分散为多个箭头。
垂直/水平线上的标签:在线条旁边,或切入线条内部(inline=True)。
annotate:无框的自由文本。
"""
import re
import unicodedata
SHADOW = "░"
MIN_DASH = 2 # 箭头标签每侧的最小破折号数量
HEADER_GAP = 2 # 标题框之间的列数
# 含义随大小写变化的单位(MB = 字节,Mb = 比特,ms = 毫秒,MS = 百万吨)。
# 仅当单词严格按如下格式之一书写时,才会保持原样。
KEEP = {
"Hz", "kHz", "MHz", "GHz",
"kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
"kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
"ms", "µs", "ns",
}
# 框线字符的臂部集合:当两条箭头线汇合时,
# 臂部会合并为一个连接字符(┼, ├, ...)。
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
"├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v):
…
[已截断以进行翻译]