Xml#

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()`	使用相同的标准重复之前的“查找”。
`insert_after()`	在当前节点之后插入一个元素。
`insert_before()`	在当前节点之前插入一个元素。
`remove()`	移除这个节点。
`set_align()`	使用CSS样式规范设置对齐方式。仅适用于块级标签。
`set_attribute()`	将任意键设置为某个值（可以为空）。
`set_bgcolor()`	设置背景颜色。仅适用于块级标签。
`set_bold()`	设置粗体开或关，或设置为某个字符串值。
`set_color()`	设置文本颜色。
`set_columns()`	设置列的数量。参数可以是任何有效的数字或字符串。
`set_font()`	设置字体系列，例如“无衬线”。
`set_fontsize()`	设置字体大小。可以是浮点数或有效的HTML/CSS字符串。
`set_id()`	设置一个 id。会进行唯一性检查。
`set_italic()`	设置斜体为开启或关闭，或设置为某个字符串值。
`set_leading()`	设置块间文本距离 (`-mupdf-leading`)，仅在块级节点上有效。
`set_lineheight()`	设置行的高度。像 `1.5 * fontsize` 这样的浮点数，将设置为
`set_margins()`	设置边距，可以是最多包含4个值的浮动或字符串。
`set_pagebreak_after()`	在此节点之后插入分页符。
`set_pagebreak_before()`	在此节点之前插入分页符。
`set_properties()`	一次调用设置任意或全部所需属性。
`add_style()`	设置（添加）一个“样式”，该样式不被其自己的 `set_` 方法支持。
`add_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。

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

add_horizontal_line()#: 添加一个 hr 标签。查看 hr。

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

添加一个img标签。这会导致在DOM中包含命名的图像。

Parameters:

name (str) – 图片的文件名。这个 必须是 Story 构造函数的 Archive 参数的某个条目的成员名称。
宽度 – 如果提供，则为绝对（int）值或类似“30%”的百分比字符串。百分比值是指在Story.place()中指定的where矩形的宽度。如果提供了此值且省略了height，则图像将以保持其纵横比的方式包含在内。
height – 如果提供了，既可以是一个绝对值（整数），也可以是像“30%”这样的百分比字符串。百分比值指的是指定的 where 矩形在 Story.place() 中的高度。如果提供了这个值并且 width 被省略，图片的纵横比将被保留。

add_link(href, text=None)#

添加一个a标签 - 行内元素，像文本一样处理。

Parameters:

href (str) – 目标URL。
文本 (字符串) – 要显示的文本。如果省略，将显示href文本。

add_number_list()#: 添加一个 ol 标签，上下文管理器。

add_paragraph()#: 添加一个 p 标签，上下文管理器。

add_span()#: 添加一个 span 标签，上下文管理器。查看 span

add_subscript(text)#: 添加“下标”文本(sub 标签) - 行内元素，像文本一样处理。

add_superscript(text)#: 添加“上标”文本（sup 标签） - 行内元素，像文本一样处理。

add_code(text)#: 添加“code”文本（code标签）- 内联元素，像文本一样处理。

add_var(text)#: 添加“变量”文本（var标签）- 行内元素，像文本一样处理。

add_samp(text)#: 添加“示例输出”文本（samp 标签） - 内联元素，像文本一样处理。

add_kbd(text)#: 添加“键盘输入”文本 (kbd 标签) - 行内元素，像文本一样处理。

add_text(text)#: 添加一个文本字符串。换行符 \n 被视为 br 标签。

set_align(value)#

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

Parameters:: value – 可以是文本对齐或text-align的值之一。

set_attribute(key, value=None)#

将任意键设置为某个值（该值可以为空）。

Parameters:

key (str) – 属性的名称。
value (str) – 属性的（可选）值。

get_attributes()#

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

Returns:: 一个包含节点属性及其值的字典。

get_attribute_value(key)#

获取 key 的属性值。

Parameters:: key (str) – 属性的名称。
Returns:: 一个字符串，其值为 key。

