`matplotlib.font_manager`#

一个用于跨平台查找、管理和使用字体的模块。

此模块提供了一个单一的 FontManager 实例，fontManager，可以在后端和平台之间共享。findfont 函数返回本地或系统字体路径中与指定 FontProperties 实例匹配的最佳 TrueType (TTF) 字体文件。FontManager 还处理 Adobe 字体度量 (AFM) 字体文件，供 PostScript 后端使用。FontManager.addfont 函数可以从文件中添加自定义字体，而无需将其安装到操作系统中。

设计基于 W3C 层叠样式表第1级 (CSS1) 字体规范。未来的版本可能会实现第2级或2.1级的规范。

class matplotlib.font_manager.FontManager(size=None, weight='normal')[源代码][源代码]#

基类：object

在导入时，FontManager 单例实例会创建一个 ttf 和 afm 字体的列表，并缓存它们的 FontProperties。FontManager.findfont 方法会进行最近邻搜索，以找到最接近指定要求的字体。如果找不到足够好的匹配，则返回默认字体。

使用 FontManager.addfont 方法添加的字体会不会在缓存中持久化；因此，每次导入 Matplotlib 时都需要调用 addfont。只有在无法通过其他方式在操作系统上安装字体时，才应使用此方法。

注释

FontManager.addfont 方法必须在全局的 FontManager 实例上调用。

示例用法:

import matplotlib.pyplot as plt
from matplotlib import font_manager

font_dirs = ["/resources/fonts"]  # The path to the custom font file.
font_files = font_manager.findSystemFonts(fontpaths=font_dirs)

for font_file in font_files:
    font_manager.fontManager.addfont(font_file)

addfont(path)[源代码][源代码]#

将 path 路径下的字体属性缓存，以便 FontManager 可以使用。字体的类型从路径后缀推断。

参数:

路径str 或 path-like

注释

此方法对于在不安装操作系统的情况下添加自定义字体非常有用。有关使用和注意事项，请参见 FontManager 单例实例。

property defaultFont#: !! 由 numpydoc 处理 !!

findfont(prop, fontext='ttf', directory=None, fallback_to_default=True, rebuild_if_missing=True)[源代码][源代码]#

找到最匹配给定字体属性的字体文件路径。

参数:

prop : str 或 FontPropertiesstr 或

要搜索的字体属性。这可以是一个 FontProperties 对象或一个定义 fontconfig 模式的字符串。

fontext{'ttf', 'afm'}, 默认: 'ttf'

字体文件的扩展名：

'ttf': TrueType 和 OpenType 字体 (.ttf, .ttc, .otf)
'afm': Adobe 字体度量 (.afm)

目录str, 可选

fallback_to_default布尔

如果为 True，将在第一次查找硬失败时回退到默认字体系列（通常是“DejaVu Sans”或“Helvetica”）。

rebuild_if_missing布尔

如果第一次匹配似乎指向一个不存在的字体（即字体缓存包含过时的条目），是否重建字体缓存并再次搜索。

返回:

str: 最佳匹配字体的文件名。

注释

这执行了一个最近邻搜索。每个字体都会根据目标字体属性得到一个相似度分数。返回分数最高的第一个字体。如果在某个阈值下没有找到匹配项，则返回默认字体（通常是DejaVu Sans）。

结果会被缓存，因此后续的查找不需要执行O(n)的最近邻搜索。

有关字体查找算法的描述，请参阅 W3C 层叠样式表，第1级文档。

static get_default_size()[源代码][源代码]#: 返回默认字体大小。

get_default_weight()[源代码][源代码]#: 返回默认的字体粗细。

get_font_names()[源代码][源代码]#: 返回可用字体的列表。

score_family(families, family2)[源代码][源代码]#

返回 families 列表中的字体族与字体族名称 family2 之间的匹配分数。

列表头部的精确匹配返回 0.0。

列表中更靠后的匹配将返回介于 0 和 1 之间的值。

没有匹配将返回 1.0。

score_size(size1, size2)[源代码][源代码]#

返回 size1 和 size2 之间的匹配分数。

如果 *size2*（字体文件中指定的尺寸）是 'scalable'，此函数总是返回 0.0，因为可以生成任何字体尺寸。

否则，结果是 size1 和 size2 之间的绝对距离，标准化后使得通常的字体大小范围（6pt - 72pt）将落在 0.0 到 1.0 之间。

