说明

python-docx库 是一个用于创建和更新 Microsoft Word（.docx） 文件的Python库。

python-docx文档

• 参考原文: https://python-docx.readthedocs.io/en/latest/index.html - 官网

• 参考翻译: https://www.zybuluo.com/belia/note/1303813 - 参考1

• 参考翻译2: https://www.osgeo.cn/python-docx/index.html - 参考2

• openxml参考: https://zhuanlan.zhihu.com/p/353332428

设置中文字体参考

• python-docx中设置中文字体 - 个人博客
• python-docx设置中文字体 - 百度文章

小梁学编程

• Python-docx添加段落
• python-docx段落设置
• python-docx设置中文字体
• python-docx字体设置
• python-docx表格（一）：添加表格
• python-docx添加和删除表格行、列
• python-docx表格添加和删除数据
• python-docx设置表格对齐方式
• python-docx图像的添加与删除
• python-docx设置图片大小和对齐方式
• python-docx节的添加、定位和分节符的设置
• python-docx页面设置
• python-docx指定页面设置成横向
• python-docx设置页眉和页脚

他能做什么

from docx import Document
from docx.shared import Inches

document = Document()

document.add_heading('Document Title', 0)

p = document.add_paragraph('A plain paragraph having some ')
p.add_run('bold').bold = True
p.add_run(' and some ')
p.add_run('italic.').italic = True

document.add_heading('Heading, level 1', level=1)
document.add_paragraph('Intense quote', style='Intense Quote')

document.add_paragraph(
    'first item in unordered list', style='List Bullet'
)
document.add_paragraph(
    'first item in ordered list', style='List Number'
)

document.add_picture('monty-truth.png', width=Inches(1.25))

records = (
    (3, '101', 'Spam'),
    (7, '422', 'Eggs'),
    (4, '631', 'Spam, spam, eggs, and spam')
)

table = document.add_table(rows=1, cols=3)
hdr_cells = table.rows[0].cells
hdr_cells[0].text = 'Qty'
hdr_cells[1].text = 'Id'
hdr_cells[2].text = 'Desc'
for qty, id, desc in records:
    row_cells = table.add_row().cells
    row_cells[0].text = str(qty)
    row_cells[1].text = id
    row_cells[2].text = desc

document.add_page_break()

document.save('demo.docx')

用户指南

• 安装
• 快速开始
• 处理Document
• 处理Text
• 处理Section
• 处理页眉和页脚
• API基础知识
• 理解样式
• 处理样式
• 理解图片和其他形状

安装

注意: python docx版本0.3.0和更高版本与以前的版本不兼容。

python-docx 托管在PyPI上，所以安装相对简单，并且取决于您安装了什么安装实用程序。

python-docx 可与 pip 如果你有空的话：

pip install python-docx

python-docx 也可以使用 easy_install ，尽管不鼓励这样做：

easy_install python-docx

如果既不使用 pip 也不使用 easy_install 它可以通过从PyPI下载发行版、解包tarball并运行来手动安装 setup.py ：

tar xvzf python-docx-{version}.tar.gz
cd python-docx-{version}
python setup.py install

python-docx 取决于 lxml 包裹。两者兼而有之 pip 和 easy_install 将负责满足这些依赖项，但如果您使用最后一种方法，则需要自己安装这些依赖项。

依赖关系

• Python2.6、2.7、3.3或3.4
• lxml>=2.3.2

快速开始

原文: Quickstart

使用 python-docx 很简单。让我们简单介绍一下基本知识。

• 打开文档
• 添加段落
• 添加标题
• 添加分页符
• 添加表
• 添加图片
• 应用段落样式
• 应用粗体和斜体
• 应用字符样式

打开文档

你需要做的第一件事是一份文件。最简单的方法是：

from docx import Document

document = Document()

这将打开一个基于默认“模板”的空白文档，这与使用内置默认值在Word中启动新文档时所获得的内容非常相似。可以使用打开并处理现有的Word文档 python-docx ，但我们暂时把事情简单化。

添加段落

段落是文字的基础。它们用于正文，也用于标题和列表项，如项目符号。

下面是添加一个段落最简单的方法：

paragraph = document.add_paragraph('Lorem ipsum dolor sit amet.')

此方法返回对段落的引用，即文档末尾新添加的段落。在本例中新段落的引用赋值给 paragraph ，除非我有需要，否则我将在下面的示例中省略这一点。在您的代码中，通常在添加项之后您不会对其执行任何操作，因此将引用保留下来没有太大意义。

也可以使用一个段落作为“光标”并在其正上方插入新段落：

prior_paragraph = paragraph.insert_paragraph_before('Lorem ipsum')

这允许在文档的中间插入一个段落，这在修改现有文档而不是从头生成文档时非常重要。

添加标题

除了短文档外，正文文本被分成多个部分，每个部分都以标题开头。以下是如何添加一个标题:

document.add_heading('The REAL meaning of the universe')

默认情况下，这会添加一个顶级标题，在Word中显示为“heading1”。如果需要子节的标题，只需将所需级别指定为1到9之间的整数：

document.add_heading('The role of dolphins', level=2)

如果指定级别为0，则会添加 “标题” 段落。这对于开始一个没有单独标题页的相对较短的文档非常方便。

添加分页符

每隔一段时间，你会希望下一页的文字放在另一页上，即使你所在的那一页还没有满。一个 “硬” 分页符就可以完成：

document.add_page_break()

如果您发现自己经常使用它，这可能表明您可以通过更好地理解段落样式而受益。 您可以设置的一个段落样式属性是在具有该样式的每个段落之前立即分页。 因此，您可以将标题设置为某个级别以始终开始新页面。 稍后会详细介绍样式。 事实证明，它们对于真正充分利用 Word 至关重要。

添加表

人们经常会遇到以表格形式呈现更为适合的内容，排成整齐的行和列。Word 在这方面做得很好。添加表的方法如下：

table = document.add_table(rows=2, cols=2)

表格有几个属性和方法，您需要这些属性和方法来填充它们。访问单个单元格可能是一个不错的起点。作为基础，您始终可以通过其行和列的索引访问单元格：

cell = table.cell(0, 1)

这为您提供了我们刚刚创建的表格顶行中的右侧单元格。请注意，行和列索引是从零开始的，就像在列表访问中一样。

一旦你有了一个单元格，你可以在里面放一些东西：

cell.text = 'parrot, possibly dead'

通常，一次访问一行单元格会更容易，例如从数据源填充可变长度的表时。表的.rows属性提供对各个行的访问，每行都有一个.cells属性。基于Row 和 Column 两个类的.cells属性都支持索引访问，如列表：

row = table.rows[1]
row.cells[0].text = 'Foo bar to you.'
row.cells[1].text = 'And a hearty foo bar to you too sir!'

表上的.rows和.columns集合是可迭代的，因此您可以直接在for循环中使用它们。与.cells行或列上的序列相同：

for row in table.rows:
    for cell in row.cells:
        print(cell.text)

如果要计算表中的行数或列数，只需在序列上使用len()：

row_count = len(table.rows)
col_count = len(table.columns)

您还可以像这样以增量方式将行添加到表中：

row = table.add_row()

这对于我们上面提到的可变长度表的场景来说非常方便：

# get table data -------------
items = (
    (7, '1024', 'Plush kittens'),
    (3, '2042', 'Furbees'),
    (1, '1288', 'French Poodle Collars, Deluxe'),
)

# add table ------------------
table = document.add_table(1, 3)

# populate header row --------
heading_cells = table.rows[0].cells
heading_cells[0].text = 'Qty'
heading_cells[1].text = 'SKU'
heading_cells[2].text = 'Description'

# add a data row for each item
for item in items:
    cells = table.add_row().cells
    cells[0].text = str(item.qty)
    cells[1].text = item.sku
    cells[2].text = item.desc

这同样适用于列，尽管我还没有看到它的用例。

Word 有一组预先格式化的表格样式，您可以从其表格样式库中选择。您可以将其中一个应用到表中，如下所示：

table.style = 'LightShading-Accent1'

样式名称是通过删除表格样式名称中的所有空格而形成的。您可以通过将鼠标悬停在 Word 的表格样式库中的缩略图上来找到表格样式名称。

添加图片

Word 允许您使用菜单项将图像放置在文档中。通过菜单栏的 Insert > Photo > Picture from file...，以下是 python-docx 如何做到这一点：

document.add_picture('image-filename.png')

此示例使用一个路径，该路径从本地文件系统加载图像文件。您还可以使用类似文件的对象【file-like object】，本质上是任何充当打开文件的对象。如果您从数据库或通过网络检索图像并且不想涉及文件系统，这可能会很方便。

图像尺寸

默认情况下，添加的图像以原始大小显示。这通常比您想要的要大。原生大小计算为 pixels / dpi 。因此，分辨率为 300 dpi 的 300x300 像素图像出现在一英寸的正方形中。问题是大多数图像不包含 dpi 属性，默认为 72 dpi。这将使相同的图像在一侧显示为 4.167 英寸，大约是页面的一半。

要获得所需大小的图像，您可以使用方便的单位指定其宽度或高度，例如英寸或厘米：

from docx.shared import Inches

document.add_picture('image-filename.png', width=Inches(1.0))

您可以自由指定宽度和高度，但通常您不想这样做。如果您只指定一个，python-docx则使用它来计算另一个的正确缩放值。这样可以保留纵横比，并且您的图片看起来不会被拉伸。

提供Inches和Cm类以让您以方便的单位指定测量值。在内部，python-docx使用英制公制单位，914400 作为一英寸。所以如果你忘记了，只是放一些东西，width=2你会得到一个非常小的图像:)。您需要从 docx.shared 子包中导入它们。您可以在算术中使用它们，就像它们是整数一样，实际上它们是。所以像这样的表达就可以了: width = Inches(3) / thing_count

应用段落样式

如果您不知道 Word 段落样式是什么，您绝对应该检查一下。基本上，它允许您一次将一整套格式选项应用于段落。如果您知道它们是什么，它很像 CSS 样式。

您可以在创建段落时应用段落样式：

document.add_paragraph('Lorem ipsum dolor sit amet.', style='ListBullet')

这种特殊的样式使段落显示为项目符号，这是一件非常方便的事情。您也可以在之后应用样式。这两行相当于上面的那一行：

paragraph = document.add_paragraph('Lorem ipsum dolor sit amet.')
paragraph.style = 'List Bullet'

该样式是使用其样式名称指定的，在此示例中为 “List Bullet”。通常，样式名称与 Word 用户界面 (UI) 中的样式名称完全相同。

应用粗体和斜体

为了理解粗体和斜体是如何工作的，你需要对段落中发生的事情有所了解。简短的版本是这样的：

1. 段落包含所有 块级别格式【block-level】，如缩进、行高、制表符等。
2. 以及在运行级别才应用的 字符级格式 【Character-level】，例如粗体和斜体 。段落中的所有内容都必须在一段中，但可以有多个。所以中间有一个粗体字的段落需要三个运行级别格式【Run】，一个正常的，一个包含单词的粗体，另一个正常的用于后面的文本。

当您通过向.add_paragraph()方法并提供文本来添加段落时，它会被放入一次Run中。您可以使用段落上的.add_run()方法添加更多内容：

paragraph = document.add_paragraph('Lorem ipsum ')
paragraph.add_run('dolor sit amet.')

这会产生一个看起来就像从单个字符串创建的段落。除非您查看 XML，否则段落文本在何处被分成几行并不明显。注意第一个字符串末尾的尾随空格。您需要明确说明空格出现在运行开始和结束的位置。它们不会在运行之间自动插入。预计会被那个抓住几次:)。

[Run]对象同时具有一个 .bold和.italic属性，允许您为它们设置值：

paragraph = document.add_paragraph('Lorem ipsum ')
run = paragraph.add_run('dolor')
run.bold = True
paragraph.add_run(' sit amet.')

这会产生如下所示的文本：“Lorem ipsum dolor sit amet。”

请注意，如果您不需要设置其他任何内容，您可以在.add_run()的结果上设置粗体或斜体：

paragraph.add_run('dolor').bold = True

# is equivalent to:

run = paragraph.add_run('dolor')
run.bold = True

# except you don't have a reference to `run` afterward

不必为.add_paragraph()方法提供文本。如果您要通过[Run]构建段落，这可以使您的代码更简单：

paragraph = document.add_paragraph()
paragraph.add_run('Lorem ipsum ')
paragraph.add_run('dolor').bold = True
paragraph.add_run(' sit amet.')

应用字符样式

除了指定一组段落级别设置的段落样式之外，Word 还具有指定一组运行级别设置的字符样式。一般来说，您可以将字符样式指定为特别的字体样式，包括其字体、大小、颜色、粗体、斜体等。

与段落样式一样，字符样式必须已经在您使用Document()调用打开的文档中定义（请参阅 [理解样式]）。

添加新运行时可以指定字符样式：

paragraph = document.add_paragraph('Normal text, ')
paragraph.add_run('text with emphasis.', 'Emphasis')

您还可以在创建运行后将样式应用到运行。此代码产生与上面几行相同的结果：

paragraph = document.add_paragraph('Normal text, ')
run = paragraph.add_run('text with emphasis.')
run.style = 'Emphasis'

与段落样式一样，样式名称与 Word UI 中显示的名称相同。

处理文档

python-docx允许您创建新文档以及对现有文档进行更改。实际上，它只允许您对现有文档进行更改；只是如果您从一个没有任何内容的文档开始，一开始可能会觉得您是从头开始创建一个文档。

这个特性是一个强大的特性。文档的外观很大程度上取决于删除所有内容时留下的部分。样式、页眉和页脚等内容与主要内容分开包含，允许您在起始文档中进行大量自定义，然后出现在您生成的文档中。

让我们逐步完成创建文档的步骤，一次创建一个示例，从您可以对文档执行的两项主要操作开始，将其打开并保存。

• 打开文档
• 真正打开一个文档
• 打开“类文件”文档

打开文档

最简单的开始方法是打开一个新文档而不指定要打开的文件：

from docx import Document

document = Document()
document.save('test.docx')

这会从内置的默认模板创建一个新文档，并将其原封不动地保存到名为“test.docx”的文件中。所谓的“默认模板”其实就是一个没有内容的Word文件，和安装的python-docx包一起存放。它与您在选择 Word 的文件 > 从模板中新建...菜单项后选择Word 文档 模板大致相同。

真正打开一个文档

如果您想对最终文档进行更多控制，或者如果您想更改现有文档，您需要打开一个带有文件名的文档：

document = Document('existing-document-file.docx')
document.save('new-file-name.docx')

注意事项：

