使用文本

为了有效地处理文本，首先了解一些块级元素（如段落）和内联级对象（如运行）是很重要的。

块级与内联文本对象

段落是Word中的主要块级对象。

块级项将其包含的文本在其左边缘和右边缘之间流动，每次文本超出其右边界时都会添加一行。对于段落，边界通常是页边距，但如果页是按列布局的，则也可以是列边界；如果段落位于表单元格内，则也可以是单元格边界。

表也是块级对象。

内联对象是出现在块级项目内的内容的一部分。例如，以粗体显示的单词或全部大写的句子。最常见的内联对象是 run 。块容器中的所有内容都在内联对象中。通常，一个段落包含一个或多个串，每个串都包含该段文本的某一部分。

块级项目的属性指定其在页面上的位置，例如段落前后的缩进和空格。内联项目的属性通常指定内容显示的字体，例如字体、字体大小、粗体和斜体。

段落属性

段落具有各种属性，这些属性指定其在容器（通常是页面）中的位置以及将其内容划分为单独行的方式。

一般来说，最好定义 段落样式 将这些属性收集到一个有意义的组中，并对每个段落应用适当的样式，而不是重复地将这些属性直接应用于每个段落。这类似于级联样式表（CSS）与HTML的工作方式。这里描述的所有段落属性都可以使用样式设置，也可以直接应用于段落。

使用访问段落的格式属性 ParagraphFormat 使用段落的 paragraph_format 属性。

水平对齐（对齐）

