PyMuPDF 1.24.4 中文文档（十）（1）

原文：https://pymupdf.readthedocs.io/en/latest/

Story

原文：pymupdf.readthedocs.io/en/latest/story-class.html

• v1.21.0 新增

类 API

class Story

__init__(self, html=None, user_css=None, em=12, archive=None)

创建一个故事，可选择提供 HTML 和 CSS 源码。HTML 被解析，并作为 DOM（文档对象模型）保存在故事中。

可以通过 Xml 类的方法添加、复制、修改或删除内容（文本、图像）。此结构可能会被修改。

完成后，故事可以写入任何设备；在典型用法中，设备可能由 DocumentWriter 提供以创建新页面。

这里有一些一般性的备注：

• Story 构造函数解析和验证提供的 HTML 以创建 DOM。
  
• PyMuPDF 提供了多种方式来通过提供对底层 DOM 的节点访问来操作 HTML 源码。文档可以完全以编程方式从头开始构建，或者现有的 DOM 可以被任意修改。有关此接口的详细信息，请参阅 Xml 类。
  
• 如果不需要（或不再需要）对 DOM 进行更改，则故事已准备好进行布局，并传递给一系列设备（通常由 DocumentWriter 提供的设备）以生成新页面。
  
• 下一步是放置故事并将其写出。这可以直接完成，通过循环调用place()和draw()，或者可以选择使用write()或write_stabilised()方法来处理循环。选择哪种方法主要是个人口味的问题。

• 要使用这些样式中的第一个进行工作，应使用以下循环：

1. 获得一个适合的设备以进行写作；通常通过从 DocumentWriter 请求一个新的空白页面来完成。
   
2. 确定页面上应该接收故事数据的一个或多个矩形。请注意，不是每一页都需要具有相同的矩形集。
   
3. 将每个矩形传递给故事以放置它，学习该矩形的哪一部分已填充，以及是否有更多未适应的故事数据。此步骤可以重复多次，直到调用者对结果满意。
   
4. 可选地，在这一点上，我们可以通过调用element_positions()方法来请求放置有趣项目的详细信息。如果其整数heading属性为非零（对应 HTML 标签h1 - h6），如果其id属性不为None（对应 HTML 标签id），或者如果其href属性不为None（对应 HTML 标签href），则项目被视为有趣项目。这可以方便地用于自动生成目录、图像索引或类似内容。
   
5. 接下来，用draw()方法将该矩形绘制到设备上。
   
6. 如果最近的一次调用place()表明所有故事数据已经适应，现在停止。
   
7. 否则，我们可以回到循环。如果有更多矩形要放置在当前设备（页面）上，我们回到步骤 3 - 如果没有，我们回到步骤 1 获取一个新设备。
   

• 或者，在使用 DocumentWriter 的情况下，可以使用write()或write_stabilized()方法。这些方法为您处理所有循环，但需要提供控制行为的回调（特别是枚举要使用的矩形/页面的回调）。
  

• 故事的哪一部分将落在哪个矩形/哪一页完全由 Story 对象控制，无法预测。
  
• 图像可能是故事的一部分。它们将与周围的文本一起放置。
  
• 多个故事可能 - 互不干扰地 - 写入同一页。例如，页面页眉、页脚、常规文本、评论框等可能有单独的故事。
  

参数：

• html (str) – HTML 源代码。如果省略，将生成基本的最小内容（见下文）。如果提供，则不需要完整的 HTML 文档。内置源解析器将容忍（许多/大多数）HTML 语法错误，并且还接受 HTML 片段，例如 "Hello, World!"。
  
• user_css (str) – CSS 源代码。如果提供，必须包含有效的 CSS 规范。
  
• em (float) – 默认文本字体大小。
  
• archive –
  从中加载资源以进行渲染的 Archive。当前支持的资源类型为图像和文本字体。如果省略，则故事将不会尝试查找任何此类数据，因此可能会产生不完整的输出。
  Note
  Instead of an actual archive, valid arguments for creating an Archive can also be provided – in which case an archive will temporarily be constructed. So, instead of story = pymupdf.Story(archive=pymupdf.Archive("myfolder")), one can also shorter write story = pymupdf.Story(archive="myfolder").
  

place(where)

计算故事内容的那部分，适合于提供的矩形内。该方法维护一个指针，指示已写入故事内容的哪一部分，并在下次调用时从该指针位置恢复。

Parameters:

where (rect_like) – 布局当前内容部分以适应此矩形。这必须是页面 MediaBox 的子矩形。

Return type:

tuple[bool, rect_like]

Returns:

