matplotlib.pyplot.figlegend

matplotlib.pyplot.figlegend(*args, **kwargs)

在图形上放置图例。

调用签名

figlegend()
figlegend(handles, labels)
figlegend(handles=handles)
figlegend(labels)

此方法的调用签名对应以下几种不同用法

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

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

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

plt.plot([1, 2, 3], label='Inline label')
plt.figlegend()

或

line, = plt.plot([1, 2, 3])
line.set_label('Label via method')
plt.figlegend()

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

2. 显式列出图例中的艺术对象和标签

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

plt.figlegend([line1, line2, line3], ['label1', 'label2', 'label3'])

3. 显式列出图例中的艺术对象

这类似于方法2，但标签取自艺术对象的标签属性。示例

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

4. 为现有绘图元素添加标签

不建议使用

不建议使用此调用签名，因为绘图元素与标签之间的关系仅由它们的顺序隐式决定，很容易混淆。

要为所有 Axes 上的所有 artist 创建图例，请使用可迭代的字符串（每个图例项一个）调用此函数。例如：

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

参数:

handlesArtist 列表，可选

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

在这种情况下，handles 和 labels 的长度应该相同。如果不同，它们将被截断为较小的长度。

labels字符串列表, 可选

要显示在艺术对象旁边的标签列表。如果您需要完全控制图例中显示的内容，并且上述自动机制不足以满足您的需求，请与 handles 一起使用此参数。

返回:

图例

其他参数:

loc字符串或浮点数对，默认值: 'upper right'

图例的位置。

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

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

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

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

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

位置字符串	位置代码
'best'（仅限 Axes）	0
'右上'	1
'左上'	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_anchorBboxBase、2-元组或4-元组浮点数

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

边界框坐标在 bbox_transform 给定的坐标系中解释，默认变换是坐标轴或图坐标，具体取决于调用 legend 的方式。

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

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

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

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

ncolsint, 默认值: 1

图例的列数。

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

prop无或 FontProperties 或 dict

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

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

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

labelcolorstr 或 list，默认值: rcParams["legend.labelcolor"] (默认值: 'None')

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

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

numpointsint，默认值: rcParams["legend.numpoints"] (默认值: 1)

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

scatterpointsint，默认值: rcParams["legend.scatterpoints"] (默认值: 1)

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

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

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

markerscalefloat，默认值: rcParams["legend.markerscale"] (默认值: 1.0)

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

markerfirst布尔值，默认值：True

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

reverse布尔值，默认值：False

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

版本 3.7 新增。

frameonbool，默认值: rcParams["legend.frameon"] (默认值: True)

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

fancyboxbool，默认值: rcParams["legend.fancybox"] (默认值: True)

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

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

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

framealphafloat，默认值: rcParams["legend.framealpha"] (默认值: 0.8)

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

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

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

edgecolor"inherit" 或 color，默认值: 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_fontsizeint 或 {'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'

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

borderpadfloat，默认值: rcParams["legend.borderpad"] (默认值: 0.4)

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

labelspacingfloat，默认值: rcParams["legend.labelspacing"] (默认值: 0.5)

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

handlelengthfloat，默认值: rcParams["legend.handlelength"] (默认值: 2.0)

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

handleheightfloat，默认值: rcParams["legend.handleheight"] (默认值: 0.7)

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

handletextpadfloat，默认值: rcParams["legend.handletextpad"] (默认值: 0.8)

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

borderaxespadfloat，默认值: rcParams["legend.borderaxespad"] (默认值: 0.5)

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

columnspacingfloat，默认值: rcParams["legend.columnspacing"] (默认值: 2.0)

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

handler_map字典或 None

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

draggable布尔值，默认值：False

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

另请参阅

Axes.legend

备注

此函数不支持某些艺术对象。详见图例指南。