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,會變為大寫。 - COMPONENT 方框(系統的一部分:服務、客戶端、資料庫、佇列、工作者):
細線
┌─┐ │ └─┘加上一個細░陰影,向右一列,向下一行。 要對部分進行分組,將一個方框拆分為多個區段:細分隔線├───┤、一個框架、一個陰影。 - TITLE 方框(文件的主標題,每個圖表一個):雙線
╔═╗ ║ ╚═╝,無陰影。 每行一個項目(名稱、文件類型、版本),每個項目在方框中居中。使用d.header(...)製作:引擎將方框居中於整個圖表上方。可選:左側一個元資料方框 (公司、RFC、日期)和右側一個印章方框(狀態)。三個方框高度相同; 標題方框的填充行包含一個居中點·。 沒有箭頭可以在標題方框處開始或結束。 - FRAME 方框(區段標題、備註、呼叫):細線,無陰影。
備註/呼叫:將名稱放在頂部邊框上,如
┌─ 備註 ───┐。 不要添加圖例:每個圖表中的樣式都相同。 - 自由文字(
d.annotate):沒有方框的簡短說明,在圖表旁邊。很少使用。 線條不得穿過它。 - 水平箭頭:標籤在線條內,兩側各一個空格:
── HTTPS ──▶。 兩端都接觸方框:線條從發送方框的陰影列開始,箭頭頭部接觸接收方框。 - 垂直箭頭:線條從底部邊框的
┬開始,以▼結束。標籤位於 線條右側,陰影下方一行。或將標籤切入線條中 (inline=True):線條、空白行、標籤行居中於線條上、空白行、線條。 - 彎曲箭頭(
d.route):任意數量的彎曲,任意方向(▲ ▼ ◀ ▶)。標籤位於 橫向段內,或位於(或者,使用inline=True,切入)向上/向下段旁邊。 交叉或連接的線條形成一個交點(┼ ├ ┤ ┬ ┴)。線條永遠不會穿過方框。 - 匯流排(
d.fan_out):從一個方框出發的一條線,分成每個目標一個箭頭。 標籤位於共用線條上。 - 箭頭頭部:填充
▶ ◀ ▲ ▼用於主要流程。空心▷ ◁ △ ▽用於第二種 關係(非同步、可選、事件)。僅在圖表需要兩種時使用空心, 並在標籤或備註中命名其含義,不要在圖例中。 - 用流經的內容(協議、事件、資料)標記每個箭頭。
- 如果不清楚方框的角色:系統部分使用 COMPONENT,主標題使用 TITLE, 其他所有內容使用 FRAME。
工作流程
- 在繪製之前列出元件、框架和箭頭。
- 將引擎寫入
/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)—a_side和b_side是"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 中的單位。
COMPONENT 方框:細線 + 向右一列、向下一行的細陰影 (░)。
TITLE 方框:雙線,無陰影,居中於圖表上方(渲染時放置)。
FRAME 方框:細線,無陰影(備註,呼叫)。
標題:標題方框帶可選左側元資料方框和右側印章方框;
標題方框的填充行包含一個居中點。
區段:一個方框由細分隔線拆分,整個方框一個陰影。
水平箭頭:標籤在線條內,兩端都接觸方框:── 標籤 ──▶
垂直箭頭:標籤在線條右側,陰影下方一行。
路線:具有任意數量彎曲的箭頭,由通道座標 (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):
…
[為翻譯進行了截斷]