Matplotlib 3.5.0 (2021年11月15日) 的新功能 #

有关自上次修订以来的所有问题和拉取请求列表，请参阅 GitHub 3.11.0 版本统计信息 (2026年6月11日)。

Figure 和 Axes 的创建/管理 #

Figure 现在拥有 `draw_without_rendering` 方法 #

图形的某些方面（例如文本对象的精确位置或自动数据限制等延迟计算）仅在绘制时确定。如果您需要这些值，可以使用 figure.canvas.draw() 强制进行完整绘制。然而，这会有副作用，有时需要打开文件，并且执行的工作量超过了实际需求。

新的 Figure.draw_without_rendering 方法会运行 draw() 所做的所有更新，但会跳过图形的实际渲染。因此，如果您需要更新后的值来配置图形的后续内容，这种方法效率更高。

Figure `init` 将关键字参数传递给 set #

与 Artist 的许多其他子类一样，FigureBase、SubFigure 和 Figure 类现在会将任何额外的关键字参数传递给 set，从而允许在初始化时设置新创建对象的属性。例如

from matplotlib.figure import Figure
fig = Figure(label='my figure')

绘图方法 #

添加 `Annulus` 补丁 #

Annulus 是一个用于绘制椭圆环的新类。

(源代码, 2x.png, png)

`FancyArrow` 补丁的 `set_data` 方法 #

FancyArrow（由 ax.arrow 返回的补丁）现在拥有一个 set_data 方法，允许在创建后修改箭头，例如用于动画制作。

`ArrowStyle` 和 `ConnectionPatch` 中的新箭头样式 #

ArrowStyle 中的新 arrow 参数替代了创建箭头时使用的 beginarrow 和 endarrow 参数。它接收诸如 '<-'、']-[' 和 ']->' 等箭头字符串，而不是独立的布尔值。

通过这种机制还添加了两种新样式 ']->' 和 '<-['。ConnectionPatch（通过其 arrowstyle 参数接受箭头样式）也支持这些新样式。

(源代码, 2x.png, png)

初始化后设置集合偏移变换 #

新增的 collections.Collection.set_offset_transform 可用于在初始化后设置偏移变换。这在 Axes 对象之外创建 collections.Collection，随后使用 Axes.add_collection() 添加并将其偏移变换设置为 Axes.transData 时非常有用。

颜色和色彩映射表 #

色彩映射表注册中心（实验性）#

现在可以通过 matplotlib.colormaps（或 pyplot.colormaps）管理色彩映射表，它是一个 ColormapRegistry。虽然我们确信该 API 已经定型，但我们在 3.5 版本中将其正式标记为“实验性”，因为我们希望保留在 3.6 版本中根据需要修改 API 的选择权。

可以使用项访问 (item access) 获取色彩映射表

import matplotlib.pyplot as plt
cmap = plt.colormaps['viridis']

要注册新的色彩映射表，请使用

plt.colormaps.register(my_colormap)

我们建议在新代码中使用此新 API，而不是 matplotlib.cm.get_cmap 和 matplotlib.cm.register_cmap 函数。matplotlib.cm.get_cmap 和 matplotlib.cm.register_cmap 最终将被弃用并删除。在 pyplot 中，为了向后兼容，plt.get_cmap() 和 plt.register_cmap() 将继续得到支持。

现在可以在 RGBA 阶段进行图像插值 #

通过 imshow 创建的 Matplotlib 图像会被重采样以匹配当前画布的分辨率。在下采样时应用抗锯齿滤镜以减少摩尔纹效果是非常有用的。默认情况下，插值是在数据上执行的，然后应用范数，最后执行色彩映射。

然而，通常希望抗锯齿插值在 RGBA 空间中进行，即对颜色进行插值而不是对原始数据进行插值。这通常会导致超出色彩映射表范围的颜色，但在视觉上能更好地混合相邻颜色，这也正是浏览器和其他图像处理软件的做法。

为 imshow 提供了一个新的关键字参数 interpolation_stage，用于设置执行抗锯齿插值的阶段。默认值是当前的“数据”（data）行为，另一种选择是“rgba”，即新提供的行为。

../../_images/sphx_glr_image_antialiasing_001.png — 插值阶段选项示例。#

有关更多详细信息，请参阅图像重采样中关于新关键字参数的讨论。

`imshow` 支持半精度浮点数组 #

imshow 方法现在支持半精度浮点数组，即数据类型为 np.float16 的 NumPy 数组。

