python-docx 使用教程

1 快速入门

安装模块：

pip install python-docx

入门python-docx很容易。让我们来看一下基础知识。

官方文档地址请点击

2 打开文档

你需要的第一件事是工作的文档。最简单的方法是：

from docx import Document

document = Document()

这将打开一个基于默认“模板”的空白文档，您可以打开并使用现有的Word文档的工作python-docx，我们会让事情变得简单。

3 增加一段

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

这里是添加一个最简单的方法：

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

方法返回对段落的引用，新添加的段落在文档的结尾。

还可以使用一个段落作为“光标”，并在其上直接插入一个新段落：

prior_paragraph = paragraph.insert_paragraph_before('Lorem ipsum')

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

4 添加标题

在除了文档之外的任何内容中，正文文本被分成多个部分，每个部分以一个标题开始。以下是如何添加一个标题：

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

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

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

如果指定级别0，将添加“标题”段落。这可以方便地启动一个相对较短的文档，没有单独的标题页。

5 添加分页符

你想要另起一页写内容，即使你所在的一个不是满的页面。分页符可以做到这一点：

document.add_page_break()

6 添加表

以下是添加表格的方法：

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

表具有几个属性和方法，访问单个单元格可能是一个好的开始的地方。作为基线，您可以始终按其行和列指示访问单元格：

cell = table.cell(0, 1)

一旦你有一个单元格，你可以在单元格中插入内容。注意，行和列指示是基于零的，就像在列表访问中一样。

cell.text = 'parrot, possibly dead'

通常，一次访问一行单元格更容易，例如，当从数据源填充可变长度的表时。在.rows 一个表中的属性提供给单独的行，每个都具有一个 .cells属性。该.cells两个属性Row和Column 支持索引访问，就像一个列表：

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 = get_things_from_database_or_something()

# 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的表样式库中的缩略图上，可以找到表样式名称。

7 添加图片

Word中，您可以将图像使用的文档中的菜单项。以下是如何做到这一点的：

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

示例使用路径，从本地文件系统加载图像文件。你也可以使用一个类文件对象，本质上就像一个打开的文件的任何对象。如果您从数据库或网络检索图像，并且不想获取涉及的文件系统，这可能很方便。

8 图像大小

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

from docx.shared import Inches

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

9 应用段落样式

如果你不知道一个Word段落风格是你应该肯定检查出来。基本上，它允许您将一整套格式化选项立即应用到段落。这很像CSS样式，如果你知道那些是。

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

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

这种特殊的风格导致段落显示为一个列表，一个非常方便的东西。这两行相当于上面的一行

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

paragraph.style = 'ListBullet'

在此示例中，样式使用其样式ID“ListBullet”指定。通常，通过去除样式名称中出现在Word用户界面（UI）中的空格来形成样式ID。所以风格'列表3号'将被指定为'ListNumber3'。但是，请注意，如果您使用的是本地化版本的Word，则样式ID可能来自英语样式名称，并且可能不会完全对应于其在Word UI中的样式名称。

10 应用粗体和斜体

为了理解如何粗体和斜体的工作，你需要了解一个段落里面发生了什么。简短的版本是这样的：

1. 一个段落包含所有的块级格式，如缩进，行高，制表符，等等。
2. 字符级格式，如粗体和斜体，都在应用的 运行水平。段落中的所有内容必须在一个运行中，但可以有多个。因此，在中间有一个粗体字的段落需要三个段落，一个正常的段落，一个包含该单词的粗体，以及另一个正常的段落。

当您的提供文本添加段落.add_paragraph()的方法，它被放入一个单一的运行。您可以添加更多的使用.add_run()上一段方法：

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

Run对象既有.bold和.italic属性，您可以设置其值为运行：这将产生一个看起来像从单个字符串创建的段落。除非你看看XML，段落文本被分成几个部分并不明显。注意第一个字符串末尾的尾部空格。您需要明确在运行的开始和结束位置出现的位置。它们不会在运行之间自动插入。期待被那一个被抓住几次:)。

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

请注意，您可以对结果集粗体或斜体正确的.add_run()，如果你不需要它为别的：其产生的文字，看起来像这样：'Lorem存有悲坐阿梅德。“

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()方法。这可以使你的代码更简单，如果你从建立段从运行反正：

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

11 应用字符样式　　

除了段落样式，其中指定一组段落级别设置，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中的空格形成样式ID。所以风格'微妙强调'将被指定为'SubtleEmphasis'。请注意，如果您使用的是本地化版本的Word，则样式ID可能来自英语样式名称，并且可能不对应于其在Word UI中的样式名称。