matplotlib.figure.Figure.legend

Figure.legend(*args, **kwargs)

在图上放置一个图例。

调用签名:

legend()
legend(handles, labels)
legend(handles=handles)
legend(labels)

调用签名对应于以下不同的使用此方法的方式：

1. 自动检测需要在图例中显示的元素

当您不传递任何额外参数时，要添加到图例中的元素会自动确定。

在这种情况下，标签取自艺术家。您可以在创建艺术家时指定它们，或者通过调用艺术家的 set_label() 方法来指定:

ax.plot([1, 2, 3], label='Inline label')
fig.legend()

或者:

line, = ax.plot([1, 2, 3])
line.set_label('Label via method')
fig.legend()

可以通过定义以下划线开头的标签来排除特定行从自动图例元素选择中。这是所有艺术家的默认设置，因此在没有参数且未手动设置标签的情况下调用 Figure.legend 将不会绘制任何图例。

2. 在图例中明确列出艺术家和标签

为了完全控制哪些艺术家有图例条目，可以分别传递一个图例艺术家和图例标签的可迭代对象:

fig.legend([line1, line2, line3], ['label1', 'label2', 'label3'])

3. 在图例中显式列出艺术家

这与2类似，但标签取自艺术家的标签属性。例如:

line1, = ax1.plot([1, 2, 3], label='label1')
line2, = ax2.plot([1, 2, 3], label='label2')
fig.legend(handles=[line1, line2])

4. 标记现有绘图元素

不鼓励

不推荐使用此调用签名，因为绘图元素与标签之间的关系仅通过它们的顺序隐含，并且很容易混淆。

要为所有 Axes 上的所有艺术家创建图例，请使用字符串的可迭代对象调用此函数，每个图例项对应一个字符串。例如:

fig, (ax1, ax2) = plt.subplots(1, 2)
ax1.plot([1, 3, 5], color='blue')
ax2.plot([2, 4, 6], color='red')
fig.legend(['the blues', 'the reds'])

参数:

handles : Artist 的列表, 可选列表

要添加到图例中的艺术家（线条、补丁）列表。如果需要完全控制图例中显示的内容，并且上述自动机制不足以满足需求，请与 labels 一起使用。

在这种情况下，句柄和标签的长度应该相同。如果它们不相同，它们将被截断为较短的长度。

标签list of str, 可选

要在艺术家旁边显示的标签列表。如果需要完全控制图例中显示的内容，并且上述自动机制不足够时，请与 handles 一起使用此选项。

返回:

Legend

其他参数:

locstr 或一对浮点数，默认值：'右上角'

图例的位置。

字符串 'upper left'、'upper right'、'lower left'、'lower right' 将图例放置在图形相应的角落。

字符串 'upper center', 'lower center', 'center left', 'center right' 将图例放置在图形相应边缘的中心位置。

字符串 'center' 将图例放置在图形的中心。

位置也可以是一个2元组，给出图例在图坐标系中左下角的坐标（在这种情况下，bbox_to_anchor 将被忽略）。

为了向后兼容，'center right'``（但不能是其他位置）也可以拼写为'right'``，并且每个“字符串”位置也可以用数值表示：

位置字符串	位置代码
'最佳' (仅适用于坐标轴)	0
'右上角'	toctree 是一个 reStructuredText 指令 ，这是一个非常多功能的标记。指令可以有参数、选项和内容。
'左上角'	2
'左下角'	3
'右下角'	4
'右'	5
'居中 左'	6
'居中右'	7
'下中'	8
'上中'	9
'中心'	10

如果一个图形使用了约束布局管理器，loc 关键字参数的字符串代码可以通过使用前缀 'outside' 获得更好的布局行为。在角落处存在歧义，因此 'outside upper right' 将在布局中为图例在其余轴的上方留出空间，而 'outside right upper' 将在布局的右侧留出空间。除了上述 loc 的值外，我们还有 'outside right upper'、'outside right lower'、'outside left upper' 和 'outside left lower'。更多详情请参见 图例指南。

