Xml#

中文

新增于 v1.21.0

该类表示一个 HTML 或 XML 节点。它是一个辅助类，旨在访问 Story 对象的 DOM（文档对象模型）内容。

无需直接创建 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()`	使用相同的查找条件重复执行“查找”操作。
`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_` 方法未提供支持的样式。
`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) – 图片的文件名。该文件 必须是 Archive 参数中的成员，且属于 Story 构造函数的输入。
width – 如果提供，可以是绝对值（int），也可以是类似 “30%” 的百分比字符串。百分比值表示相对于 Story.place() 方法中 where 矩形区域的宽度。如果提供 width 而省略 height，则图片将保持其纵横比。
height – 如果提供，可以是绝对值（int），也可以是类似 “30%” 的百分比字符串。百分比值表示相对于 Story.place() 方法中 where 矩形区域的高度。如果提供 height 而省略 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-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 中唯一标识该节点。可用于轻松定位节点，以便检查或修改。系统会检查 ID 的唯一性。

参数:: unqid (str) – 节点的唯一 ID 字符串。

set_italic(value)#

设置斜体，可以开启、关闭或指定具体的字符串值。

参数:: value – True、False，或一个有效的 font-style 值。

set_leading(value)#

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

参数:: value (float) – 以点（points）为单位的间距，表示与前一个块的距离。

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)#

添加某些 set_ 方法不支持的样式属性。

参数:: value (str) – 任何有效的 CSS 样式值。

add_class(value)#

添加 class 属性。

参数:: value (str) – 类名。必须在 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() 添加到 DOM，或通过 Xml.insert_before() 、 Xml.insert_after() 插入。

返回:: 当前节点的克隆 (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。

英文

New in v1.21.0

This represents an HTML or an XML node. It is a helper class intended to access the DOM (Document Object Model) content of a Story object.

There is no need to ever directly construct an Xml object: after creating a Story, simply take Story.body – which is an Xml node – and use it to navigate your way through the story’s DOM.

Method / Attribute	Description
`add_bullet_list()`	Add a ul tag - bulleted list, context manager.
`add_codeblock()`	Add a pre tag, context manager.
`add_description_list()`	Add a dl tag, context manager.
`add_division()`	add a div tag (renamed from “section”), context manager.
`add_header()`	Add a header tag (one of h1 to h6), context manager.
`add_horizontal_line()`	Add a hr tag.
`add_image()`	Add a img tag.
`add_link()`	Add a a tag.
`add_number_list()`	Add a ol tag, context manager.
`add_paragraph()`	Add a p tag.
`add_span()`	Add a span tag, context manager.
`add_subscript()`	Add subscript text(sub tag) - inline element, treated like text.
`add_superscript()`	Add subscript text (sup tag) - inline element, treated like text.
`add_code()`	Add code text (code tag) - inline element, treated like text.
`add_var()`	Add code text (code tag) - inline element, treated like text.
`add_samp()`	Add code text (code tag) - inline element, treated like text.
`add_kbd()`	Add code text (code tag) - inline element, treated like text.
`add_text()`	Add a text string. Line breaks `\n` are honored as br tags.
`append_child()`	Append a child node.
`clone()`	Make a copy if this node.
`create_element()`	Make a new node with a given tag name.
`create_text_node()`	Create direct text for the current node.
`find()`	Find a sub-node with given properties.
`find_next()`	Repeat previous “find” with the same criteria.
`insert_after()`	Insert an element after current node.
`insert_before()`	Insert an element before current node.
`remove()`	Remove this node.
`set_align()`	Set the alignment using a CSS style spec. Only works for block-level tags.
`set_attribute()`	Set an arbitrary key to some value (which may be empty).
`set_bgcolor()`	Set the background color. Only works for block-level tags.
`set_bold()`	Set bold on or off or to some string value.
`set_color()`	Set text color.
`set_columns()`	Set the number of columns. Argument may be any valid number or string.
`set_font()`	Set the font-family, e.g. “sans-serif”.
`set_fontsize()`	Set the font size. Either a float or a valid HTML/CSS string.
`set_id()`	Set a id. A check for uniqueness is performed.
`set_italic()`	Set italic on or off or to some string value.
`set_leading()`	Set inter-block text distance (`-mupdf-leading`), only works on block-level nodes.
`set_lineheight()`	Set height of a line. Float like 1.5, which sets to `1.5 * fontsize`.
`set_margins()`	Set the margin(s), float or string with up to 4 values.
`set_pagebreak_after()`	Insert a page break after this node.
`set_pagebreak_before()`	Insert a page break before this node.
`set_properties()`	Set any or all desired properties in one call.
`add_style()`	Set (add) a “style” that is not supported by its own `set_` method.
`add_class()`	Set (add) a “class” attribute.
`set_text_indent()`	Set indentation for first textblock line. Only works for block-level nodes.
`tagname`	Either the HTML tag name like p or `None` if a text node.
`text`	Either the node’s text or `None` if a tag node.
`is_text`	Check if the node is a text.
`first_child`	Contains the first node one level below this one (or `None`).
`last_child`	Contains the last node one level below this one (or `None`).
`next`	The next node at the same level (or `None`).
`previous`	The previous node at the same level.
`root`	The top node of the DOM, which hence has the tagname html.

Class API

设置文本属性#

Setting Text properties

中文

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

some bold textthis is bold and italicregular text。

为了实现相同的效果，方法如 Xml.set_bold() 和 Xml.set_italic() 会在当前节点下创建一个临时的 span，并应用相应的样式。

此外，这些方法会返回它们的父节点，因此可以进行链式调用。

英文

In HTML tags can be nested such that innermost text inherits properties from the tag enveloping its parent tag. For example .

To achieve the same effect, methods like Xml.set_bold() and Xml.set_italic() each open a temporary span with the desired property underneath the current node.

In addition, these methods return there parent node, so they can be concatenated with each other.

上下文管理器支持#

Context Manager support

中文

向 DOM 添加节点的标准方式如下:

body = story.body
para = body.add_paragraph()  # 添加一个段落
para.set_bold()  # 接下来的文本将加粗
para.add_text("some bold text")
para.set_italic()  # 接下来的文本将额外变为斜体
para.add_text("this is bold and italic")
para.set_italic(False).set_bold(False)  # 之后的所有文本恢复正常
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")

英文

The standard way to add nodes to a DOM is this:

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")

Methods that are flagged as “context managers” can conveniently be used in this way:

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 了解更多信息。