matplotlib.legend

legend 模块定义了 Legend 类，该类负责绘制与 Axes 和/或 Figure 关联的图例。

重要提示

您不太可能手动创建 Legend 实例。大多数用户通常会通过 legend 函数创建图例。有关图例的更多详细信息，请参阅图例指南。

Legend 类是图例句柄和图例文本的容器。

图例处理程序映射指定了如何从 Axes 或 Figure 中的艺术家（线条、补丁等）创建图例句柄。默认图例处理程序在 legend_handler 模块中定义。虽然并非所有艺术家类型都由默认图例处理程序涵盖，但可以定义自定义图例处理程序以支持任意对象。

有关更多信息，请参阅图例指南。

class matplotlib.legend.DraggableLegend(legend, use_blit=False, update='loc')

基类: DraggableOffsetBox

围绕 Legend 的包装器，支持鼠标拖动。

参数:

legendLegend

要包装的 Legend 实例。

use_blit布尔值，可选

使用 blitting 实现更快的图像合成。有关详细信息，请参阅 FuncAnimation。

update{'loc', 'bbox'}，可选

如果为“loc”，则在最终确定时更新图例的 loc 参数。如果为“bbox”，则更新 bbox_to_anchor 参数。

finalize_offset()

class matplotlib.legend.Legend(parent, handles, labels, *, loc=None, numpoints=None, markerscale=None, markerfirst=True, reverse=False, scatterpoints=None, scatteryoffsets=None, prop=None, fontsize=None, labelcolor=None, borderpad=None, labelspacing=None, handlelength=None, handleheight=None, handletextpad=None, borderaxespad=None, columnspacing=None, ncols=1, mode=None, fancybox=None, shadow=None, title=None, title_fontsize=None, framealpha=None, edgecolor=None, facecolor=None, bbox_to_anchor=None, bbox_transform=None, frameon=None, handler_map=None, title_fontproperties=None, alignment='center', ncol=1, draggable=False)

基类: Artist

在 Figure/Axes 上放置图例。

参数:

parentAxes 或 Figure

包含图例的艺术家对象。

handles艺术家（Artist）或艺术家元组（Artist）的列表

要添加到图例中的艺术家（线条、补丁）列表。

labelsstr 列表

要显示在艺术家旁边的标签列表。handles 和 labels 的长度应相同。如果不同，它们将被截断为较短列表的长度。

属性：

legend_handles

作为图例条目添加的 Artist 对象列表。

版本 3.7 新增。

其他参数:

loc字符串或浮点数对，默认值：Axes 为 rcParams["legend.loc"] (默认值: 'best')，Figure 为 'upper right'

图例的位置。

字符串 'upper left'、'upper right'、'lower left'、'lower right' 将图例放置在 Axes/Figure 的相应角点。

字符串 'upper center'、'lower center'、'center left'、'center right' 将图例放置在 Axes/Figure 相应边的中心。

字符串 'center' 将图例放置在 Axes/Figure 的中心。

字符串 'best' 将图例放置在迄今为止定义的九个位置中，与其他已绘制艺术家重叠最小的位置。对于包含大量数据的绘图，此选项可能非常慢；指定特定位置可能会提高您的绘图速度。

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

为了向后兼容，'center right'（但没有其他位置）也可以拼写为 'right'，并且每个“字符串”位置也可以给定为数值

位置字符串	位置代码
'best'（仅限 Axes）	0
'upper right'	1
'upper left'	2
'lower left'	3
'lower right'	4
'right'	5
'center left'	6
'center right'	7
'lower center'	8
'upper center'	9
'center'	10

如果 Figure 使用受限布局管理器，loc 关键字参数的字符串代码可以使用前缀“outside”获得更好的布局行为。在角落处存在歧义，因此“outside upper right”将在布局中为图例在其余 Axes 上方留出空间，“outside right upper”将在布局的右侧留出空间。除了上面列出的 loc 值之外，我们还有“outside right upper”、“outside right lower”、“outside left upper”和“outside left lower”。有关更多详细信息，请参阅图例指南。

bbox_to_anchorBboxBase、2 元组或 4 元组浮点数

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

Bbox 坐标在 bbox_transform 给定的坐标系中解释，默认变换为 Axes 或 Figure 坐标，具体取决于调用哪个 legend。

如果给定 4 元组或 BboxBase，则它指定了图例放置的边界框 (x, y, width, height)。要将图例放置在 Axes（或 Figure）右下象限的最佳位置

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

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

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

ncolsint, 默认值: 1

图例的列数。

为了向后兼容，也支持拼写 ncol，但不建议使用。如果两者都给定，则 ncols 优先。

propNone 或 FontProperties 或 dict

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

fontsize整数或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

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

labelcolor字符串或列表，默认值：rcParams["legend.labelcolor"] (默认值: 'None')

