用 Python 按模板生成办公报告：从 Excel 数据到 Word 文档的自动填充

项目周报

项目名称：{{项目名称}}
负责人：{{负责人}}
统计日期：{{统计日期}}

本周进展：
{{本周进展}}

下周计划：
{{下周计划}}

python -m pip install openpyxl python-docx

项目目录/
├── template.docx
├── data.xlsx
└── generate_reports.py

from datetime import date, datetime
from pathlib import Path
import re

from docx import Document
from openpyxl import load_workbook


EXCEL_PATH = Path("data.xlsx")
TEMPLATE_PATH = Path("template.docx")
OUTPUT_DIR = Path("output")
SHEET_NAME = None          # None 表示使用第一个工作表；也可填写工作表名称
FILENAME_FIELD = "项目名称"  # 用于命名文件的字段


def iter_paragraphs(container):
    """遍历正文、表格以及嵌套表格中的段落。"""
    for paragraph in container.paragraphs:
        yield paragraph

    for table in container.tables:
        for row in table.rows:
            for cell in row.cells:
                yield from iter_paragraphs(cell)


def iter_document_paragraphs(document):
    """遍历正文、表格、页眉和页脚中的段落。"""
    yield from iter_paragraphs(document)

    for section in document.sections:
        yield from iter_paragraphs(section.header)
        yield from iter_paragraphs(section.footer)


def to_text(value):
    """把 Excel 单元格值转换成适合填入 Word 的文本。"""
    if value is None:
        return ""

    if isinstance(value, datetime):
        if value.time().isoformat() == "00:00:00":
            return value.date().isoformat()
        return value.isoformat(sep=" ")

    if isinstance(value, date):
        return value.isoformat()

    if isinstance(value, float) and value.is_integer():
        return str(int(value))

    return str(value).strip()


def safe_filename(value):
    """移除常见文件名禁用字符，避免保存失败。"""
    name = to_text(value)
    name = re.sub(r'[<>:"/\|?*x00-x1f]', "_", name)
    name = name.strip(" .")
    return name or "未命名报告"


def replace_tokens(document, row_data):
    """替换所有单个文本片段中的占位符。"""
    for paragraph in iter_document_paragraphs(document):
        for run in paragraph.runs:
            for field, value in row_data.items():
                run.text = run.text.replace(
                    "{{" + field + "}}",
                    to_text(value),
                )


def find_tokens(document):
    """找出模板正文中尚未填充的占位符。"""
    tokens = set()
    for paragraph in iter_document_paragraphs(document):
        tokens.update(re.findall(r"{{([^{}]+)}}", paragraph.text))
    return tokens


def unique_output_path(base_name):
    """遇到重名时追加序号，避免覆盖已有文件。"""
    path = OUTPUT_DIR / f"{base_name}.docx"
    number = 2

    while path.exists():
        path = OUTPUT_DIR / f"{base_name}_{number}.docx"
        number += 1

    return path


def main():
    if not EXCEL_PATH.exists():
        raise FileNotFoundError(f"找不到 Excel 文件：{EXCEL_PATH}")
    if not TEMPLATE_PATH.exists():
        raise FileNotFoundError(f"找不到 Word 模板：{TEMPLATE_PATH}")

    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)

    workbook = load_workbook(
        EXCEL_PATH,
        data_only=True,
        read_only=True,
    )

    try:
        worksheet = (
            workbook[SHEET_NAME]
            if SHEET_NAME
            else workbook[workbook.sheetnames[0]]
        )

        rows = worksheet.iter_rows(values_only=True)
        header_row = next(rows, None)

        if not header_row:
            raise ValueError("工作表为空，找不到表头。")

        headers = [
            str(value).strip() if value is not None else ""
            for value in header_row
        ]

        if any(not header for header in headers):
            raise ValueError("表头中存在空字段名，请补齐后再运行。")

        if len(headers) != len(set(headers)):
            raise ValueError("表头中存在重名字段，请修改为唯一名称。")

        template = Document(TEMPLATE_PATH)
        template_tokens = find_tokens(template)
        missing_headers = template_tokens - set(headers)

        if missing_headers:
            names = "、".join(sorted(missing_headers))
            raise ValueError(f"Excel 缺少模板所需字段：{names}")

        if FILENAME_FIELD not in headers:
            raise ValueError(
                f"用于命名文件的字段“{FILENAME_FIELD}”不在 Excel 表头中。"
            )

        generated = 0

        for row_number, values in enumerate(rows, start=2):
            if not values or all(value is None for value in values):
                continue

            row_data = dict(zip(headers, values))

            # 空单元格会填成空文本；若业务不允许空值，可在这里改为报错。
            document = Document(TEMPLATE_PATH)
            replace_tokens(document, row_data)

            leftovers = find_tokens(document)
            if leftovers:
                names = "、".join(sorted(leftovers))
                raise ValueError(
                    f"Excel 第 {row_number} 行生成后仍有未替换字段：{names}。"
                    "请检查模板占位符是否被 Word 拆分，或字段名是否一致。"
                )

            filename = safe_filename(row_data.get(FILENAME_FIELD))
            output_path = unique_output_path(filename)
            document.save(output_path)
            generated += 1
            print(f"已生成：{output_path}")

        print(f"完成，共生成 {generated} 份文档。")

    finally:
        workbook.close()


if __name__ == "__main__":
    main()

python generate_reports.py

SHEET_NAME = "周报数据"

required_fields = ["项目名称", "负责人", "统计日期"]
empty_fields = [
    field for field in required_fields
    if not to_text(row_data.get(field))
]

if empty_fields:
    names = "、".join(empty_fields)
    raise ValueError(f"Excel 第 {row_number} 行必填字段为空：{names}")