python docx 使用总结

Posted 2023-04-07

参考技术A

本文将总结之前在使用 python-docx 包处理 word 文档时的一些理解与经验。

安装

引入

python-docx 将整个文章看做是一个 Document 对象 官方文档 - Document ，其基本结构如下：

在 python-docx 中， run 是最基本的单位，每个 run 对象内的文本样式都是一致的，也就是说，在从 docx 文件生成文档对象时， python-docx 会根据样式的变化来将文本切分为一个个的 Run 对象。

你也可以通过它来处理表格 官方文档 - 表格 ，基本结构如下：

使用python-docx处理word.docx文件

快速入门

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

打开文档

您需要做的第一件事是处理文档。最简单的方法是这样的：

from docx import Document

document = Document()

这将打开一个基于默认“模板”的空白文档，这几乎是您在Word中使用内置默认值启动新文档时所获得的。您可以使用来打开和处理现有的Word文档python-docx，但目前我们将使事情变得简单。

增加一款

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

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

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中显示为“标题1”。当您想要一个小节的标题时，只需将所需的级别指定为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属性。该.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 = (
    (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‘)

本示例使用路径从本地文件系统加载图像文件。您还可以使用类似文件的对象，基本上是任何行为类似于打开文件的对象。如果您要从数据库或网络中检索映像并且不想涉及文件系统，这可能很方便。

图像大小

默认情况下，添加的图像以原始大小显示。这通常比您想要的要大。原始大小计算为。因此，具有300 dpi分辨率的300x300像素图像出现在一个平方英寸中。问题是大多数图像不包含dpi属性，默认为72 dpi。这样一来，同一张图像的一侧就会出现4.167英寸，大约在页面的一半左右。pixels / dpi

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

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样式，则很像CSS样式。

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

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）中显示的样式名称完全相同。

应用粗体和斜体

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

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

通过向.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 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()方法提供文本。如果您仍然要通过运行来构建段落，则可以使代码更简单：

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中显示的一样。