文本相关对象

Paragraph 对象

class docx.text.paragraph.Paragraph[源代码]

代理对象包装 <w:p> 元素。

add_run(text: str | None = None, style: str | CharacterStyle | None = None) → Run[源代码]

附加管路，其中包含 text 并且有性格风格 style 。

text 可以包含制表符 (\t )字符，这些字符被转换为用于选项卡的适当的XML形式。 text 还可以包括换行符 (\n )或回程 (\r )字符，每个字符都转换为换行符。什么时候 text 是 None ，新的运行是空的。

property alignment: WD_PARAGRAPH_ALIGNMENT | None

该委员会的成员 WD_PARAGRAPH_ALIGNMENT 指定此段落的对齐设置的枚举。

价值为 None 指示段落没有直接应用的对齐值，并将从其样式层次结构继承其对齐值。分配 None 设置为此属性将移除任何直接应用的对齐值。

clear()[源代码]

删除该段落的所有内容后将其退回。

保留段落级别的格式设置，如样式。

property contains_page_break: bool

True 当本段中出现一个或多个呈现的分页符时。

A Hyperlink 实例，用于本段中的每个超链接。

insert_paragraph_before(text: str | None = None, style: str | ParagraphStyle | None = None) → Self[源代码]

返回一个新创建的段落，直接插入到该段落之前。

如果 text ，则新段落在单个运行中包含该文本。如果 style 则将该样式分配给新段落。

iter_inner_content() → Iterator[Run | Hyperlink][源代码]

按照出现的顺序生成本段中的管路和超链接。

段落中的内容由运行和超链接两部分组成。此方法允许按文档顺序分别访问其中的每一个，以便在段落文本中超链接的准确位置很重要时使用。请注意，超链接本身包含运行。

property paragraph_format

这个 ParagraphFormat 对象提供对此段落的格式属性（如行距和缩进）的访问。

property rendered_page_breaks: List[RenderedPageBreak]

本段中呈现的所有分页符。

最常见的是一个空的列表，有时包含一个分页符，但可以包含多个是罕见的或人为的案例。

property runs: List[Run]

序列 Run 与本段中的<w:r>元素相对应的实例。

property style: ParagraphStyle | None

读/写。

ParagraphStyle 对象，表示分配给此段落的样式。如果没有为该段落指定显式样式，则其值为文档的默认段落样式。可以指定段落样式名称来代替段落样式对象。分配 None 删除所有应用的样式，使其有效值成为文档的默认段落样式。

property text: str

本段的正文内容。

文本包括段落中任何超链接的可见文本部分。将XML中的制表符和换行符映射到 \t 和 \n 字符分别为。

将文本分配给此属性将导致所有现有段落内容替换为包含指定文本的单个行。A \t 文本中的字符映射到 <w:tab/> 元素和每个元素 \n 或 \r 字符映射到换行符。段落级格式（如样式）将保留。删除所有运行级别的格式，例如粗体或斜体。

ParagraphFormat 对象

class docx.text.parfmt.ParagraphFormat[源代码]

提供对段落格式的访问，如对齐、缩进、行距、前后空格和窗口/孤立控件。

property alignment

该委员会的成员 WD_PARAGRAPH_ALIGNMENT 指定此段落的对齐设置的枚举。

价值为 None 指示段落对齐方式继承自样式层次结构。

property first_line_indent

Length 值，该值指定段落第一行的缩进的相对差异。

如果为正值，将缩进第一行。负值会产生悬挂缩进。 None 指示第一行缩进继承自样式层次结构。

property keep_together

True 当呈现文档时，该段落是否应保持“完整”，并且不应跨越页面边界。

None 指示其有效值继承自样式层次结构。

property keep_with_next

True 在呈现文档时，该段是否应与后续段落保持在同一页上。

例如，此属性可用于将节标题与其第一段保持在同一页上。 None 指示其有效值继承自样式层次结构。

property left_indent