score_stretch(stretch1, stretch2)[源代码][源代码]#

返回 stretch1 和 stretch2 之间的匹配分数。

结果是 stretch1 和 stretch2 的 CSS 数值之间的差值的绝对值，标准化在 0.0 和 1.0 之间。

score_style(style1, style2)[源代码][源代码]#

返回 style1 和 style2 之间的匹配分数。

完全匹配返回 0.0。

在 'italic' 和 'oblique' 之间的匹配返回 0.1。

无匹配返回 1.0。

score_variant(variant1, variant2)[源代码][源代码]#

返回 variant1 和 variant2 之间的匹配分数。

完全匹配返回 0.0，否则返回 1.0。

score_weight(weight1, weight2)[源代码][源代码]#

返回 weight1 和 weight2 之间的匹配分数。

如果 weight1 和 weight2 都作为字符串给出并且具有相同的值，则结果为 0.0。

否则，结果是 weight1 和 weight2 的 CSS 数值之间的差的绝对值，归一化在 0.05 和 1.0 之间。

set_default_weight(weight)[源代码][源代码]#: 设置默认字体粗细。初始值为 'normal'。

class matplotlib.font_manager.FontProperties(family=None, style=None, variant=None, weight=None, stretch=None, size=None, fname=None, math_fontfamily=None)[源代码][源代码]#

基类：object

用于存储和操作字体属性的类。

字体属性是 W3C 层叠样式表第1级字体规范中描述的六个属性，以及用于数学字体的 math_fontfamily：

family: 字体名称列表，按优先级递减顺序排列。列表项可以包括通用字体族名称，如 'sans-serif', 'serif', 'cursive', 'fantasy', 或 'monospace'。在这种情况下，实际使用的字体将在 findfont 的搜索过程中从关联的 rcParam 中查找。默认值: rcParams["font.family"] (default: ['sans-serif'])
style: 可以是 'normal', 'italic' 或 'oblique'。默认值: rcParams["font.style"] (default: 'normal')
variant: 可以是 'normal' 或 'small-caps'。默认值: rcParams["font.variant"] (default: 'normal')
stretch: 一个数值在0-1000范围内，或以下之一：'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded' 或 'ultra-expanded'。默认值：rcParams["font.stretch"] (default: 'normal')
weight: 一个数值范围在0-1000之间的数字值，或者是以下之一：'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'。默认值：rcParams["font.weight"] (default: 'normal')
size: 可以是相对值 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large' 或绝对字体大小，例如 10。默认值: rcParams["font.size"] (default: 10.0)
math_fontfamily: 用于渲染数学文本的字体族。支持的值有：'dejavusans', 'dejavuserif', 'cm', 'stix', 'stixsans' 和 'custom'。默认值：rcParams["mathtext.fontset"] (default: 'dejavusans')

或者，可以通过使用 fname kwarg 指定字体文件的绝对路径来指定字体。然而，在这种情况下，通常更简单的方法是将路径（作为 pathlib.Path，而不是 str）传递给 Text 对象的 font kwarg。

推荐的字体大小用法是使用相对值，例如 'large'，而不是绝对字体大小，例如 12。这种方法允许根据字体管理器的默认字体大小调整所有文本的大小。

此类接受一个作为 fontconfig 模式的位置字符串，或者作为关键字参数的单个属性:

FontProperties(pattern)
FontProperties(*, family=None, style=None, variant=None, ...)

此支持不依赖于 fontconfig；我们只是借用其模式语法在此处使用。

请注意，Matplotlib 的内部字体管理器和 fontconfig 使用不同的算法来查找字体，因此相同模式的结果在 Matplotlib 中可能与其他使用 fontconfig 的应用程序不同。

copy()[源代码][源代码]#: 返回 self 的副本。

get_family()[源代码][源代码]#

返回一个单独的字体族名称或通用族名称的列表。

字体族或通用字体族（在搜索匹配字体时，将从各自的 rcParams 解析），按优先顺序排列。

get_file()[源代码][源代码]#: 返回关联字体的文件名。

get_fontconfig_pattern()[源代码][源代码]#

获取一个适合使用 fontconfig 的 fc-match 工具查找指定字体的 fontconfig pattern。

此支持不依赖于 fontconfig；我们只是借用其模式语法在此处使用。

get_math_fontfamily()[源代码][源代码]#

返回用于数学文本的字体族名称。