remove_attribute(key)#

从节点中移除属性 key。

Parameters:: key (str) – 属性的名称。

set_bgcolor(value)#

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

Parameters:: 值 – 可以是像 (255, 0, 0) 这样的 RGB 值（代表“红色”）或一个有效的 background-color 值。

set_bold(value)#

将粗体设置为开启或关闭，或者设置为某个字符串值。

Parameters:: 值 – True, False 或一个有效的 font-weight 值。

set_color(value)#

设置后续文本的颜色。

Parameters:: 值 – 可以是一个RGB值，如(255, 0, 0)（表示“红色”）或一个有效的颜色值。

set_columns(value)#

设置列数。

Parameters:: value – 一个有效的 columns 值。

注意

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

set_font(value)#

设置字体系列。

Parameters:: 值 (字符串) – 例如“无衬线”.

set_fontsize(value)#

设置后续文本的字体大小。

Parameters:: value – 一个浮点数或有效的 font-size 值。

set_id(unqid)#

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

Parameters:: unqid (str) – 节点的 ID 字符串。

set_italic(value)#

为后面的文本设置斜体开或关，或设置为某个字符串值。

Parameters:: 值 – True, False 或某个有效的 font-style 值。

set_leading(value)#

设置块间文本距离 (-mupdf-leading)，仅在块级节点上有效。

Parameters:: value (float) – 到前一个区块的距离，以点为单位。

set_lineheight(value)#

设置行的高度。

Parameters:: value – 一个像 1.5 的浮点数（它设置为 1.5 * fontsize），或一些有效的 line-height 值。

set_margins(value)#

设置边距。

Parameters:: 值 – 浮点数或字符串，最多可包含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_ 方法会在当前节点下生成

add_style(value)#

设置 (添加) 一些其自身 set_ 方法不支持的样式属性。

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

add_class(value)#

设置 (添加) 一些 “class” 属性。

Parameters:: value (str) – 类的名称。必须在DOM的HTML或CSS源中定义。

set_text_indent(value)#

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

Parameters:: value – 一个有效的 text-indent 值。请注意，负值无效。

append_child(node)#

添加一个子节点。这是一个底层方法，由其他方法如 Xml.add_paragraph() 使用。

Parameters:: 节点 – 要附加的 Xml 节点。

create_text_node(text)#

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

Parameters:: 文本 (str) – 要附加的文本。
Return type:: Xml
Returns:: 创建的元素。

create_element(tag)#

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

Parameters:: 标签 (str) – 元素标签。
Return type:: Xml
Returns:: 已创建的元素。要将其实际绑定到DOM，使用 Xml.append_child()。

insert_before(elem)#

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

Parameters:: elem – 一些 Xml 元素。

insert_after(elem)#

在这个节点后插入给定的元素 elem。

Parameters:: elem - 一些 Xml 元素。

clone()#

制作该节点的副本，然后可以追加（使用 Xml.append_child()）或插入（使用其中一个 Xml.insert_before()， Xml.insert_after()）到这个 DOM 中。

Returns:: 当前节点的克隆 (Xml)。

remove()#: 从DOM中移除此节点。

debug()#: 出于调试目的，以简化形式打印该节点的结构。

find(tag, att, match)#

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

Parameters:

标签 (str) – 将搜索限制为此标签。对于不受限制的搜索，可以是 None。
att (str) – 检查这个属性。可能是 None。
match (str) – 要匹配的期望属性值。可能是 None。

Return type:

Xml。

Returns:

None 如果没有找到，则返回；否则，返回第一个匹配的节点。

find_next(tag, att, match)#

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

Return type:: Xml。
Returns:: 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")

Do you have any feedback on this page?

本软件按原样提供，不作任何明示或暗示的担保。该软件根据许可证分发，除非按照该许可证的条款明确授权，否则不得复制、修改或分发。有关许可信息，请参阅artifex.com或联系Artifex Software Inc.，地址：39 Mesa Street, Suite 108A, San Francisco CA 94129, United States以获取更多信息。