【python-docx】文本操作（段落、run、标题、首行缩进、段前段后、多倍行距、对齐方式）

1.概念

块级元素（block-level） 是指作为一个整体的元素，典型的是段落（paragraph）。
行内元素（inline） ，你可以把它理解为一部分块级元素，即一个块级元素包含一个或多个行内元素，典型的是run对象（我也不知道run应该翻译成什么）。
举个例子，你在Word回车换行开始输入文本，即自成一个段落，如果你选中其中的几个文字，那这些文字即为run对象

2.段落

段落（paragraph）是最主要的块级元素，比如说我们要往文档里添加文字，其实就添加段落，add_paragraph()可以添加一个段落，返回一个Paragraph对象

2.1 插入段落

from docx import Document
from docx.text.paragraph import Paragraph

doc = Document()

paragraph1 = doc.add_paragraph("这是第1个段落")
paragraph2 = doc.add_paragraph("这是第2个段落")  # type: Paragraph
# 查看文档的所有列表
print(doc.paragraphs)  # 返回包含文档所有段落的列表
# 在paragraph2这个段落的前面插入一个段落
paragraph2.insert_paragraph_before("额外插入的段落文字")

doc.save("./test.docx")

2.1 段落样式

2.1.1 引用内置样式

设置Paragraph的style属性即可

from docx import Document
from docx.text.paragraph import Paragraph

doc = Document()

paragraph1 = doc.add_paragraph("这是第1个段落")  # type: Paragraph
paragraph1.style = "List Bullet"  # 设置段落样式为无序1

# 有序段落样式
doc.add_paragraph("测试段落List Number", style="List Number")
doc.add_paragraph("测试段落List Number", style="List Number")

# 无序段落样式2
doc.add_paragraph("测试段落List Bullet 2", style="List Bullet 2")
doc.add_paragraph("测试段落List Bullet 2", style="List Bullet 2")

doc.save("./test.docx")

# 一些常用的段落样式
# styles = doc.styles
# paragraph_styles = [s for s in styles if s.type == WD_STYLE_TYPE.PARAGRAPH]
# for style in paragraph_styles:
#     print(style.name)

官方文档说段落样式名应该与微软Office保持一致，但我看了微软给出的样式名与其对不上，建议直接参考源码的给出的枚举值，位置是/docx/enum/style.py，或者官方文档：https://python-docx.readthedocs.io/en/latest/user/styles-understanding.html

2.1.2 段落对齐

from docx import Document
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT

doc = Document()

paragraph1 = doc.add_paragraph("这是居中对齐段落")
paragraph1.alignment = WD_PARAGRAPH_ALIGNMENT.CENTER  # 居中对齐

doc.add_paragraph("这是左对齐段落").alignment = WD_PARAGRAPH_ALIGNMENT.LEFT  # 左对齐
doc.add_paragraph("这是右对齐段落").alignment = WD_PARAGRAPH_ALIGNMENT.RIGHT  # 右对齐
doc.add_paragraph("这是两端对齐段落").alignment = WD_PARAGRAPH_ALIGNMENT.JUSTIFY  # 两端对齐
doc.add_paragraph("这是分散对齐段落").alignment = WD_PARAGRAPH_ALIGNMENT.DISTRIBUTE  # 分散对齐

doc.save("./test.docx")

2.1.3 段落设置

from docx import Document
from docx.shared import Pt

doc = Document()

paragraph1 = doc.add_paragraph("这是一个普通的段落这是一个普通的段落这是一个普通的段落")
# paragraph.line_spacing_rule = WD_LINE_SPACING.EXACTLY  # 行距固定值
# paragraph.line_spacing_rule = WD_LINE_SPACING.MULTIPLE  # 多倍行距
# paragraph1.paragraph_format.line_spacing = 1.5  # 行间距，1.5倍行距
paragraph1.paragraph_format.line_spacing = Pt(20)  # 行间距，固定值20磅
paragraph1.paragraph_format.first_line_indent = Pt(10)  # 首行缩进10磅
paragraph1.paragraph_format.space_before = Pt(30)  # 段前30磅
paragraph1.paragraph_format.space_after = Pt(15)  # 段后15磅

