故事#
v1.21.0 中的新功能
方法 / 属性 |
简短描述 |
|---|---|
将故事输出“重置”到开头 |
|
计算故事内容以适应提供的矩形 |
|
将计算的内容写入当前页面 |
|
回调函数记录当前处理的故事内容 |
|
故事的基础 主体 |
|
将地点和故事绘制到 DocumentWriter |
|
将HTML内容的迭代布局写入DocumentWriter |
|
类似于 |
|
类似于 |
|
找到包含故事 |
|
类 API
- class Story#
- __init__(self, html=None, user_css=None, em=12, archive=None)#
创建一个 故事，可选地提供 HTML 和 CSS 源代码。 HTML 被解析，并作为 DOM（文档对象模型）保存在故事中。
此结构可能会被修改：内容（文本、图片）可以通过使用Xml类的方法添加、复制、修改或删除。
完成后，故事可以写入任何设备；在典型使用中，该设备可能由一个 DocumentWriter 提供，以创建新页面。
以下是一些一般性的备注：
该Story构造函数解析和验证提供的HTML，以创建DOM。
PyMuPDF 提供了多种方法来操作 HTML 源码，通过提供对底层 DOM 的 节点 的访问。文档可以完全通过编程从头构建，或者现有的 DOM 可以相当随意地修改。有关此接口的详细信息，请参见 Xml 类。
如果不需要对DOM进行任何（或更多）更改，故事就可以准备布局并传输到一系列设备（通常是由一个 DocumentWriter 提供的设备，以生成新页面）。
下一步是放置故事并将其写出。 这可以直接完成，通过循环调用
place()和draw()， 或者， 循环可以通过使用write()或write_stabilised()方法为您处理。 您选择哪种方法在很大程度上是一种品味问题。要使用这些样式中的第一个，应该使用以下循环：
获取一个合适的设备进行写入；通常通过从一个 DocumentWriter 请求一个新的空页面来实现。
确定页面上的一个或多个矩形，
这些矩形应该接收故事数据。
请注意，并非每个页面都需要具有相同的矩形集。将每个矩形传递给故事以进行放置，了解该矩形的哪个部分已被填充，以及是否有更多未适合的故事数据。此步骤可以重复多次，调整矩形，直到调用者对结果满意。
可选地，在此时，我们可以请求有关有趣项目放置位置的详细信息，通过调用
element_positions()方法。项目被认为是有趣的，如果它们的整数heading属性是非零的（对应于 HTML 标签 h1 - h6），如果它们的id属性不是None（对应于 HTML 标签 id），或者如果它们的href属性不是None（对应于 HTML 标签 href）。这可以方便地用于自动生成目录、图像索引或类似内容。接下来，使用
draw()方法将该矩形绘制到设备上。如果最近一次对
place()的调用表明所有故事数据已适配，立即停止。否则，我们可以循环回去。 如果当前设备（页面）上还有更多的矩形要放置，我们跳回第3步 - 如果没有，我们跳回第1步以获取新的设备。
或者，在使用DocumentWriter的情况下，可以使用
write()或write_stabilized()方法。这些方法为您处理所有循环，作为交换，提供控制行为的回调（特别是一个枚举要使用的矩形/页面的回调）。
故事的哪一部分将落在哪个矩形/哪个页面，完全由Story对象控制，无法预测。
图像可能是一个故事的一部分。它们将与任何周围的文本一起放置。
多个故事可以彼此独立地写入同一页面。 例如，一个页面可能有单独的故事用于页面标题、页面底部、常规文本、评论框等。
- Parameters:
html (str) – HTML 源代码。如果省略，将生成一个基本的最小值（见下文）。如果提供，则不需要完整的 HTML 文档。内置的源解析器将宽容（许多/大多数）HTML 语法错误，并且也接受像
"Hello, World!"这样的 HTML 片段。user_css (str) – CSS 源代码。如果提供，则必须包含有效的 CSS 规范。
em (float) – 默认文本字体大小。
归档 –
用于加载渲染资源的归档。目前支持的资源类型为图像和文本字体。如果省略，故事将不会尝试查找任何此类数据，因此可能会产生不完整的输出。
注意
除了实际的归档之外，可以提供有效的参数来创建一个归档——在这种情况下，将临时构建一个归档。因此，除了
story = pymupdf.Story(archive=pymupdf.Archive("myfolder"))，也可以更简短地写为story = pymupdf.Story(archive="myfolder")。
- place(where)#
计算故事内容中适合放入提供的矩形的部分。该方法维护一个指针，指向已经写入的故事内容部分，并在下一次调用时从该指针的位置继续。
- Parameters:
其中 (rect_like) – 将当前内容部分的布局适配到这个矩形中。这必须是页面的 MediaBox 的一个子矩形。
- Return type:
元组[布尔值, 矩形_like]
- Returns:
一个布尔值 (int)
more和一个矩形filled。如果more == 0，则故事的所有内容都已被写入，否则更多内容等待被写入到后续的矩形/页面。矩形filled是where实际上已被填充的部分。
- draw(dev, matrix=None)#
将由
Story.place()准备的内容部分写入页面。
- element_positions(function, args=None)#
让 Story 在计算出当前页面某些 HTML 元素的位置后提供位置信息 - 也就是说，在直接在
Story.place()之后调用此方法。故事将把位置信息传递给函数。这些信息例如可以用于生成目录。
- Parameters:
函数 (可调用) – 一个接受
ElementPosition对象的Python函数。它将由Story对象调用以处理定位信息。该函数必须是一个接受一个参数的可调用函数。args (dict) – 一个可选的字典，包含任何附加信息 这些信息应该被添加到传递给
function的ElementPosition实例中。 例如，当前输出页面的页码。 这个字典中的每个键都必须是符合有效Python标识符规则的字符串。 下面解释了完整的信息集。
- reset()#
将故事的文档 rewind 回到开头，以便重新开始输出。
- write(writer, rectfn, positionfn=None, pagefn=None)#
将故事放置并绘制到一个 DocumentWriter。避免了需要调用代码来实现一个循环，该循环调用
Story.place()和Story.draw()等函数的需求，但代价是必须提供至少一个rectfn()回调。- Parameters:
writer – 一个 DocumentWriter 或 None。
rectfn –
一个可调用的函数，接受
(rect_num: int, filled: Rect)并返回(mediabox, rect, ctm)：mediabox: None 或者新页面的矩形。
rect: 下一个应该放置内容的矩形。
ctm: None 或者一个 Matrix。
positionfn –
None，或者一个可调用的接收
(position: ElementPosition):- position:
一个
ElementPosition，带有额外的.page_num成员。
通常在我们生成标题或具有 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.write(); 使用 None 编写器，并提取ElementPosition的列表，该列表传递给下一个contentfn()的调用。当来自
contentfn()的 html 保持不变时，我们进行 最后一次迭代，使用writer。- Parameters:
writer – 一个 DocumentWriter.
contentfn – 一个函数，接受一个
ElementPositions的列表并返回包含html的字符串。返回的html可以依赖于位置列表，例如在开始附近有一个目录。rectfn –
一个可调用的函数，接收
(rect_num: int, filled: Rect)并返回(mediabox, rect, ctm):mediabox: 新页面上的 None 或 rect。
rect: 内容应放置的下一个矩形。
ctm: 一个 Matrix。
pagefn – None，或者一个可调用函数，接收
(page_num, medibox, dev, after)；在每一页的开始 (after=0) 和结束 (after=1) 时被调用。档案 –
add_header_ids – 如果为真，我们向所有没有 id 的标题标签添加唯一的 id。这可以帮助自动生成目录。
- Returns:
无。
- write_with_links(rectfn, positionfn=None, pagefn=None)#
类似于
write()，只不过我们没有writer参数，并且我们返回一个 PDF Document，在其中为每个内部 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 Document，其中为每个内部 HTML 链接创建了链接。
- class FitResult#
来自一个
Story.fit*()方法的结果。成员：
big_enough:True如果拟合成功。filled:从上一次调用
Story.place()。more:如果拟合成功，
False。numcalls:对
self.place()的调用次数。parameter:成功的参数值，或最大的失败值。
- 矩形:
从
parameter创建的矩形。
- fit(self, fn, pmin=None, pmax=None, delta=0.001, verbose=False)#
找到包含故事的最佳矩形
self。返回一个
Story.FitResult实例。成功时，对
self.place()的最后一次调用将是使用返回的矩形，因此可以直接使用self.draw()。- Parameters:
fn –
一个可调用函数，接受一个浮点
parameter并返回一个pymupdf.Rect()。如果矩形为空，我们假设故事将无法适应，因此不调用self.place()。必须保证当参数
parameter增加时，self.place()具有单调性，当给定矩形fn(parameter时。这通常意味着宽度和高度在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实例。- Parameters:
width – 矩形的宽度。
height – 矩形的高度。
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内的最小高度，其中一个大小为(width, height)的矩形足够大以容纳故事self。返回一个
Story.FitResult实例。- Parameters:
width – 矩形的宽度。
height_min – 要考虑的最小高度；必须 >= 0。
height_max – 最大考虑高度，必须 >= height_min 或
None以表示无限。原点 –
(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实例。- Parameters:
height – 矩形的高度。
width_min – 最小考虑宽度；必须 >= 0。
width_max – 最大考虑宽度，必须 >= width_min 或
None以表示无限。origin –
(x0, y0)的矩形。delta – 返回宽度的最大误差。
verbose – 如果为真，我们输出诊断信息。
元素定位回调函数#
回调函数可用于记录有关故事输出的信息。该函数对信息的访问是只读的：它无法影响故事的输出。
使用这种方法执行故事的典型循环看起来像这样：
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，1-6 对应 h1 - h6。elpos.href(str) –href属性的值，如果未定义则为 None。elpos.id(str) –id属性的值，如果未定义则为 None。elpos.rect(元组) – 元素在页面上的位置。elpos.text(str) – 元素的即时文本。elpos.open_close(int 位字段) – 位 0 设置：打开元素，位 1 设置：关闭元素。适用于可能包含其他元素的元素，因此在创建/打开后可能不会立即关闭。elpos.rect_num(int) – 到目前为止故事中填充的矩形数量。elpos.page_num(int) – 页码；仅在使用pymupdf.Story.write*()函数时出现。