Length 值，该值指定段落左侧边距和左侧之间的间距。

None 指示左缩进值继承自样式层次结构。使用一个 Inches 值对象作为一种以英寸为单位应用缩进的便捷方式。

property line_spacing

float 或 Length 值，该值指定段落连续行中基线之间的间距。

价值为 None 指示行间距继承自样式层次结构。浮点值，例如 2.0 或 1.75 ，表示以行高的倍数应用间距。一个 Length 价值，例如 Pt(12) 指示间距为固定高度。这个 Pt Value类是以点为单位应用行间距的便捷方法。分配 None 重置行间距以继承样式层次结构。

property line_spacing_rule

该委员会的成员 WD_LINE_SPACING 枚举，指示如何将 line_spacing 应该被解释为。

将任一 WD_LINE_SPACING 委员 SINGLE ， DOUBLE ，或 ONE_POINT_FIVE 将导致 line_spacing 被更新以产生相应的行距。

property page_break_before

True 如果该段应出现在前一段之后的页面顶部。

None 指示其有效值继承自样式层次结构。

property right_indent

Length 值，该值指定段落右边距和右侧之间的间距。

None 指示从样式层次结构继承右缩进值。使用 Cm 值对象作为以厘米为单位应用缩进的便捷方法。

property space_after

Length 值，该值指定在本段和下一段之间显示的间距。

None 指示该值继承自样式层次结构。 Length 对象提供了方便的属性，如 pt 和 inches ，允许轻松转换为各种长度单位。

property space_before

Length 值，该值指定在本段和上一段之间显示的间距。

None 指示该值继承自样式层次结构。 Length 对象提供了方便的属性，如 pt 和 cm ，允许轻松转换为各种长度单位。

tab_stops[源代码]

TabStops 对象提供对为此段落格式定义的选项卡停止的访问。

property widow_control

True 当Word对文档进行重新分页时，段落中的第一行和最后一行与段落的其余行保持在同一页上。

None 指示其有效值继承自样式层次结构。

Run 对象

class docx.text.run.Run[源代码]

代理对象换行 <w:r> 元素。

运行中的几个属性具有三态值， True ， False ，或 None 。 True 和 False 分别对应于开和关。 None 指示未在运行中直接指定该属性，其有效值取自样式层次结构。

add_break(break_type: WD_BREAK_TYPE = WD_BREAK_TYPE.LINE)[源代码]

添加的中断元素 break_type 到这一次跑步。

break_type 可以将这些值 WD_BREAK.LINE ， WD_BREAK.PAGE ，以及 WD_BREAK.COLUMN 哪里 WD_BREAK 从以下位置导入 docx.enum.text 。 break_type 默认为 WD_BREAK.LINE 。

add_picture(image_path_or_stream: str | IO[bytes], width: Length | None = None, height: Length | None = None) → InlineShape[源代码]

返回 InlineShape 包含由标识的图像 image_path_or_stream 。

该图片将添加到此运行的末尾。

image_path_or_stream 可以是路径(字符串)或包含二进制图像的类似文件的对象。

如果既未指定宽度也未指定高度，则图片以其原始大小显示。如果只指定了一个，则使用它来计算比例因子，然后将该比例因子应用于未指定的维度，从而保留图像的纵横比。图片的原始大小是使用图像文件中指定的每英寸点数(Dpi)值计算的，如果未指定值，则默认为72 dpi，这是通常的情况。

add_tab() → None[源代码]

添加 <w:tab/> 元素，Word将其解释为制表符。

add_text(text: str)[源代码]

返回一个新追加的 _Text 对象(对应于新的 <w:t> 子元素)添加到运行，包含 text 。

与可能更友好的将文本分配给 Run.text 财产。

property bold: bool | None

读/写三态值。

什么时候 True 使管路的文本以粗体显示。什么时候 False ，则文本无条件地显示为非粗体。什么时候 None 此运行的粗体设置继承自样式层次结构。

clear()[源代码]