• 您可以通过这种方式打开任何 Word 2007 或更高版本的文件（来自 Word 2003 和更早版本的 .doc 文件将不起作用）。虽然您可能还无法操作所有内容，但其中已经存在的任何内容都可以正常加载和保存。功能集仍在构建中，因此您还不能添加或更改诸如页眉或脚注之类的内容，但如果文档有它们，python-docx则足够礼貌，可以不理会它们，并且足够聪明，可以在不真正了解它们是什么的情况下保存它们。
• 如果使用相同的文件名打开和保存文件，python-docx会乖乖地覆盖原文件而不保存原文件。您需要确保这是您想要的。

打开“类文件”文档

python-docx可以从所谓的类文件对象打开文档。它还可以保存到类似文件的对象。当您想通过网络连接或从数据库获取源文档或目标文档并且不想（或不允许）与文件系统交互时，这会很方便。实际上，这意味着您可以传递打开的文件或 StringIO/BytesIO 流对象来打开或保存文档，如下所示：

f = open('foobar.docx', 'rb')
document = Document(f)
f.close()

# or

with open('foobar.docx', 'rb') as f:
    source_stream = StringIO(f.read())
document = Document(source_stream)
source_stream.close()
...
target_stream = StringIO()
document.save(target_stream)

'rb'并非所有操作系统都需要文件打开模式参数。默认情况下有'r'就足够了，但在 Windows 和至少某些版本的 Linux 上需要“b”（选择二进制模式）以允许 Zipfile 打开文件。

好的，所以您已经打开了一个文档，并且很确定您可以稍后将其保存在某个地方。接下来请参阅其他内容……

• 处理文本

处理文本

为了有效地处理文本，重要的是首先了解一些 块级元素（如段落）和内联级对象【inline-level objects】（如运行[Run]）。

• 块级与内联文本对象
• 段落属性
  • 水平对齐（对齐）
  • 缩进
  • 制表位
  • 段落间距
  • 行距
  • 分页属性
• 应用字符格式
  • 字体颜色

块级与内联文本对象

段落【paragraph】是 Word 中的主要块级对象【block-level object】。

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

表 也​​是块级对象。

内联对象 是出现在块级项目内的一部分内容。例如，以粗体显示的单词或全部大写的句子。最常见的内联对象是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  # 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

制表位

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

段落或样式的制表位包含在使用 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(Inches(1.5))
>>> tab_stop.position
1371600
>>> 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：

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

更多详细信息可在API文档TabStops中找到TabStop

段落间距

space_before 和 space_after 属性控制后续段落之间的间距，分别控制段落前后的间距。页面布局时，段落间距是折叠的，这意味着两个段落之间的间距是第一段的 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 是长度值、（小）浮点数或 None。 长度值表示绝对距离。 浮点数表示行高数。 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 分页以避免将段落的第一行或最后一行与段落的其余部分放在单独的页面上。

所有这四个属性都是三态的，这意味着它们可以取值 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

应用字符格式

字符格式应用于运行级别。 示例包括字体字体和大小、粗体、斜体和下划线。

Run 对象具有只读字体属性，提供对 Font 对象的访问。 运行的 Font 对象提供了用于获取和设置运行的字符格式的属性。

这里提供了几个例子。 有关可用属性的完整集，请参阅 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 = 'Calibri'
>>> font.size = Pt(12)

许多字体属性是三态的，这意味着它们可以采用值 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 对象，该对象提供对其颜色的访问，通过其只读颜色属性访问。

将特定的 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 分配给 ColorFormat 的 rgb 或 theme_color 属性，可以将字体的颜色恢复为其默认（继承）值：

>>> 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 属性将是表示 RGB 颜色的 RGBColor 值：

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

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

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

处理

Word 支持Section的概念，即具有相同页面布局设置（如页边距和页面方向）的文档的一个分区。 例如，这就是文档可以包含纵向布局的页面和横向布局的其他页面的方式。

大多数 Word 文档默认只有一个Section，而且大多数文档没有理由更改默认边距或其他页面布局。 但是当您确实需要更改页面布局时，您需要了解Section才能完成它。

访问Section

Document 对象上的 sections 属性提供对文档部分的访问：

>>> document = Document()
>>> sections = document.sections
>>> sections
<docx.parts.document.Sections object at 0x1deadbeef>
>>> len(sections)
3
>>> section = sections[0]
>>> section
<docx.section.Section object at 0x1deadbeef>
>>> for section in sections:
...     print(section.start_type)
...
NEW_PAGE (2)
EVEN_PAGE (3)
ODD_PAGE (4)

从理论上讲，文档可能没有任何明确的section，尽管我还没有看到这种情况发生。 如果您正在访问不可预测的 .docx 文件，您可能需要使用 len() 检查或 try 块来提供这种可能性，以避免未捕获的 IndexError 异常停止您的程序。

添加Section

该 Document.add_section()方法允许在文档末尾开始一个新Section。调用此方法后添加的段落和表格将出现在新的Section中：

>>> current_section = document.sections[-1]  # last section in document
>>> current_section.start_type
NEW_PAGE (2)
>>> new_section = document.add_section(WD_SECTION.ODD_PAGE)
>>> new_section.start_type
ODD_PAGE (4)

• Section属性
  • Section 开始类型
  • 页面尺寸和方向
  • 页边距

Section属性

该Section对象有十一个属性，允许查找和指定页面布局设置。

Section 开始类型

Section.start_type描述该Section之前的中断类型：

>>> section.start_type
NEW_PAGE (2)
>>> section.start_type = WD_SECTION.ODD_PAGE
>>> section.start_type
ODD_PAGE (4)

start_type 的值是 WD_SECTION_START 枚举的成员。

页面尺寸和方向

Section 上的三个属性描述页面尺寸和方向。 这些可以一起使用，例如，将部分的方向从纵向更改为横向：

>>> section.orientation, section.page_width, section.page_height
(PORTRAIT (0), 7772400, 10058400)  # (Inches(8.5), Inches(11))
>>> new_width, new_height = section.page_height, section.page_width
>>> section.orientation = WD_ORIENT.LANDSCAPE
>>> section.page_width = new_width
>>> section.page_height = new_height
>>> section.orientation, section.page_width, section.page_height
(LANDSCAPE (1), 10058400, 7772400)

页边距

Section 上的七个属性共同指定了确定文本在页面上显示位置的各种边缘间距：

>>> from docx.shared import Inches
>>> section.left_margin, section.right_margin
(1143000, 1143000)  # (Inches(1.25), Inches(1.25))
>>> section.top_margin, section.bottom_margin
(914400, 914400)  # (Inches(1), Inches(1))
>>> section.gutter
0
>>> section.header_distance, section.footer_distance
(457200, 457200)  # (Inches(0.5), Inches(0.5))
>>> section.left_margin = Inches(1.5)
>>> section.right_margin = Inches(1)
>>> section.left_margin, section.right_margin
(1371600, 914400)

处理页眉和页脚

Word 支持页眉和页脚。 页眉是出现在每页上边距区域的文本，与文本主体分开，通常传达上下文信息，例如文档标题、作者、创建日期或页码。 文档中的页眉在不同的页面之间是相同的，只有很小的内容差异，例如节标题或页码的变化。 页眉也称为动态头。

页脚在各方面都类似于页眉，只是它出现在页面底部。 它不应与脚注相混淆，脚注在页面之间是不统一的。 为简洁起见，这里经常使用术语 header 来指代可能是页眉或页脚对象的对象，相信读者能够理解它对这两种对象类型的适用性。

• 访问Section的header
• 添加header
• 添加“zoned” header内容
• 删除header
• 了解多Section文档中header
• 添加header定义

访问Section的header

页眉和页脚链接到一个Section； 这允许每个部分具有不同的页眉和/或页脚。 例如，横向部分的标题可能比纵向部分更宽。

每个section对象都有一个 .header 属性，提供对该部分的 _Header 对象的访问：

>>> document = Document()
>>> section = document.sections[0]
>>> header = section.header
>>> header
<docx.section._Header object at 0x...>

_Header 对象始终存在于 Section.header 上，即使没有为该部分定义标题。 _Header.is_linked_to_previous 表示存在实际的标头定义：

>>> header.is_linked_to_previous
True

True 值表示 _Header 对象不包含标题定义，并且该部分将显示与前一部分相同的标题。 这种“继承”行为是递归的，因此“链接”标头实际上是从具有标头定义的第一个先前部分获取其定义。 此“链接”状态在 Word UI 中指示为“与以前相同”。

新文档没有标题（在它包含的单个部分上），因此 .is_linked_to_previous 在这种情况下为 True。 请注意，这种情况可能有点违反直觉，因为没有前一个节标题可以链接到。 在这种“没有前一个标题”的情况下，不显示任何标题。

添加header

只需编辑 _Header 对象的内容，就可以将标题添加到新文档中。 _Header 对象是一个“故事”容器，其内容可以像 Document 对象一样进行编辑。 请注意，与新文档一样，新标题已经包含一个（空）段落：

>>> paragraph = header.paragraphs[0]
>>> paragraph.text = "Title of my document"

另请注意，添加内容（甚至只是访问 header.paragraphs）以及添加标题定义的行为会更改 .is_linked_to_previous 的状态：

>>> header.is_linked_to_previous
False

添加“zoned” header内容

具有多个“zoned”的标题通常使用精心放置的制表位来完成。

居中和右对齐“zone”所需的制表位是 Word 中页眉和页脚样式的一部分。 如果您使用的是自定义模板而不是 python-docx 默认模板，那么在模板中定义该样式可能是有意义的。

插入的制表符 ("\t") 用于分隔左对齐、居中和右对齐的标题内容：

>>> paragraph = header.paragraphs[0]
>>> paragraph.text = "Left Text\tCenter Text\tRight Text"
>>> paragraph.style = document.styles["Header"]

Header 样式会自动应用到新的标题中，因此上面的第三行（应用 Header 样式）在这种情况下是不必要的，但在这里包含以说明一般情况。

删除header

可以通过将 True 分配给其 .is_linked_to_previous 属性来删除不需要的标头：

>>> header.is_linked_to_previous = True
>>> header.is_linked_to_previous
True

当 True 分配给 .is_linked_to_previous 时，标题的内容将被不可逆转地删除。

了解多Section文档中header

“刚开始编辑”的方法适用于简单的案例，但要理解多节文档中的header行为，一些简单的概念会有所帮助。 简而言之：

1. 每个[Section]都可以有自己的header定义（但不是必须的）。
2. 缺少header定义的节会继承之前节的header。 _Header.is_linked_to_previous 属性仅反映标头定义的存在，当定义存在时为 False，不存在时为 True。
3. 缺少header定义是默认状态。 新文档没有定义的header，新插入的section也没有。 .is_linked_to_previous 在这两种情况下都报告 True。
4. 如果 [_Header] 对象具有header定义，则它的内容就是它自己的内容。 如果不是，则其内容是具有header定义的第一个先前部分的内容。 如果没有节具有header定义，则在第一个section上添加一个新节，并且所有其他节都继承该section。 header定义的添加发生在第一次访问header内容时，可能是通过引用 header.paragraphs。

添加header定义(通常情况)

通过将 False 分配给其 .is_linked_to_previous 属性，可以为缺少的部分提供显式header定义：

>>> header.is_linked_to_previous
True
>>> header.is_linked_to_previous = False
>>> header.is_linked_to_previous
False

新添加的header定义包含一个空段落。 请注意，以这种方式保留header有时很有用，因为它有效地“关闭”了该Section的hdaer以及之后的header，直到具有已定义header的下一个部分。

在已经具有header定义的header上将 False 分配给 .is_linked_to_previous 不会执行任何操作。

继承的内容自动定位

编辑hdaer的内容会编辑源hdaer的内容，同时考虑任何“继承”。 例如，如果第 2 个section的hdaer继承自第 1 个section并且您编辑第 2 个section的header，你实际上更改了第 1 个section的header的内容。 除非您首先明确地将 False 分配给其 .is_linked_to_previous 属性，否则不会为第 2 个section添加新的header定义。

API基础知识

python-docx 的 API 旨在使简单的事情变得简单，同时通过适度和增量的理解投入来实现更复杂的结果。

可以仅使用单个对象创建基本文档，即打开文件时返回的 docx.api.Document 对象。 docx.api.Document 上的方法允许将块级对象添加到文档的末尾。 块级对象包括段落、内嵌图片和表格。 标题、项目符号和编号列表只是应用了特定样式的段落。

通过这种方式，可以从上到下“编写”文档，大致就像一个人确切知道自己想说什么这个基本用例，内容总是添加到文档的末尾，预计可能占实际用例的 80%，因此在不影响整个 API 的功能的情况下使其尽可能简单是优先事项。

内联对象

docx.api.Document 上的每个块级方法，例如 add_paragraph()，返回创建的块级对象。 通常不需要参考； 但是当必须单独创建内联对象时，您将需要块级对象的引用来执行此操作。

了解样式

Grasshopper:

“Master, 为什么我的段落没有以我指定的样式出现？”

Master:

“你来到了正确的页面, Grasshopper； 继续阅读……”

• Word中的样式是什么？
• 为什么我应用的样式不显示？
• 词汇表
• 识别风格
• 内置样式
• 风格行为
• 潜在样式
• 样式继承
• 默认模板中的段落样式
• 默认模板中的字符样式
• 默认模板中的表格样式

Word中的样式是什么？

当类似元素的格式一致时，文档可以更好地交流。 为了实现这种一致性，专业的文档设计人员开发了一个样式表，它定义了文档元素类型并指定了每个元素的格式。 例如，也许正文段落将设置为 9 pt Times Roman，行高为 11 pt，左对齐或右对齐。 当这些规范应用于文档的每个元素时，就会获得一致且优美的外观。

Word 中的样式是一组可以一次性应用于文档元素的规范。Word 具有段落样式、字符样式、表格样式和编号定义。它们分别应用于段落、文本范围、表格和列表。

有经验的程序员会将样式识别为间接连接的方式。这些的好处是它允许您定义一次，然后多次应用该定义。这节省了重复定义相同事物的工作；但更重要的是，它允许您更改定义并将该更改反映在您应用它的所有地方。

为什么我应用的样式不显示？

这可能会有很多原因，直到我可以添加一些更高级的功能来解决它，所以最重要是：

1. 当您在 Word 中工作时，您可以将所有内置样式应用于文档，非常漂亮的样式看起来更好，但您不必自己制作它们。因为大多数人永远不会比内置样式更进一步。
2. 尽管这些样式显示在 UI 中，但它们实际上并不存在于您正在创建的文档中，至少在您第一次使用它之前不会。 这是一件好事。 它们占据了空间，而且数量很多。 如果该文件包含您可以使用但没有的所有样式定义，它会变得有点臃肿。
3. 如果您使用文件中未定义的 python-docx 应用样式（如果您好奇，则在 styles.xml 部分中），Word 会忽略它。 它不会抱怨，只是不会改变事物的格式。 我相信这是有充分理由的。 但是，如果您不了解 Word 是如何工作的，它可能会让人感到困惑。
4. 使用样式时，Word 会将其添加到文件中。 一旦到了那里，它就会留下来。 我想有办法摆脱它，但你必须努力。 如果应用样式，请删除应用它的内容，然后保存文档； 样式定义保留在保存的文件中。

