matplotlib.legend_handler

默认的图例处理器。

重要

这是一个低级的图例 API，大多数最终用户不需要使用它。

我们建议您在阅读本文档之前，先熟悉图例指南。

图例处理器应该是一个可调用对象，其签名如下：

legend_handler(legend, orig_handle, fontsize, handlebox)

其中 legend 是图例本身，orig_handle 是原始绘图对象，fontsize 是像素单位的字体大小，handlebox 是一个 OffsetBox 实例。在调用中，您应该创建相关的艺术家对象（使用 legend 和/或 orig_handle 中的相关属性），并将它们添加到 handlebox 中。艺术家对象需要根据 fontsize 进行缩放（请注意，大小以像素为单位，即这是一个经过 DPI 缩放的值）。

此模块包含多个从基类 (HandlerBase) 派生出的图例处理器类的定义，它们包含以下方法：

def legend_artist(self, legend, orig_handle, fontsize, handlebox)

class matplotlib.legend_handler.HandlerBase(xpad=0.0, ypad=0.0, update_func=None)

默认图例处理器的基类。

派生类旨在重写 create_artists 方法，其签名如下：

def create_artists(self, legend, orig_handle,
                   xdescent, ydescent, width, height, fontsize,
                   trans):

被重写的方法需要创建给定变换的艺术家对象，这些对象应符合给定尺寸（xdescent、ydescent、width、height），并在必要时按字体大小进行缩放。

参数:

xpad浮点数，可选

X 方向的填充。

ypad浮点数，可选

Y 方向的填充。

update_func可调用对象，可选

用于从另一个图例处理器更新当前图例处理器属性的函数，由 update_prop 调用。

adjust_drawing_area(legend, orig_handle, xdescent, ydescent, width, height, fontsize)

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

legend_artist(legend, orig_handle, fontsize, handlebox)

返回此 HandlerBase 为给定原始艺术家/句柄生成的艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handlematplotlib.artist.Artist 或类似对象

正在为其创建图例艺术家对象的原始对象。

fontsize整数

字体大小（像素）。正在创建的艺术家对象应根据给定的字体大小进行缩放。

handleboxOffsetBox

为容纳此图例条目的艺术家对象而创建的框。在 legend_artist 方法中创建的艺术家对象必须在此方法内部添加到此 handlebox 中。

update_prop(legend_handle, orig_handle, legend)

class matplotlib.legend_handler.HandlerCircleCollection(yoffsets=None, sizes=None, **kwargs)

CircleCollection 对象的处理器。

参数:

numpoints整数

图例条目中显示的点的数量。

yoffsets浮点数数组

图例条目中每个点的 Y 偏移量列表，长度为 numpoints。

**kwargs

转发给 HandlerNpoints 的关键字参数。

create_collection(orig_handle, sizes, offsets, offset_transform)

class matplotlib.legend_handler.HandlerErrorbar(xerr_size=0.5, yerr_size=None, marker_pad=0.3, numpoints=None, **kwargs)

误差条的处理器。

参数:

marker_pad浮点数

图例条目中点之间的填充。

numpoints整数

图例条目中显示的点的数量。

**kwargs

转发给 HandlerBase 的关键字参数。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

get_err_size(legend, xdescent, ydescent, width, height, fontsize)

class matplotlib.legend_handler.HandlerLine2D(marker_pad=0.3, numpoints=None, **kwargs)

Line2D 实例的处理器。

另请参阅

HandlerLine2DCompound

一个早期的处理器实现，它使用一个艺术家对象表示线条，另一个表示标记。

参数:

marker_pad浮点数

图例条目中点之间的填充。

numpoints整数

图例条目中显示的点的数量。

**kwargs

转发给 HandlerBase 的关键字参数。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

class matplotlib.legend_handler.HandlerLine2DCompound(marker_pad=0.3, numpoints=None, **kwargs)

这是 Line2D 实例的原始处理器，它依赖于将一个仅线条的艺术家与一个仅标记的艺术家结合起来。未来可能会被弃用。

参数:

marker_pad浮点数

图例条目中点之间的填充。

numpoints整数

图例条目中显示的点的数量。

**kwargs

转发给 HandlerBase 的关键字参数。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

class matplotlib.legend_handler.HandlerLineCollection(marker_pad=0.3, numpoints=None, **kwargs)

LineCollection 实例的处理器。

参数:

marker_pad浮点数

图例条目中点之间的填充。

numpoints整数

图例条目中显示的点的数量。

**kwargs

转发给 HandlerBase 的关键字参数。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

get_numpoints(legend)

class matplotlib.legend_handler.HandlerNpoints(marker_pad=0.3, numpoints=None, **kwargs)

一个图例处理器，在图例条目中显示 numpoints 个点。

参数:

marker_pad浮点数

图例条目中点之间的填充。

numpoints整数

图例条目中显示的点的数量。

**kwargs

转发给 HandlerBase 的关键字参数。

