Matplotlib 3.8.0 新特性（2023年9月13日）#
有关自上次修订以来的所有问题和拉取请求列表，请参阅 GitHub 3.11.0 版本统计信息 (2026年6月11日)。
类型提示（Type Hints）#
Matplotlib 现在为大多数公共 API 提供了一流的 PEP484 风格类型提示文件。
虽然它们仍被视为试验性并可能发生变化（有时我们无法完全指定我们想要的内容），但它们应为类型检查许多常见使用模式以及与编辑器/IDE 集成提供合理的基础。
绘图和注释改进#
支持自定义文本和注释的抗锯齿功能#
matplotlib.pyplot.annotate() 和 matplotlib.pyplot.text() 现在支持 antialiased 参数。当 antialiased 设置为 True 时，将对文本应用抗锯齿；当设置为 False 时，不应用。若未指定，则在创建 Text 和 Annotation 对象时，抗锯齿由 rcParams["text.antialiased"]（默认值：True）决定。示例
mpl.text.Text(.5, .5, "foo\nbar", antialiased=True)
plt.text(0.5, 0.5, '6 inches x 2 inches', antialiased=True)
ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5), antialiased=False)
如果文本包含数学表达式，antialiased 将应用于整个文本。示例
# no part will be antialiased for the text below
plt.text(0.5, 0.25, r"$I'm \sqrt{x}$", antialiased=False)
另请注意，刻度标签的抗锯齿功能在创建（通常是创建 Figure 时）即由 rcParams["text.antialiased"]（默认值：True）决定，之后无法更改。
此外，使用此新功能时，请确保在相同的上下文中创建和保存/展示图形。
# previously this was a no-op, now it is what works
with rccontext(text.antialiased=False):
fig, ax = plt.subplots()
ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5))
fig.savefig('/tmp/test.png')
# previously this had an effect, now this is a no-op
fig, ax = plt.subplots()
ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5))
with rccontext(text.antialiased=False):
fig.savefig('/tmp/test.png')
用于 AutoMinorLocator 分割的 rcParams#
新增 rcParams rcParams["xtick.minor.ndivs"]（默认：'auto'）和 rcParams["ytick.minor.ndivs"]（默认：'auto'），用于设置默认分割数量；如果设置为 auto，分割数量将根据主刻度之间的距离自动选择。
Axline 的设置器和获取器#
由 axes.Axes.axline 返回的对象现在支持为其 xy1、xy2 和 slope 属性使用获取器和设置器方法。
line1.get_xy1()
line1.get_slope()
line2.get_xy2()
line1.set_xy1(.2, .3)
line1.set_slope(2.4)
line2.set_xy2(.1, .6)
等高线图的剪裁功能#
contour 和 contourf 现在接受 clip_path 参数。
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.patches as mpatches
x = y = np.arange(-3.0, 3.01, 0.025)
X, Y = np.meshgrid(x, y)
Z1 = np.exp(-X**2 - Y**2)
Z2 = np.exp(-(X - 1)**2 - (Y - 1)**2)
Z = (Z1 - Z2) * 2
fig, ax = plt.subplots()
patch = mpatches.RegularPolygon((0, 0), 5, radius=2,
transform=ax.transData)
ax.contourf(X, Y, Z, clip_path=patch)
plt.show()
Axes.ecdf#
一个新的 Axes 方法 ecdf，允许在不进行任何分箱（binning）的情况下绘制经验累积分布函数。
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots()
ax.ecdf(np.random.randn(100))
Figure.get_suptitle(), Figure.get_supxlabel(), Figure.get_supylabel()#
这些方法分别返回由 Figure.suptitle()、Figure.supxlabel() 和 Figure.supylabel() 设置的字符串。
Ellipse.get_vertices(), Ellipse.get_co_vertices()#
这些方法返回椭圆长轴和短轴顶点的坐标。此外，还增加了一个示例库演示，展示了如何向椭圆添加箭头以显示其顺时针或逆时针旋转。为了将箭头精确放置在椭圆上，使用了顶点的坐标。
移除 label_outer() 中的内部刻度#
到目前为止，label_outer() 仅移除了刻度标签，刻度线仍然可见。现在可以通过新参数 label_outer(remove_inner_ticks=True) 进行配置。
import numpy as np
import matplotlib.pyplot as plt
x = np.linspace(0, 2 * np.pi, 100)
fig, axs = plt.subplots(2, 2, sharex=True, sharey=True,
gridspec_kw=dict(hspace=0, wspace=0))
axs[0, 0].plot(x, np.sin(x))
axs[0, 1].plot(x, np.cos(x))
axs[1, 0].plot(x, -np.cos(x))
axs[1, 1].plot(x, -np.sin(x))
for ax in axs.flat:
ax.grid(color='0.9')
ax.label_outer(remove_inner_ticks=True)
可配置的图例阴影#
图例的 shadow 参数现在除了布尔值外还接受字典。字典可以包含 patches.Patch 的任何关键字。例如，这允许设置图例阴影的颜色和/或透明度，
ax.legend(loc='center left', shadow={'color': 'red', 'alpha': 0.5})
并控制阴影位置。
ax.legend(loc='center left', shadow={"ox":20, "oy":-20})
目前不支持通过 rcParams["legend.shadow"]（默认：False）进行配置。
MultipleLocator 的 offset 参数#
现在可以指定一个 offset 来按给定值平移所有刻度。
import matplotlib.pyplot as plt
import matplotlib.ticker as mticker
_, ax = plt.subplots()
ax.plot(range(10))
locator = mticker.MultipleLocator(base=3, offset=0.3)
ax.xaxis.set_major_locator(locator)
plt.show()
添加新的有效颜色格式 (matplotlib_color, alpha)#
import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle
fig, ax = plt.subplots()
rectangle = Rectangle((.2, .2), .6, .6,
facecolor=('blue', 0.2),
edgecolor=('green', 0.5))
ax.add_patch(rectangle)
用户可以使用新的颜色规范 (matplotlib_color, alpha) 定义颜色。注意，显式的 alpha 关键字参数将覆盖 (matplotlib_color, alpha) 中的 alpha 值。
饼图阴影可被控制#
PolyQuadMesh：用于绘制四边形网格的新类#
pcolor 此前返回一个扁平化的 PolyCollection。现在，我们返回一个 PolyQuadMesh，它结合了二维数组和网格坐标处理的实用性，同时继承了 PolyCollection 的绘图方法，相比 pcolormesh 返回的常规 QuadMesh，它提供了更多的渲染属性控制。新类是 PolyCollection 的子类，因此行为与以前保持一致。
阴影的深浅（shade）可被控制#
Shadow 补丁现在有一个 shade 参数来控制阴影的黑暗程度。如果为 1，则阴影为黑色；如果为 0，则阴影与被阴影化的补丁颜色相同。默认值由以前的固定值变为 0.7。
SpinesProxy 现在支持调用 set() 方法#
现在可以调用例如 ax.spines[:].set(visible=False)。
允许通过关键字参数设置刻度标签字体#
Axes.tick_params 现在接受 labelfontfamily 关键字，可将刻度标签字体与其他文本对象分开修改。
Axis.tick_params(labelfontfamily='monospace')
Figure、Axes 和 Legend 布局#
savefig 的 pad_inches="layout" 选项#
当使用受限或压缩布局时，
savefig(filename, bbox_inches="tight", pad_inches="layout")
现在将使用布局引擎上定义的填充大小。
添加用于修改 Legend 位置的公共方法#
Legend 的位置现在可以在定义后进行调整。
from matplotlib import pyplot as plt
fig = plt.figure()
ax = fig.add_subplot(1, 1, 1)
x = list(range(-100, 101))
y = [i**2 for i in x]
ax.plot(x, y, label="f(x)")
ax.legend()
ax.get_legend().set_loc("right")
# Or
# ax.get_legend().set(loc="right")
plt.show()
rcParams['legend.loc'] 现在接受浮点数元组输入#
rcParams["legend.loc"]（默认：'best'）现在接受浮点数元组输入，与 Legend 的 loc 关键字参数一致，允许用户更灵活、更一致地设置图例位置。
Mathtext 改进#
对 Matplotlib 原生的类 TeX 数学解析器 Mathtext 进行了改进（参见 书写数学表达式，不要与直接使用 LaTeX 混淆：使用 LaTeX 进行文本渲染）。
Boldsymbol mathtext 命令 \boldsymbol#
支持在 mathtext 中使用 \boldsymbol{} 命令。
要将符号加粗，请按如下所示将文本括在字体命令中：
r'$\boldsymbol{a+2+\alpha}$'
mathtext 拥有更多可变大小的分隔符#
添加了 \lgroup 和 \rgroup 可变大小分隔符。
以下分隔符名称之前已支持，但现在可以使用 \left 和 \right 进行大小调整：
\lbrace,\rbrace,\leftbrace, 和\rightbrace\lbrack和\rbrack\leftparen和\rightparen
使用它们确实没有明显优势，添加它们仅为了完整性。
mathtext 文档改进#
文档已更新，直接从解析器获取信息。这意味着（几乎）所有受支持的符号、运算符等都会显示在 书写数学表达式 中。
mathtext 现在支持 \substack#
\substack 可用于在方程式内创建多行下标或上标。
使用时按如下方式将数学内容括在 substack 命令中：
r'$\sum_{\substack{1\leq i\leq 3\\ 1\leq j\leq 5}}$'
mathtext 现在支持 \middle 分隔符#
添加了 \middle 分隔符，现在可以与 \left 和 \right 分隔符配合使用。
使用时按如下方式将其括在 \left 和 \right 分隔符命令之间：
r'$\left( \frac{a}{b} \middle| q \right)$'
mathtext 运算符#
在使用 Unicode 字体时，新增并修正了许多运算符。此外，对之前的一些运算符增加了正确的间距。特别是 \gnapprox, \lnapprox, \leftangle 和 \rightangle 所用的字符已得到修正。
mathtext 间距修正#
作为文档更新的结果，许多关系运算符和符号被重新分类，因此现在可以正确排布间距。
mathtext 现在支持 \text#
\text 可用于在方程式内获取直立文本以及获得普通的破折号 (-)。
import matplotlib.pyplot as plt
plt.text(0.1, 0.5, r"$a = \sin(\phi) \text{ such that } \phi = \frac{x}{y}$")
plt.text(0.1, 0.3, r"$\text{dashes (-) are retained}$")
粗斜体 mathtext 命令 \mathbfit#
支持在 mathtext 中使用 \mathbfit{} 命令使用粗斜体字型。
要将字体更改为粗斜体，请按如下所示将文本括在字体命令中：
r'$\mathbfit{\eta \leq C(\delta(\eta))}$
3D 绘图改进#
指定 3D 绘图的刻度和轴标签位置#
现在可以指定 3D 绘图的刻度和轴标签位置。
import matplotlib.pyplot as plt
positions = ['lower', 'upper', 'default', 'both', 'none']
fig, axs = plt.subplots(2, 3, figsize=(12, 8),
subplot_kw={'projection': '3d'})
for ax, pos in zip(axs.flatten(), positions):
for axis in ax.xaxis, ax.yaxis, ax.zaxis:
axis.set_label_position(pos)
axis.set_ticks_position(pos)
title = f'position="{pos}"'
ax.set(xlabel='x', ylabel='y', zlabel='z', title=title)
axs[1, 2].axis('off')
3D 悬停坐标#
3D 绘图中显示的 x、y、z 坐标此前显示的是无意义数值。现已修复，可直接报告鼠标光标下方视图平面上的坐标。这在沿主轴方向查看 3D 绘图（使用正交投影）或将 2D 绘图投影到 3D 轴平面上时最有用。注意，仍无法直接显示已绘制数据点的坐标。
其他改进#
macosx：新图形可以在窗口或标签页中打开#
新增一个 rcParams["macosx.window_mode"]（默认：'system'）来控制如何使用 macosx 后端打开新图形。默认值为 system（使用系统设置），也可以指定 tab 或 window 来明确选择打开新图形的模式。
matplotlib.mpl_toolkits 现在是一个隐式命名空间包#
随着 setuptools 67.3.0 中 pkg_resources.declare_namespace 的弃用，matplotlib.mpl_toolkits 现在遵循 PEP 420，实现为隐式命名空间。
Plot Directive 现在可以使用 "srcset" 创建响应式图像#
plot sphinx 指令（matplotlib.sphinxext.plot_directive，在 rst 中调用为 .. plot::）可以配置为自动生成更高分辨率的图形，并将其添加到构建的 html 文档中。在 conf.py 中：
extensions = [
...
'matplotlib.sphinxext.plot_directive',
'matplotlib.sphinxext.figmpl_directive',
...]
plot_srcset = ['2x']
将生成双倍分辨率的 png 文件以适应 hiDPI 显示器。生成的 html 文件将包含如下图片条目：
<img src="../_images/nestedpage-index-2.png" style="" srcset="../_images/nestedpage-index-2.png, ../_images/nestedpage-index-2.2x.png 2.00x" alt="" class="plot-directive "/>