Matplotlib 3.1 新特性（2019年5月18日）#

有关自上次修订以来的所有问题和拉取请求列表，请参阅 3.10.3 (2025年5月8日) 的 GitHub 统计数据。

新特性#

ConciseDateFormatter#

默认使用的自动日期格式化器可能过于冗长。现在可以访问一个新的格式化器，它尝试使刻度标签更加简洁。

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

辅助 x/y 轴支持#

新增方法可以通过 Axes.secondary_xaxis 和 Axes.secondary_yaxis 为现有轴添加第二个轴。有关示例，请参阅 辅助轴。

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

FuncScale 用于任意轴刻度#

新增 FuncScale 类（以及 FuncTransform），允许用户进行任意刻度变换，而无需编写 ScaleBase 的新子类。可以通过以下方式访问：

ax.set_yscale('function', functions=(forward, inverse))

其中 forward 和 inverse 是返回刻度变换及其逆变换的可调用对象。请参阅 刻度概览 中的最后一个示例。

散点图图例#

引入了一种为散点图创建图例的新方法。以前，为了获得 scatter() 图的图例，用户可以绘制多个散点图，每个都有单独的标签，或者手动创建代理艺术家以在图例中显示。现在，PathCollection 提供了一个方法 legend_elements()，可以自动化地获取散点图的句柄和标签。这使得创建散点图图例变得像以下代码一样简单：

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

示例可在 自动图例创建 中找到。

Matplotlib 不再要求在 MacOSX 后端上构建框架应用#

Matplotlib 以前的版本需要 Python 的 Framework 构建才能工作。应用程序类型已更新，不再需要此项，因此 MacOSX 后端应可与非框架 Python 配合使用。

这也增加了对 PyPy3 的 MacOSX 后端的支持。

Figure、FigureCanvas 和后端#

Figure.frameon 现在是 Figure 补丁可见性状态的直接代理#

现在访问 Figure.frameon（包括通过 get_frameon 和 set_frameon）将直接转发到底层 Rectangle 艺术家对象（Figure.patch.get_frameon, Figure.patch.set_frameon）的可见性。

savefig 中新增 pil_kwargs 参数#

Matplotlib 使用 Pillow 处理保存为 JPEG 和 TIFF 格式。 savefig() 函数新增了 pil_kwargs 关键字参数，可用于将参数转发给 Pillow 的 PIL.Image.Image.save 方法。

在保存为 PNG 格式时也可以使用 pil_kwargs 参数。在这种情况下，Matplotlib 也会使用 Pillow 的 PIL.Image.Image.save 方法，而不是通过其内置的 PNG 支持。

向 FigureCanvasBase 添加 inaxes 方法#

The FigureCanvasBase 类现在有一个 inaxes 方法，用于检查一个点是否在一个轴内，并返回最上层的轴，否则返回 None。

cairo 后端默认使用 pycairo 而非 cairocffi#

这在某些情况下可带来更快的导入/运行时性能。如果 pycairo 不可用，后端将回退到 cairocffi。

轴和艺术家对象#

axes_grid1 和 axisartist 轴不再重复绘制边框#

此前，axes_grid1 和 axisartist 轴的边框会被绘制两次，导致其看起来“加粗”。现在不再如此。

ArtistInspector.get_aliases 的返回类型已更改#

ArtistInspector.get_aliases 之前以 {fullname: {alias1: None, alias2: None, ...}} 的形式返回别名集合。在早期版本的 Python 中，这种从字典到 None 的映射被用来模拟集合。现在它已被替换为一个集合，即 {fullname: {alias1, alias2, ...}}。

此值也存储在 ArtistInspector.aliasd 中，该值也已相应更改。

ConnectionPatch 接受任意变换#

除了 "data" 或 "axes fraction" 等字符串外，ConnectionPatch 现在接受任意 Transform 作为 coordsA 和 coordsB 参数的输入。这允许在不同用户定义坐标系中的点之间绘制线条。另请参阅 使用 ConnectionPatch。

mplot3d Line3D 现在支持 {set,get}_data_3d#

使用 mplot3d 中 3D 投影创建的线条现在可以使用 get_data_3d() 访问数据，该方法返回一个包含 (x, y, z) 数据的类似数组的元组。等效的 set_data_3d 可用于修改现有 Line3D 的数据。

Axes3D.voxels 现在为生成的体素着色#

Axes3D.voxels 方法现在接受一个 shade 参数，其默认值为 True。这会根据面的方向对其进行着色，其行为与 plot_trisurf() 和 bar3d() 的匹配参数一致。下图显示了这如何影响输出。

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

轴和刻度#

添加了 Axis.get_inverted 和 Axis.set_inverted#