所有这些加起来如下：如果您想在使用 python-docx 创建的文档中使用样式，则您开始使用的文档必须包含样式定义。 否则它只是行不通。 它不会引发异常，它只是不起作用。

如果您使用“默认”模板文档，它包含下面列出的样式，如果您不自己设计，您可能会想要这些样式。 如果您使用自己的起始文档，则需要在其中至少使用一次所需的每种样式。 您不必保留内容，但您需要在保存文档之前将样式至少应用一次。 创建一个单词段落，连续对其应用五种样式，然后删除该段落就可以了。 这就是我将以下内容放入默认模板的方式:)。

词汇表

• 样式定义 (style definition)

  文档样式部分中的 <w:style> 元素显式定义样式的属性。

• 定义样式 (defined style)

  在文档中明确定义的样式。 与潜在风格形成对比。

• 内置样式 (built-in style)

  Word 中内置的 276 种预设样式中的一种，例如“Heading 1”。 内置样式可以是已定义的或潜在的。 尚未定义的内置样式称为潜在样式。 已定义的和潜在的内置样式都可以作为选项出现在 Word 的样式面板和样式库中。

• 自定义样式 (custom style)

  也称为用户定义样式，在 Word 文档中定义的任何非内置样式的样式。 请注意，自定义样式不能是潜在样式。

• 潜在样式 (latent style)

  在特定文档中没有定义的内置样式在该文档中称为潜在样式。 根据文档的 LatentStyles 对象中的设置，潜在样式可以作为选项出现在 Word UI 中。

• 推荐样式列表 (recommended style list)

  当从“列表：”下拉框中选择“推荐”时出现在样式工具箱或面板中的样式列表。

• 样式风格 (Style Gallery)

  选择出现在 Word UI 的功能区中的示例样式，可以通过单击其中一个来应用这些样式。

识别样式

样式具有三个标识属性，name、style_id 和type。

每种样式的 name 属性是其用于访问目的的稳定、唯一标识符。

样式的 style_id 在内部用于将内容对象（例如段落）设置为其样式的键。 然而，这个值是由 Word 自动生成的，不能保证在保存过程中保持稳定。 通常，style_id 只需从本地化样式名称中删除空格即可形成，但也有例外。 python-docx 的用户通常应该避免使用 style_id，除非他们对所涉及的内部结构有信心。

样式的type是在创建时设置的，不能更改。

内置样式

Word 带有近 300 种所谓的内置样式，例如 Normal、Heading 1 和 List Bullet。 样式定义存储在 .docx 包的 styles.xml 部分中，但内置样式定义存储在 Word 应用程序本身中，并且在实际使用之前不会写入 styles.xml。 这是一个明智的策略，因为它们占用了相当大的空间，否则在每个 .docx 文件中将是大量冗余和无用的开销。

内置样式在使用之前不会写入 .docx 包，这一事实引起了对潜在样式定义的需求，如下所述。

风格行为

除了收集一组格式属性之外，样式还有五个指定其行为的属性。这种行为比较简单，基本上相当于样式出现在 Word 或 LibreOffice UI 中的时间和位置。

理解风格行为的关键概念是推荐列表。在 Word 的样式窗格中，用户可以选择他们想要查看的样式列表。其中之一被命名为推荐并且被称为推荐列表。所有五个行为属性都会影响此列表和样式库中样式外观的某些方面。

简而言之:

如果一个样式的 hidden 属性为 False（默认值），它就会出现在推荐列表中。

如果样式未隐藏且其 quick_style 属性为 True，则它也会出现在样式库中。

如果隐藏样式的 unhide_when_used 属性为 True，则其隐藏属性在第一次使用时设置为 False。

样式列表和样式库中的样式按优先级排序，然后按字母顺序排列相同优先级的样式。

如果样式的locked属性为 True 并且为文档打开了格式限制，则该样式将不会出现在任何列表或样式库中，并且不能应用于内容。

潜在样式

需要指定未在 styles.xml 中定义的内置样式的 UI 行为，从而需要潜在的样式定义。 潜在样式定义基本上是一个存根样式定义，除了样式名称外，它最多具有五个行为属性。 通过为每个行为属性定义默认值来节省额外的空间，因此只需要定义与默认值不同的那些，并且匹配所有默认值的样式不需要潜在样式定义。

使用 style.xml 中出现的 w:latentStyles 和 w:lsdException 元素指定潜在样式定义。

只有内置样式才需要潜在样式定义，因为只有内置样式才能出现在 UI 中，而 style.xml 中没有样式定义。

样式继承

一个样式可以从另一个样式继承属性，有点类似于层叠样式表 (CSS) 的工作方式。 使用 base_style 属性指定继承。 通过将一种风格建立在另一种风格上，可以形成任意深度的继承层次结构。 没有基本样式的样式会从文档默认值继承属性。

• 默认模板中的段落样式
  • 文本
  • 标题
  • 列表
  • 引用
  • 其他

默认模板中的段落样式

文本

• Normal

  常规

• Body Text

  正文

• Body Text 2

  正文 2

• Body Text 3

  正文 3

标题

• Caption

  标题

• Title

  标题

• TOCHeading

  目录标题

• Subtitle

  子标题

• Heading 1

  标题 1

• Heading 2

  标题 2

• Heading 3

  标题 3

• Heading 4

  标题 4

• Heading 5

  标题 5

• Heading 6

  标题 6

• Heading 7

  标题 7

• Heading 8

  标题 8

• Heading 9

  标题 9

列表

• List

  列表

• List 2

  列表 2

• List 3

  列表 3

• List Bullet

  列表项目符号

• List Bullet 2

  列表项目符号 2

• List Bullet 3

  列表项目符号 3

• List Continue

  列表继续

• List Continue 2

  列表继续 2

• List Continue 3

  列表继续 3

• List Number

  列表编号

• List Number 2

  列表编号 2

• List Number 3

  列表编号 3

• List Paragraph

  列表段落

引用

• Quote

  引用

• Intense Quote

  强调引用

其他

• Macro Text

  宏文本

• No Spacing

  无间距

• 默认模板中的字符样式
  • 文本
  • 标题
  • 其他

默认模板中的字符样式

文本

• Body Text Char

  正文字符

• Body Text 2 Char

  正文字符 2

• Body Text 3 Char

  正文字符 3

• Book Title

  书名

• Default Paragraph Font

  默认段落字体

• Emphasis

  重点

标题

• Heading 1 Char

  标题字符 1

• Heading 2 Char

  标题字符 2

• Heading 3 Char

  标题字符 3

• Heading 4 Char

  标题字符 4

• Heading 5 Char

  标题字符 5

• Heading 6 Char

  标题字符 6

• Heading 7 Char

  标题字符 7

• Heading 8 Char

  标题字符 8

• Heading 9 Char

  标题字符 9

• Strong

  粗体

• Title Char

  标题字符

• Subtitle Char

  子标题字符

其他

• Intense Emphasis

  强烈强调

• Intense Quote Char

  强烈强调字符

• Intense Reference

  强烈引用

• Macro Text Char

  宏文本字符

• Quote Char

  引用字符

• Subtle Emphasis

  微弱强调

• Subtle Reference

  微弱引用

• 默认模板中的表格样式
  • 彩色网格
  • 多彩列表
  • 彩色底纹
  • 黑色列表
  • 光栅
  • 光栅列表
  • 光栅底纹
  • 中网格1
  • 中网格2
  • 中网格3
  • 中列表1
  • 中列表2
  • 中底纹1
  • 中底纹2

默认模板中的表格样式

• Table Normal

  常规表格

• Table Grid

  网格表格

彩色网格

• Colorful Grid

  彩色网格

• Colorful Grid Accent 1

  彩色网格强调 1

• Colorful Grid Accent 2

  彩色网格强调 2

• Colorful Grid Accent 3

  彩色网格强调 3

• Colorful Grid Accent 4

  彩色网格强调 4

• Colorful Grid Accent 5

  彩色网格强调 5

• Colorful Grid Accent 6

  彩色网格强调 6

多彩列表

• Colorful List

  多彩列表

• Colorful List Accent 1

  多彩列表强调 1

• Colorful List Accent 2

  多彩列表强调 2

• Colorful List Accent 3

  多彩列表强调 3

• Colorful List Accent 4

  多彩列表强调 4

• Colorful List Accent 5

  多彩列表强调 5

• Colorful List Accent 6

  多彩列表强调 6

彩色底纹

• Colorful Shading

  彩色底纹

• Colorful Shading Accent 1

  彩色底纹 1

• Colorful Shading Accent 2

  彩色底纹 2

• Colorful Shading Accent 3

  彩色底纹 3

• Colorful Shading Accent 4

  彩色底纹 4

• Colorful Shading Accent 5

  彩色底纹 5

• Colorful Shading Accent 6

  彩色底纹 6

黑色列表

• Dark List

  黑色列表

• Dark List Accent 1

  黑色列表 1

• Dark List Accent 2

  黑色列表 2

• Dark List Accent 3

  黑色列表 3

• Dark List Accent 4

  黑色列表 4

• Dark List Accent 5

  黑色列表 5

• Dark List Accent 6

  黑色列表 6

光栅

• Light Grid

  光栅

• Light Grid Accent 1

  光栅 1

• Light Grid Accent 2

  光栅 2

• Light Grid Accent 3

  光栅 3

• Light Grid Accent 4

  光栅 4

• Light Grid Accent 5

  光栅 5

• Light Grid Accent 6

  光栅 6

光栅列表

• Light List

  光栅列表

• Light List Accent 1

  光栅列表 1

• Light List Accent 2

  光栅列表 2

• Light List Accent 3

  光栅列表 3

• Light List Accent 4

  光栅列表 4

• Light List Accent 5

  光栅列表 5

• Light List Accent 6

  光栅列表 6

光栅底纹

• Light Shading

  光栅底纹

• Light Shading Accent 1

  光栅底纹 1

• Light Shading Accent 2

  光栅底纹 2

• Light Shading Accent 3

  光栅底纹 3

• Light Shading Accent 4

  光栅底纹 4

• Light Shading Accent 5

  光栅底纹 5

• Light Shading Accent 6

  光栅底纹 6

中网格1

• Medium Grid 1

  中网格1

• Medium Grid 1 Accent 1

  中网格1 强调 1

• Medium Grid 1 Accent 2

  中网格1 强调 2

• Medium Grid 1 Accent 3

  中网格1 强调 3

• Medium Grid 1 Accent 4

  中网格1 强调 4

• Medium Grid 1 Accent 5

  中网格1 强调 5

• Medium Grid 1 Accent 6

  中网格1 强调 6

中网格2

• Medium Grid 2

  中网格2

• Medium Grid 2 Accent 1

  中网格2 强调 1

• Medium Grid 2 Accent 2

  中网格2 强调 2

• Medium Grid 2 Accent 3

  中网格2 强调 3

• Medium Grid 2 Accent 4

  中网格2 强调 4

• Medium Grid 2 Accent 5

  中网格2 强调 5

• Medium Grid 2 Accent 6

  中网格2 强调 6

中网格3

• Medium Grid 3

  中网格3

• Medium Grid 3 Accent 1

  中网格3 强调 1

• Medium Grid 3 Accent 2

  中网格3 强调 2

• Medium Grid 3 Accent 3

  中网格3 强调 3

• Medium Grid 3 Accent 4

  中网格3 强调 4

• Medium Grid 3 Accent 5

  中网格3 强调 5

• Medium Grid 3 Accent 6

  中网格3 强调 6

中列表1

• Medium List 1

  中列表1

• Medium List 1 Accent 1

  中列表 1 强调 1

• Medium List 1 Accent 2

  中列表 1 强调 2

• Medium List 1 Accent 3

  中列表 1 强调 3

• Medium List 1 Accent 4

  中列表 1 强调 4

• Medium List 1 Accent 5

  中列表 1 强调 5

• Medium List 1 Accent 6

  中列表 1 强调 6

中列表2

• Medium List 2

  中列表2

• Medium List 2 Accent 1

  中列表 2 强调 1

• Medium List 2 Accent 2

  中列表 2 强调 2

• Medium List 2 Accent 3

  中列表 2 强调 3

• Medium List 2 Accent 4

  中列表 2 强调 4

• Medium List 2 Accent 5

  中列表 2 强调 5

• Medium List 2 Accent 6

  中列表 2 强调 6

中底纹1

• Medium Shading 1

  中底纹1

• Medium Shading 1 Accent 1

  中底纹1 强调 1

• Medium Shading 1 Accent 2

  中底纹1 强调 2

• Medium Shading 1 Accent 3

  中底纹1 强调 3

• Medium Shading 1 Accent 4

  中底纹1 强调 4

• Medium Shading 1 Accent 5

  中底纹1 强调 5

• Medium Shading 1 Accent 6

  中底纹1 强调 6

中底纹2

• Medium Shading 2

  中底纹2

• Medium Shading 2 Accent 1

  中底纹2 强调 1

• Medium Shading 2 Accent 2

  中底纹2 强调 2

• Medium Shading 2 Accent 3

  中底纹2 强调 3

• Medium Shading 2 Accent 4

  中底纹2 强调 4

• Medium Shading 2 Accent 5

  中底纹2 强调 5

• Medium Shading 2 Accent 6

  中底纹2 强调 6

使用样式

本页使用上一页中提出的概念，不作介绍。如果某个术语不熟悉，请参阅上一页了解样式以获取定义。

• 访问样式
• 应用样式
• 添加或删除样式
• 定义字符格式
• 定义段落格式
• 使用特定于段落的样式属性
• 控制样式在 Word UI 中的显示方式
• 使用潜在样式

访问样式

使用 Document.styles 属性访问样式：

>>> document = Document()
>>> styles = document.styles
>>> styles
<docx.styles.styles.Styles object at 0x10a7c4f50>

Styles 对象提供对按名称定义的样式的字典式访问：

>>> styles['Normal']
<docx.styles.style._ParagraphStyle object at <0x10a7c4f6b>

注意

内置样式使用其英文名称存储在 WordprocessingML 文件中，例如 “Heading 1”，即使使用本地化版本的 Word 的用户会在 UI 中看到母语名称，例如 'Kop 1'。 因为 python-docx 对 WordprocessingML 文件进行操作，所以样式查找必须使用英文名称。 此外部站点上提供的文档允许您在本地语言名称和英文样式名称之间创建映射：http://www.thedoctools.com/index.php?show=mt_create_style_name_list

用户定义的样式（也称为自定义样式）未本地化，并且使用与 Word UI 中显示的名称完全相同的名称进行访问。

Styles 对象也是可迭代的。 通过使用 BaseStyle 上的标识属性，可以生成已定义样式的各种子集。 例如，此代码将生成已定义段落样式的列表：