已向 Normalize 对象添加回调注册中心 #

colors.Normalize 对象现在拥有一个回调注册中心 callbacks，其他对象可以连接到该注册中心，以便在范数（norm）更新时收到通知。当范数被修改时，回调会发出 changed 键。 cm.ScalarMappable 现在是一个监听者，当范数的 vmin、vmax 或其他属性发生更改时，它会注册一个变更。

标题、刻度和标签 #

在 `set_ticks` 中同时设置刻度位置和标签 #

Axis.set_ticks（以及相应的 Axes.set_xticks / Axes.set_yticks）具有一个新参数 labels，允许同时设置刻度位置和标签。

以前，设置刻度标签是使用 Axis.set_ticklabels（或相应的 Axes.set_xticklabels / Axes.set_yticklabels）完成的；这通常只有在刻度位置通过 set_ticks 事先固定时才有意义。

ax.set_xticks([1, 2, 3])
ax.set_xticklabels(['a', 'b', 'c'])

组合功能现在在 set_ticks 中提供。

ax.set_xticks([1, 2, 3], ['a', 'b', 'c'])

不鼓励使用 Axis.set_ticklabels，但为了向后兼容，它将保持可用。

注：此添加使得 set_ticks 的 API 与已经具有额外 labels 参数的 pyplot.xticks / pyplot.yticks 更加相似。

字体和文本 #

三点和四点数学文本重音 #

除了单点和双点重音外，数学文本现在还支持三点和四点重音。

fig = plt.figure(figsize=(3, 1))
fig.text(0.5, 0.5, r'$\dot{a} \ddot{b} \dddot{c} \ddddot{d}$', fontsize=40,
         horizontalalignment='center', verticalalignment='center')

(源代码, 2x.png, png)

图例标题的字体属性可配置 #

标题的字体属性可以通过 title_fontproperties 关键字参数进行设置，例如

(源代码, 2x.png, png)

`Text` 和 `TextBox` 添加了 parse_math 选项 #

Text 和 TextBox 对象现在允许一个仅限关键字参数 parse_math，它控制是否应从显示的字符串中解析数学内容。如果为 True，字符串将作为数学文本对象进行解析。如果为 False，字符串将被视为字面量，不会进行任何解析。

简化 usetex 模式的字体设置 #

现在 rcParams["font.family"]（默认值：['sans-serif']）接受某些字体名称作为值，以提供更人性化的设置。

plt.rcParams.update({
    "text.usetex": True,
    "font.family": "Helvetica"
})

PDF/PS 后端现已启用 Type 42 子集嵌入 #

backend_pdf 和 backend_ps 现在借助 fontTools 使用统一的 Type 42 字体子集嵌入接口。

将 rcParams["pdf.fonttype"]（默认值：3）或 rcParams["ps.fonttype"]（默认值：3）设置为 42 以触发此工作流。

# for PDF backend
plt.rcParams['pdf.fonttype'] = 42

# for PS backend
plt.rcParams['ps.fonttype'] = 42

fig, ax = plt.subplots()
ax.text(0.4, 0.5, 'subsetted document is smaller in size!')

fig.savefig("document.pdf")
fig.savefig("document.ps")

rcParams 改进 #

允许全局设置默认图例标签颜色 #

新的 rcParams["legend.labelcolor"]（默认值：'None'）设置 Figure.legend 的默认 labelcolor 参数。特殊值 'linecolor'、'markerfacecolor'（或 'mfc'）或 'markeredgecolor'（或 'mec'）将使图例文本颜色与标记对应的颜色相匹配。

(源代码, 2x.png, png)

3D Axes 改进 #

Axes3D 现在允许手动控制绘制顺序 #

Axes3D 类现在具有 computed_zorder 参数。当设置为 False 时，Artist 对象将使用其 zorder 属性进行绘制。

(源代码, 2x.png, png)

允许在 3d 绘图中更改垂直轴 #

view_init 现在有一个 vertical_axis 参数，允许切换哪个轴垂直对齐。

(源代码, 2x.png, png)

`plot_surface` 支持掩码数组和 NaNs #

axes3d.Axes3D.plot_surface 支持掩码数组和 NaNs，现在会隐藏包含掩码或 NaN 点的四边形。其行为类似于 corner_mask=True 的 Axes.contour。

(源代码, 2x.png, png)

3D 绘图方法支持 data 关键字参数 #

为了匹配所有 2D 绘图方法，3D Axes 现在支持 data 关键字参数。这允许从 DataFrame 类结构中通过引用间接传递参数。