The Axis.get_inverted and Axis.set_inverted 方法用于查询和设置轴是否使用“反向”方向（即 x 轴向左增加，y 轴向下增加）。

它们执行与 Axes.xaxis_inverted、Axes.yaxis_inverted、Axes.invert_xaxis 和 Axes.invert_yaxis 类似的任务，但具体区别在于 Axis.set_inverted 使得设置轴的反转变得更容易，无论该轴之前是否已被反转过。

调整默认次刻度间距#

主刻度间隔 2.5 单位时，默认次刻度间距从 0.625 更改为 0.5。

EngFormatter 现在接受 usetex、useMathText 作为仅关键字参数#

已向 EngFormatter 添加公共 API，用于控制刻度标签中数字的渲染方式。默认情况下，useMathText 的计算结果为 rcParams["axes.formatter.use_mathtext"] (默认值: False)，usetex 的计算结果为 rcParams["text.usetex"] (默认值: False)。

如果其中任一为 True，则数字将用 $ 符号封装。当使用 TeX 时，这意味着数字将以 TeX 的数学字体显示。当使用 mathtext 时，数字周围的 $ 符号将确保 Unicode 渲染（如 mathtext 所暗示）。这将确保在使用 mathtext 时，刻度中的减号渲染为 Unicode 减号 (U+2212)（不依赖于 fix_minus 方法）。

动画和交互性#

支持鼠标前进/后退按钮#

Figure 管理器现在支持鼠标按钮的 button_press 事件，类似于 key_press 事件。这允许将操作绑定到鼠标按钮（参见 MouseButton）。此机制的首次应用是支持使用 Qt5 后端创建的图形中的鼠标前进/后退按钮。

向 save() 方法添加 progress_callback 参数#

Animation.save 方法新增了一个可选的 progress_callback 参数，用于通知保存进度。

向 animation.FuncAnimation 添加 cache_frame_data 仅关键字参数#

matplotlib.animation.FuncAnimation 默认会缓存帧数据；然而，在某些情况下，这种缓存并不理想，例如当 FuncAnimation 仅需交互式绘制（而非保存）且帧数据所需的内存相当大时。通过添加 cache_frame_data 仅关键字参数，用户现在可以禁用此缓存；因此，此新参数解决了问题 #8528。

使用 PillowWriter 创建无限循环 GIF#

我们认识到大多数人都希望多次观看 GIF。现在使用 PillowWriter 将动画保存为 GIF 将生成无限循环的 GIF。

调整 matplotlib.widgets.Slider 以具有垂直方向#

The matplotlib.widgets.Slider 小部件现在接受一个可选参数 orientation，该参数指示滑块应采取的方向（'horizontal' 或 'vertical'）。

当存在色条时，改进了光标下图像值的格式#

当存在色条时，现在使用其格式化器来格式化状态栏中鼠标光标下的图像值。例如，对于显示值 10,000 和 10,001 的图像，状态栏现在（使用默认设置）将值显示为 10000 和 10001，而以前这两个值都显示为 1e+04。

MouseEvent 的 button 属性现在是 IntEnum 类型#

The button attribute of MouseEvent 实例可以取值 None、1（左键）、2（中键）、3（右键）、“up”（滚动）和“down”（滚动）。为了更好的可读性，现在 1、2 和 3 的值使用 enum.IntEnum 类 matplotlib.backend_bases.MouseButton 表示，其值为 MouseButton.LEFT (== 1)、MouseButton.MIDDLE (== 2) 和 MouseButton.RIGHT (== 3)。

配置、安装和开发#

MATPLOTLIBRC 环境变量现在可以指向任意“文件”路径#

这包括设备文件；特别是在 Unix 系统上，可以将 MATPLOTLIBRC 设置为 /dev/null 以忽略用户的 matplotlibrc 文件并回退到 Matplotlib 的默认设置。

提醒一下，如果 MATPLOTLIBRC 指向一个目录，Matplotlib 将尝试从 $MATPLOTLIBRC/matplotlibrc 加载 matplotlibrc 文件。

允许在 MATPLOTLIBRC 文件中使用 LaTeX 代码 pgf.preamble 和 text.latex.preamble#

此前，rc 文件键 rcParams["pgf.preamble"] (默认值: '') 和 rcParams["text.latex.preamble"] (默认值: '') 是使用逗号作为分隔符进行解析的。这会破坏有效的 LaTeX 代码，例如

\usepackage[protrusion=true, expansion=false]{microtype}

解析方式已修改为将整行传递给 LaTeX 系统，保留所有逗号。从 Python 脚本内部传递字符串列表仍然像以前一样有效。

新的日志 API#

可以调用 matplotlib.set_loglevel / pyplot.set_loglevel 来显示更详细（或更少详细）的日志输出。

在此页