一个布尔值（int）more 和一个矩形 filled。如果 more == 0，则所有故事内容均已写入，否则还有待写入后续矩形/页面。矩形 filled 是实际填充的 where 部分。

draw(dev, matrix=None)

将由Story.place()准备的内容部分写入页面。

Parameters:

• dev – 由 dev = writer.begin_page(mediabox) 创建的 Device。该设备知道如何调用所有写入内容所需的 MuPDF 函数。
  
• matrix (matrix_like) – 用于在写入页面时转换内容的矩阵。例如，可以写入旋转文本的示例。默认情况下不进行转换（即 Identity 矩阵）。
  

element_positions(function, args=None)

让 Story 在计算出当前页面上某些 HTML 元素的位置后提供位置信息 - 即在Story.place()之后直接调用此方法。

Story将位置信息传递给function。例如，这些信息可用于生成目录。

Parameters:

• function (callable) – 一个接受ElementPosition对象的 Python 函数。它将由 Story 对象调用以处理位置信息。此函数必须是一个接受正好一个参数的可调用对象。
  
• args (dict) – 一个可选的字典，包含应该添加到传递给function的ElementPosition实例的任何附加信息。例如，当前输出页码。该字典中的每个键必须是符合有效 Python 标识符规则的字符串。所有信息的完整集合将在下面解释。
  

reset()

将故事文档倒回到开始以重新开始其输出。

body

故事 DOM 的body部分。此属性包含 PDF 制作的所有相关内容，位于“”和“”之间的 Xml 节点。

write(writer, rectfn, positionfn=None, pagefn=None)

将 Story 放置并绘制到 DocumentWriter。避免调用代码实现调用Story.place()和Story.draw()等循环的需要，代价是至少要提供rectfn()回调函数。

参数：

• writer – 一个 DocumentWriter，或者为 None。
  
• rectfn –一个可调用的函数，接受(rect_num: int, filled: Rect)并返回(mediabox, rect, ctm)：

• mediabox：None 或新页面的矩形。
  
• rect：下一个放置内容的矩形。
  
• ctm：None 或者一个 Matrix。
  

• positionfn –None，或者一个接受(position: ElementPosition)的可调用函数：

• 位置：
  一个带有额外的.page_num成员的ElementPosition。
  

• 通常作为生成具有标题或 ID 的元素的多次调用。
  
• pagefn – None，或者一个接受(page_num, mediabox, dev, after)的可调用函数；在每页的开始（after=0）和结束（after=1）时调用。
  

static write_stabilized(writer, contentfn, rectfn, user_css=None, em=12, positionfn=None, pagefn=None, archive=None, add_header_ids=True)

执行 HTML 内容的迭代布局到 DocumentWriter 的静态方法。

例如，这允许在确保页码稳定之前添加目录部分。

从(contentfn(), user_css, em, archive)创建一个新的 Story 并使用内部调用Story.write()布局它；使用 None writer 并提取传递给下一个contentfn()调用的ElementPosition列表。

当contentfn()的 HTML 变化不再变化时，我们使用writer进行最终迭代。

参数：

• writer – 一个 DocumentWriter。
  
• contentfn – 接受ElementPosition列表并返回包含 HTML 的字符串的函数。返回的 HTML 可以依赖于位置列表，例如在开头附近有目录。
  
• rectfn –一个可调用的函数，接受(rect_num: int, filled: Rect)并返回(mediabox, rect, ctm)：

• mediabox：None 或新页面的矩形。
  
• rect：下一个放置内容的矩形。
  
• ctm：一个 Matrix。
  

• pagefn – None，或者一个接受(page_num, medibox, dev, after)的可调用函数；在每页的开始（after=0）和结束（after=1）时调用。
  
• archive –
  
• add_header_ids – 如果为真，我们为所有尚未具有 ID 的标题标签添加唯一的 ID。这有助于自动生成目录。
  

返回：

无。

write_with_links(rectfn, positionfn=None, pagefn=None)

类似于write()，但我们没有writer参数，返回一个 PDF 文档，其中为每个内部 HTML 链接创建了链接。

static write_stabilized_with_links(contentfn, rectfn, user_css=None, em=12, positionfn=None, pagefn=None, archive=None, add_header_ids=True)

类似于write_stabilized()，但我们没有writer参数，而是返回一个 PDF 文档，其中为每个内部 HTML 链接创建了链接。

class FitResult

来自Story.fit*()方法的结果。

成员：

big_enough：

True如果适合成功。

filled：

从上一次调用Story.place()。

more：

False如果适合成功。

numcalls：

调用self.place()的次数。

parameter：

成功的参数值，或最大的失败值。

Rect:

从parameter创建的 rect。

fit(self, fn, pmin=None, pmax=None, delta=0.001, verbose=False)

