Matplotlib 注释与文本：把关键点标清楚

Name: Amber de Ligt

Updated on 2025/11/21

没有标注的峰值或柱子会让读者猜测；文本重叠或漂得太远，故事就模糊了。解决办法是清晰的注释：简短标签、合适的箭头、统一的字体，既引导注意力又不添噪声.

选对文本工具

任务	工具	原因
用箭头标记特定点	`annotate`	一次调用同时设置文字和箭头
在轴坐标写自由文本	`text`	标题、面板说明、角标
自动给柱子加标签	`bar_label`	标签固定在柱子上
保持标签在图内	`clip_on=True`、偏移	防止文字跑出轴界
换行/格式化文本	`textwrap.fill`、f-string	让标签短而易读

用箭头标出峰值

import matplotlib.pyplot as plt
import numpy as np
 
x = np.linspace(0, 10, 300)
y = np.sin(x) * np.exp(-x / 5)
 
fig, ax = plt.subplots(figsize=(7, 4))
ax.plot(x, y, color="tab:blue")
 
peak_idx = np.argmax(y)
peak_x, peak_y = x[peak_idx], y[peak_idx]
 
ax.annotate(
    "峰值",
    xy=(peak_x, peak_y),
    xytext=(peak_x + 1.2, peak_y + 0.2),
    arrowprops=dict(arrowstyle="->", color="tab:red", lw=1.5),
    bbox=dict(boxstyle="round,pad=0.3", fc="white", ec="tab:red", alpha=0.9),
    fontsize=10,
    color="tab:red",
)
 
ax.set_xlabel("Time (s)")
ax.set_ylabel("Amplitude")
ax.grid(True, linestyle="--", alpha=0.3)
plt.tight_layout()
plt.show()

提示：

通过 xytext 轻微偏移，让箭头短而清晰。
用浅色 bbox 在复杂图上增强对比。
保持 2–4 个词，避免遮挡数据。

柱状图标签不重叠

import matplotlib.pyplot as plt
 
items = ["A", "B", "C", "D"]
values = [28, 35, 30, 22]
 
fig, ax = plt.subplots(figsize=(6, 4))
bars = ax.bar(items, values, color="tab:purple", alpha=0.9)
 
ax.bar_label(bars, labels=[f"{v}k" for v in values], padding=3)
ax.set_ylabel("Units sold")
ax.set_ylim(0, 40)
 
plt.tight_layout()
plt.show()

提示：

padding 控制距离；负值可把标签放到柱子内部。
堆叠柱使用 label_type="center" 把标签放到每段中心。
数值很小时，把文字改成白色并放在柱内以增强对比。

内联备注与安全放置

ax.text(
    0.02, 0.95, "Experiment 3\nn=120",
    transform=ax.transAxes,
    ha="left", va="top",
    fontsize=9,
    bbox=dict(boxstyle="round", fc="white", ec="0.7", alpha=0.8)
)

要点：

transform=ax.transAxes 让 0–1 坐标在窗口缩放后也保持位置。
需要留在图内时，用 clip_on=True。
结合 ha/va 对齐和短换行，避免撞到边缘。

快速排查

标签重叠？减小字号、调整 padding 或轻微旋转。
箭头不见？提高 zorder 或在填充图形之后再画。
文本超出？启用 constrained_layout=True 或用 textwrap.fill 缩短。