matplotlib.legend

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

重要

你不太可能手动创建一个 Legend 实例。大多数用户通常通过 legend 函数创建图例。关于图例的更多细节，还可以参考 图例指南。

Legend 类是一个包含图例句柄和图例文本的容器。

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

更多信息请参见 <legend_guide>。

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

基类：DraggableOffsetBox

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

参数:

图例 : Legend图例

要包装的 Legend 实例。

use_blitbool, 可选

使用blitting以获得更快的图像合成。详情请参见 FuncAnimation。

更新{'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

在图形/坐标轴上放置图例。

参数:

父级 : Axes 或 FigureAxes 或 Figure

包含图例的艺术家。

handles : Artist 或 Artist 元组的列表列表

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

标签list of str

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

属性:

legend_handles

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

Added in version 3.7.

其他参数:

loc : str 或一对浮点数, 默认值: 对于 Axes 是 rcParams["legend.loc"] (default: 'best'), 对于 Figure 是 'upper right'str 或一对浮点数，默认值：

图例的位置。

字符串 'upper left', 'upper right', 'lower left', 'lower right' 将图例放置在坐标轴/图形的相应角落。

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

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

字符串 'best' 将图例放置在九个定义位置中与其他绘制元素重叠最小的位置。对于包含大量数据的图表，此选项可能会非常慢；提供一个具体位置可能会提高绘图速度。

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

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

位置字符串	位置代码
'最佳' (仅限Axes)	0
'右上角'	toctree 是一个 reStructuredText 指令 ，这是一个非常多功能的标记。指令可以有参数、选项和内容。
'左上角'	2
'左下角'	3
'右下角'	4
'右'	5
'居中靠左'	6
'居中右'	7
'lower center'	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 的浮点数

用于与 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)bool, 默认值:

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

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

是否应在构成图例背景的 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')。

模式expand, 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 : float, 默认值: 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

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

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)

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

参数:

mouseevent鼠标事件

返回:

包含布尔值

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

详情dict

一个特定于艺术家的关于事件上下文细节的字典，例如哪些点包含在拾取半径内。详情请参阅各个 Artist 子类。

draw(renderer)

使用给定的渲染器绘制艺术家（及其子项）。

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

参数:

渲染器 : RendererBase 子类。RendererBase 子类。

注释

此方法在 Artist 子类中被重写。

draw_frame(b)

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

参数:

b布尔值

get_alignment()

获取图例框的对齐值

get_bbox_to_anchor()

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

get_children()

返回此 Artist 的子 Artist 列表。

classmethod get_default_handler_map()

返回全局默认处理程序映射，由所有图例共享。

get_draggable()

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

get_frame()

返回用于框定图例的 Rectangle。

get_frame_on()

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

static get_legend_handler(legend_handler_map, orig_handle)

从 legend_handler_map 返回与 orig_handler 对应的图例处理程序。

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，但包括任何裁剪。

参数:

渲染器 : RendererBase 子类, 可选RendererBase 子类，可选

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

返回:

Bbox 或 None

包围的边界框（在图像像素坐标中）。如果裁剪结果没有交集，则返回 None。

get_title()

返回图例标题的 Text 实例。

get_window_extent(renderer=None)

获取艺术家在显示空间中的边界框。

边界框的宽度和高度是非负的。

子类应重写以包含在边界框“紧密”计算中。默认是返回位于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) 数组和两个从图像左下角开始的偏移量
对齐	{'center', 'left', 'right'}.
alpha	标量或无
animated	布尔值
bbox_to_anchor	BboxBase 或元组
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	补丁或（路径，变换）或无
可拖动	布尔值
figure	Figure 或 SubFigure
frame_on	布尔值
gid	str
in_layout	布尔值
标签	对象
loc	str 或一对浮点数，默认值：对于 Axes 是 rcParams["legend.loc"] (default: 'best')，对于 Figure 是 'upper right'
鼠标悬停	布尔值
ncols	未知
path_effects	AbstractPathEffect 列表
picker	None 或 bool 或 float 或 callable
光栅化	布尔值
sketch_params	(scale: float, length: float, randomness: float)
snap	布尔值或无
标题	str
transform	Transform
url	str
可见	布尔值
zorder	float

set_alignment(alignment)

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

条目被对齐为一个单独的块，因此标记总是对齐的。

参数:

对齐{'center', 'left', 'right'}.

set_bbox_to_anchor(bbox, transform=None)

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

参数:

bbox : BboxBase 或 元组BboxBase 或元组

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

• 一个 BboxBase 实例

• 一个 (左, 底, 宽度, 高度) 的元组，在给定的变换中（如果为 None，则为归一化的轴坐标）

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

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

变换 : Transform, 可选转换，可选

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

classmethod set_default_handler_map(handler_map)

设置全局默认处理程序映射，由所有图例共享。

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

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

参数:

状态布尔值

是否启用鼠标拖动。

use_blitbool, 可选

使用blitting以获得更快的图像合成。详情请参见 FuncAnimation。

更新{'loc', 'bbox'}, 可选

拖动时要更改的图例参数：

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

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

返回:

DraggableLegend 或 None

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

set_frame_on(b)

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

参数:

b布尔值

set_loc(loc=None)

设置图例的位置。

Added in version 3.8.

参数:

loc : str 或一对浮点数, 默认值: 对于 Axes 是 rcParams["legend.loc"] (default: 'best'), 对于 Figure 是 'upper right'str 或一对浮点数，默认值：

图例的位置。

字符串 'upper left', 'upper right', 'lower left', 'lower right' 将图例放置在坐标轴/图形的相应角落。

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

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

字符串 'best' 将图例放置在九个定义位置中与其他绘制元素重叠最小的位置。对于包含大量数据的图表，此选项可能会非常慢；提供一个具体位置可能会提高绘图速度。

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

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

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

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

set_ncols(ncols)

设置列数。

set_title(title, prop=None)

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

参数:

标题str

图例标题。

prop : font_manager.FontProperties 或 str 或 pathlib.Pathfont_manager.FontProperties 或 str 或 pathlib.Path

图例标题的字体属性。如果是一个 str，它被解释为 FontProperties 解析的字体配置模式。如果是一个 pathlib.Path，它被解释为字体文件的绝对路径。

classmethod update_default_handler_map(handler_map)

更新全局默认处理程序映射，该映射由所有图例共享。

zorder = 5