>>> from docx.enum.style import WD_STYLE_TYPE
>>> styles = document.styles
>>> paragraph_styles = [
...     s for s in styles if s.type == WD_STYLE_TYPE.PARAGRAPH
... ]
>>> for style in paragraph_styles:
...     print(style.name)
...
Normal
Body Text
List Bullet

应用样式

Paragraph、Run 和 Table 对象各有一个样式属性。 将样式对象分配给此属性会应用该样式：

>>> document = Document()
>>> paragraph = document.add_paragraph()
>>> paragraph.style
<docx.styles.style._ParagraphStyle object at <0x11a7c4c50>
>>> paragraph.style.name
'Normal'
>>> paragraph.style = document.styles['Heading 1']
>>> paragraph.style.name
'Heading 1'

也可以直接指定样式名称，在这种情况下，python-docx 将为您进行查找：

>>> paragraph.style = 'List Bullet'
>>> paragraph.style
<docx.styles.style._ParagraphStyle object at <0x10a7c4f84>
>>> paragraph.style.name
'List Bullet'

样式也可以在创建时使用样式对象或其名称应用：

>>> paragraph = document.add_paragraph(style='Body Text')
>>> paragraph.style.name
'Body Text'
>>> body_text_style = document.styles['Body Text']
>>> paragraph = document.add_paragraph(style=body_text_style)
>>> paragraph.style.name
'Body Text'

添加或删除样式

可以通过指定唯一名称和样式类型将新样式添加到文档中：

>>> from docx.enum.style import WD_STYLE_TYPE
>>> styles = document.styles
>>> style = styles.add_style('Citation', WD_STYLE_TYPE.PARAGRAPH)
>>> style.name
'Citation'
>>> style.type
PARAGRAPH (1)

使用 base_style 属性来指定新样式应该继承格式设置的样式：

>>> style.base_style
None
>>> style.base_style = styles['Normal']
>>> style.base_style
<docx.styles.style._ParagraphStyle object at 0x10a7a9550>
>>> style.base_style.name
'Normal'

只需调用其 delete() 方法即可从文档中删除样式：

>>> styles = document.styles
>>> len(styles)
10
>>> styles['Citation'].delete()
>>> len(styles)
9

注意

[Style.delete()] 方法从文档中删除样式的定义。 它不会影响应用该样式的文档中的内容。 文档中未定义样式的内容使用该内容对象的默认样式呈现，例如 在段落的情况下为“Normal”。

定义字符格式

字符、段落和表格样式都可以指定要应用于具有该样式的内容的字符格式。 所有可以直接应用于文本的字符格式都可以在样式中指定。 示例包括字体字体和大小、粗体、斜体和下划线。

这三种样式类型中的每一种都有一个font属性，提供对 Font 对象的访问。 样式的 Font 对象提供用于获取和设置该样式的字符格式的属性。

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

可以像这样访问样式的字体：

>>> from docx import Document
>>> document = Document()
>>> style = document.styles['Normal']
>>> font = style.font

字体和大小设置如下：

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

许多字体属性是三态的，这意味着它们可以采用值 True、False 和 None。 True 表示该属性“开启”，False 表示该属性“关闭”。 从概念上讲， None 值意味着“继承”。 因为样式存在于继承层次结构中，所以能够在层次结构中的正确位置指定属性非常重要，通常在层次结构中尽可能远。 例如，如果所有标题都应采用 Arial 字体，则将属性设置为 Heading 1 样式并让 Heading 2 从 Heading 1 继承会更有意义。

粗体和斜体是三态属性，全大写、删除线、上标和许多其他属性也是如此。 有关完整列表，请参阅 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

定义段落格式

段落样式和表格样式都允许指定段落格式。 这些样式通过其 paragraph_format 属性提供对 ParagraphFormat 对象的访问。

段落格式包括布局行为，例如对齐、缩进、前后空格、前分页符和孤/孤控制。 有关可用属性的完整列表，请参阅 ParagraphFormat 对象的 API 文档页面。

下面是一个示例，说明如何创建具有 1/4 英寸悬挂缩进、上方 12 点间距和寡/孤控制的段落样式：

>>> from docx.enum.style import WD_STYLE_TYPE
>>> from docx.shared import Inches, Pt
>>> document = Document()
>>> style = document.styles.add_style('Indent', WD_STYLE_TYPE.PARAGRAPH)
>>> paragraph_format = style.paragraph_format
>>> paragraph_format.left_indent = Inches(0.25)
>>> paragraph_format.first_line_indent = Inches(-0.25)
>>> paragraph_format.space_before = Pt(12)
>>> paragraph_format.widow_control = True

使用特定于段落的样式属性

段落样式具有 next_paragraph_style 属性，该属性指定要应用于在该样式的段落之后插入的新段落的样式。 当样式通常在一个序列中只出现一次时，这是最有用的，例如标题。 在这种情况下，段落样式可以在完成标题后自动设置回正文样式。

在最常见的情况下（正文段落），后续段落应采用与当前段落相同的样式。 如果未指定下一个段落样式，则默认通过应用相同的样式很好地处理这种情况。

下面是如何将标题 1 样式的下一段样式更改为正文文本的示例：

>>> from docx import Document
>>> document = Document()
>>> styles = document.styles

>>> styles['Heading 1'].next_paragraph_style = styles['Body Text']

可以通过分配 None 或样式本身来恢复默认行为：

>>> heading_1_style = styles['Heading 1']
>>> heading_1_style.next_paragraph_style.name
'Body Text'

>>> heading_1_style.next_paragraph_style = heading_1_style
>>> heading_1_style.next_paragraph_style.name
'Heading 1'

>>> heading_1_style.next_paragraph_style = None
>>> heading_1_style.next_paragraph_style.name
'Heading 1'

• 控制样式在 Word UI 中的显示方式
  • 在样式库中显示样式
  • 从样式库中删除样式

控制样式在 Word UI 中的显示方式

样式的属性分为两类，行为属性和格式属性。 它的行为属性控制样式出现在 Word UI 中的时间和位置。 其格式属性确定应用该样式的内容的格式，例如字体大小及其段落缩进。

风格有五个行为属性：

• hidden
• unhide_when_used
• priority
• quick_style
• locked

有关这些行为属性如何交互以确定样式在 Word UI 中出现的时间和位置的说明，请参阅了解样式中的样式行为部分。

priority 属性采用整数值。 其他四个样式行为属性是三态的，这意味着它们可以取值 True（打开）、False（关闭）或 None（继承）。

在样式库中显示样式

以下代码将实现 “Body Text” 段落样式首先出现在样式库中：

>>> from docx import Document
>>> document = Document()
>>> style = document.styles['Body Text']

>>> style.hidden = False
>>> style.quick_style = True
>>> style.priorty = 1

从样式库中删除样式

此代码将从样式库中删除 “Normal” 段落样式，但允许它保留在推荐列表中：

>>> style = document.styles['Normal']

>>> style.hidden = False
>>> style.quick_style = False

• 使用潜在样式
  • 访问文档中的潜在样式
  • 更改潜在样式默认值
  • 添加潜在样式定义
  • 删除潜在样式定义

使用潜在样式

有关潜在样式如何定义尚未在 .docx 文件的 styles.xml 部分中定义的内置样式的行为属性的说明，请参阅了解样式中的内置样式和潜在样式部分。

访问文档中的潜在样式

文档中的潜在样式可从样式对象访问：

>>> document = Document()
>>> latent_styles = document.styles.latent_styles

LatentStyles 对象支持按样式名称的 len()、迭代和字典样式访问：

>>> len(latent_styles)
161

>>> latent_style_names = [ls.name for ls in latent_styles]
>>> latent_style_names
['Normal', 'Heading 1', 'Heading 2', ... 'TOC Heading']

>>> latent_quote = latent_styles['Quote']
>>> latent_quote
<docx.styles.latent.LatentStyle object at 0x10a7c4f50>
>>> latent_quote.priority
29

更改潜在样式默认值

LatentStyles 对象还提供对当前文档中内置样式的默认行为属性的访问。 这些默认值为 _LatentStyle 定义的任何未定义属性以及没有显式潜在样式定义的内置样式的所有行为属性提供值。 有关完整的可用属性集，请参阅 LatentStyles 对象的 API 文档：

>>> latent_styles.default_to_locked
False
>>> latent_styles.default_to_locked = True
>>> latent_styles.default_to_locked
True

添加潜在样式定义

可以使用 LatentStyles 上的 add_latent_style() 方法添加新的潜在样式。 此代码为内置样式“List Bullet”添加了一个新的潜在样式，将其设置为出现在样式库中：

>>> latent_style = latent_styles['List Bullet']
KeyError: no latent style with name 'List Bullet'
>>> latent_style = latent_styles.add_latent_style('List Bullet')
>>> latent_style.hidden = False
>>> latent_style.priority = 2
>>> latent_style.quick_style = True

删除潜在样式定义

可以通过调用其 delete() 方法来删除潜在样式定义：

>>> latent_styles['Light Grid']
<docx.styles.latent.LatentStyle object at 0x10a7c4f50>
>>> latent_styles['Light Grid'].delete()
>>> latent_styles['Light Grid']
KeyError: no latent style with name 'Light Grid'

理解图片和其他形状

从概念上讲，Word 文档有两层，一个文本层和一个绘图层。 在文本层中，文本对象从左到右，从上到下流动，当前一页被填满时开始新的一页。 在绘图层中，称为形状的绘图对象放置在任意位置。 这些有时被称为浮动形状。

图片是可以出现在文本或绘图层中的形状。 当它出现在文本层中时，它被称为内嵌形状，或者更具体地说，是内嵌图片。

内联形状被视为大文本字符（字符字形）。 增加了行高以适应形状，并且形状被包裹成一条适合宽度方向的线，就像文本一样。 在它前面插入文本会导致它向右移动。 通常，图片单独放置在段落中，但这不是必需的。 它可以在放置它的段落中前后放置文本。

在撰写本文时，python-docx 仅支持内联图片。 可以添加浮动图片。 如果您有一个活跃的用例，请在问题跟踪器上提交功能请求。 Document.add_picture() 方法将指定图片添加到文档末尾的一段中。 但是，通过更深入地研究 API，您可以将文本放置在段落中图片的任一侧，或两者兼而有之。

API参考文档

• Document对象
• Document Settings 对象
• Style相关对象
• Text相关对象
• Table对象
• Sesiont对象
• Shape相关对象
• DrawingML对象
• 共享类
• 枚举

Document对象

主要 Document 和相关对象。

• Document构造函数
• Document对象
• CoreProperties对象

Document构造函数

docx.Document(docx=None)

• 返回从 docx 加载的 Document 对象，其中 docx 可以是 .docx 文件（字符串）的路径或类似文件的对象。 如果 docx 缺失或无，则加载内置的默认文档“模板”。

Document对象

class docx.document.Document

WordprocessingML (WML) 文档。

不打算直接构建。 使用 docx.Document() 打开或创建文档。

• add_heading(text=u'', level=1)

  返回一个新添加到文档末尾的标题段落。

  标题段落将包含文本，其段落样式由级别决定。 如果 level 为 0，则样式设置为 Title。 如果级别为 1（或省略），则使用标题 1。 否则样式设置为标题 {level}。 如果级别超出范围 0-9，则引发 ValueError。

• add_page_break()

  返回仅包含分页符的新 Paragraph 对象。

• add_paragraph(text=u'', style=None)

  返回一个新添加到文档末尾的段落，其中填充了文本并具有段落样式样式。 text 可以包含制表符 (\t) 字符，这些字符被转换为适当的 XML 格式的制表符。 text 还可以包含换行符 (\n) 或回车符 (\r)，每个字符都转换为换行符。

• add_picture(image_path_or_stream, width=None, height=None)

  返回在文档末尾自己的段落中添加的新图片形状。 图片包含位于 image_path_or_stream 的图像，根据宽度和高度进行缩放。 如果既没有指定宽度也没有指定高度，则图片以其原始大小显示。 如果只指定了一个，则它用于计算缩放因子，然后将其应用于未指定的维度，保留图像的纵横比。 图片的原始尺寸是使用图像文件中指定的每英寸点数 (dpi) 值计算的，通常情况下，如果没有指定值，则默认为 72 dpi。

• add_section(start_type=2)

  返回一个 Section 对象，该对象表示在文档末尾添加的新部分。 可选的 start_type 参数必须是 WD_SECTION_START 枚举的成员，如果未提供，则默认为 WD_SECTION_START.NEW_PAGE。

• add_table(rows, cols, style=None)

  添加一个表格，该表格分别具有行数和列数以及表格样式的样式。 style 可以是段落样式对象或段落样式名称。 如果 style 为 None，则表格继承文档的默认表格样式。

• core_properties

  一个 CoreProperties 对象，提供对该文档核心属性的读/写访问。

• inline_shapes

  一个 InlineShapes 对象，提供对本文档中的内联形状的访问。 内联形状是一个图形对象，例如图片，包含在一系列文本中，表现得像字符字形，像段落中的其他文本一样流动。

• paragraphs

  与文档中的段落相对应的Paragraph实例列表，按文档顺序排列。 请注意，修订标记内的段落（例如 <w:ins> 或 <w:del>）不会出现在此列表中。

• part

  此文档的 [DocumentPart] 对象。

• save(path_or_stream)

  将此文档保存到 path_or_stream，它可以是文件系统位置的路径（字符串）或类似文件的对象。

• sections

  Sections 对象提供对本文档中每个部分的访问。

• settings

  一个 Settings 对象，提供对该文档的文档级设置的访问。

• styles

  一个 Styles 对象，提供对该文档中样式的访问。

• tables

  与文档中的表相对应的Table实例列表，按文档顺序排列。 请注意，只有出现在文档顶层的表格才会出现在此列表中； 不会出现嵌套在表格单元格内的表格。 <w:ins> 或 <w:del> 等修订标记内的表格也不会出现在列表中。

CoreProperties对象

每个 Document 对象通过其 core_properties 属性提供对其 CoreProperties 对象的访问。 CoreProperties 对象提供对文档的所谓核心属性的读/写访问。 核心属性是作者、类别、评论、内容状态、创建、标识符、关键字、语言、最后修改人、最后打印、修改、修订、主题、标题和版本。

每个属性都是 str、datetime.datetime 或 int 三种类型之一。 字符串属性的长度限制为 255 个字符，如果未设置，则返回空字符串 ('')。 日期属性作为没有时区的 datetime.datetime 对象分配和返回，即 UTC。 任何时区转换都是客户的责任。 如果未设置，则日期属性返回 None。

python-docx 不会自动设置任何文档核心属性，只会将核心属性部分添加到没有核心属性的演示文稿中（非常罕见）。 如果 python-docx 添加核心属性部分，它包含标题、最后修改人、修订和修改属性的默认值。 如果需要该行为，客户端代码应更新诸如修订和 最后修改人 之类的属性。

class docx.opc.coreprops.CoreProperties

• author

  string - 主要负责制作资源内容的实体。

