Font#

  • v1.16.18 中新增

该类表示 MuPDF 定义的字体（fz_font_s 结构）。它是新类 TextWriter 和新方法 Page.write_text() 所必需的。目前，它与方法 Page.insert_text() 或 Page.insert_textbox() 的字体使用方式无关。

Font 对象还包含一些有用的常规信息，例如字体的边界框（bbox）、已定义字形的数量、字形名称或单个字形的边界框。

方法 / 属性

简要描述

glyph_advance()

字符宽度

glyph_bbox()

字形矩形

glyph_name_to_unicode()

通过字形名称获取 Unicode

has_glyph()

返回 Unicode 的字形 ID

text_length()

计算字符串长度

char_lengths()

获取字符串中每个字符的宽度元组

unicode_to_glyph_name()

获取 Unicode 对应的字形名称

valid_codepoints()

支持的 Unicode 代码点数组

ascender

字体上升距离

descender

字体下降距离

bbox

字体矩形

buffer

字体二进制数据的副本

flags

字体属性集合

glyph_count

支持的字形数量

name

字体名称

is_bold

如果是粗体，则为 True

is_monospaced

如果是等宽字体，则为 True

is_serif

如果是衬线字体，则为 True，否则为无衬线 (False)

is_italic

如果是斜体，则为 True

Class API

class Font#
__init__(self, fontname=None, fontfile=None,
fontbuffer=None, script=0, language=None, ordering=-1, is_bold=0,
is_italic=0, is_serif=0)

字体构造函数。众多参数用于定位最符合要求的字体。并非所有参数都是必需的 —— 请参考下方伪代码，了解参数的评估逻辑。

参数:

  • fontname (str) –

    其中之一 PDF Base 14 字体 或 CJK 字体名称。此外，还可以使用部分特定的其他字体名称（请注意正确拼写）：”Arial”、”Times”、”Times Roman”。

    (v1.17.5 版本更改)

    如果已安装 pymupdf-fonts，还可以使用新的“保留”字体名称。这些名称列在 fitz_fonts 中，并在下表中列出。

  • fontfile (str) – 系统上的某个字体文件的文件名 [3]。

  • fontbuffer (bytes,bytearray,io.BytesIO) – 加载到内存中的字体文件 [3]。

  • script (int) – UCDN 脚本编号。PyMuPDF 目前支持编号 24 以及 32 到 35。

  • language (str) – 语言代码，可选值包括 “zh-Hant”（繁体中文）、”zh-Hans”（简体中文）、”ja”（日语）和 “ko”（韩语）。此外，还支持所有 ISO 639 代码的子集 1、2、3 和 5，但目前仅作文档记录之用。

  • ordering (int) – 选择 CJK 字体的另一种方式。

  • is_bold (bool) – 查找粗体字体。

  • is_italic (bool) – 查找斜体字体。

  • is_serif (bool) – 查找衬线字体。

返回:

成功时返回一个 MuPDF 字体。以下是确定适用字体的检查顺序：

参数

处理逻辑

fontfile?

从文件创建字体，失败则抛出异常。

fontbuffer?

从缓冲区创建字体，失败则抛出异常。

ordering>=0

创建通用字体，总是成功。

fontname?

创建 Base-14 字体、通用字体或 pymupdf-fonts 提供的字体。请参见下表。

备注

使用常见的保留名称 “helv”、”tiro” 等，可以创建预期名称的字体，如 “Helvetica”、”Times-Roman” 等。然而，与 Page.insert_font() 及类似方法不同：

  • 字体文件 始终 会被嵌入到 PDF 中，

  • 需要希腊字母和西里尔字母时，无需额外指定 encoding 参数。

使用 ordering >= 0，或者指定字体名称为 “cjk”、”china-t”、”china-s”、”japan” 或 “korea”，都会创建相同的“通用”字体——“Droid Sans Fallback Regular”。该字体支持 所有中、日、韩（CJK）字符及拉丁字符，包括希腊字母和西里尔字母。此字体为无衬线体（sans-serif）。