bbox_to_anchor : BboxBase, 2-tuple, 或 4-tuple 的浮点数BboxBase, 2-tuple, 或 4-tuple of floats

用于与 loc 一起定位图例的框。默认为 axes.bbox``（如果作为 `.Axes.legend` 的方法调用）或 ``figure.bbox``（如果 ``figure.legend）。此参数允许图例的任意放置。

Bbox 坐标在由 bbox_transform 给出的坐标系中解释，默认转换为 Axes 或 Figure 坐标，具体取决于调用 legend 的对象。

如果给定一个4元组或 BboxBase ，则它指定图例放置的bbox (x, y, width, height)。要将图例放置在Axes（或图形）右下象限的最佳位置:

loc='best', bbox_to_anchor=(0.5, 0., 0.5, 0.5)

一个 2 元组 (x, y) 将图例的指定角 loc 放置在 x, y 处。例如，要将图例的右上角放置在 Axes（或图形）的中心，可以使用以下关键字:

loc='upper right', bbox_to_anchor=(0.5, 0.5)

ncolsint, 默认值: 1

图例所占的列数。

为了向后兼容，拼写 ncol 也被支持，但不推荐使用。如果两者都给出，ncols 优先。

prop : None 或 FontProperties 或 dict无或

图例的字体属性。如果为 None（默认），将使用当前的 matplotlib.rcParams。

字体大小int 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

图例的字体大小。如果值是数字，则大小将是绝对字体大小（以点为单位）。字符串值相对于当前默认字体大小。仅当未指定 prop 时，才使用此参数。

labelcolor : str 或 list, 默认值: rcParams["legend.labelcolor"] (default: 'None')str 或 list, 默认:

图例中文本的颜色。可以是有效的颜色字符串（例如，'red'），或者是颜色字符串的列表。labelcolor 也可以设置为与线条或标记的颜色相匹配，使用 'linecolor'、'markerfacecolor'（或 'mfc'），或 'markeredgecolor'（或 'mec'）。

标签颜色可以通过 rcParams["legend.labelcolor"] (default: 'None') 全局设置。如果为 None，则使用 rcParams["text.color"] (default: 'black')。

numpoints : int, 默认值: rcParams["legend.numpoints"] (default: 1)int, 默认值:

在为 `.Line2D`（线）创建图例条目时，图例中的标记点数量。

scatterpoints : int, 默认值: rcParams["legend.scatterpoints"] (default: 1)int, 默认值:

为 `.PathCollection`（散点图）创建图例条目时图例中的标记点数量。

scatteryoffsets : 浮点数可迭代对象, 默认: [0.375, 0.5, 0.3125]浮点数的可迭代对象，默认值：

散点图图例条目创建的标记的垂直偏移（相对于字体大小）。0.0 位于图例文本的基线，1.0 位于顶部。要使所有标记在同一高度绘制，请设置为 [0.5]。

markerscale : float, 默认值: rcParams["legend.markerscale"] (default: 1.0)浮点数，默认值：

图例标记相对于最初绘制的标记的相对大小。

markerfirstbool, 默认: True

如果 True，图例标记放置在图例标签的左侧。如果 False，图例标记放置在图例标签的右侧。

反向bool, 默认: False

如果 True，图例标签按输入的反序显示。如果 False，图例标签按输入的顺序显示。

Added in version 3.7.

frameon : bool, 默认值: rcParams["legend.frameon"] (default: True)布尔值, 默认:

图例是否应绘制在补丁（框架）上。

fancybox : bool, 默认值: rcParams["legend.fancybox"] (default: True)布尔值, 默认:

是否应在构成图例背景的 FancyBboxPatch 周围启用圆角。