• category

  string - 此包内容的分类。 示例值可能包括：简历、信函、财务预测、提案或技术演示。(Resume, Letter, Financial Forecast, Proposal, Technical Presentation.)

• comments

  string - 资源内容的说明。

• content_status

  string - 文档的完成状态，例如 '草案'(‘draft’)

• created

  datetime - 文档的初始创建时间

• identifier

  string - 在给定上下文中对资源的明确引用，例如 ISBN。

• keywords

  string - 可能用作本文档搜索词的描述性词或短语

• language

  string - 编写文档的语言

• last_modified_by

  string - 上次修改文档的人的姓名或其他标识符（例如电子邮件地址）

• last_printed

  datetime - 上次打印文档的时间

• modified

  datetime - 文档最后一次修改的时间

• revision

  int - 此修订的编号，每次保存文档时按 Word 递增。但是，注意python-docx在保存文档时不会自动增加修订号。

• subject

  string - 资源内容的主题。

• title

  string - 给资源的名称。

• version

  string - 自由格式的字符串

文档设置对象

class docx.settings.Settings

提供对文档的文档级设置的访问。

使用 Document.settings 属性访问。

• element

  此对象代理的 lxml 元素。

• odd_and_even_pages_header_footer

  如果此文档具有明显的奇数页和偶数页页眉和页脚，则为True。

  读/写。

样式相关对象

样式用于在单个名称下收集一组格式属性，并将这些属性一次性应用于内容对象。 这促进了整个文档和相关文档的格式一致性，并允许通过以适当的样式更改定义来全局进行格式更改。

• Styles对象
• BaseStyle对象
• _CharacterStyle对象
• _ParagraphStyle对象
• _TableStyle对象
• _NumberingStyle对象
• LatentStyles对象
• _LatentStyle对象

Styles对象

class docx.styles.styles.Styles

提供对文档中定义的样式的访问。

使用 Document.styles 属性访问。 通过样式名称支持 len()、迭代和字典样式访问。

• add_style(name, style_type, builtin=False)

  返回一个新添加的 style_type 样式对象，并由名称标识。 可以通过为可选的内置参数传递 True 来定义内置样式。

• default(style_type)

  如果没有为该类型定义默认值（不常见），则返回 style_type 或 None 的默认样式。

• element

  此对象代理的 lxml 元素。

• latent_styles

  一个 LatentStyles 对象，提供对潜在样式的默认行为和 _LatentStyle 对象集合的访问，这些对象为特定命名的潜在样式定义了这些默认值的覆盖。

BaseStyle对象

class docx.styles.style.BaseStyle

各种样式对象、段落、字符、表格和编号的基类。 这些属性和方法被所有样式对象继承。

• builtin

  只读。 如果此样式是内置样式，则为True。 False 表示它是自定义（用户定义的）样式。 请注意，此值基于 XML 中是否存在 customStyle 属性，而不是基于 Word 中内置了哪些样式的特定知识。

• delete()

  从文档中删除此样式定义。 请注意，调用此方法不会删除或更改应用于任何文档内容的样式。 具有已删除样式的内容项将使用默认样式呈现，与文档中未定义样式的任何内容一样。

• element

  此对象代理的 lxml 元素。

• hidden

  如果在样式库和推荐样式列表中禁止显示此样式，则为True。 否则为False。 为了在样式库中显示，此值必须为 False，并且 quick_style 必须为 True。

• locked

  读/写布尔值。 如果此样式已锁定，则为True。 锁定的样式不会出现在样式面板或样式库中，并且不能应用于文档内容。 仅当为文档打开格式保护时（通过“开发人员”菜单），此行为才有效。

• name

  此样式的 UI 名称。

• priority

  在 Word UI 中控制此样式的显示顺序的整数排序键。 None 表示未定义任何设置，导致 Word 使用默认值 0。样式名称用作辅助排序键来解析具有相同优先级值的样式的排序。

• quick_style

  当hidden为False时, 此属性为True，则表示此样式应显示在样式库中. 读/写布尔值。

• type

  WD_STYLE_TYPE 的成员对应该样式的类型，例如 WD_STYLE_TYPE.PARAGRAPH。

• unhide_when_used

  如果应用程序应该在下次将其应用于内容时使此样式可见，则为True。 否则为False。 请注意，python-docx 在应用于内容时不会自动取消隐藏该属性为 True 的样式。

_CharacterStyle对象

class docx.styles.style._CharacterStyle

继承自: docx.styles.style.BaseStyle

一种字符样式。 字符样式应用于 Run 对象，主要通过其font属性中的 Font 对象提供字符级格式。

• base_style

  此样式继承的样式对象，如果此样式不基于其他样式，则为 None。

• builtin

  只读。 如果此样式是内置样式，则为True。 False 表示它是自定义（用户定义的）样式。 请注意，此值基于 XML 中是否存在 customStyle 属性，而不是基于 Word 中内置了哪些样式的特定知识。

• delete()

  从文档中删除此样式定义。 请注意，调用此方法不会删除或更改应用于任何文档内容的样式。 具有已删除样式的内容项将使用默认样式呈现，与文档中未定义样式的任何内容一样。

• font

  Font 对象提供对该样式的字符格式属性的访问，例如字体名称和大小。

• hidden

  如果在样式库和推荐样式列表中禁止显示此样式，则为True。 否则为False。 为了在样式库中显示，此值必须为 False，并且 [quick_style] 必须为 True。

• locked

  读/写布尔值。 如果此样式已锁定，则为True。 锁定的样式不会出现在样式面板或样式库中，并且不能应用于文档内容。 仅当为文档打开格式保护时（通过“开发人员”菜单），此行为才有效。

• name

  此样式的 UI 名称。

• priority

  在 Word UI 中控制此样式的显示顺序的整数排序键。 None 表示未定义任何设置，导致 Word 使用默认值 0。样式名称用作辅助排序键来解析具有相同优先级值的样式的排序。

• quick_style

  当[hidden]为False时, 此属性为True，则表示此样式应显示在样式库中. 读/写布尔值。

• unhide_when_used

  如果应用程序应该在下次将其应用于内容时使此样式可见，则为True。 否则为False。 请注意，python-docx 在应用于内容时不会自动取消隐藏该属性为 True 的样式。

_ParagraphStyle对象

class docx.styles.style._ParagraphStyle

继承自: docx.styles.style._CharacterStyle

段落样式。 段落样式提供字符格式和段落格式，例如缩进和行间距。

• base_style

  此样式继承的样式对象，如果此样式不基于其他样式，则为 None。

• builtin

  只读。 如果此样式是内置样式，则为True。 False 表示它是自定义（用户定义的）样式。 请注意，此值基于 XML 中是否存在 customStyle 属性，而不是基于 Word 中内置了哪些样式的特定知识。

• delete()

  从文档中删除此样式定义。 请注意，调用此方法不会删除或更改应用于任何文档内容的样式。 具有已删除样式的内容项将使用默认样式呈现，与文档中未定义样式的任何内容一样。

• font

  Font 对象提供对该样式的字符格式属性的访问，例如字体名称和大小。

• hidden

  如果在样式库和推荐样式列表中禁止显示此样式，则为True。 否则为False。 为了在样式库中显示，此值必须为 False，并且 [quick_style] 必须为 True。

• locked

  读/写布尔值。 如果此样式已锁定，则为True。 锁定的样式不会出现在样式面板或样式库中，并且不能应用于文档内容。 仅当为文档打开格式保护时（通过“开发人员”菜单），此行为才有效。

• name

  此样式的 UI 名称。

• next_paragraph_style

  _ParagraphStyle 对象，表示要自动应用于插入此样式的段落之后的新段落的样式。 如果没有定义下一段样式，则返回 self。 分配 None 或 self 会删除设置，以便使用相同的样式创建新段落。

• paragraph_format

  ParagraphFormat 对象提供对该样式的段落格式属性的访问，例如缩进。

• priority

  在 Word UI 中控制此样式的显示顺序的整数排序键。 None 表示未定义任何设置，导致 Word 使用默认值 0。样式名称用作辅助排序键来解析具有相同优先级值的样式的排序。

• quick_style

  当[hidden]为False时, 此属性为True，则表示此样式应显示在样式库中. 读/写布尔值。

• unhide_when_used

  如果应用程序应该在下次将其应用于内容时使此样式可见，则为True。 否则为False。 请注意，python-docx 在应用于内容时不会自动取消隐藏该属性为 True 的样式。

_TableStyle对象

class docx.styles.style._TableStyle

继承自: docx.styles.style._ParagraphStyle

一种表格样式。表格样式为其内容提供字符和段落格式以及特殊的表格格式属性。

• base_style base_style

  此样式继承的样式对象，如果此样式不基于其他样式，则为 None。

• builtin builtin

  只读。 如果此样式是内置样式，则为True。 False 表示它是自定义（用户定义的）样式。 请注意，此值基于 XML 中是否存在 customStyle 属性，而不是基于 Word 中内置了哪些样式的特定知识。

• delete() delete

  从文档中删除此样式定义。 请注意，调用此方法不会删除或更改应用于任何文档内容的样式。 具有已删除样式的内容项将使用默认样式呈现，与文档中未定义样式的任何内容一样。

• font font

  Font 对象提供对该样式的字符格式属性的访问，例如字体名称和大小。

• hidden hidden

  如果在样式库和推荐样式列表中禁止显示此样式，则为True。 否则为False。 为了在样式库中显示，此值必须为 False，并且 [quick_style] 必须为 True。

• locked locked

  读/写布尔值。 如果此样式已锁定，则为True。 锁定的样式不会出现在样式面板或样式库中，并且不能应用于文档内容。 仅当为文档打开格式保护时（通过“开发人员”菜单），此行为才有效。

• name name

  此样式的 UI 名称。

• next_paragraph_style next_paragraph_style

  _ParagraphStyle 对象，表示要自动应用于插入此样式的段落之后的新段落的样式。 如果没有定义下一段样式，则返回 self。 分配 None 或 self 会删除设置，以便使用相同的样式创建新段落。

• paragraph_format paragraph_format

  ParagraphFormat 对象提供对该样式的段落格式属性的访问，例如缩进。

• priority priority

  在 Word UI 中控制此样式的显示顺序的整数排序键。 None 表示未定义任何设置，导致 Word 使用默认值 0。样式名称用作辅助排序键来解析具有相同优先级值的样式的排序。

• quick_style quick_style

  当[hidden]为False时, 此属性为True，则表示此样式应显示在样式库中. 读/写布尔值。

• unhide_when_used unhide_when_used

  如果应用程序应该在下次将其应用于内容时使此样式可见，则为True。 否则为False。 请注意，python-docx 在应用于内容时不会自动取消隐藏该属性为 True 的样式。

_NumberingStyle对象

class docx.styles.style._NumberingStyle

编号样式。 尚未实现。

LatentStyles对象

class docx.styles.latent.LatentStyles

提供对本文档中潜在样式的默认行为和 _LatentStyle 对象集合的访问，这些对象定义了对特定命名潜在样式的这些默认值的覆盖。

• add_latent_style(name)

  返回一个新添加的 _LatentStyle 对象，以覆盖在此潜在样式对象中为具有名称的内置样式定义的继承默认值。

• default_priority

  0 到 99 之间的整数，指定样式列表和样式库中潜在样式的默认排序顺序。 如果未指定任何值，则为None，这会导致 Word 使用默认值 99。

• default_to_hidden

  布尔值，指定是否隐藏潜在样式的默认行为。 隐藏的样式不会出现在推荐列表或样式库中。

• default_to_locked

  布尔值，指定是否要锁定潜在样式的默认行为。 锁定的样式不会出现在样式面板或样式库中，并且不能应用于文档内容。 仅当为文档打开格式保护时（通过“开发人员”菜单），此行为才有效。

• default_to_quick_style

  布尔值，指定潜在样式的默认行为是否在不隐藏时显示在样式库中。

• default_to_unhide_when_used

  布尔值，指定潜在样式的默认行为是否在首次应用于内容时不隐藏。

• element

  此对象代理的 lxml 元素。

• load_count

  整数，指定要初始化为此 LatentStyles 对象中指定的默认值的内置样式的数量。 如果 XML 中没有设置，则为None（非常罕见）。 默认 Word 2011 模板将此值设置为 276，说明 Word 2010 中的内置样式。

_LatentStyle对象

class docx.styles.latent._LatentStyle

w:lsdException 元素的代理，当该样式的定义尚未存储在 styles.xml 部分中时，该元素指定该样式的显示行为。 此元素中的值会覆盖父 w:latentStyles 元素中指定的默认值。

• delete()

  删除此潜在样式定义，以便包含 LatentStyles 对象中定义的默认值为其每个属性提供有效值。 在调用此方法后尝试访问此对象上的任何属性将引发 AttributeError。

• element

  此对象代理的 lxml 元素。

• hidden

  指定此潜在样式是否应出现在推荐列表中的三态值。 None 表示有效值是从父 <w:latentStyles> 元素继承的。

• locked

  指定此潜在样式是否被锁定的三态值。 锁定的样式不会出现在样式面板或样式库中，并且不能应用于文档内容。 仅当为文档打开格式保护时（通过“开发人员”菜单），此行为才有效。

• name

  此异常适用的内置样式的名称。

• priority

  Word UI 中此潜在样式的整数排序键。

• quick_style

  三态值，指定此潜在样式在不隐藏时是否应出现在 Word 样式库中。 None 表示应该从其父 LatentStyles 对象中的默认值继承有效值。

• unhide_when_used

  三态值指定此样式是否应在下次将样式应用于内容时将其隐藏属性设置为 False。 None 表示应该从其父 LatentStyles 对象指定的默认值继承有效值。

文本相关对象

• Paragraph对象
• ParagraphFormat对象
• Run对象
• Font对象
• TabStop对象
• TabStops对象

Paragraph对象

class docx.text.paragraph.Paragraph

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

• add_run(text=None, style=None)

  向包含文本且字符样式由样式 ID 样式标识的此段落附加一个段落。 text 可以包含制表符 (\t) 字符，这些字符被转换为适当的 XML 格式的制表符。 text 还可以包含换行符 (\n) 或回车符 (\r)，每个字符都转换为换行符。

• alignment

  WD_PARAGRAPH_ALIGNMENT 枚举的成员，指定此段落的对齐设置。 None 值表示段落没有直接应用的对齐值，并将从其样式层次结构继承其对齐值。 将 None 分配给此属性会删除任何直接应用的对齐值。

• clear()

  删除所有内容后返回相同的段落。 保留段落级别的格式，例如样式。

• insert_paragraph_before(text=None, style=None)

  返回一个新创建的段落，直接插入到该段落之前。 如果提供了text，则新段落会在一次运行中包含该text。 如果提供了style，则将该style分配给新段落。

• paragraph_format

  ParagraphFormat 对象提供对该段落格式属性的访问，例如行距和缩进。

• runs

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

