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

设置文本属性

上下文管理器支持

设置文本属性

上下文管理器支持

热门文章

最新文章

相关课程

相关电子书

热门

活动广场

任务中心

开发者评测

高校计划

乘风者计划

训练营

阿里云MVP

话题

直播

下载

镜像站

技术资料

插件

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

Xml

设置文本属性

上下文管理器支持

设置文本属性

上下文管理器支持

热门文章

最新文章

相关课程

相关电子书