快速启动¶

开始使用 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在这方面做得很好。下面是如何添加表：

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 表上的集合是iterable的，因此可以直接在 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')

本例使用一个路径，从本地文件系统加载 Mapfile 。也可以使用 file-like object ，本质上是任何类似于打开文件的对象。如果您从数据库或通过网络检索图像，并且不想让文件系统卷入其中，这可能会很方便。

图像尺寸¶

默认情况下，添加的图像显示在 native 尺码。这往往比你想要的要大。本机大小计算为 pixels / dpi 。因此，具有300dpi分辨率的300x300像素图像显示在一英寸的正方形中。问题是大多数图像不包含dpi属性，默认为72dpi。这将使相同的图像显示在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 很好用。

应用段落样式¶

如果你不知道一个词的段落风格是什么，你一定要去看看。基本上，它允许你一次对一个段落应用一整套格式选项。它很像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”指定样式。通常，样式名称与单词user interface（UI）中显示的名称完全相同。

应用粗体和斜体¶

为了理解粗体和斜体是如何工作的，你需要对段落内部的内容有一点了解。简短的说法是：

一个段落包含所有 block-level 格式，如缩进、行高、制表符等。
字符级别的格式(如粗体和斜体)在 run 水平。一个段落中的所有内容都必须在一个运行中，但可以有多个。因此，中间有粗体单词的段落需要三次运行，一次正常运行，一次粗体包含该单词，另一次正常运行后的文本。

当您通过向 .add_paragraph() 方法，它将被放入单个运行中。您可以使用 .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 忧郁坐阿美特吧

请注意，您可以将结果设置为粗体或斜体 .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() 方法。这可以使您的代码更简单，如果您是从运行构建的段落无论如何：：

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

应用字符样式¶

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

与段落样式一样，字符样式必须已在使用 Document() 打电话 (see 了解样式 )。

添加新管路时可以指定字符样式：

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'

与段落样式一样，样式名称与单词UI中的名称相同。