PyMuPDF 1.24.4 中文文档（十一）（2）-阿里云开发者社区

PyMuPDF 1.24.4 中文文档（十一）（1）https://developer.aliyun.com/article/1559460

Xml

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

新增于 v1.21.0

这代表一个 HTML 或 XML 节点。它是一个辅助类，用于访问 Story 对象的 DOM（文档对象模型）内容。

不需要直接构建 Xml 对象：在创建 Story 后，直接获取 Story.body —— 它是一个 Xml 节点 —— 并用它来浏览故事的 DOM 结构。

| 方法 / 属性 | 描述 | |
 | — | — |
 | add_bullet_list() | 添加一个ul标签 - 项目列表，上下文管理器。 |
 | add_codeblock() | 添加一个pre标签，上下文管理器。 |
 | add_description_list() | 添加一个dl标签，上下文管理器。 |
 | add_division() | 添加一个div标签（从“section”改名），上下文管理器。 |
 | add_header() | 添加一个标题标签（从h1到h6），上下文管理器。 |
 | add_horizontal_line() | 添加一个hr标签。 |
 | add_image() | 添加一个img标签。 |
 | add_link() | 添加一个a标签。 |
 | add_number_list() | 添加一个ol标签，上下文管理器。 |
 | add_paragraph() | 添加一个p标签。 |
 | add_span() | 添加一个span标签，上下文管理器。 |
 | add_subscript() | 添加下标文本（sub标签） - 内联元素，视为文本。 |
 | add_superscript() | 添加上标文本（sup标签） - 内联元素，视为文本。 |
 | add_code() | 添加代码文本（code标签） - 内联元素，视为文本。 |
 | add_var() | 添加代码文本（code标签） - 内联元素，视为文本。 |
 | add_samp() | 添加代码文本（code标签） - 内联元素，视为文本。 |
 | add_kbd() | 添加代码文本（code标签） - 内联元素，视为文本。 |
 | add_text() | 添加文本字符串。换行符 n 被视为br标签。 |
 | append_child() | 添加一个子节点。 |
 | clone() | 复制此节点。 |
 | create_element() | 创建具有给定标签名的新节点。 |
 | create_text_node() | 为当前节点创建直接文本。 |
 | find() | 查找具有给定属性的子节点。 |
 | find_next() | 重复以相同条件执行的上一个“find”。 |
 | insert_after() | 在当前节点之后插入一个元素。 |
 | insert_before() | 在当前节点之前插入一个元素。 |
 | remove() | 移除此节点。 |
 | set_align() | 使用 CSS 样式规范设置对齐方式。仅适用于块级标签。 |
 | set_attribute() | 将任意键设置为某个值（可以为空）。 |
 | set_bgcolor() | 设置背景颜色。仅适用于块级标签。 |
 | set_bold() | 打开或关闭粗体或设置为某个字符串值。 |
 | set_color() | 设置文本颜色。 |
 | set_columns() | 设置列数。参数可以是任何有效的数字或字符串。 |
 | set_font() | 设置字体系列，例如“sans-serif”。 |
 | set_fontsize() | 设置字体大小。可以是浮点数或有效的 HTML/CSS 字符串。 |
 | set_id() | 设置id。会执行唯一性检查。 |
 | set_italic() | 打开或关闭斜体或设置为某个字符串值。 |
 | set_leading() | 设置块级文本之间的间距（-mupdf-leading），仅适用于块级节点。 |
 | set_lineheight() | 设置行高。像 1.5 这样的浮点数，它设置为1.5 * fontsize。 |
 | set_margins() | 设置边距，可以是浮点数或具有最多 4 个值的字符串。 |
 | set_pagebreak_after() | 在此节点之后插入分页符。 |
 | set_pagebreak_before() | 在此节点之前插入分页符。 |
 | set_properties() | 一次设置任意或所有所需的属性。 |
 | add_style() | 设置（添加）不被自身set_方法支持的“style”。 |
 | add_class() | 设置（添加）“class”属性。 |
 | set_text_indent() | 为第一个文本块行设置缩进。仅适用于块级节点。 |
 | tagname | 可以是 HTML 标签名，如p，或者是None（如果是文本节点）。 |
 | text | 节点的文本或None（如果是标签节点）。 |
 | is_text | 检查节点是否为文本。 |
 | first_child | 包含此节点下一级的第一个节点（或 None）。 |
 | last_child | 包含此节点下一级的最后一个节点（或 None）。 |
 | next | 同级别中的下一个节点（或 None）。 |
 | previous | 同级别中的上一个节点。 |
 | root | DOM 的顶级节点，因此其标签名为 html。 |

Class API

class Xml

add_bullet_list()

添加一个 ul 标签 - 无序列表，上下文管理器。查看 ul。

add_codeblock()

添加一个 pre 标签，上下文管理器。查看 pre。

add_description_list()

添加一个 dl 标签，上下文管理器。查看 dl。

add_division()

添加一个 div 标签，上下文管理器。查看 div。

add_header(value)

添加一个标题标签（从 h1 到 h6 之一），上下文管理器。查看 headings。

参数：

value (int) – 一个值 1 - 6。