找到包含故事self的最佳 rect。

返回一个Story.FitResult 实例。

成功时，最后一次调用self.place()将使用返回的矩形，因此可以直接使用self.draw()。

参数：

• fn –
  一个可调用对象，接受一个浮点parameter并返回一个pymupdf.Rect()。如果 rect 为空，我们假设故事不会适合，并且不调用self.place()。
  必须确保当给定 rect fn(parameter)作为parameter增加时，self.place()行为单调递增。通常情况下，随着parameter增加，宽度和高度都会增加或保持不变。
  
• pmin – 要考虑的最小参数；None表示负无穷。
  
• pmax – 要考虑的最大参数；None表示正无穷。
  
• delta – 返回的parameter的最大误差。
  
• verbose – 如果为真，我们输出诊断信息。
  

fit_scale(self, rect, scale_min=0, scale_max=None, delta=0.001, verbose=False)

在范围scale_min..scale_max中找到一个比例scale，其中scale * rect足够大以容纳故事self。

返回一个Story.FitResult 实例。

参数：

• width – rect 的宽度。
  
• height – rect 的高度。
  
• scale_min – 要考虑的最小比例，必须>= 0。
  
• scale_max – 要考虑的最大比例，必须>= scale_min 或None表示无限。
  
• delta – 返回的比例的最大误差。
  
• verbose – 如果为真，我们输出诊断信息。
  

fit_height(self, width, height_min=0, height_max=None, origin=(0, 0), delta=0.001, verbose=False)

在范围height_min..height_max中找到一个 rect 的最小高度，其中一个大小为(width, height)的 rect 足够大以包含故事self。

返回一个Story.FitResult 实例。

参数：

• width – rect 的宽度。
  
• height_min – 要考虑的最小高度；必须>= 0。
  
• height_max – 考虑的最大高度，必须>= height_min 或None表示无限。
  
• origin – rect 的(x0, y0)。
  
• delta – 返回的高度的最大误差。
  
• verbose – 如果为真，我们输出诊断信息。
  

fit_width(self, height, width_min=0, width_max=None, origin=(0, 0), delta=0.001, verbose=False)

查找在范围width_min..width_max内最小的宽度，在该宽度下矩形大小为(width, height)足够大以包含故事self。

返回Story.FitResult实例。

参数：

• height – 矩形的高度。
  
• width_min – 要考虑的最小宽度；必须 >= 0。
  
• width_max – 要考虑的最大宽度；必须 >= width_min 或者None表示无限宽度。
  
• origin – 矩形的(x0, y0)坐标。
  
• delta – 返回宽度的最大误差。
  
• verbose – 如果为 true，则输出诊断信息。
  

元素定位回调函数

回调函数可用于记录关于故事输出的信息。该函数对信息的访问是只读的：它无法影响故事的输出。

使用此方法执行故事的典型循环如下所示：

HTML = """
<html>
 <head></head>
 <body>
 <h1>Header level 1</h1>
 <h2>Header level 2</h2>
 <p>Hello MuPDF!</p>
 </body>
</html>
"""
MEDIABOX = pymupdf.paper_rect("letter")  # size of a page
WHERE = MEDIABOX + (36, 36, -36, -36)  # leave borders of 0.5 inches
story =  pymupdf.Story(html=HTML)  # make the story
writer = pymupdf.DocumentWriter("test.pdf")  # make the writer
pno = 0 # current page number
more = 1  # will be set to 0 when done
while more:  # loop until all story content is processed
    dev = writer.begin_page(MEDIABOX)  # make a device to write on the page
    more, filled = story.place(WHERE)  # compute content positions on page
    story.element_positions(recorder, {"page": pno})  # provide page number in addition
    story.draw(dev)
    writer.end_page()
    pno += 1  # increase page number
writer.close()  # close output file
def recorder(elpos):
    pass 

ElementPosition 类的属性

必须向Story.element_positions()提供的函数传递一个参数。它是一个具有以下属性的对象：

传递给recorder函数的参数是一个具有以下属性的对象：

• elpos.depth (int) – 箱结构中此元素的深度。
  
• elpos.heading (int) – 标题级别，如果没有标题则为 0，对应h1至h6的 1 至 6。
  
• elpos.href (str) – href属性的值，如果未定义则为 None。
  
• elpos.id (str) – id属性的值，如果未定义则为 None。
  
• elpos.rect (tuple) – 页面上元素的位置。
  
• elpos.text (str) – 元素的即时文本。
  
• elpos.open_close (int 位字段) – 比特 0 设置：打开元素，比特 1 设置：关闭元素。适用于可能包含其他元素并因此创建/打开后可能不会立即关闭的元素。
  
