python-docx 文档翻译（二）Quickstart

1. 创建（打开）一个文档 document

创建一个 document 对象：

from docx import Document
document = Document()

这和在 Word 中使用默认设置创建一个新文档差不多。也可以打开并处理现有的 Word 文档（后面介绍）。

2. 添加段落（paragraph）

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

该方法在文档末尾添加新的段落，返回对新建段落的引用。利用该引用可以执行一些操作，比如在该段落前添加一个段落：

prior_paragraph = paragraph.insert_paragraph_before('Lorem ipsum')

3. 应用段落样式

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

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

这使段落显示为项目符号。也可以在之后应用样式：

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

通常，样式名称与 Word 用户界面 (UI) 中的样式名称完全相同。

4. 应用粗体和斜体

在段落（paragraph）中，具有相同格式的一段文本称为一个 run。python-docx 在 run 级别应用字符级格式，例如粗体和斜体 。例如下图的段落需要五个 run，图片来源：

Run 对象示意图

当通过 .add_paragraph(text) 方法向文档添加 text 文本时，text 会被放入一个 run 中，样式默认。可以使用 .add_run() 方法向段落添加更多内容：

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

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() 返回所添加的 run 对象的引用，如果不需要对它进行其他操作，可以放弃该引用，直接在结果上设置粗体或斜体：

paragraph.add_run('dolor').bold = True
# is equivalent to:
run = paragraph.add_run('dolor')
run.bold = True

不必为 .add_paragraph() 方法提供文本，这可以使您的代码更简单：

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

5. 应用字符样式

除了 paragraph 级别的段落样式之外，Word 还有 run 级别的字符样式。一般来说，可以将字符样式视为指定字体，包括其字体、大小、颜色、粗体、斜体等。

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

paragraph.add_run('text with emphasis.', 'Emphasis')

还可以在创建 run 后将样式应用到 run：

run = paragraph.add_run('text with emphasis.')
run.style = 'Emphasis'

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

6. 添加标题（heading）

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

默认情况下，这会添加一个顶级标题，就是 Word 中的“标题 1”。将参数 level 指定为 1 到 9 之间的整数，可得小节的标题：

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

如果指定级别为 0，则会添加“标题”段落。

7. 添加分页（page_break）

document.add_page_break()

8. 添加表格

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

可以通过行列索引访问单元格（索引从零开始）：

cell = table.cell(0, 1)

单元格可以放一些东西：

cell.text = 'parrot, possibly dead'

表的 .rows 属性提供对各行的访问，每行都有一个 .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!'

.columns 与 .rows 同理，提供对各列的访问。可以直接在 for 循环中使用它们：

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

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 qty, sku, desc in items:
    cells = table.add_row().cells  # 添加后直接返回了 cells
    cells[0].text = str(qty)
    cells[1].text = sku
    cells[2].text = desc

Word 中有一组预先定义的表格样式，鼠标悬停在“设计”中的样式预览上可以看到样式的名字，删除其中的所有空格，可用于 python-docx 的 table：

table.style = 'LightShading-Accent1'
# UserWarning: style lookup by style_id is deprecated. Use style name as key instead. 有人知道为什么吗？

9. 添加图片（picture）

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

默认情况下，添加的图像以原始大小显示。可以指定其宽度或高度，单位 Inches 或 Cm：

from docx.shared import Inches
document.add_picture('image-filename.png', width=Inches(1.0))

如果只指定宽和高的一个，python-docx 自动计算另一个的正确缩放值。