add_horizontal_line()

添加一个 hr 标签。查看 hr。

add_image(name, width=None, height=None)

添加一个 img 标签。这会在 DOM 中包含指定名称的图像。

参数：

name (str) – 图像的文件名。这 必须是 Story 构造函数的 Archive 参数的某个条目的成员名称。
width – 如果提供，可以是绝对值（int），或者像“30%”这样的百分比字符串。百分比值指的是在 Story.place() 中指定 where 矩形的宽度。如果提供了此值，并且省略了 height，则图像将按比例缩放。
height – 如果提供，可以是绝对值（int），或者像“30%”这样的百分比字符串。百分比值指的是在 Story.place() 中指定 where 矩形的高度。如果提供了此值，并且省略了 width，则图像将保持其宽高比。

add_link(href, text=None)

添加一个 a 标签 - 内联元素，被视为文本。

参数：

href (str) – URL 的目标。
text (str) – 要显示的文本。如果省略，则显示 href 的文本。

add_number_list()

添加一个 ol 标签，上下文管理器。

add_paragraph()

添加一个 p 标签，上下文管理器。

add_span()

添加一个 span 标签，上下文管理器。查看 span

add_subscript(text)

添加“下标”文本 (sub 标签) - 内联元素，被视为文本。

add_superscript(text)

添加“上标”文本 (sup 标签) - 内联元素，被视为文本。

add_code(text)

添加“代码”文本 (code 标签) - 内联元素，被视为文本。

add_var(text)

添加“变量”文本 (var 标签) - 内联元素，被视为文本。

add_samp(text)

添加“示例输出”文本 (samp 标签) - 内联元素，被视为文本。

add_kbd(text)

添加“键盘输入”文本（kbd 标签） - 内联元素，视为文本处理。

add_text(text)

添加一个文本字符串。换行 n 将被视为 br 标签。

set_align(value)

设置文本对齐方式。仅适用于块级标签。

参数：

value - Text Alignment 或 text-align 值之一。

set_attribute(key, value=None)

设置一个任意的键到某个值（可能为空）。

参数：

key（str）- 属性的名称。
value（str）- 属性的（可选）值。

get_attributes()

检索当前节点的所有属性作为字典。

节点的属性及其值的字典。

get_attribute_value(key)

获取 key 属性值。

参数：

key（str）- 属性的名称。

一个带有 key 值的字符串。

remove_attribute(key)

从节点中删除属性 key。

参数：

key（str）- 属性的名称。

set_bgcolor(value)

设置背景颜色。仅适用于块级标签。

参数：

value - RGB 值如 (255, 0, 0)（表示“红色”）或有效的 background-color 值。

set_bold(value)

设置文本的粗体开启或关闭，或设置为某个字符串值。

参数：

value - True，False 或有效的 font-weight 值。

set_color(value)

设置接下来文本的颜色。

参数：

value - RGB 值如 (255, 0, 0)（表示“红色”）或有效的 color 值。

set_columns(value)

设置列数。

参数：

value - 一个有效的 columns 值。

注意

当前版本忽略 - 在未来的 MuPDF 版本中支持。

set_font(value)

设置字体系列。

参数：

value（str）- 例如“sans-serif”。

set_fontsize(value)

设置接下来文本的字体大小。

参数：

value - 浮点数或有效的 font-size 值。

set_id(unqid)

设置一个 id。这用作 DOM 中节点的唯一标识。使用它可以轻松定位节点以检查或修改它。会执行唯一性检查。

参数：

unqid（str）- 节点的 id 字符串。

set_italic(value)

设置接下来文本的斜体开启或关闭，或设置为某个字符串值。

参数：

value - True，False 或一些有效的 font-style 值。

set_leading(value)

设置块级文本间距（-mupdf-leading），仅适用于块级节点。

参数：

value（float）- 距离上一个块的距离（以点为单位）。

set_lineheight(value)

设置行的高度。

参数：

value - 一个类似 1.5 的浮点数（设置为 1.5 * fontsize），或一些有效的 line-height 值。

set_margins(value)

设置边距。

参数：

value - 浮点数或包含最多 4 个值的字符串。参见 CSS 文档。

set_pagebreak_after()

在此节点之后插入分页符。

set_pagebreak_before()

在此节点之前插入分页符。

set_properties(align=None, bgcolor=None, bold=None, color=None, columns=None, font=None, fontsize=None, indent=None, italic=None, leading=None, lineheight=None, margins=None, pagebreak_after=False, pagebreak_before=False, unqid=None, cls=None)

一次性设置所有所需属性。参数值的含义等同于相应的set_方法的值。

注意

此方法设置的属性直接附加到节点，而每个set_方法生成一个新的span，该span具有相应的属性。因此，要“全局”设置某些属性以供body使用，必须使用此方法。

add_style(value)

设置不受其自身set_方法支持的某些样式属性。

参数：

value（str） – 任何有效的 CSS 样式值。

add_class(value)

设置（添加）某些“class”属性。

参数：

value（str） – 类名。必须已在 DOM 的 HTML 或 CSS 源中定义。

set_text_indent(value)