实际上，”Droid Sans Fallback Regular” 已经足够满足大部分无衬线字体需求。唯一例外 是该字体文件较大，压缩后约 1.65 MB，会显著增加 PDF 文件的大小。如果不需要 CJK 支持，可以选择 “helv”、”tiro” 等，这样压缩后仅需约 35 KB。

如果你 确定 文本包含 CJK 和拉丁字符的混合内容，可以考虑直接使用 Font("cjk")，因为它不仅能支持所有字符，还能显著加快渲染速度（最多提高三倍）：MuPDF 只需在该字体中查找字符，而无需检查回退字体。

但如果你选择其他字体，仍然可以自动写入 CJK 字符：MuPDF 会检测到这种情况，并静默回退到通用字体（该字体仍会被嵌入到 PDF 中）。

(v1.17.5 版本新增) 如果安装了 pymupdf-fonts （可通过 pip install pymupdf-fonts 安装），则可以使用一些新的“保留”字体名称代码。”Fira Mono” 是一款等宽无衬线字体，而 FiraGO 是另一款“通用”无衬线字体，支持所有拉丁字符（包括西里尔字母和希腊字母）以及泰文、阿拉伯文、希伯来文和梵文（Devanagari）——但不支持 CJK 语言。相比 “Droid Sans Fallback”，FiraGO 字体的大小仅为其四分之一（压缩后 400 KB vs. 1.65 MB），且 额外提供了粗体、斜体、粗斜体等字重，而通用字体不提供这些特性。

“Space Mono” 是另一款来自 Google Fonts 的小巧等宽字体，支持扩展拉丁字符集，并提供四种主要字重。

下表列出了字体名称代码与对应字体的映射关系。有关当前可用字体的详细内容，请参阅官方文档：

代码

字体名称

New in

备注

figo

FiraGO Regular

v1.0.0

比 Helvetica 更窄

figbo

FiraGO Bold

v1.0.0

figit

FiraGO Italic

v1.0.0

figbi

FiraGO Bold Italic

v1.0.0

fimo

Fira Mono Regular

v1.0.0

fimbo

Fira Mono Bold

v1.0.0

spacemo

Space Mono Regular

v1.0.1

spacembo

Space Mono Bold

v1.0.1

spacemit

Space Mono Italic

v1.0.1

spacembi

Space Mono Bold-Italic

v1.0.1

math

Noto Sans Math Regular

v1.0.2

数学符号

music

Noto Music Regular

v1.0.2

音乐符号

symbol1

Noto Sans Symbols Regular

v1.0.2

“symb” 字体的替代方案

symbol2

Noto Sans Symbols2 Regular

v1.0.2

扩展符号集

notos

Noto Sans Regular

v1.0.3

Helvetica 的替代方案

notosit

Noto Sans Italic

v1.0.3

notosbo

Noto Sans Bold

v1.0.3

notosbi

Noto Sans BoldItalic

v1.0.3
has_glyph(chr, language=None, script=0, fallback=False)#

检查 Unicode 字符 chr 是否存在于该字体或（可选）某个回退字体中。可用于检测输出是否会出现 “TOFU” 符号。

参数:

  • chr (int) – 要检查的字符的 Unicode 码点（即 ord()）。

  • language (str) – 语言 —— 目前未使用。

  • script (int) – UCDN 脚本编号。

  • fallback (bool) – (v1.17.5 新增) 是否执行扩展搜索以包含回退字体，或仅限制在当前字体（默认）。

返回:

(v1.17.7 变更) 返回字符的字形编号。返回 0 表示未找到相应字形。

valid_codepoints()#

  • v1.17.5 新增

返回当前字体支持的 Unicode 码点数组。

返回:

一个 array.array [4]，长度最多为 Font.glyph_count。即：数组中每个元素的 chr() 都有对应的字形，并且未使用回退字体。这是一个示例，展示了支持的字形：

>>> import pymupdf
>>> font = pymupdf.Font("math")
>>> vuc = font.valid_codepoints()
>>> for i in vuc:
      print("%04X %s (%s)" % (i, chr(i), font.unicode_to_glyph_name(i)))