shadow : None, bool 或 dict, 默认值: rcParams["legend.shadow"] (default: False)None, bool 或 dict, 默认:

是否在图例后面绘制阴影。阴影可以使用 Patch 关键字进行配置。目前不支持通过 rcParams["legend.shadow"] (default: False) 进行自定义。

framealpha : float, 默认值: rcParams["legend.framealpha"] (default: 0.8)浮点数，默认值：

图例背景的透明度。如果 shadow 被激活且 framealpha 为 None，则默认值将被忽略。

facecolor : "inherit" 或颜色, 默认: rcParams["legend.facecolor"] (default: 'inherit')“继承”或颜色，默认：

图例的背景颜色。如果为 "inherit"，则使用 rcParams["axes.facecolor"] (default: 'white')。

edgecolor : "inherit" 或颜色, 默认值: rcParams["legend.edgecolor"] (default: '0.8')“继承”或颜色，默认：

图例背景补丁边缘颜色。如果为 "inherit"，则使用 rcParams["axes.edgecolor"] (default: 'black')。

模式{"展开", None}

如果 mode 设置为 "expand" ，图例将水平扩展以填充 Axes 区域（如果定义了 bbox_to_anchor ，则填充其定义的图例大小）。

bbox_transform : None 或 Transform无或

边界框的变换（bbox_to_anchor）。对于值 ``None``（默认），将使用 Axes 的 transAxes 变换。

标题str 或 None

图例的标题。默认无标题 (None)。

title_fontproperties : None 或 FontProperties 或 dict无或

图例标题的字体属性。如果为 None（默认），将使用 title_fontsize 参数（如果存在）；如果 title_fontsize 也为 None，则将使用当前的 rcParams["legend.title_fontsize"] (default: None)。

title_fontsize : int 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, 默认值: rcParams["legend.title_fontsize"] (default: None)int 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}，默认值：

图例标题的字体大小。注意：这不能与 title_fontproperties 结合使用。如果你想在设置其他字体属性时设置字体大小，请在 title_fontproperties 中使用 size 参数。

对齐{'center', 'left', 'right'}, 默认: 'center'

图例标题和条目框的对齐方式。条目作为一个整体块对齐，因此标记总是对齐的。

borderpad : float, 默认值: rcParams["legend.borderpad"] (default: 0.4)浮点数，默认值：

图例边框内的分数空白，以字体大小为单位。

labelspacing : float, 默认值: rcParams["legend.labelspacing"] (default: 0.5)浮点数，默认值：

图例条目之间的垂直空间，以字体大小为单位。

handlelength : float, 默认值: rcParams["legend.handlelength"] (default: 2.0)浮点数，默认值：

图例句柄的长度，以字体大小为单位。

handleheight : float, 默认值: rcParams["legend.handleheight"] (default: 0.7)浮点数，默认值：

图例句柄的高度，以字体大小单位表示。

handletextpad : float, 默认值: rcParams["legend.handletextpad"] (default: 0.8)浮点数，默认值：

图例句柄和文本之间的填充，以字体大小为单位。

borderaxespad : 浮点数, 默认值: rcParams["legend.borderaxespad"] (default: 0.5)浮点数，默认值：

Axes 和图例边框之间的填充，以字体大小为单位。

columnspacing : float, 默认值: rcParams["legend.columnspacing"] (default: 2.0)浮点数，默认值：

列之间的间距，以字体大小单位表示。

handler_map字典或无

自定义字典，将实例或类型映射到图例处理程序。这个 handler_map 更新了在 matplotlib.legend.Legend.get_legend_handler_map 中找到的默认处理程序映射。

可拖动bool, 默认: False

图例是否可以用鼠标拖动。

参见

Axes.legend

注释

此功能不支持某些艺术家。详情请参阅 图例指南。

使用 matplotlib.figure.Figure.legend 的示例

图例演示

Figure legend demo

图例指南

Legend guide

约束布局指南

Constrained layout guide