Xml#

v1.21.0 新增

这表示一个 HTML 或 XML 节点。这是一个辅助类，用于访问 Story 对象的 DOM (Document Object Model) 内容。

无需直接构造 Xml 对象：创建 Story 后，只需获取 Story.body（它是一个 Xml 节点），然后使用它来浏览 Story 的 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()`	设置（添加）一个不支持其 own `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。

类 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 – 如果提供，可以是绝对值（整数）或百分比字符串，如“30%”。百分比值是指 Story.place() 中指定的 where 矩形的宽度。如果提供此值且省略 height，图像将保持其宽高比。
height – 如果提供，可以是绝对值（整数）或百分比字符串，如“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。因此，例如要“全局”为 body 设置一些属性，必须使用此方法。

add_style(value)#

设置（添加）一些不受其 own set_ 方法支持的“style”属性。

参数:: 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 节点。

返回类型:

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

参数:: 创建的元素。
Return type:: Xml
返回:: the created element.

create_element(tag)#

使用给定的标签创建一个新节点。这是一个低级方法，由 Xml.add_paragraph() 等其他方法使用。

参数:: tag (str) – 元素标签。
Return type:: 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。

Return type:

Xml.

返回:

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

find_next(tag, att, match)#

使用相同的值继续先前的 Xml.find()（或 find_next()）。

Return type:: Xml.
返回:: 如果未找到更多，则为 None，否则为下一个匹配节点。

tagname#: HTML 标签名称，如 p，或者如果是文本节点则为 None。

text#: 节点的文本，如果是标签节点则为 None。

is_text#: 检查是否为文本节点。

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

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

next#: 同一层级的下一个节点（或 None）。

previous#: 同一层级的上一个节点。

root#: DOM 的顶层节点，其标签名为 html。

设置文本属性#

在 HTML 中，标签可以嵌套，最里面的文本会继承其父标签的外层标签的属性。例如 <p>。

为了达到同样的效果，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., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States 获取更多信息。