data = {  # A labelled data set, or e.g., Pandas DataFrame.
    'x': ...,
    'y': ...,
    'z': ...,
    'width': ...,
    'depth': ...,
    'top': ...,
}

fig, ax = plt.subplots(subplot_kw={'projection': '3d')
ax.bar3d('x', 'y', 'z', 'width', 'depth', 'top', data=data)

交互式工具改进 #

颜色条现具有平移和缩放功能 #

带有颜色条的交互式绘图现在可以在颜色条轴上进行缩放和平移。这将调整与颜色条关联的 ScalarMappable 的 vmin 和 vmax。目前此功能仅针对连续范数启用。与 contourf 和分类数据一起使用的范数（例如 BoundaryNorm 和 NoNorm）默认禁用此交互能力。cb.ax.set_navigate() 可用于设置颜色条轴是否可交互。

更新了滑块小部件的外观 #

更新了 Slider 和 RangeSlider 小部件的外观，并为添加的手柄提供了新的样式参数。

(源代码, 2x.png, png)

删除 PolygonSelector 上的点 #

在完成 PolygonSelector 后，现在可以通过右键点击单个点来将其删除。

拖动选择器 #

SpanSelector、RectangleSelector 和 EllipseSelector 拥有一个新的关键字参数 drag_from_anywhere，设置为 True 时，允许您点击并在选择器内的任何位置进行拖动以移动它。以前，只能通过激活移动修饰符按钮或点击中心手柄来移动它。

SpanSelector 的大小现在可以使用边缘手柄进行更改。

清除选择器 #

选择器（EllipseSelector、LassoSelector、PolygonSelector、RectangleSelector 和 SpanSelector）具有一个新方法 clear，该方法将清除当前选择并使选择器准备好进行新的选择。这等同于按下 escape 键。

设置选择器的 Artist 属性 #

EllipseSelector、LassoSelector、PolygonSelector、RectangleSelector 和 SpanSelector 选择器的 Artist 属性可以使用 set_props 和 set_handle_props 方法进行更改。

忽略选择区域之外的事件 #

EllipseSelector、RectangleSelector 和 SpanSelector 选择器具有一个新关键字参数 ignore_event_outside，设置为 True 时，将忽略当前选择之外的事件。手柄或新的拖动功能可以用来更改选择。

`CallbackRegistry` 对象增加了暂时屏蔽信号的方法 #

上下文管理器 blocked 可用于阻止回调信号被 CallbackRegistry 处理。可选关键字 signal 可用于阻止特定信号被处理，并允许所有其他信号通过。

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.imshow([[0, 1], [2, 3]])

# Block all interactivity through the canvas callbacks
with fig.canvas.callbacks.blocked():
    plt.show()

fig, ax = plt.subplots()
ax.imshow([[0, 1], [2, 3]])

# Only block key press events
with fig.canvas.callbacks.blocked(signal="key_press_event"):
    plt.show()

定向缩放光标 #

画布现在支持设置定向缩放光标，即水平和垂直双箭头。这些光标用于例如选择器小部件中。请尝试鼠标光标示例，查看在您所需后端下的光标样式。

Sphinx 扩展 #

后端特定改进 #

GTK 后端 #

增加了对 GTK4 的支持。Agg 和 Cairo 渲染器均受支持。GTK4 后端可以选择为 GTK4Agg 或 GTK4Cairo。

Qt 后端 #

增加了对 Qt6（使用 PyQt6 或 PySide6）的支持，均可选择 Agg 或 Cairo 渲染器。同时，对 Qt4 的支持已被放弃。Qt6 和 Qt5 均由组合后端（QtAgg 或 QtCairo）支持，加载的版本由已导入的模块、QT_API 环境变量以及可用软件包决定。详情请参阅 Qt 绑定。版本化的 Qt5 后端名称（Qt5Agg 或 Qt5Cairo）仍保留以实现向后兼容。

Cairo、GTK 和 Tk 后端中的 HiDPI 支持 #

GTK3 后端现在完全支持 HiDPI，包括混合显示器情况（仅限 Wayland）。新添加的 GTK4 后端也支持 HiDPI。

TkAgg 后端现在仅在 Windows 上支持 HiDPI，包括混合显示器情况。

所有基于 Cairo 的后端都像它们的 Agg 对应后端一样正确支持 HiDPI（即如果工具包支持 HiDPI，则 Cairo 后端现在也会支持，否则不支持）。