get_numpoints(legend)

get_xdata(legend, xdescent, ydescent, width, height, fontsize)

class matplotlib.legend_handler.HandlerNpointsYoffsets(numpoints=None, yoffsets=None, **kwargs)

一个图例处理器，在图例中显示 numpoints 个点，并允许它们在 Y 方向上单独偏移。

参数:

numpoints整数

图例条目中显示的点的数量。

yoffsets浮点数数组

图例条目中每个点的 Y 偏移量列表，长度为 numpoints。

**kwargs

转发给 HandlerNpoints 的关键字参数。

get_ydata(legend, xdescent, ydescent, width, height, fontsize)

class matplotlib.legend_handler.HandlerPatch(patch_func=None, **kwargs)

Patch 实例的处理器。

参数:

patch_func可调用对象，可选

创建图例键艺术家对象的函数。patch_func 应该具有以下签名：

def patch_func(legend=legend, orig_handle=orig_handle,
               xdescent=xdescent, ydescent=ydescent,
               width=width, height=height, fontsize=fontsize)

随后，创建的艺术家对象将调用其 update_prop 方法，并应用适当的变换。

**kwargs

转发给 HandlerBase 的关键字参数。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

class matplotlib.legend_handler.HandlerPathCollection(yoffsets=None, sizes=None, **kwargs)

PathCollection 对象的处理器，此对象由 scatter 使用。

参数:

numpoints整数

图例条目中显示的点的数量。

yoffsets浮点数数组

图例条目中每个点的 Y 偏移量列表，长度为 numpoints。

**kwargs

转发给 HandlerNpoints 的关键字参数。

create_collection(orig_handle, sizes, offsets, offset_transform)

class matplotlib.legend_handler.HandlerPolyCollection(xpad=0.0, ypad=0.0, update_func=None)

PolyCollection 对象的处理器，此对象用于 fill_between 和 stackplot。

参数:

xpad浮点数，可选

X 方向的填充。

ypad浮点数，可选

Y 方向的填充。

update_func可调用对象，可选

用于从另一个图例处理器更新当前图例处理器属性的函数，由 update_prop 调用。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

class matplotlib.legend_handler.HandlerRegularPolyCollection(yoffsets=None, sizes=None, **kwargs)

RegularPolyCollection 对象的处理器。

参数:

numpoints整数

图例条目中显示的点的数量。

yoffsets浮点数数组

图例条目中每个点的 Y 偏移量列表，长度为 numpoints。

**kwargs

转发给 HandlerNpoints 的关键字参数。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

create_collection(orig_handle, sizes, offsets, offset_transform)

get_numpoints(legend)

get_sizes(legend, orig_handle, xdescent, ydescent, width, height, fontsize)

update_prop(legend_handle, orig_handle, legend)

class matplotlib.legend_handler.HandlerStem(marker_pad=0.3, numpoints=None, bottom=None, yoffsets=None, **kwargs)

用于处理由 stem 生成的图表的处理器。

参数:

marker_pad浮点数，默认值：0.3

图例条目中点之间的填充。

numpoints整数，可选

图例条目中显示的点的数量。

bottom浮点数，可选

yoffsets浮点数数组，可选

图例条目中每个点的 Y 偏移量列表，长度为 numpoints。

**kwargs

关键字参数转发至 HandlerNpointsYoffsets。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

get_ydata(legend, xdescent, ydescent, width, height, fontsize)

class matplotlib.legend_handler.HandlerStepPatch(xpad=0.0, ypad=0.0, update_func=None)

StepPatch 实例的处理器。

参数:

xpad浮点数，可选

X 方向的填充。

ypad浮点数，可选

Y 方向的填充。

update_func可调用对象，可选

用于从另一个图例处理器更新当前图例处理器属性的函数，由 update_prop 调用。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

class matplotlib.legend_handler.HandlerTuple(ndivide=1, pad=None, **kwargs)

Tuple 的处理器。

参数:

ndivide整数或 None，默认值：1

图例区域要划分的节数。如果为 None，则使用输入元组的长度。

pad浮点数，默认值：rcParams["legend.borderpad"]（默认值：0.4）

以字体大小分数表示的填充。

**kwargs

转发给 HandlerBase 的关键字参数。

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)

返回生成的图例艺术家对象。

参数:

legendLegend

正在为其创建图例艺术家对象的图例。

orig_handleArtist 或类似对象

正在为其创建图例艺术家对象的原始对象。

xdescent, ydescent, width, height整数

正在创建的图例艺术家对象应适应的矩形区域（xdescent, ydescent, width, height）。

fontsize整数

字体大小（像素）。正在创建的图例艺术家对象应根据给定的字体大小进行缩放。

transTransform

应用于正在创建的图例艺术家对象的变换。通常是从处理器框中的单位坐标到屏幕坐标的变换。

matplotlib.legend_handler.update_from_first_child(tgt, src)