• style

  读/写。 _ParagraphStyle 对象，表示分配给此段落的样式。 如果没有为该段落分配明确的样式，则其值为文档的默认段落样式。 可以指定段落样式名称来代替段落样式对象。 指定 None 会删除任何应用的样式，使其有效值成为文档的默认段落样式。

• text

  通过连接段落中每个运行的文本形成的字符串。 XML 中的制表符和换行符分别映射到 \t 和 \n 字符。

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

ParagraphFormat对象

class docx.text.parfmt.ParagraphFormat

提供对段落格式的访问，例如对正、缩进、行间距、前后空间以及寡/孤【widow/orphan】控制。

• alignment

  WD_PARAGRAPH_ALIGNMENT 枚举的成员，指定此段落的对齐设置。 None 值表示段落对齐是从样式层次结构继承的。

• first_line_indent

  指定段落第一行缩进的相对差异的Length值。 正值会使第一行缩进。 负值产生悬挂缩进。 None 表示第一行缩进是从样式层次结构继承的。

• keep_together

  如果段落应该保持“一体”并且在呈现文档时不跨越页面边界，则为True。 None 表示其有效值是从样式层次结构继承的。

• keep_with_next

  如果在呈现文档时该段落应与后续段落保持在同一页面上，则为True。 例如，此属性可用于将章节标题与其第一段保持在同一页面上。 None 表示其有效值是从样式层次结构继承的。

• left_indent

  Length值指定左边距和段落左侧之间的空间。 None 表示左缩进值是从样式层次结构继承的。 使用Inches值对象作为以英寸为单位应用缩进的便捷方式。

• line_spacing

  浮点数或Length值，指定段落连续行中基线之间的空间。 None 值表示行距是从样式层次结构继承的。 一个浮点值，例如 2.0 或 1.75，表示间距以行高的倍数应用。 诸如 Pt(12) 之类的 Length 值表示间距是固定高度。 Pt 值类是一种以点为单位应用行距的便捷方式。 指定 None 会将行距重置为从样式层次结构继承。

• line_spacing_rule

  WD_LINE_SPACING 枚举的成员，指示应该如何解释 line_spacing 的值。 分配任何 WD_LINE_SPACING 成员 SINGLE、DOUBLE 或 ONE_POINT_FIVE 将导致 line_spacing 的值被更新以产生相应的行间距。

• page_break_before

  如果该段落应出现在上一段之后的页面顶部，则为True。 None 表示其有效值是从样式层次结构继承的。

• right_indent

  Length值，指定段落右边距和右边距之间的距离。 None 表示正确的缩进值是从样式层次结构继承的。 使用 Cm 值对象作为以厘米为单位应用缩进的便捷方式。

• space_after

  Length值，指定在此段落和后续段落之间出现的间距。 None 表示此值是从样式层次结构继承的。 Length对象提供方便的属性，例如 pt 和inches，可以轻松转换为各种长度单位。

• space_before

  指定在本段和前一段之间出现的间距的Length值。 None 表示此值是从样式层次结构继承的。 长度对象提供方便的属性，例如 pt 和 cm，可以轻松转换为各种长度单位。

• tab_stops

  TabStops 对象提供对为此段落格式定义的制表位的访问。

• widow_control

  当 Word 重新分页文档时，如果段落中的第一行和最后一行与该段落的其余部分保持在同一页上，则为True。 None 表示其有效值是从样式层次结构继承的。

Run对象

class docx.text.run.Run

包装 <w:r> 元素的代理对象。 Run 上的一些属性采用三态值，True、False 或 None。 True 和 False 分别对应 on 和 off。 None 表示该属性不是直接在run中指定的，其有效值取自样式层次结构。

• add_break(break_type=6)

  在此 run 中添加一个 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, width=None, height=None)

  返回包含由 image_path_or_stream 标识的图像的 InlineShape 实例，添加到此run的末尾。 image_path_or_stream 可以是路径（字符串）或包含二进制图像的类似文件的对象。 如果既没有指定宽度也没有指定高度，则图片以其原始大小显示。 如果只指定了一个，则它用于计算缩放因子，然后将其应用于未指定的维度，保留图像的纵横比。 图片的原始尺寸是使用图像文件中指定的每英寸点数 (dpi) 值计算的，如果没有指定值，则默认为 72 dpi，通常情况下。

• add_tab()

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

• add_text(text)

  将新附加的 _Text 对象（对应于新的 <w:t> 子元素）返回到run，其中包含文本。 与将文本直接分配给 Run.text 属性相比较，该方法可能更友好。

• bold

  读/写。 使run的文本以粗体显示。

• clear()

  删除所有内容后返回对此run的引用。 保留所有run格式。

• font

  Font 对象提供对该运行的字符格式属性的访问，例如字体名称和大小。

• italic

  读/写三态值。 如果为 True，则使运行的文本以斜体显示。

• style

  读/写。 一个 _CharacterStyle 对象，表示应用于此运行的字符样式。 如果运行没有直接应用的字符样式，则返回文档的默认字符样式（通常为默认字符字体）。 将此属性设置为 None 会删除任何直接应用的字符样式。

• text

  通过将每个运行内容子元素的等效文本连接成 Python 字符串而形成的字符串。 每个 <w:t> 元素添加它包含的文本字符。 <w:tab/> 元素添加了一个 \t 字符。 <w:cr/> 或 <w:br> 元素每个都添加一个 \n 字符。 请注意，<w:br> 元素可以指示分页符或分栏符以及换行符。 所有 <w:br> 元素都转换为单个 \n 字符，无论其类型如何。 所有其他内容子元素，例如 <w:drawing>，都会被忽略。

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

• underline

  此 Run 的下划线样式，None、True、False 之一或来自 WD_UNDERLINE 的值。 None 值表示运行没有直接应用的下划线值，因此将继承其包含段落的下划线值。 将 None 分配给此属性会删除任何直接应用的下划线值。 False 值表示直接应用的无下划线设置，覆盖任何继承的值。 True 值表示单个下划线。 WD_UNDERLINE 中的值用于指定其他轮廓样式，例如双线、波浪线和点线。

Font对象

class docx.text.run.Font

代理对象, 用于包装 <w:rPr> 元素的父元素，并提供对字符属性的访问，例如字体名称、字体大小、粗体和下标。

• all_caps

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

• bold

  读/写。 使此字体中的文本以粗体显示。

• color

  一个 ColorFormat 对象，提供了一种获取和设置此字体的文本颜色的方法。

• complex_script

  读/写三态值。 如果为 True，则导致run中的字符被视为复杂脚本，而不管其 Unicode 值如何。

• cs_bold

  读/写三态值。 当为 True 时，会使运行中的复杂脚本字符以粗体字显示。

• cs_italic

  读/写三态值。 当为 True 时，会导致运行中的复杂脚本字符以斜体字体显示。

• double_strike

  读/写三态值。 当为 True 时，会导致运行中的文本带有双删除线。

• emboss

  读/写三态值。 当为 True 时，会使运行中的文本看起来好像浮雕般从页面上抬起。

• hidden

  读/写三态值。 当为 True 时，会导致运行中的文本从显示中隐藏，除非应用程序设置强制显示隐藏的文本。

• highlight_color

  WD_COLOR_INDEX 的成员，指示应用突出显示的颜色，如果未应用突出显示，则为 None。

• imprint

  读/写三态值。 如果为 True，则使运行中的文本看起来好像被压入页面。

• italic

  读/写三态值。 如果为 True，则使运行的文本以斜体显示。 None 表示有效值是从样式层次结构继承的。

• math

  读/写三态值。 如果为 True，则指定此运行包含 WML，应该像处理 Office Open XML Math 一样处理。

• name

  获取或设置此 Font 实例的字体名称，如果找到匹配的字体，则使其控制的文本以命名字体显示。 None 表示字体是从样式层次结构继承的。

• no_proof

  读/写三态值。 如果为 True，则指定此运行的内容在扫描文档的拼写和语法时不应报告任何错误。

• outline

  读/写三态值。 当 True 时，通过在每个字符字形的内部和外部边框周围绘制一个像素宽的边框，使运行中的字符看起来好像它们有一个轮廓。

• rtl

  读/写三态值。 当 True 导致运行中的文本具有从右到左的特征。

• shadow

  读/写三态值。 当 True 时，会使运行中的文本看起来好像每个字符都有阴影。

• size

  读/写Length值或无，以英制单位 (EMU) 指示字体高度。 None 表示应该从样式层次结构继承字体大小。 Length 是 int 的子类，具有便于转换为点或其他长度单位的属性。 docx.shared.Pt 类允许方便地指定点值：

  >> font.size = Pt(24)
  >> font.size
  304800
  >> font.size.pt
  24.0
  

• small_caps

  读/写三态值。 当为 True 时，run中的小写字符显示为大写字母，比为run指定的字体大小小两点。

• snap_to_grid

  读/写三态值。 当 True 时，会导致run在布置此run中的字符时使用 docGrid 元素中定义的每行文档网格字符设置。

• spec_vanish

  读/写三态值。 当为 True 时，指定给定的run应始终表现为隐藏，即使当前文档中显示隐藏文本也是如此。 该属性具有与目录相关的非常狭窄的专门用途。 有关更多详细信息，请参阅规范 (§17.3.2.36)。

• strike

  读/写三态值。 当为 True 时，会导致运行中的文本以一条穿过行中心的水平线出现。

• subscript

  布尔值，指示此 Font 中的字符是否显示为下标。 None 表示下标/下标值是从样式层次结构继承的。

• superscript

  布尔值，指示此字体中的字符是否显示为上标。 None 表示下标/上标值是从样式层次结构继承的。

• underline

  此Font的下划线样式，None、True、False 之一，或来自 WD_UNDERLINE 的值。 None 表示字体从样式层次结构继承其下划线值。 False 表示没有下划线。 True 表示单下划线。 WD_UNDERLINE 中的值用于指定其他轮廓样式，例如双线、波浪线和点线。

• web_hidden

  读/写三态值。 当为 True 时，指定当文档在网页视图中显示时应隐藏此run的内容。

TabStop对象

class docx.text.tabstops.TabStop

应用于段落或样式的单个制表位。 使用列表语义对其包含的 TabStops 对象进行访问。

• alignment

  读/写。 指定此制表位的对齐设置的 WD_TAB_ALIGNMENT 的成员。

• leader

  读/写。 WD_TAB_LEADER 的成员，指定用作“前导”的重复字符，填充此选项卡跨越的空间。 分配 None 产生与分配 WD_TAB_LEADER.SPACES 相同的结果。

• position

  读/写。 一个 Length 对象，表示此制表位距段落内边缘的距离。 可能是正的或负的。

TabStops对象

class docx.text.tabstops.TabStops

一系列 TabStop 对象，提供对段落或段落样式的制表位的访问。 支持迭代、索引访问、del 和 len()。 使用 ParagraphFormat 的 tab_stops 属性访问它； 它不打算直接构建。

• add_tab_stop(position, alignment=WD_TAB_ALIGNMENT.LEFT, leader=WD_TAB_LEADER.SPACES)

  在 position 处添加一个新的制表位，一个 Length 对象，指定制表位相对于段落边缘的位置。 负位置值有效并出现在悬挂缩进中。 制表符对齐默认为左对齐，但可以通过传递 WD_TAB_ALIGNMENT 枚举的成员作为对齐方式来指定。 可以通过传递 WD_TAB_LEADER 枚举的成员作为领导者来指定可选的领导者字符。

• clear_all()

  删除所有自定义制表位。

表格对象

表对象是使用 Document 上的 [add_table()] 方法构造的。

• Table对象
• _Cell对象
• _Row对象
• _Column对象
• _Rows对象
• _Columns对象

Table对象

class docx.table.Table(tbl, parent)

WordprocessingML <w:tbl> 元素的代理类。

• add_column(width)

  返回一个width为 _Column 的对象，新添加到表的最右侧。

• add_row()

  返回一个 _Row 实例，新添加到表的最底部。

• alignment

  读/写。 WD_TABLE_ALIGNMENT 或 None 的成员，指定此表在页边距之间的位置。 如果未指定设置，则为None，从而导致从样式层次结构继承有效值。

• autofit

  如果可以自动调整列宽以提高单元格内容的匹配度，则为True。 如果表格布局是固定的，则为 False。 如果总列宽超过页面宽度，则在任何一种情况下都会调整列宽。 读/写布尔值。

• cell(row_idx, col_idx)

  返回与第 row_idx 行、col_idx 交叉处的表格单元格对应的 Cell 实例，其中 (0, 0) 是最顶部、最左侧的单元格。

• column_cells(column_idx)

  此表中 column_idx 列中的单元格序列。

• columns

  _Columns 实例表示此表中的列序列。

• row_cells(row_idx)

  此表中 row_idx 行中的单元格序列。

• rows

  _Rows 实例包含此表中的行序列。

• style

  读/写。 一个 _TableStyle 对象，表示应用于此表的样式。 如果表格没有直接应用的样式，则返回文档的默认表格样式（通常是普通表格）。 将 None 分配给此属性会删除任何直接应用的表格样式，从而使其继承文档的默认表格样式。 请注意，表格样式的样式名称与用户界面中显示的样式名称略有不同； 如果出现连字符，则必须删除。 例如，Light Shading - Accent 1 变为 Light Shading Accent 1。

• table_direction

  WD_TABLE_DIRECTION 的成员，指示表格单元格的排序方向，例如 WD_TABLE_DIRECTION.LTR。 None 表示该值是从样式层次结构继承的。

_Cell对象

class docx.table._Cell(tc, parent)

表格单元格

• add_paragraph(text=u'', style=None)

  返回一个新添加到此单元格内容末尾的段落。 如果存在，文本将在一次运行中添加到段落中。 如果指定，则应用段落样式样式。 如果 style 未指定或为 None，则结果就像应用了“正常”样式。 请注意，单元格中文本的格式可能会受到表格样式的影响。 text 可以包含制表符 (\t) 字符，这些字符被转换为适当的 XML 格式的制表符。 text 还可以包含换行符 (\n) 或回车符 (\r)，每个字符都转换为换行符。

• add_table(rows, cols)

  在任何现有单元格内容之后返回一个新添加到此单元格的表格，具有rows行和cols列。 因为 Word 需要一个段落元素作为每个单元格中的最后一个元素，所以会在表格后添加一个空段落。

• merge(other_cell)

  返回一个合并的单元格，该单元格通过跨越矩形区域而创建，该单元格和 other_cell 作为对角线的角。 如果单元格没有定义矩形区域，则引发 InvalidSpanError。

• paragraphs

  单元格中的段落列表。 表格单元格必须包含至少一个块级元素并以段落结尾。 默认情况下，新单元格包含一个段落。 只读

• tables

  单元格中的表格列表，按它们出现的顺序排列。 只读。

• text

  此单元格的全部内容为一串文本。 将字符串分配给此属性会在一次运行中将所有现有内容替换为包含分配文本的单个段落。

