docxtpl，一个强大的 Python 库！

大家好，我是涛哥，本文内容来自 涛哥聊Python ，转载请标原创。

更多Python学习内容：http://ipengtao.com

今天为大家分享一个强大的 Python 库 - docxtpl。

项目地址：https://docxtpl.readthedocs.io/en/latest/

---

在日常工作中，自动生成和处理 Word 文档是一个常见需求。docxtpl 是一个功能强大的 Python 库，专门用于基于模板生成 Microsoft Word 文档。它使得通过预定义的模板快速生成个性化的文档变得非常简单，适用于生成合同、报告、发票等。本文将详细介绍 docxtpl 库，包括其安装方法、主要特性、基本和高级功能，以及实际应用场景，帮助全面了解并掌握该库的使用。

安装

要使用 docxtpl 库，首先需要安装它。可以通过 pip 工具方便地进行安装。

以下是安装步骤：

pip install docxtpl

安装完成后，可以通过导入 docxtpl 库来验证是否安装成功：

import docxtpl
print("docxtpl 库安装成功！")

特性

1. 模板驱动：基于预定义的 Word 模板生成文档，简单直观。
2. 变量替换：支持在模板中使用变量和表达式，自动替换为实际值。
3. 丰富的控制结构：支持循环、条件判断等控制结构，生成动态内容。
4. 图片嵌入：支持在文档中嵌入图片，生成图文并茂的文档。
5. 表格和列表：支持生成复杂的表格和列表，满足各种文档需求。

基本功能

创建简单文档

使用 docxtpl，可以方便地创建一个简单的 Word 文档。

from docxtpl import DocxTemplate

# 创建模板文档
doc = DocxTemplate("template.docx")

# 定义要替换的变量
context = {
    'name': 'John Doe',
    'date': '2023-06-01'
}

# 渲染模板
doc.render(context)

# 保存生成的文档
doc.save("generated_doc.docx")

插入图片

docxtpl 支持在文档中插入图片。

from docxtpl import DocxTemplate, InlineImage
from docx.shared import Cm

# 创建模板文档
doc = DocxTemplate("template_with_image.docx")

# 定义要替换的变量
context = {
    'name': 'Jane Doe',
    'image': InlineImage(doc, 'image.png', width=Cm(5))
}

# 渲染模板
doc.render(context)

# 保存生成的文档
doc.save("generated_doc_with_image.docx")

生成表格

docxtpl 支持生成复杂的表格。

from docxtpl import DocxTemplate

# 创建模板文档
doc = DocxTemplate("template_with_table.docx")

# 定义要替换的变量
context = {
    'table_data': [
        {'item': 'Item 1', 'description': 'Description 1', 'price': 10},
        {'item': 'Item 2', 'description': 'Description 2', 'price': 20},
        {'item': 'Item 3', 'description': 'Description 3', 'price': 30}
    ]
}

# 渲染模板
doc.render(context)

# 保存生成的文档
doc.save("generated_doc_with_table.docx")

高级功能

使用控制结构

docxtpl 支持在模板中使用控制结构，如循环和条件判断。

from docxtpl import DocxTemplate

# 创建模板文档
doc = DocxTemplate("template_with_control_structures.docx")

# 定义要替换的变量
context = {
    'items': [
        {'name': 'Item 1', 'price': 10},
        {'name': 'Item 2', 'price': 20},
        {'name': 'Item 3', 'price': 30}
    ],
    'total_price': 60,
    'discount': 5
}

# 渲染模板
doc.render(context)

# 保存生成的文档
doc.save("generated_doc_with_control_structures.docx")

嵌套表格

docxtpl 支持嵌套表格的生成。

from docxtpl import DocxTemplate

# 创建模板文档
doc = DocxTemplate("template_with_nested_table.docx")

# 定义要替换的变量
context = {
    'orders': [
        {
            'order_id': '1001',
            'items': [
                {'name': 'Item A', 'quantity': 2, 'price': 100},
                {'name': 'Item B', 'quantity': 1, 'price': 200}
            ],
            'total': 400
        },
        {
            'order_id': '1002',
            'items': [
                {'name': 'Item C', 'quantity': 3, 'price': 50},
                {'name': 'Item D', 'quantity': 2, 'price': 150}
            ],
            'total': 450
        }
    ]
}

# 渲染模板
doc.render(context)

# 保存生成的文档
doc.save("generated_doc_with_nested_table.docx")

动态图片

docxtpl 支持动态插入图片。

from docxtpl import DocxTemplate, InlineImage
from docx.shared import Cm

# 创建模板文档
doc = DocxTemplate("template_with_dynamic_images.docx")

# 定义要替换的变量
context = {
    'products': [
        {'name': 'Product 1', 'image': InlineImage(doc, 'product1.png', width=Cm(4))},
        {'name': 'Product 2', 'image': InlineImage(doc, 'product2.png', width=Cm(4))}
    ]
}

# 渲染模板
doc.render(context)

# 保存生成的文档
doc.save("generated_doc_with_dynamic_images.docx")

实际应用场景

合同生成

通过 docxtpl 自动生成合同文档，减少手动填写的工作量。

from docxtpl import DocxTemplate

# 创建模板文档
doc = DocxTemplate("contract_template.docx")

# 定义要替换的变量
context = {
    'party_a': 'Company A',
    'party_b': 'Company B',
    'contract_date': '2023-06-01',
    'contract_terms': 'All terms and conditions of the contract...'
}

# 渲染模板
doc.render(context)

# 保存生成的合同文档
doc.save("generated_contract.docx")

报告生成

通过 docxtpl 自动生成数据报告，方便定期生成和分发。

from docxtpl import DocxTemplate

# 创建模板文档
doc = DocxTemplate("report_template.docx")

# 定义要替换的变量
context = {
    'report_date': '2023-06-01',
    'author': 'John Doe',
    'summary': 'This is a summary of the report...',
    'details': 'Detailed data and analysis...',
    'conclusion': 'Conclusion of the report...'
}

# 渲染模板
doc.render(context)

# 保存生成的报告文档
doc.save("generated_report.docx")

发票生成

通过 docxtpl 自动生成发票，减少手动填写和计算的工作量。

from docxtpl import DocxTemplate

# 创建模板文档
doc = DocxTemplate("invoice_template.docx")

# 定义要替换的变量
context = {
    'invoice_number': 'INV-2023-001',
    'billing_date': '2023-06-01',
    'customer_name': 'Jane Doe',
    'items': [
        {'description': 'Item 1', 'quantity': 2, 'unit_price': 100, 'total': 200},
        {'description': 'Item 2', 'quantity': 1, 'unit_price': 150, 'total': 150}
    ],
    'subtotal': 350,
    'tax': 35,
    'total': 385
}

# 渲染模板
doc.render(context)

# 保存生成的发票文档
doc.save("generated_invoice.docx")

总结

docxtpl 库是一个功能强大且易于使用的文档生成工具，能够帮助开发者在 Python 项目中高效地创建和管理 Word 文档。通过支持基于模板的文档生成、变量替换、丰富的控制结构、图片嵌入和复杂表格生成，docxtpl 能够满足各种复杂的文档生成需求。本文详细介绍了 docxtpl 库的安装方法、主要特性、基本和高级功能，以及实际应用场景。希望本文能帮助大家全面掌握 docxtpl 库的使用，并在实际项目中发挥其优势。