【python-docx 03】对文本操作

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

块级与内联文本对象

段落是Word中的主要块级对象，块级项目在其左右边缘之间流动包含的文本，每次文本超出其右边界时添加一条附加行。
对于段落，边界通常是页边距，但如果页面按列布局，它们也可以是列边界，如果段落出现在表格单元格内，则它们也可以是单元格边界。表也​​是块级对象。

内联对象是在块级项目内发生的内容的一部分。一个例子是以粗体显示的单词或全部大写的句子。最常见的内联对象是run。块容器中的所有内容都在内联对象内。

通常，段落包含一个或多个run对象，每个run对象包含段落文本的某些部分。

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

段落属性

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

对于段落属性应将适当的样式应用于每个段落，而不是将这些属性直接重复应用于每个段落。这类似于层叠样式表（CSS）如何与HTML一起使用。

此处描述的所有段落属性都可以使用样式设置，也可以直接应用于段落。使用段落的paragraph_format属性提供的ParagraphFormat对象访问段落的格式属性。

水平对齐

也称为对齐，可以使用枚举WD_PARAGRAPH_ALIGNMENT中的值将段落的水平对齐设置为左对齐，居中对齐，右对齐或完全对齐（在左侧和右侧对齐）：

from docx.enum.text import WD_PARAGRAPH_ALIGNMENT

document = Document()
paragraph = document.add_paragraph()
paragraph_format = paragraph.paragraph_format

paragraph_format.alignment = WD_PARAGRAPH_ALIGNMENT.CENTER #居中

缩进

缩进是段落与其容器边缘之间的水平空间，通常是页边距。
段落可以在左侧和右侧分别缩进。

第一行也可以具有与段落其余部分不同的缩进。第一行缩进比段落的其余部分多进行了一部分缩进。

缩进的第一行有一个悬挂缩进。使用Length值指定缩进，例如Inches，Pt或Cm。

负值有效并导致段落重叠。

None表示缩进值从样式层次结构继承。

将“None”分配给缩进属性将删除任何直接应用的缩进设置，并·从样式层次结构中恢复继承：

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

paragraph_format.left_indent = Cm(0.5) # 默认为None

右侧缩进类似：

from docx.shared import Pt
paragraph_format.right_indent = Pt(24)

使用first_line_indent属性指定第一行缩进，并相对于左缩进进行缩进。负值表示悬挂缩进：

paragraph_format.first_line_indent = Inches(-0.25)

制表符

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

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

>>> 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(Cm(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)

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

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

段落间距

space_before和space_after属性控制后续段落之间的间距，分别控制段落前后的间距。

在页面布局期间折叠段间间距，这意味着两个段落之间的间距是第一个段落的space_after和第二个段落的space_before的最大值。

段落间距指定为长度值，通常使用Pt：

paragraph_format.space_before = Pt(18)
paragraph_format.space_after = Pt(12)

行间距

行间距是段落行中后续基线之间的距离。
行间距可以指定为绝对距离或相对于行高（基本上是所用字体的点大小）。

典型的绝对衡量标准是18pt。
典型的相对测量是双倍间距（2.0线高）。
默认行间距是单行间距（1.0行高）。

行间距由line_spacing和line_spacing_rule属性相互控制。line_spacing是长度值，浮点型或None。
长度值表示绝对距离。
浮点表示行数高度。
None表示继承行间距。
line_spacing_rule值为WD_LINE_SPACING中的元素或为None：

paragraph_format.line_spacing = Pt(18)
print(paragraph_format.line_spacing_rule) # EXACTLY (4)

paragraph_format.line_spacing = 1.75
print(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表示“on”，False表示“off”

print(paragraph_format.keep_together)  # None
paragraph_format.keep_with_next = True
paragraph_format.page_break_before = False

应用字符格式

run级别的应用字符格式：包括字体字体和大小，粗体，斜体和下划线。

Run对象具有只读字体属性，可以访问Font对象。一个run的Font对象提供了获取和设置该run对象的字符格式属性。

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

可以像这样访问run对象的的字体：

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

设置字体和大小如下：

from docx.shared import Pt
font.name = '宋体'
font.size = Pt(12)

许多字体属性都是三种状态，True，False和None。
True表示属性为“on”，False表示属性为“off”。
从概念上讲，None值表示“继承”。样式继承层次结构中存在run对象，并且默认情况下从该层次结构继承其字符格式。使用Font对象直接应用的任何字符格式都会覆盖继承的值。

粗体和斜体都是三态的，如全大写，删除线，上标等等。有关这类属性的完整列表，请参阅Font API文档：

# 斜体
font.italic = True  
font.italic = False
font.italic = None

下划线是一种特殊情况。它是三态属性和枚举值属性的混合体。
True表示单个下划线，是迄今为止最常见的。
False意味着没有下划线，但更多情况下，如果不需要下划线，则None是正确的选择。
其他形式的下划线（如double或dashed）是使用WD_UNDERLINE里的方法指定：

from docx.enum.text import WD_UNDERLINE
font.underline = True
font.underline = WD_UNDERLINE.DOT_DASH  # 点划线

字体颜色

每个Font对象都有一个ColorFormat属性，可以指定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_INDEX
font.color.theme_color = MSO_THEME_COLOR_INDEX.ACCENT_1

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

font.color.rgb = None

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

print(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颜色：

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

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

print(font.color.theme_color)  # ACCENT_1 (5)