• vertical_alignment

  WD_CELL_VERTICAL_ALIGNMENT的成员 或 None 。

  None 的值表示此单元格的垂直对齐方式是继承的。 分配 None 会导致任何明确定义的垂直对齐被删除，从而恢复继承。

• width

  EMU 中此单元格的宽度，如果未设置显式宽度，则为 None。

_Row对象

class docx.table._Row[tr, parent]

表格行

• cells

  与该行中的单元格对应的 _Cell 实例序列。

• height

  返回表示此单元格高度的 Length 对象，如果未设置显式高度，则返回 None。

• height_rule

  返回此单元格的高度规则作为 WD_ROW_HEIGHT_RULE 枚举的成员，如果未设置显式的 height_rule，则返回 None。

• table

  引用该行所属的 Table 对象。

_Column对象

class docx.table._Column(gridCol, parent)

表格列

• cells

  与此列中的单元格对应的 _Cell 实例序列。

• table

  引用该列所属的 Table 对象。

• width

  EMU 中此列的宽度，如果未设置显式宽度，则为 None。

_Rows对象

class docx.table._Rows(tbl, parent)

与表中的行相对应的 _Row 对象序列。 支持 len()、迭代、索引访问和切片。

• table

  对此行集合所属的 Table 对象的引用。

_Columns对象

class docx.table._Columns(tbl, parent)

与表中的列相对应的 _Column 实例序列。 支持 len()、迭代和索引访问。

• table

  引用此列集合所属的 Table 对象。

分段对象

提供对部分属性的访问，例如边距和页面方向。

• Sections对象
• Section对象
• _Header和_Footer对象

Sections对象

class docx.section.Sections(document_elm, document_part)

与文档中的部分对应的Section对象的序列。

支持 len(), iteration, 和 索引访问.

Section对象

class docx.section.Section(sectPr, document_part)

文档 section ，提供对 section 和页面设置的访问。

还提供对页眉和页脚的访问。

• bottom_margin

  Length对象，表示此Section中所有页面的下边距，以英制公制单位表示。

• different_first_page_header_footer

  如果此Section显示不同的首页页眉和页脚，则为 True。

  读/写。 分别使用 first_page_header 和 first_page_footer 访问首页页眉和页脚的定义。

• even_page_footer

  _Footer 对象定义偶数页的页脚内容。

  除非文档设置 odd_and_even_pages_header_footer 设置为True，否则此页脚定义的内容将被忽略。

• even_page_header

  _Header 对象定义偶数页的标题内容。

  除非文档设置 odd_and_even_pages_header_footer 设置为True，否则此标题定义的内容将被忽略。

• first_page_footer

  _Footer 对象定义本节第一页的页脚内容。

  除非属性 different_first_page_header_footer 设置为 True，否则此页脚定义的内容将被忽略。

• first_page_header

  _Header 对象定义本节第一页的标题内容。

  除非属性 different_first_page_header_footer 设置为 True，否则此标题定义的内容将被忽略。

• footer

  _Footer 对象表示此部分的默认页脚。

  当启用单独的奇数/偶数页脚时，默认页脚用于奇数页。 否则，它用于奇数页和偶数页。

• footer_distance

  Length 对象，表示从页面底部边缘到页脚底部边缘的距离。 如果 XML 中没有设置，则为None。

• gutter

  Length 对象，表示本节中所有页面的页面装订线大小（以英制公制单位）。 页面装订线是在内部边距中添加的额外间距，以确保页面装订后的边距均匀。

• header

  _Header 对象表示此部分的默认页眉。

  当启用单独的奇数/偶数页眉时，默认页眉用于奇数页。 否则，它用于奇数页和偶数页。

• header_distance

  Length 对象，表示从页面上边缘到页眉上边缘的距离。 如果 XML 中没有设置，则为None。

• left_margin

  Length 对象，表示本节中所有页面的左边距，以英制公制单位表示。

• orientation

  WD_ORIENTATION 枚举的成员，指定此部分的页面方向，WD_ORIENT.PORTRAIT 或 WD_ORIENT.LANDSCAPE 之一。

• page_height

  此部分使用的总页面高度，包括所有边缘间距值，例如边距。 考虑了页面方向，例如，当方向为横向时，对于信纸大小的纸张，其预期值为 Inches(8.5)。

• page_width

  此部分使用的总页面宽度，包括所有边缘间距值，例如边距。 考虑了页面方向，例如，当方向为横向时，对于信纸大小的纸张，其预期值为 Inches(11)。

• right_margin

  Length 对象，表示此部分中所有页面的右边距，以英制公制单位表示。

• start_type

  WD_SECTION_START 枚举的成员对应于本节的初始中断行为，例如 WD_SECTION.ODD_PAGE 如果该部分应该从下一个奇数页开始。

• top_margin

  Length 对象，表示本节中所有页面的上边距，以英制公制单位表示。

_Header和_Footer对象

class docx.section._Header

页眉，用于所有三种类型（默认、偶数页和首页）。

请注意，与文档或表格单元格一样，标题必须至少包含一个段落，并且新的或“空”标题包含单个空段落。 第一段可以作为 header.paragraphs[0] 访问，以便向其中添加内容。 单独使用 add_paragraph() 添加内容会在新添加的段落上方留下一个空段落。

• add_paragraph(text=u'', style=None)

  返回一个新添加到此容器内容末尾的段落，如果存在则在单个运行中包含文本，并具有段落样式样式。 如果 style 为 None，则不应用任何段落样式，这与应用“Normal”样式的效果相同。

• add_table(rows, cols, width)

  返回一个具有 rows 行和 cols 列的宽度表，新附加到此容器中的内容。 宽度均匀分布在表格列之间。

• is_linked_to_previous

  如果此页眉/页脚使用上一节中的定义，则为True。

  如果此页眉/页脚有明确定义，则为 False。

  将 True 分配给该属性会删除该节的页眉/页脚定义，从而使其“继承”上一节的相应定义。 分配 False 会导致为此部分添加一个新的空定义，但前提是没有定义已经存在。

• paragraphs

  只读。包含此容器中的段落的列表，按文档顺序排列。

• tables

  只读。包含此容器中的表的列表，按文档顺序排列。

_Footer对象

class docx.section._Footer

页脚，用于所有三种类型（默认、偶数页和首页）。

请注意，与文档或表格单元格一样，页脚必须至少包含一个段落，而新的或其他“空”页脚包含一个空段落。 为了向其中添加内容，可以将第一段作为 footer.paragraphs[0] 访问。 单独使用 add_paragraph() 添加内容会在新添加的段落上方留下一个空段落。

• add_paragraph(text=u'', style=None)

  返回一个新添加到此容器内容末尾的段落，如果存在则在单个运行中包含文本，并具有段落样式样式。 如果 style 为 None，则不应用任何段落样式，这与应用“Normal”样式的效果相同。

• add_table(rows, cols, width)

  返回一个具有 rows 行和 cols 列的宽度表，新附加到此容器中的内容。 宽度均匀分布在表格列之间。

• is_linked_to_previous

  如果此页眉/页脚使用上一节中的定义，则为True。

  如果此页眉/页脚有明确定义，则为 False。

  将 True 分配给该属性会删除该节的页眉/页脚定义，从而使其“继承”上一节的相应定义。 分配 False 会导致为此部分添加一个新的空定义，但前提是没有定义已经存在。

• paragraphs

  只读。包含此容器中的段落的列表，按文档顺序排列。

• tables

  只读。包含此容器中的表的列表，按文档顺序排列。

形状相关对象

• InlineShapes对象
• InlineShape对象

InlineShapes对象

class docx.shape.InlineShapes(body_elm, parent)

[InlineShape] 实例的序列，支持 `len()`、迭代和索引访问。

InlineShape对象

InlineShape 的 width 和 height 属性提供了一个 length 对象，它是 Length 的一个实例。 这些实例的行为类似于 int，但也具有内置的单位转换属性，例如:

>>> inline_shape.height
914400
>>> inline_shape.height.inches
1.0

class docx.shape.InlineShape(inline)

wp:inline 元素的代理，代表内联图形对象的容器。

• height

  读/写。 此内联形状作为 Emu 实例的显示高度。

• type

  只读。此内联形状的类型作为 docx.enum.shape.WD_INLINE_SHAPE 的成员，例如 LINKED_PICTURE。

• width

  读/写。 此内联形状作为 Emu 实例的显示宽度。

DrawingML对象

出现在各种文档上下文中的低级绘图元素，例如颜色。

• ColorFormat对象

ColorFormat对象

class docx.dml.color.ColorFormat

提供对颜色设置的访问，例如 RGB 颜色、主题颜色和亮度调整。

• rgb

  如果未指定 RGB 颜色，则为 RGBColor 值或 None。

  当 type 为 MSO_COLOR_TYPE.RGB 时，此属性的值将始终为 RGBColor 值。 如果类型为 MSO_COLOR_TYPE.THEME，它也可能是 RGBColor 值，因为 Word 在分配主题颜色时会写入主题颜色的当前值。 在这种情况下，RGB 值应该被解释, 只是一个好的猜测，因为主题颜色在渲染时优先。 只要 type 为 None 或 MSO_COLOR_TYPE.AUTO 时，其值为 None。

  分配 RGBColor 值会导致类型变为 MSO_COLOR_TYPE.RGB 并删除任何主题颜色。 分配 None 会导致删除任何颜色，以便从样式层次结构继承有效颜色。

• theme_color

  如果未指定主题颜色，则为MSO_THEME_COLOR_INDEX的成员 或 None 。 当 type 为 MSO_COLOR_TYPE.THEME 时，此属性的值将始终是 MSO_THEME_COLOR_INDEX 的成员。 当 type 有任何其他值时，此属性的值为 None。

  分配 MSO_THEME_COLOR_INDEX 的成员会导致类型变为 MSO_COLOR_TYPE.THEME。 任何现有的 RGB 值都会保留，但会被 Word 忽略。 分配 None 会导致删除任何颜色规范，以便从样式层次结构继承有效颜色。

• type

  只读。 MSO_COLOR_TYPE 的成员，RGB、THEME 或 AUTO 之一，对应于定义此颜色的方式。 如果在此级别未应用颜色，则其值为 None，这会导致从样式层次结构继承有效颜色。

枚举

• Length对象
• RGBColor对象
• Inches对象
• Cm对象
• Mm对象
• Pt对象
• Twips对象
• Emu对象

Length对象

python-docx 中的长度值表示为标准化的Length值对象。 Length 是 int 的子类，具有 int 的所有行为。 此外，它具有内置的单位转换属性，例如：

>>> inline_shape.height
914400
>>> inline_shape.height.inches
1.0

Length对象是使用一系列便利构造函数构造的，允许以最适合上下文的单位表示值。

class docx.shared.Length

长度构造函数类 [Inches]、[Cm]、[Mm]、[Px] 和 [Emu] 的基类。 表现为英制公制单位的 int 计数，914,400 英寸，36,000 毫米。 以只读属性的形式提供方便的单位转换方法。 不可变。

• cm

  以厘米（float）表示的等效长度。

• emu

  以英制公制单位 (int) 表示的等效长度。

• inches

  以英寸（float）表示的等效长度。

• mm

  以毫米（float）表示的等效长度。

• pt

  以点为单位的浮点长度.(float)

• twips

  以缇 (int) 表示的等效长度。

RGBColor对象

class docx.shared.RGBColor(r, g, b)

定义特定 RGB 颜色的不可变值对象。

r、g 和 b 都是 0-255 范围内的整数，包括 0-255。 使用十六进制整数表示法，例如 0x42 可以增强使用十六进制 RGB 值的可读性：

>>> lavender = RGBColor(0xff, 0x99, 0xcc)

• classmethod from_string(rgb_hex_str)

  从 RGB 颜色十六进制字符串（如“3C2F80”）返回一个新实例。

Inches对象

class docx.shared.Inches

以英寸为单位的长度的便利构造函数，例如 width = Inches(0.5).

Cm对象

class docx.shared.Cm

以厘米为单位的方便构造函数，例如: height = Cm(12).

Mm对象

class docx.shared.Mm

以毫米为单位的方便构造函数，例如: width = Mm(240.5).

Pt对象

class docx.shared.Pt

用于以点为单位指定长度的便利值类

Twips对象

class docx.shared.Twips

以缇为单位的长度的便利构造函数，例如: width = Twips(42)。 一缇是二十分之一点，635 EMU。

Emu对象

class docx.shared.Emu

英制单位长度的便利构造函数，例如: width = Emu(457200).

枚举

可在此处找到用于 python-docx 属性设置的各种枚举的文档：

• MSO_COLOR_TYPE
• MSO_THEME_COLOR_INDEX
• WD_PARAGRAPH_ALIGNMENT
• WD_BUILTIN_STYLE
• WD_CELL_VERTICAL_ALIGNMENT
• WD_COLOR_INDEX
• WD_LINE_SPACING
• WD_ORIENTATION
• WD_TABLE_ALIGNMENT
• WD_ROW_HEIGHT_RULE
• WD_SECTION_START
• WD_STYLE_TYPE
• WD_TAB_ALIGNMENT
• WD_TAB_LEADER
• WD_TABLE_DIRECTION
• WD_UNDERLINE

MSO_COLOR_TYPE

指定颜色规范方案

例子：

from docx.enum.dml import MSO_COLOR_TYPE

assert font.color.type == MSO_COLOR_TYPE.THEME

• RGB

  颜色由 RGBColor 值指定。

• THEME

  颜色是预设的主题颜色之一。

• AUTO

  颜色由应用程序自动确定。

MSO_THEME_COLOR_INDEX

表示 Office 主题颜色，它是格式功能区颜色库中显示的颜色之一。

别名：MSO_THEME_COLOR

例子：

from docx.enum.dml import MSO_THEME_COLOR

font.color.theme_color = MSO_THEME_COLOR.ACCENT_1

• NOT_THEME_COLOR

  表示颜色不是主题颜色。

• ACCENT_1

  指定 Accent 1 主题颜色。

• ACCENT_2

  指定 Accent 2 主题颜色。

• ACCENT_3

  指定 Accent 3 主题颜色。

• ACCENT_4

  指定 Accent 4 主题颜色。

• ACCENT_5

  指定 Accent 5 主题颜色。

• ACCENT_6

  指定 Accent 6 主题颜色。

• BACKGROUND_1

  指定背景 1 主题颜色。

• BACKGROUND_2

  指定背景 2 主题颜色。

• DARK_1

  指定 Dark 1 主题颜色。

• DARK_2

  指定 Dark 2 主题颜色。

• FOLLOWED_HYPERLINK

  指定单击的超链接的主题颜色。

• HYPERLINK

  指定超链接的主题颜色。

• LIGHT_1

  指定 Light 1 主题颜色。

• LIGHT_2

  指定 Light 2 主题颜色。

• TEXT_1

  指定文本 1 主题颜色。

