python-docx官方文档翻译--用户指南04--使用文本

使用文本

为了有效地处理文本，了解段落等块级内容元素和 run 等运行级内容（内联文字）对象是有必要的。

块级与内联文本对象

段落是Word中的主要块级对象。
块级项的文本内容在其左右边界之间，每当文本超出其右边界时，其内容就会增加一行。对于段落而言，其左右边界通常是指页边距，但是如果页面按列布局，边界也可以是列边界，如果段落出现在表格单元格内，则边界可以是单元格边界。
表也是块级对象。
内联对象是块级元素内的部分内容。例如，一个粗体单词或一个全大写的句子。最常见的内联对象是 run。块级容器的所有内容（文本，图片等）都在内联对象中。通常，一个段落包含一个或多个 run，每个 run 包含该段落文本的一部分。
块级项目的属性指定其在页面上的表现，如段落前后的缩进和空格。内联项的属性通常指定显示内容的字形，如字体、字体大小、粗体和斜体。

段落属性

段落具有多种属性，可以指定其在容器（通常是页面）中的位置以及将内容划分为不同行的方式。
通常，最好定义一个段落样式并将段落属性集中到该样式，然后将适当的样式应用到对应的段落，而不是直接修改段落的属性。这与级联样式表（CSS）与 HTML 的工作方式相似。这里提到的所有段落属性都可以使用样式设置，也可以直接应用到段落。
段落的格式设置属性可通过使用段落的 paragraph_format 属性获取 ParagraphFormat 对象进行访问。

水平对齐

段落的水平对齐可以使用枚举类 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
# 这表示对齐方式是从样式层次结构中继承的
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_formatparagraph_format.left_indent
# None
# 这表示缩进是从样式层次结构中继承的
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 属性特别进行指定。负值表示悬挂缩进:

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

制表位

制表位决定了段落文本中制表符的呈现方式。特别是，它指定了制表符后面的文本的开始位置，与该位置的对齐方式，以及一个可选的前导字符，它将填充制表符跨越的水平空间。
段落或样式的制表位包含在 TabStops 对象中，该对象使用 ParagraphFormat 上的 tab_stops 属性f进行访问：

tab_stops = paragraph_format.tab_stops
print(tab_stops)
# <docx.text.tabstops.TabStops object at 0x106b802d8>

使用 add_tab_stop 方法添加一个新的制表位:

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

对齐方式默认为左对齐，但可以通过提供 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 类可以访问现有的制表位：

print(tab_stops[0])
# <docx.text.tabstops.TabStop object at 0x1105427e8>

更多详细信息可查阅 TabStops 和 TabStop 的 API 文档。

段落间距

space_before 和 space_after 属性控制后续段落之间的间距，分别控制段落之前和之后的间距。在页面布局期间，段落之间的间距是折叠的，这意味着两个段落之间的间距是第一段的 space_after 和第二段的space_before 的最大值。通常使用磅（Pt）来指定段落间距的 Length 值：

print(paragraph_format.space_before, paragraph_format.space_after)
# (None, None)
# 默认继承paragraph_format.space_before = Pt(18)
print(paragraph_format.space_before.pt)
# 18.0paragraph_format.space_after = Pt(12)
print(paragraph_format.space_after.pt)
# 12.0

行间距

行距是段落行中后续基线之间的距离。行距可以指定为绝对距离或相对于行高（基本上是所用字体的磅 Pt 值）。典型的绝对度量值为18磅（Pt）。典型的相对度量是双倍间距（2.0行高）。默认行距是单行距（1.0行高）。
行间距由 line_spacing 和 line_spacing_rule 属性的相互作用控制。 line_spacing 可以是 Length 值，float 值（小数）或 None。 Length 值指定绝对距离。float 表示行高数。None 表示行距是继承的。line_spacing_rule 可以是WD_LINE_SPACING 枚举的成员，或者是None：

from docx.shared import Length
paragraph_format.line_spacing
# None
paragraph_format.line_spacing_rule
# Noneparagraph_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 中断页面以避免将段落的第一行或最后一行与段落的其余部分分开在不同页面上。
所有这四个属性都是三态的，这意味着它们可以采用值True，False 或 None。 None 表示属性值是从样式层次结构继承的。 True 表示 “打开”，False 表示 “关闭”：

paragraph_format.keep_together
# None
# 默认情况下所有这四个都是继承
paragraph_format.keep_with_next = True
paragraph_format.keep_with_next
# True
paragraph_format.page_break_before = False
paragraph_format.page_break_before
# False

应用字符格式

字符格式在运行级别（Run Level）应用。示例包括字形的字体和大小、粗体、斜体和下划线。
Run 对象具有只读的 font 属性，提供对 Font 对象的访问。Run 的 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)

许多字体属性是三态的，这意味着它们可以采用值True，False 和 None。
True 表示属性为 “ on”，False 表示属性为 “ off”。从概念上讲，None 值表示 “继承”。存在于样式继承层次结构中的 run 在默认情况下，其会从该层次结构继承其字符格式。使用 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
# 或者
font.underline = WD_UNDERLINE.DOT_DASH

字体颜色

每个 Font 对象都有一个 ColorFormat 对象，该对象可通过其只读的 color 属性访问其颜色。

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

可以通过为 ColorFormat 的 rgb 或 theme_color 属性指定为 None 来将字体的颜色恢复为其默认（继承）值：

font.color.rgb = None

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

font.color.type
# RGB (1)

type 属性的值可以是 MSO_COLOR_TYPE 枚举的成员，也可以是 None。MSO_COLOR_TYPE.RGB 表示它是RGB颜色。 MSO_COLOR_TYPE.THEME 指示主题颜色。 MSO_COLOR_TYPE.AUTO 指示其值由应用程序自动确定，通常设置为黑色。（此值相对很少。）None 表示未应用颜色，并且颜色是从样式层次结构继承的；这是最常见的情况。
当颜色类型为 MSO_COLOR_TYPE.RGB 时，rgb 属性将是 RGBColor 值，表示为 RGB 格式颜色：

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

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

font.color.theme_color
# ACCENT_1 (5)