0000
000D   (CR)
0020   (space)
0021 ! (exclam)
0022 " (quotedbl)
0023 # (numbersign)
0024 $ (dollar)
0025 % (percent)
...
00AC ¬ (logicalnot)
00B1 ± (plusminus)
...
21D0 ⇐ (arrowdblleft)
21D1 ⇑ (arrowdblup)
21D2 ⇒ (arrowdblright)
21D3 ⇓ (arrowdbldown)
21D4 ⇔ (arrowdblboth)
...
221E ∞ (infinity)
...

备注

该方法仅对具有 CMAP（字符映射表，charmap，对应 PDF 的 /ToUnicode 键）的字体返回有效数据。否则，该数组的长度将为 1，并且仅包含 0。

glyph_advance(chr, language=None, script=0, wmode=0)#

计算字符字形（视觉表示）的“宽度”。

参数:

  • chr (int) – 字符的 Unicode 码点。请使用 ord()，而不是直接输入字符。即使该字体不支持该字符，该方法通常仍可工作，因为必要时会检查回退字体。

  • wmode (int) – 书写模式，0 = 水平，1 = 垂直。

其他参数目前未使用。

返回:

一个浮点数，表示相对于 字号 1 的字形宽度。

glyph_name_to_unicode(name)#

返回指定字形名称对应的 Unicode 值。如果希望输出特定符号，可与 chr() 结合使用。

参数:

name (str) – 字形名称。

返回:

对应的 Unicode 整数值，或者 65533 = 0xFFFD （如果名称未知）。示例： font.glyph_name_to_unicode("Sigma") = 931 ， font.glyph_name_to_unicode("sigma") = 963 。可参考 Adobe Glyph List 获取字形名称及其对应的 Unicode 编号。示例：

>>> font = pymupdf.Font("helv")
>>> font.has_glyph(font.glyph_name_to_unicode("infinity"))
True

glyph_bbox(chr, language=None, script=0)#

获取相对于 fontsize 1 的字形矩形区域。

参数:

chr (int) – 字符的 ord() 值。

返回:

一个 Rect 对象。

unicode_to_glyph_name(ch)#

获取字符对应的字形名称。

参数:

ch (int) – 字符的 Unicode 码点。请使用 ord()，而不是直接输入字符。

返回:

一个字符串，表示字形名称。例如：font.glyph_name(ord("#")) = "numbersign"。对于无效码点，返回 “.notfound”。

备注

(v1.18.0 变更) 该方法与 Font.glyph_name_to_unicode() 不再依赖特定字体，而是改为从 Adobe Glyph List 获取信息。此外，该方法也可作为 pymupdf.unicode_to_glyph_name() 和 pymupdf.glyph_name_to_unicode() 调用。

text_length(text, fontsize=11)#

计算 Unicode 字符串的长度（单位：点）。

备注

该方法在 Base-14 字体范围内与 get_text_length() 功能重叠。

参数:

  • text (str) – 以 UTF-8 编码的文本字符串。

  • fontsize (float) – 指定的 fontsize。

返回类型:

float

返回:

该字符串存储在 PDF 中的长度（单位：点）。如果某个字符不包含在当前字体中，将自动在回退字体中查找。

备注

该方法最初是基于 Python 实现的，并调用 Font.glyph_advance() 进行计算。为了提高性能，从 v1.18.14 开始，该方法已改用 C 语言实现。要计算单个字符的宽度，现在可以使用以下任一方式，而不会影响性能：

  1. font.glyph_advance(ord("Ä")) * fontsize

  2. font.text_length("Ä", fontsize=fontsize)

对于多字符字符串，该方法相比之前的实现具有显著的性能提升：每个字符的计算时间从大约 0.5 微秒减少到 12.5 纳秒（从第二个字符开始）。

char_lengths(text, fontsize=11)#

v1.18.14 新增

计算 Unicode 字符串中各个字符的长度（单位：点）。

参数:

  • text (str) – 以 UTF-8 编码的文本字符串。

  • fontsize (float) – 指定的 fontsize。

