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