• elpos.rect_num (int) – 到目前为止故事中填充的矩形数量。
  
• elpos.page_num (int) – 页码；仅在使用pymupdf.Story.write*()函数时出现。
  

您对此页面有何反馈？

本软件按原样提供，不附带任何形式的明示或暗示担保。本软件按许可分发，未经授权不得复制、修改或分发。有关详细信息，请参阅artifex.com，或联系位于美国加利福尼亚州旧金山 94129 号梅萨街 39 号 108A 套房的 Artifex Software Inc。

此文档涵盖所有 1.24.4 版本。

元素定位回调函数

回调函数可用于记录关于故事输出的信息。该函数对信息的访问是只读的：它无法影响故事的输出。

使用此方法执行故事的典型循环如下所示：

HTML = """
<html>
 <head></head>
 <body>
 <h1>Header level 1</h1>
 <h2>Header level 2</h2>
 <p>Hello MuPDF!</p>
 </body>
</html>
"""
MEDIABOX = pymupdf.paper_rect("letter")  # size of a page
WHERE = MEDIABOX + (36, 36, -36, -36)  # leave borders of 0.5 inches
story =  pymupdf.Story(html=HTML)  # make the story
writer = pymupdf.DocumentWriter("test.pdf")  # make the writer
pno = 0 # current page number
more = 1  # will be set to 0 when done
while more:  # loop until all story content is processed
    dev = writer.begin_page(MEDIABOX)  # make a device to write on the page
    more, filled = story.place(WHERE)  # compute content positions on page
    story.element_positions(recorder, {"page": pno})  # provide page number in addition
    story.draw(dev)
    writer.end_page()
    pno += 1  # increase page number
writer.close()  # close output file
def recorder(elpos):
    pass 

ElementPosition 类的属性

必须向 Story.element_positions() 提供的函数传递一个参数。它是具有以下属性的对象：

传递给 recorder 函数的参数是具有以下属性的对象：

• elpos.depth（int）- 此元素在框结构中的深度。
  
• elpos.heading（int）- 标题级别，如果没有标题则为 0，h1 - h6 对应 1-6。
  
• elpos.href（str）- href 属性的值，如果未定义则为 None。
  
• elpos.id（str）- id 属性的值，如果未定义则为 None。
  
• elpos.rect（tuple）- 页面上的元素位置。
  
• elpos.text（str）- 元素的即时文本。
  
• elpos.open_close（int 位字段）- 设置位 0：打开元素，设置位 1：关闭元素。对于可能包含其他元素的元素以及因此可能在创建/打开后不会立即关闭的元素相关。
  
• elpos.rect_num（int）- 故事到目前为止填充的矩形数量。
  
• elpos.page_num（int）- 页码；仅在使用 pymupdf.Story.write*() 函数时存在。
  

在这页上有任何反馈吗？

本软件按原样提供，不附带任何明示或暗示的保证。本软件在许可下分发，并且除非根据该许可明确授权，否则不得复制、修改或分发本软件。有关详细信息，请参阅 artifex.com 上的许可信息，或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，United States。

此文档涵盖所有版本，直至 1.24.4。

ElementPosition 类的属性

必须向 Story.element_positions() 提供的函数传递一个参数。它是具有以下属性的对象：

传递给 recorder 函数的参数是具有以下属性的对象：

• elpos.depth（int）- 此元素在框结构中的深度。
  
• elpos.heading（int）- 标题级别，如果没有标题则为 0，h1 - h6 对应 1-6。
  
• elpos.href（str）- href 属性的值，如果未定义则为 None。
  
• elpos.id（str）- id 属性的值，如果未定义则为 None。
  
• elpos.rect（tuple）- 页面上的元素位置。
  
• elpos.text（str）- 元素的即时文本。
  
• elpos.open_close（int 位字段）- 设置位 0：打开元素，设置位 1：关闭元素。对于可能包含其他元素的元素以及因此可能在创建/打开后不会立即关闭的元素相关。
  
• elpos.rect_num（int）- 故事到目前为止填充的矩形数量。
  
• elpos.page_num（int）- 页码；仅在使用 pymupdf.Story.write*() 函数时存在。
  

在这页上有任何反馈吗？

此软件按原样提供，不附任何明示或暗示的保证。此软件在许可下分发，未经许可明确授权，不得复制、修改或分发。请参阅artifex.com获取许可信息，或联系美国旧金山 94129 Mesa 街 39 号 108A 套房 Artifex Software Inc.以获取进一步信息。

此文档覆盖所有版本直至 1.24.4。

PyMuPDF 1.24.4 中文文档（十）（2）https://developer.aliyun.com/article/1559522