matplotlib.axes.Axes.legend#
- Axes.legend(*args, **kwargs)[源]#
在 Axes 上放置图例。
调用签名
legend() legend(handles, labels) legend(handles=handles) legend(labels)
此方法的调用签名对应以下几种不同用法
1. 自动检测要在图例中显示的元素
当您不传入任何额外参数时，要添加到图例中的元素将自动确定。
在这种情况下，标签取自艺术对象（artist）。您可以在创建艺术对象时指定它们，也可以通过调用艺术对象上的
set_label()方法来指定。ax.plot([1, 2, 3], label='Inline label') ax.legend()
或
line, = ax.plot([1, 2, 3]) line.set_label('Label via method') ax.legend()
注意
通过使用以下划线“_”开头的标签，可以将特定的艺术对象排除在自动图例元素选择之外。以下划线开头的字符串是所有艺术对象的默认标签，因此在不带任何参数且不手动设置标签的情况下调用
Axes.legend将导致UserWarning并绘制一个空图例。2. 显式列出图例中的艺术对象和标签
为了完全控制哪些艺术对象拥有图例条目，可以分别传递一个图例艺术对象的可迭代对象，后跟一个图例标签的可迭代对象。
ax.legend([line1, line2, line3], ['label1', 'label2', 'label3'])
3. 显式列出图例中的艺术对象
这类似于方法2，但标签取自艺术对象的标签属性。示例
line1, = ax.plot([1, 2, 3], label='label1') line2, = ax.plot([1, 2, 3], label='label2') ax.legend(handles=[line1, line2])
4. 为现有绘图元素添加标签
不建议使用
不建议使用此调用签名，因为绘图元素与标签之间的关系仅由它们的顺序隐式决定，很容易混淆。
要为 Axes 上的所有艺术对象创建图例，请使用字符串的可迭代对象调用此函数，每个图例项一个字符串。例如
ax.plot([1, 2, 3]) ax.plot([5, 6, 7]) ax.legend(['First line', 'Second line'])
- 参数:
- handles艺术对象（
Artist或艺术对象元组）列表，可选 要添加到图例中的艺术对象（线条、补丁）列表。如果您需要完全控制图例中显示的内容，并且上述自动机制不足以满足您的需求，请与 labels 一起使用此参数。
在这种情况下，handles 和 labels 的长度应该相同。如果不同，它们将被截断为较小的长度。
如果一个条目包含一个元组，那么元组中所有 Artist 的图例处理器将与单个标签并排放置。
- labels字符串列表, 可选
要显示在艺术对象旁边的标签列表。如果您需要完全控制图例中显示的内容，并且上述自动机制不足以满足您的需求，请与 handles 一起使用此参数。
- handles艺术对象（
- 返回:
- 其他参数:
- loc字符串或浮点数对，默认值：
rcParams["legend.loc"]（默认值：'best'） 图例的位置。
字符串
'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'，并且每个“字符串”位置也可以给定为数字值。位置字符串
位置代码
'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
- bbox_to_anchor
BboxBase、2元组或4元组浮点数 与 loc 结合用于定位图例的框。默认为
axes.bbox（如果作为Axes.legend的方法调用）或figure.bbox（如果调用figure.legend）。此参数允许图例的任意放置。边界框坐标在 bbox_transform 给定的坐标系中解释，默认变换是 Axes 或 Figure 坐标，具体取决于调用的是哪个
legend。如果给定4元组或
BboxBase，则它指定图例放置在的边界框(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 优先。
- propNone 或
FontProperties或 字典 图例的字体属性。如果为 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、布尔值或字典，默认值：
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或 字典 图例标题的字体属性。如果为 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
图例是否可以用鼠标拖动。
- loc字符串或浮点数对，默认值：
另请参阅
备注
此函数不支持某些艺术对象。详见图例指南。
示例