也称为 justification ，可以使用枚举中的值将段落的水平对齐设置为左对齐、居中、右对齐或完全对齐(左右对齐 WD_PARAGRAPH_ALIGNMENT **

>>> from docx.enum.text import WD_ALIGN_PARAGRAPH
>>> document = Document()
>>> paragraph = document.add_paragraph()
>>> paragraph_format = paragraph.paragraph_format

>>> paragraph_format.alignment
None  # indicating alignment is inherited from the style hierarchy
>>> paragraph_format.alignment = WD_ALIGN_PARAGRAPH.CENTER
>>> paragraph_format.alignment
CENTER (1)

缩进

缩进是段落与其容器边缘之间的水平间距，通常是页边距。段落可以在左右两侧分别缩进。第一行也可以有不同于段落其余部分的缩进。比段落其余部分缩进的第一行 首行缩进 . 缩进较少的第一行具有 悬挂缩进 .

缩进是使用 Length 值，例如 Inches ， Pt 或 Cm . 负值是有效的，会导致段落与边距重叠指定的量。价值 None 指示缩进值是从样式层次结构继承的。分配 None 到缩进属性删除任何直接应用的缩进设置并从样式层次结构恢复继承：

>>> from docx.shared import Inches
>>> paragraph = document.add_paragraph()
>>> paragraph_format = paragraph.paragraph_format

>>> paragraph_format.left_indent
None  # indicating indentation is inherited from the style hierarchy
>>> paragraph_format.left_indent = Inches(0.5)
>>> paragraph_format.left_indent
457200
>>> paragraph_format.left_indent.inches
0.5

右侧缩进的工作方式类似：

>>> from docx.shared import Pt
>>> paragraph_format.right_indent
None
>>> paragraph_format.right_indent = Pt(24)
>>> paragraph_format.right_indent
304800
>>> paragraph_format.right_indent.pt
24.0

第一行缩进是使用 first_line_indent 属性，并相对于左缩进进行解释。负值表示挂起缩进：

>>> paragraph_format.first_line_indent
None
>>> paragraph_format.first_line_indent = Inches(-0.25)
>>> paragraph_format.first_line_indent
-228600
>>> paragraph_format.first_line_indent.inches
-0.25

制表位

制表位决定段落文本中制表符字符的呈现方式。特别是，它指定制表符后面的文本开始的位置、它将如何与该位置对齐，以及一个可选的引线字符，它将填充制表符跨越的水平空间。

段落或样式的制表位包含在 TabStops 对象使用 tab_stops 属性对 ParagraphFormat ：：

>>> tab_stops = paragraph_format.tab_stops
>>> tab_stops
<docx.text.tabstops.TabStops object at 0x106b802d8>

使用添加新的制表位 add_tab_stop() 方法：

>>> tab_stop = tab_stops.add_tab_stop(Inches(1.5))
>>> tab_stop.position
1371600
>>> tab_stop.position.inches
1.5

Alignment默认为left，但可以通过提供 WD_TAB_ALIGNMENT 枚举。引线字符默认为空格，但可以通过提供 WD_TAB_LEADER 枚举：：

>>> from docx.enum.text import WD_TAB_ALIGNMENT, WD_TAB_LEADER
>>> tab_stop = tab_stops.add_tab_stop(Inches(1.5), WD_TAB_ALIGNMENT.RIGHT, WD_TAB_LEADER.DOTS)
>>> print(tab_stop.alignment)
RIGHT (2)
>>> print(tab_stop.leader)
DOTS (1)

现有的制表位使用序列语义 TabStops ：：

>>> tab_stops[0]
<docx.text.tabstops.TabStop object at 0x1105427e8>

更多详细信息请参见 TabStops 和 TabStop API文档

段落间距

这个 space_before 和 space_after 属性控制后续段落之间的间距，分别控制段落前后的间距。段间间距为 collapsed 在页面布局期间，这意味着两个段落之间的间距是 space_after 对于第一段和 space_before 第二段的内容。段落间距指定为 Length 值，通常使用 Pt **

>>> paragraph_format.space_before, paragraph_format.space_after
(None, None)  # inherited by default

>>> paragraph_format.space_before = Pt(18)
>>> paragraph_format.space_before.pt
18.0

>>> paragraph_format.space_after = Pt(12)
>>> paragraph_format.space_after.pt
12.0

行距

行距是段落行中后续基线之间的距离。行距可以指定为绝对距离或相对于行高（基本上是所用字体的点大小）。典型的绝对测量值是18分。典型的相对测量值为双倍行距（2.0线高）。默认行距为单倍行距（1.0行高）。

行距由 line_spacing 和 line_spacing_rule 性质。 line_spacing 或者是 Length 值，a（小写） float 或没有。A Length 值表示绝对距离。A float 指示多个线条高度。 None 表示行距是继承的。 line_spacing_rule 是的成员 WD_LINE_SPACING 枚举或 None ：：

>>> from docx.shared import Length
>>> paragraph_format.line_spacing
None
>>> paragraph_format.line_spacing_rule
None

>>> paragraph_format.line_spacing = Pt(18)
>>> isinstance(paragraph_format.line_spacing, Length)
True
>>> paragraph_format.line_spacing.pt
18.0
>>> paragraph_format.line_spacing_rule
EXACTLY (4)

>>> paragraph_format.line_spacing = 1.75
>>> paragraph_format.line_spacing
1.75
>>> paragraph_format.line_spacing_rule
MULTIPLE (5)

分页属性

四个段落属性， keep_together ， keep_with_next ， page_break_before 和 widow_control 控制段落在页面边界附近的行为。

keep_together 使整个段落出现在同一页上，如果不这样做，会在段落前面发出分页符，否则会在两页之间断开。

keep_with_next 将段落与后续段落保持在同一页上。例如，这可以用来保持节标题与节的第一段在同一页上。

page_break_before 使段落置于新页的顶部。这可以用于章节标题，以确保章节从新的页面开始。

widow_control 分页符以避免将段落的第一行或最后一行与段落其余部分分开放置在单独的页面上。

这四个属性都是 tri-state ，意味着他们可以接受价值 True ， False 或 None . None 指示属性值是从样式层次结构继承的。 True 意思是“开”和 False 表示“关闭”：

>>> paragraph_format.keep_together
None  # all four inherit by default
>>> paragraph_format.keep_with_next = True
>>> paragraph_format.keep_with_next
True
>>> paragraph_format.page_break_before = False
>>> paragraph_format.page_break_before
False

应用字符格式

字符格式在运行级别应用。例如字体字体和大小、粗体、斜体和下划线。

A Run 对象具有只读 font 提供访问 Font 对象。跑步的 Font 对象提供用于获取和设置该运行的字符格式的属性。

这里提供了几个例子。有关可用属性的完整集合，请参见 Font API文档。

可以这样访问运行的字体：

>>> from docx import Document
>>> document = Document()
>>> run = document.add_paragraph().add_run()
>>> font = run.font

字体和大小如下：

>>> from docx.shared import Pt
>>> font.name = 'Calibri'
>>> font.size = Pt(12)

许多字体属性是 tri-state ，意味着他们可以接受这些值 True ， False 和 None . True 表示属性为“开”， False 表示“关闭”。从概念上讲 None 值的意思是“继承”。运行存在于样式继承层次结构中，默认情况下从该层次结构继承其字符格式。使用 Font 对象重写继承的值。

粗体和斜体是三态属性，所有大写、删除线、上标和许多其他属性也是如此。见 Font 完整列表的API文档：

>>> font.bold, font.italic
(None, None)
>>> font.italic = True
>>> font.italic
True
>>> font.italic = False
>>> font.italic
False
>>> font.italic = None
>>> font.italic
None

下划线有点特殊。它是三态属性和枚举值属性的混合体。 True 表示单下划线，目前最常见。 False 意思是没有下划线，但更常见 None 如果不需要下划线，则是正确的选择。其他形式的下划线，如双下划线或虚线下划线，则使用 WD_UNDERLINE 枚举：：

>>> font.underline
None
>>> font.underline = True
>>> # or perhaps
>>> font.underline = WD_UNDERLINE.DOT_DASH

字体颜色

各 Font 对象具有 ColorFormat 对象，该对象提供对其颜色的访问，通过其只读访问 color 属性。

将特定的RGB颜色应用于字体：

>>> from docx.shared import RGBColor
>>> font.color.rgb = RGBColor(0x42, 0x24, 0xE9)

也可以通过指定 MSO_THEME_COLOR_INDEX 枚举：：

>>> from docx.enum.dml import MSO_THEME_COLOR
>>> font.color.theme_color = MSO_THEME_COLOR.ACCENT_1

字体的颜色可以通过赋值恢复为默认（继承）值 None 或者 rgb 或 theme_color 属性 ColorFormat ：：

>>> font.color.rgb = None

确定字体的颜色首先要确定字体的颜色类型：

>>> font.color.type
RGB (1)

的值 type 属性可以是 MSO_COLOR_TYPE 枚举或无。 MSO_COLOR_TYPE.RGB 指示它是RGB颜色。 MSO_COLOR_TYPE.THEME 指示主题颜色。 MSO_COLOR_TYPE.AUTO 指示其值由应用程序自动确定，通常设置为黑色。（此值相对较少。） None 表示不应用颜色，颜色是从样式层次结构继承的；这是最常见的情况。

当颜色类型为 MSO_COLOR_TYPE.RGB , the rgb 属性将是 RGBColor 指示RGB颜色的值：

>>> font.color.rgb
RGBColor(0x42, 0x24, 0xe9)

当颜色类型为 MSO_COLOR_TYPE.THEME , the theme_color 属性将是的成员 MSO_THEME_COLOR_INDEX 表示主题颜色：

>>> font.color.theme_color
ACCENT_1 (5)