默认字体是 rcParams["mathtext.fontset"] (default: 'dejavusans')。

get_name()[源代码][源代码]#: 返回最匹配字体属性的字体名称。

get_size()[源代码][源代码]#: 返回字体大小。

get_size_in_points()[源代码]#: 返回字体大小。

get_slant()[源代码]#: 返回字体样式。值为：'normal'、'italic' 或 'oblique'。

get_stretch()[源代码][源代码]#: 返回字体拉伸或宽度。选项包括：'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'。

get_style()[源代码][源代码]#: 返回字体样式。值为：'normal'、'italic' 或 'oblique'。

get_variant()[源代码][源代码]#: 返回字体变体。值为：'normal' 或 'small-caps'。

get_weight()[源代码][源代码]#: 设置字体粗细。选项包括：0-1000范围内的数值，或以下之一：'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'

set_family(family)[源代码][源代码]#: 更改字体族。可以是别名（在CSS术语中称为通用名称），例如：'serif'、'sans-serif'、'cursive'、'fantasy' 或 'monospace'，也可以是实际字体名称或实际字体名称列表。当 rcParams["text.usetex"] (default: False) 为 True 时，不支持实际字体名称。默认值：rcParams["font.family"] (default: ['sans-serif'])

set_file(file)[源代码][源代码]#: 设置要使用的字体文件的文件名。在这种情况下，所有其他属性将被忽略。

set_fontconfig_pattern(pattern)[源代码][源代码]#

通过解析一个 fontconfig 模式来设置属性。

此支持不依赖于 fontconfig；我们只是借用其模式语法在此处使用。

set_math_fontfamily(fontfamily)[源代码][源代码]#

设置数学模式中文本的字体族。

如果没有明确设置，将使用 rcParams["mathtext.fontset"] (default: 'dejavusans')。

参数:

字体家族str

字体家族的名称。

可用的字体族在默认的 matplotlibrc 文件中定义。

参见

text.Text.get_math_fontfamily

set_name(family)[源代码]#: 更改字体族。可以是别名（在CSS术语中称为通用名称），例如：'serif'、'sans-serif'、'cursive'、'fantasy' 或 'monospace'，也可以是实际字体名称或实际字体名称列表。当 rcParams["text.usetex"] (default: False) 为 True 时，不支持实际字体名称。默认值：rcParams["font.family"] (default: ['sans-serif'])

set_size(size)[源代码][源代码]#

设置字体大小。

参数:

size : float 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, 默认值: rcParams["font.size"] (default: 10.0)浮点数或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}，默认值：: 如果是一个浮点数，表示字体大小（以点为单位）。字符串值表示相对于默认字体大小的尺寸。

set_slant(style)[源代码]#

设置字体样式。

参数:

样式 : {'正常', '斜体', '倾斜'}, 默认值: rcParams["font.style"] (default: 'normal'){'normal', 'italic', 'oblique'}, 默认:

set_stretch(stretch)[源代码][源代码]#

设置字体拉伸或宽度。

参数:

stretch : int 或 {'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}, 默认值: rcParams["font.stretch"] (default: 'normal')int 或 {'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}，默认值：: 如果是整数，必须在 0-1000 范围内。

set_style(style)[源代码][源代码]#

设置字体样式。

参数:

样式 : {'正常', '斜体', '倾斜'}, 默认值: rcParams["font.style"] (default: 'normal'){'normal', 'italic', 'oblique'}, 默认:

set_variant(variant)[源代码][源代码]#

设置字体变体。

参数:

variant : {'normal', 'small-caps'}, 默认值: rcParams["font.variant"] (default: 'normal'){'normal', 'small-caps'}, 默认:

set_weight(weight)[源代码][源代码]#

设置字体粗细。

参数:

weight : int 或 {'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}，默认值: rcParams["font.weight"] (default: 'normal')int 或 {'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}，默认值：: 如果是整数，必须在 0-1000 范围内。

matplotlib.font_manager.afmFontProperty(fontpath, font)[源代码][源代码]#

从 AFM 字体文件中提取信息。

参数:

字体路径str: 与 font 对应的文件名。
字体AFM: 将从中提取信息的 AFM 字体文件。

返回:

FontEntry: 提取的字体属性。

matplotlib.font_manager.findSystemFonts(fontpaths=None, fontext='ttf')[源代码][源代码]#: 在指定的字体路径中搜索字体。如果没有给出路径，将使用一组标准的系统路径，以及如果安装并可用的fontconfig跟踪的字体列表。默认情况下返回TrueType字体列表，AFM字体作为选项。

