python-docx官方文档翻译--用户指南02--快速开始

快速开始

使用python-docx入门很容易。我们先了解下基础知识。

打开文档

首先我们需要准备一个文档。最简单的方法是这样：

from docx import Document

document = Document()

这将打开一个默认模板的空白文档，这与 Word 中新建的默认空白文档几乎是一样的。我们也可以使用 python-docx 打开和处理现有的 Word 文档，如下：

from docx import Document
# demo.docx 是现有的 Word 文档文件路径
document = Document('demo.docx')

添加段落

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

直接添加

最简单的添加段落的方法：

paragraph = document.add_paragraph('我用python-docx写 Word.')

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

通过插入添加

也可以将一个段落用作“游标”，并在其上方直接插入一个新段落：

prior_paragraph = paragraph.insert_paragraph_before('我')

这样可将段落插入文档的中间，这在修改现有文档时通常很重要。

添加标题

除最短文档外，正文中的正文均分为多个部分，每个部分均以标题开头。以下是添加方法：

document.add_heading('论打弟要趁早的意义')

默认情况下，这会添加一个顶级标题，在Word中显示为“标题1”。当我们想要一个小节的标题时，只需将所需的级别指定为1到9之间的整数即可：

document.add_heading('老弟长大的意义', level=2)

如果将级别指定为0，则会添加“标题”段落。这样可以方便地开始一个相对简短的文档，该文档没有单独的标题页。

添加分页符

即使我们所浏览的文本不完整，我们有时还是希望接下来的文本在单独的页面上显示。一个“强制性”分页符可以做到这一点：

document.add_page_break()

使用这个方法可以对 Word 进行灵活的排版，同时可以中断段落属性和样式的继承。因此，我们可以将某个级别的标题设置为始终开始一个新页面。稍后更多有关样式的信息。事实证明，它们对于真正充分利用Word至关重要。

添加表格

在 Word 中添加表格的方法如下：

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

表格类具有一些属性和方法。以下通过行和列索引来访问单元格：

cell = table.cell(0, 1)

此时访问的是第一行第二列的单元格。行和列索引都是从0开始的。
可以修改其文本：

cell.text = '来了老弟'

我们也可以先通过表格的 rows 属性访问某一行，再通过行的 cells 属性访问单元格，也有相似的列属性 columns：

row = table.rows[1]
row.cells[0].text = '你愁啥'
row.cells[1].text = '瞅你咋地'

表格的 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()

这样可以灵活制作可变长度的表：

items = (
    (7, '1024', '毛绒小猫'),
    (3, '2042', '毛蜂'),
    (1, '1288', '泰迪, 二哈'),
)

# 添加表 ------------------
table = document.add_table(1, 3)

# 填充表头 --------
heading_cells = table.rows[0].cells
heading_cells[0].text = 'Qty'
heading_cells[1].text = 'SKU'
heading_cells[2].text = 'Description'

# 给每一个 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'

注意：python-docx 并不支持 Word 中所有的表格样式，python-docx 的表格样式可以这样获取 :

import docx
document = docx.Document()
styles = document.styles.element.xpath('.//w:style[@w:type="table"]/@w:styleId')

一般通过 Word 中表的样式英文名删除所有空格来形成样式名称。鼠标悬念在 Word 表格样式库的缩略图上，可看到其名称。

添加图片

我们可以通过在 Word 中使用 “插入>图片” 菜单选项来添加图片。 在 python-docx 中是这样的：

document.add_picture('千年美女图.png')

通过向该方法传入图片路径或文件实例来添加图片（此处传入的是图片路径）

图片大小

默认情况下，添加的图像是以原始大小显示的。这通常比我们想要的大。原始大小以 像素/dpi 计算。如，具有 300dpi 分辨率的 300x300 像素图像以 1 (300 / 300) x 1 (300 / 300) 平方英寸显示。问题是大多数图像不包含 dpi 属性，默认为 72 dpi。这样，同一张图像会显示为 4.167 (300 / 72) x 4.167 (300 / 72) 平方英寸，约占页面的一半。
我们可以使用特定单位（如 英寸 或 厘米）来指定图像的宽度或高度：