删除所有内容后，返回对此运行的引用。

所有运行格式都将保留。

property contains_page_break: bool

True 在此运行中出现一个或多个呈现的分页符时。

请注意，作者插入的“硬”分页符不包括在内。硬分页符会在正确的位置产生呈现的分页符，因此如果包含这些分页符，则该分页符将被“重复计算”。

在一次运行中出现多个呈现的分页符的情况非常罕见，但这是可能的。

property font: Font

这个 Font 对象提供对此运行的字符格式属性（如字体名称和大小）的访问权限。

property italic: bool | None

读/写三态值。

什么时候 True 使管路的文本以斜体显示。什么时候 False ，则文本无条件地显示为非斜体。什么时候 None 此管路的斜体设置继承自样式层次结构。

iter_inner_content() → Iterator[str | Drawing | RenderedPageBreak][源代码]

按显示顺序生成此运行中的内容项。

注意：仅当前支持的内容类型 python-docx 都是生成的。在此版本中，这是文本和呈现的分页符。包含绘图，但当前仅提供对其在其 ._drawing 属性。 Drawing 属性和方法可能会在将来的版本中进行扩展。

Run中可以出现许多元素类型，但大多数元素类型(w：br、w：cr、w：noBreakHyphen、w：t、w：Tab)都具有清晰的纯文本等效项。这类元素的任何连续范围都将作为单个 str 。呈现的分页符和绘图元素是单独生成的。任何其他元素都将被忽略。

property style: CharacterStyle

读/写。

