`matplotlib.font_manager`#

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

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

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

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

基类: object

导入时，FontManager 单例实例会创建 ttf 和 afm 字体列表并缓存其 FontProperties。FontManager.findfont 方法执行最近邻搜索以查找与规范最匹配的字体。如果未找到足够好的匹配项，则返回默认字体。

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

备注

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

示例用法

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)[source]#

缓存 path 处字体的属性，使其可供 FontManager 使用。字体类型从路径后缀推断。

参数:

pathstr 或 path-like

备注

此方法对于添加自定义字体而无需将其安装在您的操作系统中非常有用。有关此函数的用法和注意事项，请参阅 FontManager 单例实例。

property defaultFont#

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

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

参数:

propstr 或 FontProperties

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

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

字体文件的扩展名

'ttf': TrueType 和 OpenType 字体（.ttf、.ttc、.otf）
'afm': Adobe Font Metrics (.afm)

directorystr, 可选

fallback_to_defaultbool

如果为 True，则在首次查找硬失败时，将回退到默认字体家族（通常为 "DejaVu Sans" 或 "Helvetica"）。

rebuild_if_missingbool

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

返回:

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

备注

这执行最近邻搜索。每个字体都会根据目标字体属性获得一个相似度分数。返回第一个得分最高的字体。如果找不到低于特定阈值的匹配项，则返回默认字体（通常为 DejaVu Sans）。

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

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

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

get_default_weight()[source]#: 返回默认字体粗细。

get_font_names()[source]#: 返回可用字体列表。

score_family(families, family2)[source]#

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

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

列表中更靠下的匹配将返回 0 到 1 之间的值。

无匹配返回 1.0。

score_size(size1, size2)[source]#

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

如果 size2（字体文件中指定的大小）是 'scalable'，则此函数始终返回 0.0，因为可以生成任何字体大小。

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

score_stretch(stretch1, stretch2)[source]#

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

结果是 stretch1 和 stretch2 的 CSS 数值之间差的绝对值，归一化到 0.0 和 1.0 之间。

score_style(style1, style2)[source]#

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

精确匹配返回 0.0。

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

无匹配返回 1.0。

score_variant(variant1, variant2)[source]#

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

精确匹配返回 0.0，否则返回 1.0。

score_weight(weight1, weight2)[source]#

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

如果 weight1 和 weight2 都作为字符串给定且值相同，则结果为 0.0。

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

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

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

基类: object

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

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

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

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

字体大小的首选用法是使用相对值，例如 'large'，而不是绝对字体大小，例如 12。这种方法允许所有文本大小根据字体管理器的默认字体大小进行放大或缩小。

此类别接受单个位置字符串作为 fontconfig 模式，或者也可以使用关键字参数的形式提供单个属性。

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

此支持不依赖于 fontconfig；我们只是借用它的模式语法在这里使用。

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

copy()[source]#: 返回自身的副本。

get_family()[source]#

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

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

get_file()[source]#: 返回相关联字体的文件名。

get_fontconfig_pattern()[source]#

获取一个 fontconfig 模式，适用于使用 fontconfig 的 fc-match 工具查找字体。

此支持不依赖于 fontconfig；我们只是借用它的模式语法在这里使用。

get_math_fontfamily()[source]#

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

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

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

get_size()[source]#: 返回字体大小。

get_size_in_points()[source]#: 返回字体大小。

get_slant()[source]#: 返回字体样式。值有：'normal'、'italic' 或 'oblique'。

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

get_style()[source]#: 返回字体样式。值有：'normal'、'italic' 或 'oblique'。

get_variant()[source]#: 返回字体变体。值有：'normal' 或 'small-caps'。

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

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

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

set_fontconfig_pattern(pattern)[source]#

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

此支持不依赖于 fontconfig；我们只是借用它的模式语法在这里使用。

set_math_fontfamily(fontfamily)[source]#

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

如果未明确设置，将使用 rcParams["mathtext.fontset"]（默认值：'dejavusans'）。

参数:

fontfamily字符串

字体族的名称。

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

另请参阅

text.Text.get_math_fontfamily

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

set_size(size)[source]#

设置字体大小。

参数:

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

set_slant(style)[source]#

设置字体样式。

参数:

style{'normal', 'italic', 'oblique'}，默认值：rcParams["font.style"]（默认值：'normal'）

set_stretch(stretch)[source]#

设置字体的伸展或宽度。

参数:

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

set_style(style)[source]#

设置字体样式。

参数:

style{'normal', 'italic', 'oblique'}，默认值：rcParams["font.style"]（默认值：'normal'）

set_variant(variant)[source]#

设置字体变体。

参数:

variant{'normal', 'small-caps'}，默认值：rcParams["font.variant"]（默认值：'normal'）

set_weight(weight)[source]#

设置字体粗细。

参数:

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

matplotlib.font_manager.afmFontProperty(fontpath, font)[source]#

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

参数:

fontpath字符串: 与 font 对应的文件名。
fontAFM: 将从中提取信息的 AFM 字体文件。

返回:

FontEntry: 提取的字体属性。

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

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

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

参数:

propstr 或 FontProperties

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

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

字体文件的扩展名

'ttf': TrueType 和 OpenType 字体（.ttf、.ttc、.otf）
'afm': Adobe Font Metrics (.afm)

directorystr, 可选

fallback_to_defaultbool

如果为 True，则在首次查找硬失败时，将回退到默认字体家族（通常为 "DejaVu Sans" 或 "Helvetica"）。

rebuild_if_missingbool

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

返回:

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

备注

这执行最近邻搜索。每个字体都会根据目标字体属性获得一个相似度分数。返回第一个得分最高的字体。如果找不到低于特定阈值的匹配项，则返回默认字体（通常为 DejaVu Sans）。

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

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

matplotlib.font_manager.get_font(font_filepaths, hinting_factor=None)[source]#

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

参数:

font_filepaths可迭代对象[字符串, 路径, 字节], 字符串, 路径, 字节

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

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

如果传入多个文件路径，则返回的 FT2Font 对象将按给定顺序回退查找所需的字形。

返回:

ft2font.FT2Font

matplotlib.font_manager.get_font_names()[source]#: 返回可用字体列表。

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

matplotlib.font_manager.is_opentype_cff_font(filename)[source]#: 返回给定字体是否为嵌入在 OpenType 包装器中的 Postscript Compact Font Format 字体。由无法对这些字体进行子集化的 PostScript 和 PDF 后端使用。

matplotlib.font_manager.json_dump(data, filename)[source]#

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

另请参阅

json_load

备注

作为 Matplotlib 数据路径子目录的文件路径（通常是 Matplotlib 附带的字体）相对于该数据路径存储（以在不同的虚拟环境中保持有效）。

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

matplotlib.font_manager.json_load(filename)[source]#

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

另请参阅

json_dump

matplotlib.font_manager.list_fonts(directory, extensions)[source]#: 返回在目录下递归找到的所有匹配任何给定扩展名的字体列表。

matplotlib.font_manager.ttfFontProperty(font)[source]#

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

参数:

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

返回:

FontEntry: 提取的字体属性。

matplotlib.font_manager.win32FontDirectory()[source]#

返回 Win32 系统的用户指定字体目录。此目录从注册表键中查找

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

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

matplotlib.font_manager.fontManager[source]#: FontManager 的全局实例。

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

一个用于存储字体属性的类。

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

matplotlib.font_manager#

`matplotlib.font_manager`#