TextWriter#
v1.16.18 版本新增
此类表示一个 MuPDF 文本 对象。其基本思想是**将 (1) 文本准备与 (2) 将文本输出**到 PDF 页面**解耦**。
在**准备**过程中，文本写入器会存储任意数量的文本片段（“跨度”）及其位置和单独的字体信息。写入器准备好的内容可以多次**输出**到任何具有兼容页面大小的 PDF 页面。
文本写入器是方法 Page.insert_text() 及相关方法的优雅替代方案
**改进的文本定位：** 选择文本插入的任何起点。存储文本会返回跨度中*最后一个字符*之后的“光标位置”。
**自由选择字体：** 每个文本跨度都有自己的字体和
fontsize。这让您在排版较长的文本时可以轻松切换。**自动备用字体：** 如果所选字体不支持某个字符，将自动搜索替代字体。这显著降低了在输出中看到不可打印符号（“豆腐块”——看起来像一个小矩形）的风险。PyMuPDF 现在还附带了**通用字体“Droid Sans Fallback Regular”**，它支持**所有拉丁**字符（包括西里尔和希腊）和**所有 CJK** 字符（中文、日文、韩文）。
**西里尔和希腊语支持：** PDF Base 14 字体 集成了对西里尔和希腊字符的支持，**无需指定编码。**您的文本可以是拉丁、希腊和西里尔字符的混合。
**透明度支持：** 支持参数 *opacity*。这提供了一种创建水印样式文本的便捷方法。
**两端对齐文本：** 支持任何字体——不仅仅是像
Page.insert_textbox()中的简单字体。**可重用性：** TextWriter 对象独立于 PDF 页面存在。它可以多次写入，无论是写入同一页面还是其他页面，无论是同一 PDF 还是不同的 PDF，都可以选择不同的颜色或透明度。
使用此对象包括三个步骤
在**创建**时，TextWriter 需要一个固定的**页面矩形**，它将以此为参照计算文本位置。文本写入器只能写入此大小的页面。
使用方法
TextWriter.append()、TextWriter.appendv()和TextWriter.fill_textbox()根据需要多次将文本存储到 TextWriter 中。将 TextWriter 对象输出到一个或多个 PDF 页面。
注意
从版本 1.17.0 开始，TextWriter **支持** 通过
TextWriter.write_text()的 *morph* 参数进行文本旋转。还存在
Page.write_text()方法，它可以组合一个或多个 TextWriter 并将其联合写入给定的矩形和给定的旋转角度——非常类似于Page.show_pdf_page()。
方法 / 属性 |
简要描述 |
|---|---|
以水平书写模式添加文本 |
|
以垂直书写模式添加文本 |
|
填充矩形（水平书写模式） |
|
将 TextWriter 输出到 PDF 页面 |
|
文本颜色（可更改） |
|
最后写入的字符在此结束 |
|
文本不透明度（可更改） |
|
此 TextWriter 使用的页面矩形 |
|
目前已占用的区域 |
类 API
- class TextWriter#
- __init__(self, rect, opacity=1, color=None)#
- 参数：
rect (类似矩形) – 内部用于文本定位计算的矩形。
opacity (浮点数) – 设置此处存储文本的透明度。区间
[0, 1)之外的值将被忽略。例如，值 0.5 表示 50% 透明度。color (浮点数,序列) – 文本的颜色。所有颜色都指定为浮点数 0 <= color <= 1。单个浮点数表示某个灰度级别，序列通过其长度暗示颜色空间。
- append(pos, text, font=None, fontsize=11, language=None, right_to_left=False, small_caps=0)#
在 v1.18.9 中更改
在 v1.18.15 中更改
以水平书写模式添加一些新文本。
- 参数：
pos (类似点) – 文本的起始位置，即第一个字符的左下角点。
text (str) – 任意长度的字符串。它将从位置“pos”开始写入。
font – 一个 Font 对象。如果省略，将使用
pymupdf.Font("helv")。fontsize (浮点数) –
fontsize，一个正数，默认为 11。language (str) – 要使用的语言，例如表示英语的“en”。有意义的值应符合 ISO 639 标准 1、2、3 或 5。保留供将来使用：据我们所知，目前没有效果。
right_to_left (布尔值) – (v1.18.9 新增) 文本是否应从右向左书写。适用于阿拉伯语或希伯来语等语言。默认为
False。如果为True，文本中的任何拉丁部分将自动转换。没有其他后果，即TextWriter.last_point仍将是最右边的字符，并且不会发生任何对齐。因此，您可能希望改用TextWriter.fill_textbox()。small_caps (布尔值) –
(v1.18.15 新增) 在字体中查找字符的小写大写版本。如果存在，则使用该值。否则将使用原始字符（此字体或备用字体）。备用字体绝不会返回小写大写。例如，此代码片段
>>> doc = pymupdf.open() >>> page = doc.new_page() >>> text = "PyMuPDF: the Python bindings for MuPDF" >>> font = pymupdf.Font("figo") # choose a font with small caps >>> tw = pymupdf.TextWriter(page.rect) >>> tw.append((50,100), text, font=font, small_caps=True) >>> tw.write_text(page) >>> doc.ez_save("x.pdf")
将生成此 PDF 文本
- 返回：
text_rect和last_point。(在 v1.18.0 中更改：) 如果字体不受支持，则会引发异常——通过Font.is_writable进行检查。
- appendv(pos, text, font=None, fontsize=11, language=None, small_caps=0)#
在 v1.18.15 中更改
以垂直、从上到下书写模式添加一些新文本。
- 参数：
- 返回：
text_rect和last_point。(在 v1.18.0 中更改：) 如果字体不受支持，则会引发异常——通过Font.is_writable进行检查。
- fill_textbox(rect, text, *, pos=None, font=None, fontsize=11, align=0, right_to_left=False, warn=None, small_caps=0)#
在 1.17.3 中更改：新增参数
pos，用于指定在矩形内的书写起始位置。在 v1.18.9 中更改：返回不适合矩形的行列表。支持从右向左书写（例如阿拉伯语、希伯来语）。
在 v1.18.15 中更改：如果字体支持，则优先使用小写大写。
以水平书写模式用文本填充给定矩形。这是一个方便的方法，可作为
append()的替代方案。- 参数：
rect (类似矩形) – 要填充的区域。文本的任何部分都不会出现在此区域之外。
text (str,序列) – 文本。可以指定为 (UTF-8) 字符串或字符串列表 / 元组。字符串将首先使用 splitlines() 转换为列表。列表中的每个项目都将在新行开始（强制换行）。
pos (类似点) – (v1.17.3 新增) 从此点开始存储。默认为靠近矩形左上角的点。
font – Font 对象，默认为
pymupdf.Font("helv")。fontsize (浮点数) –
fontsize。align (int) – 文本对齐方式。使用 TEXT_ALIGN_LEFT、TEXT_ALIGN_CENTER、TEXT_ALIGN_RIGHT 或 TEXT_ALIGN_JUSTIFY 之一。
right_to_left (布尔值) – (v1.18.9 新增) 文本是否应从右向左书写。适用于阿拉伯语或希伯来语等语言。默认为
False。如果为True，任何拉丁部分会自动反转。您仍然需要设置对齐方式（如果您想要右对齐），这不会自动发生——其他对齐选项也仍然可用。warn (布尔值) –
文本溢出时不做任何操作、警告或引发异常。溢出的文本绝不会被写入。在 v1.18.9 中更改：
默认为
None。将返回溢出行列表。
small_caps (布尔值) – (v1.18.15 新增) 参见
append()。
- 返回类型：
list
- 返回：
v1.18.9 新增 – 不适合矩形的行列表。每个项目都是一个元组
(text, length)，包含一个字符串及其（在页面上的）长度。
注意
根据需要多次使用这些方法——没有技术限制（除了系统的内存限制）。您也可以混合使用
append()和文本框，并且可以使用多个。文本定位完全由插入点控制。因此，无需遵守任何顺序。(在 v1.18.0 中更改：) 如果字体不受支持，则会引发异常——通过Font.is_writable进行检查。- write_text(page, opacity=None, color=None, morph=None, overlay=True, oc=0, render_mode=0)#
将 TextWriter 文本写入页面，这是唯一必需的参数。其他参数可用于临时覆盖创建 TextWriter 时使用的值。
- 参数：
page – 写入此 Page。
opacity (浮点数) – 覆盖此输出的 TextWriter 值。
color (序列) – 覆盖此输出的 TextWriter 值。
morph (序列) – 通过应用矩阵修改文本外观。如果提供，这必须是一个序列 (fixpoint, matrix)，其中 fixpoint 类似点，matrix 类似矩阵。一个典型示例是围绕 fixpoint 旋转文本。
overlay (布尔值) – 放在前景（默认）或背景。
render_mode (int) –
PDF
Tr操作符值。值：0（默认）、1、2、3（不可见）。
- opacity#
文本不透明度（可修改）。
- 返回类型：
float
- color#
文本颜色（可修改）。
- 返回类型：
float,tuple
注意
要查看一些处理 TextWriter 的演示脚本，请查看 TextWriter 演示脚本。
不透明度和颜色适用于此对象中的**所有文本**。
如果您需要不同的颜色/透明度，则必须创建单独的 TextWriter。每当您确定颜色应该更改时，只需使用之前返回的
last_point作为新文本跨度的位置，将文本附加到相应的 TextWriter。附加项目或文本框可以按任意顺序进行：只有位置参数控制文本出现的位置。
字体和
fontsize可以在同一 TextWriter 中自由变化。这可以用来让具有不同属性的文本出现在同一显示行上：只需相应地指定 pos，例如将其设置为之前添加项的last_point。您可以使用
TextWriter.fill_textbox()的 pos 参数来设置第一个文本字符的位置。这允许使用来自不同 TextWriter 对象的内填充同一个文本框，从而允许使用多种颜色、不透明度等。MuPDF 不支持所有字体具有此特性，例如不支持 Type3 字体。从 v1.18.0 开始，可以通过字体属性
Font.is_writable进行检查。在使用 TextWriter 方法时也会检查此属性。