• TEXT_2

  指定文本 2 主题颜色。

• MIXED

  表示使用了多种主题颜色。

WD_PARAGRAPH_ALIGNMENT

别名：WD_ALIGN_PARAGRAPH

指定段落对齐类型。

例子：

from docx.enum.text import WD_ALIGN_PARAGRAPH

paragraph = document.add_paragraph()
paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER

• LEFT

  左对齐

• CENTER

  居中对齐。

• RIGHT

  右对齐。

• JUSTIFY

  合理。

• DISTRIBUTE

  段落字符分布以填充段落的整个宽度。

• JUSTIFY_MED

  以中等字符压缩率合理分布。

• JUSTIFY_HI

  以高等字符压缩率合理分布。

• JUSTIFY_LOW

  以较低字符压缩率合理分布。

• THAI_JUSTIFY

  根据泰语格式合理布局。

• WD_BUILTIN_STYLE
  • 文本类
  • 格式
  • 标题
  • HTML
  • 超链接
  • 索引
  • 列表
  • 列表项目符号
  • 列表继续
  • 列表编号
  • 宏
  • 表格
  • 标题

WD_BUILTIN_STYLE

别名：WD_STYLE

指定内置的 Microsoft Word 样式。

例子：

from docx import Document
from docx.enum.style import WD_STYLE

document = Document()
styles = document.styles
style = styles[WD_STYLE.BODY_TEXT]

文本类

• BLOCK_QUOTATION

  块文本。

• BODY_TEXT

  正文文本。

• BODY_TEXT_2

  正文文本 2.

• BODY_TEXT_3

  正文文本 3.

• BODY_TEXT_FIRST_INDENT

  正文文本第一个缩进.

• BODY_TEXT_FIRST_INDENT_2

  正文文本第二个缩进.

• BODY_TEXT_INDENT

  正文文本缩进.

• BODY_TEXT_INDENT_2

  正文文本缩进 2.

• BODY_TEXT_INDENT_3

  正文文本缩进 3.

格式

• BOOK_TITLE

  书名.

• CAPTION

  标题.

• CLOSING

  结束.

• COMMENT_REFERENCE

  评论参考.

• COMMENT_TEXT

  评论文本.

• DATE

  日期.

• DEFAULT_PARAGRAPH_FONT

  默认段落字体.

• EMPHASIS

  重点.

• ENDNOTE_REFERENCE

  尾注参考.

• ENDNOTE_TEXT

  尾注文本.

• ENVELOPE_ADDRESS

  信封地址.

• ENVELOPE_RETURN

  信封退回.

• FOOTER

  页脚.

• FOOTNOTE_REFERENCE

  脚注参考.

• FOOTNOTE_TEXT

  脚注文本.

标题

• HEADER

  标题.

• HEADING_1

  标题 1.

• HEADING_2

  标题 2.

• HEADING_3

  标题 3.

• HEADING_4

  标题 4.

• HEADING_5

  标题 5.

• HEADING_6

  标题 6.

• HEADING_7

  标题 7.

• HEADING_8

  标题 8.

• HEADING_9

  标题 9.

HTML

• HTML_ACRONYM

  HTML 首字母缩略词.

• HTML_ADDRESS

  HTML 地址.

• HTML_CITE

  HTML 引用.

• HTML_CODE

  HTML 代码.

• HTML_DFN

  HTML 定义.

• HTML_KBD

  HTML 键盘.

• HTML_NORMAL

  常规 (Web).

• HTML_PRE

  HTML 预格式化.

• HTML_SAMP

  HTML 示例.

• HTML_TT

  HTML 打字机.

• HTML_VAR

  HTML 变量.

超链接

• HYPERLINK

  超链接.

• HYPERLINK_FOLLOWED

  关注的超链接.

索引

• INDEX_1

  索引 1.

• INDEX_2

  索引 2.

• INDEX_3

  索引 3.

• INDEX_4

  索引 4.

• INDEX_5

  索引 5.

• INDEX_6

  索引 6.

• INDEX_7

  索引 7.

• INDEX_8

  索引 8.

• INDEX_9

  索引 9.

• INDEX_HEADING

  索引标题

• INTENSE_EMPHASIS

  强烈强调。

• INTENSE_QUOTE

  强烈引用

• INTENSE_REFERENCE

  强烈参考

• LINE_NUMBER

  电话号码。

列表

• LIST

  列表.

• LIST_2

  列表 2.

• LIST_3

  列表 3.

• LIST_4

  列表 4.

• LIST_5

  列表 5.

列表项目符号

• LIST_BULLET

  列表项目符号.

• LIST_BULLET_2

  列表项目符号 2.

• LIST_BULLET_3

  列表项目符号 3.

• LIST_BULLET_4

  列表项目符号 4.

• LIST_BULLET_5

  列表项目符号 5.

列表继续

• LIST_CONTINUE

  列表继续.

• LIST_CONTINUE_2

  列表继续 2.

• LIST_CONTINUE_3

  列表继续 3.

• LIST_CONTINUE_4

  列表继续 4.

• LIST_CONTINUE_5

  列表继续 5.

列表编号

• LIST_NUMBER

  列表编号.

• LIST_NUMBER_2

  列表编号 2.

• LIST_NUMBER_3

  列表编号 3.

• LIST_NUMBER_4

  列表编号 4.

• LIST_NUMBER_5

  列表编号 5.

• LIST_PARAGRAPH

  列表段落.

宏

• MACRO_TEXT

  宏文本.

• MESSAGE_HEADER

  消息头.

• NAV_PANE

  文档地图.

• NORMAL

  常规.

• NORMAL_INDENT

  正常缩进.

• NORMAL_OBJECT

  正常（应用于对象）.

• NORMAL_TABLE

  正常（在表格中应用）.

• NOTE_HEADING

  注释标题.

• PAGE_NUMBER

  页码.

• PLAIN_TEXT

  纯文本.

• QUOTE

  引用.

• SALUTATION

  称呼.

• SIGNATURE

  签名.

• STRONG

  强调.

• SUBTITLE

  副标题.

• SUBTLE_EMPHASIS

  微强调.

• SUBTLE_REFERENCE

  微参考.

表格

• TABLE_COLORFUL_GRID

  彩色网格.

• TABLE_COLORFUL_LIST

  多彩列表.

• TABLE_COLORFUL_SHADING

  彩色底纹.

• TABLE_DARK_LIST

  黑色列表.

• TABLE_LIGHT_GRID

  光栅.

• TABLE_LIGHT_GRID_ACCENT_1

  浅色网格强调 1.

• TABLE_LIGHT_LIST

  浅色列表.

• TABLE_LIGHT_LIST_ACCENT_1

  浅色列表强调 1.

• TABLE_LIGHT_SHADING

  光影.

• TABLE_LIGHT_SHADING_ACCENT_1

  光影强调 1.

• TABLE_MEDIUM_GRID_1

  中网格 1.

• TABLE_MEDIUM_GRID_2

  中网格 2.

• TABLE_MEDIUM_GRID_3

  中网格 3.

• TABLE_MEDIUM_LIST_1

  介质列表 1.

• TABLE_MEDIUM_LIST_1_ACCENT_1

  介质列表 1 强调 1.

• TABLE_MEDIUM_LIST_2

  介质列表 2.

• TABLE_MEDIUM_SHADING_1

  中等阴影 1.

• TABLE_MEDIUM_SHADING_1_ACCENT_1

  中等阴影 1 强调 1.

• TABLE_MEDIUM_SHADING_2

  中等阴影 2.

• TABLE_MEDIUM_SHADING_2_ACCENT_1

  中等阴影 2 强调 1.

• TABLE_OF_AUTHORITIES

  权限表.

• TABLE_OF_FIGURES

  图表.

标题

• TITLE

  标题.

• TOAHEADING

  TOA 标题.

• TOC_1

  目录 1.

• TOC_2

  目录 2.

• TOC_3

  目录 3.

• TOC_4

  目录 4.

• TOC_5

  目录 5.

• TOC_6

  目录 6.

• TOC_7

  目录 7.

• TOC_8

  目录 8.

• TOC_9

  目录 9.

WD_CELL_VERTICAL_ALIGNMENT

别名：WD_ALIGN_VERTICAL

指定表格的一个或多个单元格中文本的垂直对齐方式。

例子：

from docx.enum.table import WD_ALIGN_VERTICAL

table = document.add_table(3, 3)
table.cell(0, 0).vertical_alignment = WD_ALIGN_VERTICAL.BOTTOM

• TOP

  文本与单元格的上边框对齐。

• CENTER

  文本与单元格的中心对齐。

• BOTTOM

  文本与单元格的底部边框对齐。

• BOTH

  这是 OpenXml 规范中的一个选项，但在 Word 本身中没有。 目前尚不清楚此设置会产生什么 Word 行为。 如果您发现了，请告诉我们，我们将更新此文档。 否则，最好避免使用此选项。

WD_COLOR_INDEX

别名：WD_COLOR

指定要应用的标准预设颜色。 用于字体突出显示和可能的其他应用程序。

• AUTO

  自动上色。 默认; 通常是黑色的。

• BLACK

  黑色。

• BLUE

  蓝色

• BRIGHT_GREEN

  明亮的绿色。

• DARK_BLUE

  深蓝色。

• DARK_RED

  深红色。

• DARK_YELLOW

  深黄色。

• GRAY_25

  25% 的灰色阴影。

• GRAY_50

  50% 的灰色阴影。

• GREEN

  绿色。

• PINK

  粉色。

• RED

  红色。

• TEAL

  蓝绿色彩。

• TURQUOISE

  绿松石色。

• VIOLET

  紫罗兰色。

• WHITE

  白色。

• YELLOW

  黄色。

WD_LINE_SPACING

指定要应用于段落的行距格式。

例子：

from docx.enum.text import WD_LINE_SPACING

paragraph = document.add_paragraph()
paragraph.paragraph_format.line_spacing_rule = WD_LINE_SPACING.EXACTLY

• ONE_POINT_FIVE

  空格半行距。

• AT_LEAST

  行距始终至少为指定量。 金额单独指定。

• DOUBLE

  双倍行距。

• EXACTLY

  行距正好是指定的量。 金额单独指定。

• MULTIPLE

  行间距指定为行高的倍数。 更改字体大小将按比例更改行距。

• SINGLE

  单行距（默认）。

WD_ORIENTATION

别名：WD_ORIENT

指定页面布局方向。

例子：

from docx.enum.section import WD_ORIENT

section = document.sections[-1]
section.orientation = WD_ORIENT.LANDSCAPE

• PORTRAIT

  纵向。

• LANDSCAPE

  横向。

WD_TABLE_ALIGNMENT

指定表格对齐类型。

例子：

from docx.enum.table import WD_TABLE_ALIGNMENT

table = document.add_table(3, 3)
table.alignment = WD_TABLE_ALIGNMENT.CENTER

• LEFT

  左对齐

• CENTER

  居中对齐。

• RIGHT

  右对齐。

WD_ROW_HEIGHT_RULE

别名：WD_ROW_HEIGHT

指定确定表格行高的规则

例子：

from docx.enum.table import WD_ROW_HEIGHT_RULE

table = document.add_table(3, 3)
table.rows[0].height_rule = WD_ROW_HEIGHT_RULE.EXACTLY

• AUTO

  调整行高以适应行中的最高值。

• AT_LEAST

  行高至少是最小指定值。

• EXACTLY

  行高是一个精确值。

WD_SECTION_START

别名：WD_SECTION

指定分节符的开始类型。

例子：

from docx.enum.section import WD_SECTION

section = document.sections[0]
section.start_type = WD_SECTION.NEW_PAGE

• CONTINUOUS

  连续分节。

• NEW_COLUMN

  新的列分节符。

• NEW_PAGE

  新的分页符。

• EVEN_PAGE

  甚至页面分节符。

• ODD_PAGE

  部分从下一个奇数页开始。

WD_STYLE_TYPE

指定四种样式类型之一：段落、字符、列表或表格。

例子：

from docx import Document
from docx.enum.style import WD_STYLE_TYPE

styles = Document().styles
assert styles[0].type == WD_STYLE_TYPE.PARAGRAPH

• CHARACTER

  字符样式

• LIST

  列表样式

• PARAGRAPH

  段落样式

• TABLE

  表格样式

WD_TAB_ALIGNMENT

指定要应用的制表位对齐方式。

• LEFT

  左对齐。

• CENTER

  居中对齐。

• RIGHT

  右对齐。

• DECIMAL

  小数对齐。

• BAR

  条形对齐。

• LIST

  列表对齐。 （已弃用）

• CLEAR

  清除继承的制表位。

• END

  右对齐。 （已弃用）

• NUM

  左对齐。 （已弃用）

• START

  左对齐。 （已弃用）

WD_TAB_LEADER

指定用作带格式制表符的前导符的字符。

• SPACES

  空格。 默认。

• DOTS

  点。

• DASHES

  破折号。

• LINES

  双线。

• HEAVY

  一条粗线。

• MIDDLE_DOT

  一个垂直居中的点。

WD_TABLE_DIRECTION

指定应用程序对指定表或行中的单元格进行排序的方向。

例子：

from docx.enum.table import WD_TABLE_DIRECTION

table = document.add_table(3, 3)
table.direction = WD_TABLE_DIRECTION.RTL

• LTR

  表格或行以第一列在最左边的位置排列。

• RTL

  表格或行的第一列位于最右侧。

WD_UNDERLINE

指定应用于一系列字符的下划线样式。

• NONE

  没有下划线。 此设置覆盖任何继承的下划线值，因此可用于从继承其包含段落的下划线的运行中删除下划线。 请注意，这与将 None 分配给 Run.underline 不同。 None 是一个有效的赋值，但会导致运行继承其下划线值。 分配 WD_UNDERLINE.NONE 会导致无条件关闭下划线。

• SINGLE

  单行。 请注意，此设置是只写的，即为具有此设置的运行返回 True（而不是 WD_UNDERLINE.SINGLE）。

• WORDS

  仅在单个单词下划线。

• DOUBLE

  一条双线。

• DOTTED

  点。

• THICK

  一条粗线。

• DASH

  破折号。

• DOT_DASH

  交替的点和破折号。

• DOT_DOT_DASH

  交替的点点划线图案。

• WAVY

  单波浪线。

• DOTTED_HEAVY

  重点。

• DASH_HEAVY

  沉重的破折号。

• DOT_DASH_HEAVY

  交替的重点和重破折号。

• DOT_DOT_DASH_HEAVY

  交替的重点-点-划线图案。

• WAVY_HEAVY

  沉重的波浪线。

• DASH_LONG

  长破折号。

• WAVY_DOUBLE

  双波浪线。

• DASH_LONG_HEAVY

  长而沉重的破折号。

参与者指南

分析

原文: https://python-docx.readthedocs.io/en/latest/dev/analysis/index.html

为支持 API 和代码设计而进行的研究的文档。

docx源码