设置首个文本块行的缩进。仅适用于块级节点。

参数：

value – 有效的text-indent值。请注意，负值不起作用。

append_child(node)

追加子节点。这是其他方法（如Xml.add_paragraph()）使用的底层方法。

参数：

node – 要追加的 Xml 节点。

create_text_node(text)

为当前节点创建直接文本。

参数：

text（str） – 要追加的文本。

返回类型：

Xml

创建的元素。

create_element(tag)

使用给定标签创建新节点。这是其他方法（如Xml.add_paragraph()）使用的底层方法。

参数：

tag（str） – 元素标签。

返回类型：

Xml

创建的元素。要实际将其绑定到 DOM，请使用Xml.append_child()。

insert_before(elem)

在此节点之前插入给定元素elem。

参数：

elem – 某个 Xml 元素。

insert_after(elem)

在此节点之后插入给定元素elem。

参数：

elem – 某个 Xml 元素。

clone()

创建此节点的副本，随后可附加（使用Xml.append_child()）或插入（使用其中之一Xml.insert_before()、Xml.insert_after()）到此 DOM 中。

当前节点的克隆（Xml）。

remove()

从 DOM 中删除此节点。

debug()

出于调试目的，以简化形式打印此节点的结构。

find(tag, att, match)

在当前节点下，查找具有给定tag、属性att和值match的第一个节点。

参数：

tag（str） – 限制搜索到此标签。可能为None以进行无限制搜索。
att（str） – 检查此属性。可能为None。
match（str） – 要匹配的期望属性值。可能为None。

返回类型：

Xml。

如果未找到任何内容，则为None，否则为第一个匹配节点。

find_next(tag, att, match)

继续前一个Xml.find()（或find_next()）相同值的搜索。

返回类型：

Xml。

如果没有更多发现，则为None，否则为下一个匹配节点。

tagname

HTML 标签名称如p或None如果是文本节点。

text

节点的文本或None如果是标签节点。

is_text

检查是否为文本节点。

first_child

包含此节点下一级的第一个节点（或None）。

last_child

包含此节点下一级的最后一个节点（或None）。

next

相同级别的下一个节点（或None）。

previous

相同级别的上一个节点。

root

DOM 的顶级节点，因此具有标签名html。

设置文本属性

在 HTML 标签中，标签可以嵌套，这样最内层的文本继承其父标签的属性。例如

。

为了达到相同的效果，像Xml.set_bold()和Xml.set_italic()这样的方法每个都会在当前节点下方打开一个临时的span，具有所需的属性。

另外，这些方法返回其父节点，因此它们可以彼此连接。

上下文管理器支持

将节点添加到 DOM 的标准方法是这样的：

body = story.body
para = body.add_paragraph()  # add a paragraph
para.set_bold()  # text that follows will be bold
para.add_text("some bold text")
para.set_italic()  # text that follows will additionally be italic
para.add_txt("this is bold and italic")
para.set_italic(False).set_bold(False)  # all following text will be regular
para.add_text("regular text")

被标记为“上下文管理器”的方法可以方便地以这种方式使用：

body = story.body
with body.add_paragraph() as para:
   para.set_bold().add_text("some bold text")
   para.set_italic().add_text("this is bold and italic")
   para.set_italic(False).set_bold(False).add_text("regular text")
   para.add_text("more regular text")

您对本页面有任何反馈意见吗？

此软件按原样提供，没有任何明示或暗示的保证。此软件按许可分发，除非根据该许可的条款明确授权，否则不得复制、修改或分发此软件。有关详细信息，请参阅artifex.com上的许可信息或联系 Artifex Software Inc.，美国加利福尼亚州旧金山市 Mesa Street 39 号 108A 套房，94129，了解更多信息。

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

设置文本属性

在 HTML 标签中，标签可以嵌套，这样最内层的文本继承其父标签的属性。例如

。

为了达到相同的效果，像Xml.set_bold()和Xml.set_italic()这样的方法每个都会在当前节点下方打开一个临时的span，具有所需的属性。

另外，这些方法返回其父节点，因此它们可以彼此连接。

上下文管理器支持

将节点添加到 DOM 的标准方法是这样的：

body = story.body
para = body.add_paragraph()  # add a paragraph
para.set_bold()  # text that follows will be bold
para.add_text("some bold text")
para.set_italic()  # text that follows will additionally be italic
para.add_txt("this is bold and italic")
para.set_italic(False).set_bold(False)  # all following text will be regular
para.add_text("regular text")

被标记为“上下文管理器”的方法可以方便地以这种方式使用：

body = story.body
with body.add_paragraph() as para:
   para.set_bold().add_text("some bold text")
   para.set_italic().add_text("this is bold and italic")
   para.set_italic(False).set_bold(False).add_text("regular text")
   para.add_text("more regular text")

您对本页面有任何反馈意见吗？

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

PyMuPDF 1.24.4 中文文档（十一）（3）https://developer.aliyun.com/article/1559463

PyMuPDF 1.24.4 中文文档（十一）（2）

Xml

设置文本属性

上下文管理器支持

设置文本属性

上下文管理器支持

热门文章

最新文章

相关课程

相关电子书