图例中文本的颜色。可以是有效的颜色字符串（例如，“red”），或颜色字符串列表。标签颜色也可以通过使用“linecolor”、“markerfacecolor”（或“mfc”）或“markeredgecolor”（或“mec”）来匹配线条或标记的颜色。

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

numpoints整型，默认值：rcParams["legend.numpoints"] (默认值: 1)

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

scatterpoints整型，默认值：rcParams["legend.scatterpoints"] (默认值: 1)

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

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

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

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

图例标记相对于原始绘制标记的相对大小。

markerfirst布尔值，默认值：True

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

reverse布尔值，默认值：False

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

版本 3.7 新增。

frameon布尔值，默认值：rcParams["legend.frameon"] (默认值: True)

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

fancybox布尔值，默认值：rcParams["legend.fancybox"] (默认值: True)

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

shadowNone、布尔值或 dict，默认值：rcParams["legend.shadow"] (默认值: False)

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

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

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

facecolor"inherit" 或 颜色，默认值：rcParams["legend.facecolor"] (默认值: 'inherit')

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

edgecolor"inherit" 或 颜色，默认值：rcParams["legend.edgecolor"] (默认值: '0.8')

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

mode{"expand", None}

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

bbox_transformNone 或 Transform

边界框 (bbox_to_anchor) 的变换。如果值为 None (默认)，将使用 Axes 的 transAxes 变换。

title字符串或 None

图例的标题。默认没有标题（None）。

title_fontpropertiesNone 或 FontProperties 或 dict

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

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

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

alignment{'center', 'left', 'right'}，默认值：'center'

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

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

图例边框内的空白区域比例，以字体大小单位表示。

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

图例条目之间的垂直间距，以字体大小单位表示。

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

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

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

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

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

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

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

Axes 与图例边框之间的填充，以字体大小单位表示。

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

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

handler_map字典或 None

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

draggable布尔值，默认值：False

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

codes = {'best': 0, 'center': 10, 'center left': 6, 'center right': 7, 'lower center': 8, 'lower left': 3, 'lower right': 4, 'right': 5, 'upper center': 9, 'upper left': 2, 'upper right': 1}

contains(mouseevent)

测试艺术家是否包含鼠标事件。

参数:

mouseeventMouseEvent

返回:

contains布尔值

是否有任何值在半径范围内。

details字典

一个艺术家特定的字典，包含事件上下文的详细信息，例如哪些点包含在选择半径内。有关详细信息，请参阅各个 Artist 子类。

draw(renderer)

使用给定的渲染器绘制 Artist（及其子对象）。

如果艺术家不可见（Artist.get_visible 返回 False），则此操作无效。

参数:

rendererRendererBase 子类。

备注

此方法在 Artist 子类中被覆盖。

draw_frame(b)

设置是否绘制图例框补丁。

参数:

bbool

get_alignment()

获取图例框的对齐值

get_bbox_to_anchor()

返回图例将锚定到的边界框。

get_children()

返回此 Artist 的子 Artist 列表。

类方法 get_default_handler_map()

返回所有图例共享的全局默认处理器映射。

get_draggable()

如果图例可拖动，则返回 True；否则返回 False。

get_frame()

返回用于框定图例的 Rectangle。

get_frame_on()

获取是否绘制图例框补丁。

静态 get_legend_handler(legend_handler_map, orig_handle)

从 legend_handler_map 中返回与 orig_handle 对应的图例处理器。

legend_handler_map 应该是一个字典对象（由 get_legend_handler_map 方法返回）。

它首先检查 orig_handle 本身是否是 legend_handler_map 中的一个键，并返回关联的值。否则，它会检查其方法解析顺序中的每个类。如果未找到匹配的键，它将返回 None。

get_legend_handler_map()

返回此图例实例的处理器映射。

get_lines()

返回图例中的 Line2D 列表。

get_patches()

返回图例中的 Patch 列表。

get_texts()

返回图例中的 Text 列表。

get_tightbbox(renderer=None)

类似于 Artist.get_window_extent，但包含任何裁剪。

参数:

rendererRendererBase 子类，可选

用于绘制图形的渲染器（即 fig.canvas.get_renderer()）

返回:

Bbox 或 None

封闭的边界框（以图形像素坐标表示）。如果剪裁导致没有交集，则返回 None。

get_title()

返回图例标题的 Text 实例。

get_window_extent(renderer=None)

获取 artist 在显示空间中的边界框。

边界框的宽度和高度均为非负值。

子类应覆盖此方法，以便将其包含在边界框“紧密”计算中。默认返回一个位于 0, 0 的空边界框。

使用此函数时请小心，如果艺术家的窗口范围发生变化，结果将不会更新。范围可能会因变换堆栈中的任何变化而改变，例如更改坐标轴限制、图形大小或所使用的画布（如保存图形时所做）。这可能导致意外行为，即交互式图形在屏幕上看起来正常，但保存时会出错。

