Python Matplotlib annotate函数详解：参数、坐标系与实战示例

沿途有光

发布时间：2026-10-16 | 7人浏览过

原创

本文深入解析Python Matplotlib库中的annotate函数，详细讲解其添加指向型注释文本的功能。通过剖析string、xy、xytext、bbox及arrowprops等核心参数，结合不同坐标系（如axes fraction与figure fraction）的实战案例，展示如何精准控制注释位置、样式及箭头效果，帮助开发者高效实现数据可视化标注。

在Python的数据可视化库Matplotlib中，annotate函数是一个用于增强图表信息表达的重要工具。

annotate函数的基本用法与核心功能。

若需了解该函数支持的所有详细参数，可通过调用内置属性__doc__进行查看，例如使用print(plt.annotate.__doc__)获取帮助文档。

	import matplotlib.pyplot as plt
    # plt.annotate(str, xy=data_point_position, xytext=annotate_position, 
    #              va="center",  ha="center", xycoords="axes fraction", 
    #              textcoords="axes fraction", bbox=annotate_box_type, arrowprops=arrow_style)
    # str是给数据点添加注释的内容，支持输入一个字符串
    # xy=是要添加注释的数据点的位置
    # xytext=是注释内容的位置
    # bbox=是注释框的风格和颜色深度，fc越小，注释框的颜色越深，支持输入一个字典
    # va="center",  ha="center"表示注释的坐标以注释框的正中心为准，而不是注释框的左下角(v代表垂直方向，h代表水平方向)
    # xycoords和textcoords可以指定数据点的坐标系和注释内容的坐标系，通常只需指定xycoords即可，textcoords默认和xycoords相同
    # arrowprops可以指定箭头的风格支持，输入一个字典
    # plt.annotate()的详细参数可用__doc__查看，如：print(plt.annotate.__doc__)

以下是第一个基础示例：

	import matplotlib.pyplot as plt
    fig = plt.figure(1, facecolor='white')
    fig.clf()
    plt.annotate('a decision node', (0.1, 0.5), (0.5, 0.1), va="center",  ha="center",
                 xycoords="axes fraction", textcoords="axes fraction", 
                 bbox=dict(boxstyle="sawtooth", fc="0.8"), arrowprops=dict(arrowstyle="<-"))
    plt.show()

运行上述代码后的输出结果如下：

示例二：演示如何为注释文本和数据点指定不同的坐标系，以解决注释位置偏移问题。

	import matplotlib.pyplot as plt
    fig = plt.figure(1, facecolor='white')
    fig.clf()
    # 这里指定数据点的坐标系原点在xy轴的左下角，而注释的坐标系原点在这个图像(figure)的左下角
    # 所以才会出现注释内容下移覆盖了x轴
    plt.annotate('a decision node', (0.1, 0.5), (0.5, 0.1), va="center",  ha="center",
                 xycoords="axes fraction", textcoords="figure fraction", 
                 bbox=dict(boxstyle="sawtooth", fc="0.8"), arrowprops=dict(arrowstyle="<-"))
    plt.show()

该示例对应的运行结果如下：

对annotate()函数各参数的详细解析。

该函数的主要功能是向图形中添加带有指向性箭头的注释文本，用于突出显示特定数据点或区域。

其标准调用签名如下所示：

plt.annotate(string, xy=(np.pi/2, 1.0), xytext=((np.pi/2)+0.15, 1,5), weight="bold", color="b", arrowprops=dict(arrowstyle="->", connectionstyle="arc3", color="b"))

string：表示添加给数据点的注释文本内容，通常为一个字符串。
xy：指定被注释数据点在图中的位置坐标。
xytext：指定注释文本本身在图中的显示位置坐标。
weight：用于设置注释文本的字体粗细风格，例如加粗。
color：用于设置注释文本的颜色。
arrowprops：一个字典，用于定义指向数据点的箭头的样式属性。

以下是完整的代码实现部分：

import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0.05, 10, 1000)
y = np.sin(x)
plt.plot(x, y, ls="-.", lw=2, c="c", label="plot figure")
plt.legend()
plt.annotate("maximum", xy=(np.pi/2, 1.0), xytext=((np.pi/2)+1.0, .8),
             weight="bold", color="b", 
             arrowprops=dict(arrowstyle="->", connectionstyle="arc3", color="b"))
plt.show()