matplotlib.font_manager.findfont(prop, fontext='ttf', directory=None, fallback_to_default=True, rebuild_if_missing=True)[源代码]#

找到最匹配给定字体属性的字体文件路径。

参数:

prop : str 或 FontPropertiesstr 或

要搜索的字体属性。这可以是一个 FontProperties 对象或一个定义 fontconfig 模式的字符串。

fontext{'ttf', 'afm'}, 默认: 'ttf'

字体文件的扩展名：

'ttf': TrueType 和 OpenType 字体 (.ttf, .ttc, .otf)
'afm': Adobe 字体度量 (.afm)

目录str, 可选

fallback_to_default布尔

如果为 True，将在第一次查找硬失败时回退到默认字体系列（通常是“DejaVu Sans”或“Helvetica”）。

rebuild_if_missing布尔

如果第一次匹配似乎指向一个不存在的字体（即字体缓存包含过时的条目），是否重建字体缓存并再次搜索。

返回:

str: 最佳匹配字体的文件名。

注释

这执行了一个最近邻搜索。每个字体都会根据目标字体属性得到一个相似度分数。返回分数最高的第一个字体。如果在某个阈值下没有找到匹配项，则返回默认字体（通常是DejaVu Sans）。

结果会被缓存，因此后续的查找不需要执行O(n)的最近邻搜索。

有关字体查找算法的描述，请参阅 W3C 层叠样式表，第1级文档。

matplotlib.font_manager.get_font(font_filepaths, hinting_factor=None)[源代码][源代码]#

给定一个文件路径列表，获取一个 ft2font.FT2Font 对象。

参数:

字体文件路径Iterable[str, Path, bytes], str, Path, bytes

要使用的字体文件的相对或绝对路径。

如果是一个单独的字符串、字节或 pathlib.Path，那么它将被视为仅包含该条目的列表。

如果传递了多个文件路径，那么返回的 FT2Font 对象将按照给定的顺序依次遍历这些字体，以找到所需的 glyph。

返回:

ft2font.FT2Font

matplotlib.font_manager.get_font_names()[源代码]#: 返回可用字体的列表。

matplotlib.font_manager.get_fontext_synonyms(fontext)[源代码][源代码]#: 返回一个文件扩展名列表，这些扩展名是给定文件扩展名 fileext 的同义词。

matplotlib.font_manager.is_opentype_cff_font(filename)[源代码][源代码]#: 返回给定的字体是否是一个嵌入在 OpenType 包装器中的 Postscript 紧凑字体格式字体。由无法子集化这些字体的 PostScript 和 PDF 后端使用。

matplotlib.font_manager.json_dump(data, filename)[源代码][源代码]#

将 FontManager 的数据以 JSON 格式转储到名为 文件名 的文件中。

参见

json_load

注释

Matplotlib 数据路径（通常是与 Matplotlib 一起提供的字体）的子文件路径存储在该数据路径的相对位置（以在虚拟环境中保持有效）。

此函数暂时锁定输出文件，以防止多个进程相互覆盖输出。

matplotlib.font_manager.json_load(filename)[源代码][源代码]#

从名为 filename 的 JSON 文件中加载 FontManager。

参见

json_dump

matplotlib.font_manager.list_fonts(directory, extensions)[源代码][源代码]#: 返回一个包含所有匹配扩展名的字体列表，这些字体在目录下递归查找。

matplotlib.font_manager.ttfFontProperty(font)[源代码][源代码]#

从 TrueType 字体文件中提取信息。

参数:

字体 : FT2FontFT2Font: 将从中提取信息的 TrueType 字体文件。

返回:

FontEntry: 提取的字体属性。

matplotlib.font_manager.win32FontDirectory()[源代码][源代码]#

返回用户指定的 Win32 字体目录。这是从注册表项中查找的

\\HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Fonts

如果未找到该键，将返回 %WINDIR%\Fonts。

matplotlib.font_manager.fontManager[源代码]#: FontManager 的全局实例。

class matplotlib.font_manager.FontEntry(fname='', name='', style='normal', variant='normal', weight='normal', stretch='normal', size='medium')[源代码][源代码]#

用于存储字体属性的类。

它在填充字体查找字典时使用。

matplotlib.font_manager#

`matplotlib.font_manager`#