set(*, agg_filter=<UNSET>, alignment=<UNSET>, alpha=<UNSET>, animated=<UNSET>, bbox_to_anchor=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, draggable=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, loc=<UNSET>, mouseover=<UNSET>, ncols=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

一次性设置多个属性。

支持的属性包括：

属性	描述
agg_filter	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
alignment	{'center', 'left', 'right'}。
alpha	浮点数或 None
animated	布尔值
bbox_to_anchor	BboxBase 或 元组
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	Patch 或 (Path, Transform) 或 None
draggable	布尔值
figure	Figure 或 SubFigure
frame_on	布尔值
gid	字符串
in_layout	布尔值
label	对象
loc	字符串 或 浮点数对，默认值：rcParams["legend.loc"]（默认值：'best'）用于 Axes，'upper right' 用于 Figure
mouseover	布尔值
ncols	未知
path_effects	AbstractPathEffect 列表
picker	None 或 布尔值 或 浮点数 或 可调用对象
rasterized	布尔值
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
title	字符串
transform	变换
url	字符串
visible	布尔值
zorder	浮点数

set_alignment(alignment)

设置图例标题和条目框的对齐方式。

条目作为一个单一块对齐，因此标记始终对齐。

参数:

alignment{'center', 'left', 'right'}。

set_bbox_to_anchor(bbox, transform=None)

设置图例将锚定到的边界框。

参数:

bboxBboxBase 或 元组

边界框可以通过以下方式指定

• 一个 BboxBase 实例

• 给定变换中的一个 (left, bottom, width, height) 元组（如果为 None，则为归一化的坐标轴坐标）

• 一个 (left, bottom) 元组，其中宽度和高度将被假定为零。

• None，用于移除边界框锚定，并使用父边界框。

transformTransform，可选

应用于边界框的变换。如果未指定，将使用变换到父边界框。

类方法 set_default_handler_map(handler_map)

设置所有图例共享的全局默认处理器映射。

set_draggable(state, use_blit=False, update='loc')

启用或禁用图例的鼠标拖动支持。

参数:

statebool

是否启用鼠标拖动。

use_blit布尔值，可选

使用 blitting 实现更快的图像合成。有关详细信息，请参阅 FuncAnimation。

update{'loc', 'bbox'}，可选

拖动时要更改的图例参数

• 'loc'：更新图例的 loc 参数

• 'bbox'：更新图例的 bbox_to_anchor 参数

返回:

DraggableLegend 或 None

如果 state 为 True，则返回 DraggableLegend 辅助实例。否则返回 None。

set_frame_on(b)

设置是否绘制图例框补丁。

参数:

bbool

set_loc(loc=None)

设置图例的位置。

在版本 3.8 中添加。

参数:

loc字符串或浮点数对，默认值：Axes 为 rcParams["legend.loc"] (默认值: 'best')，Figure 为 'upper right'

图例的位置。

字符串 'upper left'、'upper right'、'lower left'、'lower right' 将图例放置在 Axes/Figure 的相应角点。

字符串 'upper center'、'lower center'、'center left'、'center right' 将图例放置在 Axes/Figure 相应边的中心。

字符串 'center' 将图例放置在 Axes/Figure 的中心。

字符串 'best' 将图例放置在迄今为止定义的九个位置中，与其他已绘制艺术家重叠最小的位置。对于包含大量数据的绘图，此选项可能非常慢；指定特定位置可能会提高您的绘图速度。

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

为了向后兼容，'center right'（但没有其他位置）也可以拼写为 'right'，并且每个“字符串”位置也可以给定为数值

位置字符串	位置代码
'best'（仅限 Axes）	0
'upper right'	1
'upper left'	2
'lower left'	3
'lower right'	4
'right'	5
'center left'	6
'center right'	7
'lower center'	8
'upper center'	9
'center'	10

如果 Figure 使用受限布局管理器，loc 关键字参数的字符串代码可以使用前缀“outside”获得更好的布局行为。在角落处存在歧义，因此“outside upper right”将在布局中为图例在其余 Axes 上方留出空间，“outside right upper”将在布局的右侧留出空间。除了上面列出的 loc 值之外，我们还有“outside right upper”、“outside right lower”、“outside left upper”和“outside left lower”。有关更多详细信息，请参阅图例指南。

set_ncols(ncols)

设置列数。

set_title(title, prop=None)

设置图例标题和标题样式。

参数:

title字符串

图例标题。

propfont_manager.FontProperties 或 str 或 pathlib.Path

图例标题的字体属性。如果为 str，则将其解释为由 FontProperties 解析的 fontconfig 模式。如果为 pathlib.Path，则将其解释为字体文件的绝对路径。

类方法 update_default_handler_map(handler_map)

更新所有图例共享的全局默认处理器映射。

zorder = 5