返回类型:

tuple

返回:

该字符串在 PDF 中存储时，各字符的长度（单位：点）。此方法的作用类似于 Font.text_length()，但结果分解到单个字符级别。该方法执行速度极快，例如在 TextWriter.fill_textbox() 中被使用。以下等式成立（允许因四舍五入产生的误差）：font.text_length(text) == sum(font.char_lengths(text))。

>>> font = pymupdf.Font("helv")
>>> text = "PyMuPDF"
>>> font.text_length(text)
50.115999937057495
>>> pymupdf.get_text_length(text, fontname="helv")
50.115999937057495
>>> sum(font.char_lengths(text))
50.115999937057495
>>> pprint(font.char_lengths(text))
(7.336999952793121,  # P
5.5,                 # y
9.163000047206879,   # M
6.115999937057495,   # u
7.336999952793121,   # P
7.942000031471252,   # D
6.721000015735626)   # F

buffer#

  • v1.17.6 新增

二进制字体文件内容的副本。

返回类型:

bytes

flags#

包含各种字体属性的字典，每个属性均表示为布尔值。例如 Helvetica 的示例:

>>> pprint(font.flags)
{'bold': 0,
'fake-bold': 0,
'fake-italic': 0,
'invalid-bbox': 0,
'italic': 0,
'mono': 0,
'opentype': 0,
'serif': 1,
'stretch': 0,
'substitute': 0}
返回类型:

dict

name#
返回类型:

str

字体名称，可能为空字符串 "" 或 "(null)"。

bbox#

字体的边界框（bounding box），其值是该字体所有字形边界框的最大范围。

返回类型:

Rect

glyph_count#
返回类型:

int

该字体定义的字形数量。

ascender#

  • v1.18.0 新增

字体的上升高度（ascender），具体含义可参考 此处。请注意，这里的定义与严格意义上的上升高度略有不同：我们的值包括基线（baseline）之上的所有部分，而不仅仅是大写 “A” 和小写 “a” 之间的高度差。

返回类型:

float

descender#

  • v1.18.0 新增

字体的下降高度（descender），具体含义可参考 此处。该值始终为负数，表示某些字形（如 “g” 或 “y”）超出基线的部分。因此，ascender - descender 代表该字体的整体高度——即所有字形都应适应的总高度。对于大多数字体而言，这一规则成立，但某些特殊字体（如书法字体）可能会有例外情况。

返回类型:

float

is_bold#
is_italic#
is_monospaced#
is_serif#

一些含义明显的属性。反映了 Font.flags 字典中的一些值。

返回类型:

bool

  • New in v1.16.18

This class represents a font as defined in MuPDF (fz_font_s structure). It is required for the new class TextWriter and the new Page.write_text(). Currently, it has no connection to how fonts are used in methods Page.insert_text() or Page.insert_textbox(), respectively.

A Font object also contains useful general information, like the font bbox, the number of defined glyphs, glyph names or the bbox of a single glyph.

Method / Attribute

Short Description

glyph_advance()

Width of a character

glyph_bbox()

Glyph rectangle

glyph_name_to_unicode()

Get unicode from glyph name

has_glyph()

Return glyph id of unicode

text_length()

Compute string length

char_lengths()

Tuple of char widths of a string

unicode_to_glyph_name()

Get glyph name of a unicode

valid_codepoints()

Array of supported unicodes

ascender

Font ascender

descender

Font descender

bbox

Font rectangle

buffer

Copy of the font’s binary image

flags

Collection of font properties

glyph_count

Number of supported glyphs

name

Name of font

is_bold

True if bold

is_monospaced

True if mono-spaced

is_serif

True if serif, False if sans-serif

is_italic

True if italic

Class API

Footnotes

本软件按原样提供，不作任何明示或暗示担保。本软件根据许可分发，除非根据该许可条款明确授权，否则不得复制、修改或分发。请参阅 artifex.com 上的许可信息，或联系 Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States 了解更多信息。

This documentation covers all versions up to 1.25.4.