from docx.shared import Inches

document.add_picture('千年美女图.png', width=Inches(1.0))

我们可以自由指定宽度和高度，不过通常不会都指定。因为，当我们只指定其中一个时， python-docx 会按图片原始宽高比例计算出另一个的值，这个图片就会保持原始宽高比例。
python-docx 提供英寸 (Inches) 和 厘米 (Cm) 类，从 docx.shared 中导入。在库内部，python-docx 使用英制公制单位，整数914400 代表一英寸。所以，如果 输入 width=2 之类的图片，则会得到一个非常小的图像😂。
我们可以对它们进行算术计算，跟整数一样。故，诸如 width=Inches(3) / count 之类的表达式是可以的。

应用段落样式

段落样式与前端的 CSS 样式相似。
在创建段落时直接应用段落样式：

document.add_paragraph('打弟要趁早啊！', style='List Bullet')

这种特殊样式将段落显示为项目符号，非常方便。
也可以在创建段落后，对段落应用段落样式。以下两步与上一步等同：

paragraph = document.add_paragraph('打弟要趁早啊！')
paragraph.style = 'List Bullet'

在此示例中，使用样式名称 “List Bullet" 指定样式。通常，样式名称与在 Word 中显示的英文名称完全相同。
注意：python-docx 支持的段落样式可以这样获取 :

import docx
document = docx.Document()
styles = document.styles.element.xpath('.//w:style[@w:type="paragraph"]/@w:styleId')

粗体和斜体

为了了解粗体和斜体的工作原理，您需要对段落中的内容有所了解。简短的版本是这样的：

1. 段落包含所有块级格式，例如缩进，行高，制表符等。
2. 字符级别的格式，如粗体和斜体，应用在文本运行级内容run中。段落中的所有内容都必须在一个或多个run中。因此，在中间有一个粗体字的段落中将需要三个run，一个普通字体run，一个粗体字run，以及后面的另一个普通字体run。
   当通过向 .add_paragraph() 方法传递文本来添加段落时，该段落包含一个run。我们也可以在使用段落的 .add_run() 方法添加更多run：

paragraph = document.add_paragraph('打弟 ')
paragraph.add_run('要趁早.')

这将生成一个看似使用单个字符串创建的段落。除非查看文档的 xml 结构，否则看不出段落文本在哪里断开。注意第一个字符串末尾的空格。末尾的空格不会自动插入，run 之间不会自动插入空格。
运行对象 Run 有 .bold 和 .italic 属性，我们可以设置它们的值：

paragraph = document.add_paragraph('老弟 ')
run = paragraph.add_run('就是')
run.bold = True
paragraph.add_run(' 用来打的.')

生成的文字是这样的： “老弟 就是 用来打的.”。
注意：

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

# 等同于:

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

应用字符样式

除了可以为段落指定段落级别的样式外，Word 还有 运行（run）级别 的字符样式。通常，我们可以将字符样式视为指定一种字形，如 字体、大小、颜色、粗体、斜体等。
与段落样式一样，字符字体必须是通过 Document() 调用打开的文档中被定义的（请参阅 了解样式）。
添加新的运行 run 时可以指定字符样式：

paragraph = document.add_paragraph('普通文本, ')
paragraph.add_run('强调文本.', 'Emphasis')

也可以在创建运行 run 后指定。这段代码生成与上面几行相同的结果：

paragraph = document.add_paragraph('普通文本, ')
run = paragraph.add_run('强调文本.')
run.style = 'Emphasis'

与段落样式一样，样式名称与在 Word UI 中显示的英文名称一样。
注意：python-docx 支持的字符样式可以这样获取 :

import docx
document = docx.Document()
styles = document.styles.element.xpath('.//w:style[@w:type="character"]/@w:styleId')