A CharacterStyle 对象，该对象表示应用于此运行的字符样式。文档的默认字符样式(通常 Default Character Font 如果运行没有直接应用的字符样式，则返回。将此属性设置为 None 删除任何直接应用的字符样式。

property text: str

将每个运行的文本等效项连接起来形成的字符串。

每个 <w:t> 元素添加它包含的文本字符。一个 <w:tab/> 元素添加了一个 t 性格。一个 <w:cr/> 或 <w:br> 元素中的每个元素添加一个 n 性格。请注意，一个 <w:br> 元素可以指示分页符或分栏符以及分行符。只有换行符 <w:br> 元素转换为 n 性格。其他人则被忽视了。所有其他内容子元素，如 <w:drawing> ，则被忽略。

将文本分配给此属性会产生相反的效果，即将每个 t 字符转换为 <w:tab/> 元素和每个元素 n 或 r 字符转换为 <w:cr/> 元素。任何现有运行内容都将被替换。运行格式将被保留。

property underline: bool | WD_UNDERLINE | None

此对象的下划线样式 Run 。

价值是以下之一 None ， True ， False ，或其成员 WD_UNDERLINE 。

价值为 None 指示运行没有直接应用的下划线值，因此将继承其包含的段落的下划线值。分配 None 设置为此属性将移除任何直接应用的下划线值。

价值为 False 指示直接应用的设置，不带下划线，重写任何继承值。

价值为 True 表示单下划线。

值来自 WD_UNDERLINE 用于指定其他轮廓样式，如双精度、波浪形和虚线。

Font 对象

class docx.text.run.Font[源代码]

对象的父级的代理对象 <w:rPr> 元素，并提供对字体名称、字体大小、粗体和下标等字符属性的访问。

property all_caps: bool | None

读/写。

使此字体的文本以大写字母显示。

property bold: bool | None

读/写。

使此字体的文本以粗体显示。

property color

A ColorFormat 对象提供获取和设置此字体的文本颜色的方法。

property complex_script: bool | None

读/写三态值。

什么时候 True 使运行中的字符被视为复杂脚本，而不考虑其Unicode值。

property cs_bold: bool | None

读/写三态值。

什么时候 True 会导致运行中的复杂脚本字符以粗体显示。

property cs_italic: bool | None

读/写三态值。

什么时候 True 使运行中的复杂脚本字符以斜体显示。

property double_strike: bool | None

读/写三态值。

什么时候 True ，使运行中的文本显示为带有双删除线。

property emboss: bool | None

读/写三态值。

什么时候 True ，使管路中的文本看起来就像在浮雕中凸出页面一样。

property hidden: bool | None

读/写三态值。

什么时候 True 会导致显示不显示管路中的文本，除非应用程序设置强制显示隐藏的文本。

property highlight_color: WD_COLOR_INDEX | None

已应用的加亮颜色或 None 如果不突出显示。

property imprint: bool | None

读/写三态值。

什么时候 True ，使管路中的文本看起来就像被按到页面中一样。

property italic: bool | None

读/写三态值。

什么时候 True 使管路的文本以斜体显示。 None 指示有效值继承自样式层次结构。

property math: bool | None

读/写三态值。

什么时候 True ，指定此运行包含WML，应将其视为Office Open XML Math进行处理。

property name: str | None

此字体的字体名称 Font 。

如果找到匹配的字体，则使其控制的文本以命名字体显示。 None 指示字体继承自样式层次结构。

property no_proof: bool | None

读/写三态值。

什么时候 True 指定在扫描文档的拼写和语法时，此运行的内容不应报告任何错误。

property outline: bool | None

读/写三态值。

什么时候 True 通过在每个字符字形的内外边框周围绘制一个1像素宽的边框，使梯段中的字符看起来就像有轮廓一样。

property rtl: bool | None

读/写三态值。

什么时候 True 使运行中的文本具有从右向左的特征。

property shadow: bool | None

读/写三态值。

什么时候 True 使管路中的文本看起来好像每个字符都有阴影。

property size: Length | None

以英制公制单位(EMU)表示的字体高度。

None 指示字体大小应从样式层次结构继承。 Length 是的子类 int 具有便于转换为点或其他长度单位的特性。这个 docx.shared.Pt 类允许方便地指定点值：

>>> font.size = Pt(24)
>>> font.size
304800
>>> font.size.pt
24.0
property small_caps: bool | None

读/写三态值。

什么时候 True 使管路中的小写字符显示为大写字母，比为管路指定的字体小两磅。

property snap_to_grid: bool | None

读/写三态值。

什么时候 True 使运行在布局此运行中的字符时使用在docGrid元素中定义的文档网格每行字符数设置。

property spec_vanish: bool | None

读/写三态值。

什么时候 True ，指定即使当前文档中显示隐藏文本，给定管路的行为也应始终与隐藏的相同。该属性具有与目录相关的非常有限的专门用途。有关更多详细信息，请参阅规范(§17.3.2.36)。

property strike: bool | None

读/写三态值。

什么时候 True 使管路中的文本显示为一条穿过该线中心的水平线。

property subscript: bool | None

布尔值，指示此 Font 显示为下标。

None 指示下标/下标值继承自样式层次结构。

property superscript: bool | None

布尔值，指示此 Font 以上标的形式出现。

None 指示下标/上标值继承自样式层次结构。

property underline: bool | WD_UNDERLINE | None

此对象的下划线样式 Font 。

该值是以下值之一 None ， True ， False ，或其成员 WD_UNDERLINE 。

None 指示字体从样式层次结构继承其下划线值。 False 表示没有下划线。 True 表示单下划线。值来自 WD_UNDERLINE 用于指定其他轮廓样式，如双精度、波浪形和虚线。

property web_hidden: bool | None

读/写三态值。

什么时候 True 指定在网页视图中显示文档时，应隐藏此运行的内容。

RenderedPageBreak 对象

class docx.text.pagebreak.RenderedPageBreak[源代码]

为打印或显示目的，在排版时由Word插入的分页符。

这通常不对应于文档作者插入的“硬”分页符，而只是一个页面上的单词用完了空间，需要开始另一个页面。它们的位置可以根据打印机和页面大小以及页边距等而改变。它们也会随着编辑的进行而改变，但直到Word加载并保存文档后才会改变。

请注意，这些内容绝不会由 python-docx 因为它没有渲染功能。它们通常仅在以下情况下才对现有文档的文本提取有用 python-docx 仅仅被用作文件的“阅读器”。

注意：呈现的分页符可能出现在一个超链接中；考虑一个多字超链接，比如“优秀的维基百科关于LLMS的文章”，它恰好落在页面最后一行的末尾，使得页面在“维基百科”和“文章”之间进行分页。在这种“超链接中的分页符”情况下，这些方法将把分页符“移动”到超链接之后，这样整个超链接就会出现在 .preceding_paragraph_fragment 。虽然这会将超链接的“尾部”文本放在“错误的”页面上，但它避免了两个超链接，每个超链接都有实际文本的片段并指向相同的地址。

property following_paragraph_fragment: Paragraph | None

包含此分页符后面内容的“松散”段落。

有潜在的令人惊讶的行为，所以仔细阅读，确保这是你想要的。这主要是针对文本提取用例，对于这些用例来说，准确地将文本与其出现的页面相关联是很重要的。

比较 .preceding_paragraph_fragment 因为这两者是要一起使用的。

此值为 None 当此分页符后面没有内容时。这种情况在实践中不太可能发生，因为Word会在段落上放置偶数段分页符 following 换页符。尽管如此，这是可能的，而且必须加以检查。归来 None 对于这种情况，避免了在内容流中“插入”额外的、不存在的段落。请注意，内容可以包括DrawingML项，如图像或图表，而不仅仅是文本。

返回的段落 is divorced from the document body 。对其所做的任何更改都不会反映在文档中。它的目的是提供一个容器 (Paragraph )具有熟悉的属性和方法，这些属性和方法可用于描述段落中间分页符之后的段落内容。

在超链接内发生此中断时，不包含超链接的一部分。

property preceding_paragraph_fragment: Paragraph | None

包含此分页符之前内容的“松散”段落。

比较 .following_paragraph_fragment 因为这两者是要一起使用的。

此值为 None 当此分页符之前没有内容时。这种情况很常见，每当页面在偶数段落边界上换行时就会发生这种情况。归来 None 对于这种情况，避免了将不存在的段落“插入”到内容流中。请注意，内容可以包括DrawingML项，如图像或图表。

请注意返回的段落 is divorced from the document body 。对其所做的任何更改都不会反映在文档中。它的目的是提供一个熟悉的容器 (Paragraph )在出现分页符的段落中询问该分页符之前的内容。

在超链接内发生此中断时包含整个超链接。

TabStop 对象

class docx.text.tabstops.TabStop[源代码]

应用于段落或样式的单个制表位。

使用其包含的列表语义访问 TabStops 对象。

property alignment

成员之一 WD_TAB_ALIGNMENT 正在指定此制表位的对齐设置。

读/写。

property leader

成员之一 WD_TAB_LEADER 指定用作“前导”的重复字符，填充此制表符所跨越的空格。

分配 None 产生的结果与赋值 WD_TAB_LEADER.SPACES 。读/写。

property position

A Length 对象，该对象表示此制表位距段落内边缘的距离。

可能是积极的，也可能是消极的。读/写。

TabStops 对象

class docx.text.tabstops.TabStops[源代码]

一系列 TabStop 提供对段落或段落样式的制表位的访问的对象。

支持迭代、索引访问、del和len()。它是使用 tab_stops 属性；它不打算直接构造。

add_tab_stop(position, alignment=WD_TAB_ALIGNMENT.LEFT, leader=WD_TAB_LEADER.SPACES)[源代码]

在添加新的制表位 position 一种 Length 对象，指定制表位相对于段落边缘的位置。

A负数 position 值是有效的，并显示在悬挂缩进中。制表符对齐默认为左对齐，但可以通过传递 WD_TAB_ALIGNMENT 枚举为 alignment 。可通过传递 WD_TAB_LEADER 枚举为 leader 。

clear_all()[源代码]

删除所有自定义制表位。