doc.save("./test.docx")

特别说明，首行缩进的单位支持Pt、Cm、Mm、Inches等，如果想要缩进几个字符，需要自己进行转换，因为不同字号字符占用的磅数是不同的（五号字体 = 10.5pt = 3.70mm = 14px = 0.146inch）

3.Run

Run是指段落中某一部分文本，我们取到某些文本之后才能设置它们的样式，例如加粗、斜体、下划线等

from docx import Document
from docx.oxml.ns import qn
from docx.shared import Pt, RGBColor
from docx.text.paragraph import Paragraph

doc = Document()

paragraph1 = doc.add_paragraph("这是第1个段落")  # type: Paragraph
run1 = paragraph1.add_run("追加的文字")
run1.bold = True  # 加粗
run1.italic = True  # 斜体
run1.underline = True  # 下划线
# run1.text = "修改之后的文字"  # 修改文本
run1.font.name = "Times New Roman"  # 设置西文是新罗马字体
run1.element.rPr.rFonts.set(qn('w:eastAsia'), '宋体')  # 设置中文是宋体
run1.font.size = Pt(30)  # 字号大小
run1.font.bold = False  # 是否加粗
run1.font.italic = False  # 是否斜体
run1.font.underline = False  # 是否下划线
# run.font.underline = WD_UNDERLINE.DOUBLE  # 设置为双下划线
# 查看所有下划线类型
# for line_type in WD_UNDERLINE.__members__:
#     print(line_type.name)
run1.font.shadow = True  # 是否阴影
run.font.strike = True  # 是否删除线
# run.font.double_strike = True  # 是否双删除线
run1.font.color.rgb = RGBColor(56, 36, 255)  # 字体颜色
# run1.font.color.rgb = RGBColor.from_string("ff0056")  # 字体颜色
run.font.highlight_color = WD_COLOR_INDEX.YELLOW  # 文本高亮颜色，此次设置为黄色
# 查看所有支持的高亮颜色
# for color in WD_COLOR_INDEX.__members__:
#     print(color.name)

doc.save("./test.docx")

关于下划线，font.underline=True是单行下划线，其他样式可以参考官方给出的枚举值：https://python-docx.readthedocs.io/en/latest/api/enum/WdUnderline.html#wdunderline

当然也可以直接使用完整的字符样式

from docx import Document
from docx.text.paragraph import Paragraph

doc = Document()

paragraph1 = doc.add_paragraph("这是第1个段落")  # type: Paragraph
run2 = paragraph1.add_run("又追加了文字")
run2.style = "Emphasis"  # 使用“强调”样式

doc.save("./test.docx")

4.标题

可以通过add_heading()添加标题，标题等级用数字0-9表示，其实标题也是一个Paragraph对象

from docx import Document

doc = Document()
title = doc.add_heading(text="这是一级标题", level=1)  # type: Paragraph
doc.add_heading(text="这是一级标题2", level=1)
doc.add_heading(text="这是二级标题", level=2)
print("text:", title.text)  # text: 这是一级标题
print("style:", title.style)  # style: _ParagraphStyle('Heading 1') id: 1883614425040
doc.save("./test.docx")

标题等级(level)默认是1，对应“标题1”，如果设置为0，对应“标题”

5.Document对象常用方法和属性

from docx import Document
from docx.shared import Inches
from docx.text.paragraph import Paragraph

doc = Document()

doc.add_heading("这是一个标题")
doc.add_paragraph("这是一个段落")
doc.add_page_break()  # 插入一个分页符，实际上是调用新建段落的add_break(WD_BREAK.PAGE)
doc.add_picture('xxx.png', width=Inches(1.0))  # 添加一张图片，实际上是调用新建段落的run.add_picture
doc.add_table(5, 6)  # 添加一个5行6列的表格

print(doc.paragraphs)  # 返回所有段落（列表）
print(doc.tables)  # 返回所有表格(列表)
print(doc.styles)  # 返回默认Styles对象

doc.save("./test.docx")