从业务数据到 Excel：模板导出的实现与验证

Excel 导出有一种常见错觉：只要文件能下载、单元格里有值，功能就完成了。实际交付时，用户还会打印、筛选、复制公式，甚至把文件发给另一个部门继续加工。导出结果是一份会被继续使用的文档。

在一次模板新增耗时列的修改中，数据已经写进新列，但标题合并范围仍停留在旧边界，打印区域也没有完整覆盖。这类问题不会让 Python 报错，却会直接影响打开后的观感和使用。

本文围绕这次经历整理导出实现与验证的方法。示例重新制作为六列合成报表，不使用真实报价、客户名称或业务模板。

先整理导出数据，再碰单元格

如果导出函数一边查询业务对象、一边判断状态、一边写单元格，模板变化很容易牵动业务逻辑。更清楚的边界，是先构造导出数据，再由模板层负责摆放。

例如一行数据包含演示编号、状态、数量和两个阶段耗时。耗时单位应在进入模板前确定，空值保持空白，不能把没有完成的任务导出为耗时零秒。时间差也需要使用口径一致的时间戳，而不是混合客户端时间与服务端时间。

对分组报表而言，数据模型还应表达哪些记录属于同一组、何时插入小计。不要完全依赖相邻单元格是否为空来反推业务分组，否则一条缺失数据就可能改变整张表的结构。

新增列会改变一组关联设置

原表有 A 到 D 四列，现在扩展到 F 列。除了写入 E、F，至少还要核对：标题与副标题合并、表头、列宽、行内样式、边框、筛选范围、打印区域和横向分页。

下面是可以独立生成合成工作簿的示例，使用 openpyxl：

from copy import copy
from openpyxl import Workbook
from openpyxl.utils.cell import quote_sheetname

wb = Workbook()
ws = wb.active
ws.title = "演示汇总"
ws.merge_cells("A1:D1")
ws["A1"] = "处理耗时演示"
ws.unmerge_cells("A1:D1")
ws.merge_cells("A1:F1")

headers = ["编号", "状态", "数量", "说明", "解析秒数", "总耗时秒数"]
for col, title in enumerate(headers, start=1):
    ws.cell(3, col, title)
for col in (5, 6):
    ws.cell(3, col)._style = copy(ws.cell(3, 4)._style)
ws.append(["DEMO-01", "完成", 100, "合成数据", 12, 20])
ws["E4"].number_format = "0.0"
ws["F4"].number_format = "0.0"
ws.print_area = "A1:F4"
ws.auto_filter.ref = "A3:F4"
ws.page_setup.orientation = "landscape"
ws.page_setup.fitToWidth = 1
ws.sheet_properties.pageSetUpPr.fitToPage = True

summary = wb.create_sheet("汇总校验")
summary["A1"] = f"={quote_sheetname(ws.title)}!F4"
wb.save("demo-export.xlsx")

_style 是内部属性，这里用于紧凑展示样式复制；长期维护的导出模块也可以分别复制 font、fill、border、alignment 等属性，减少对内部 API 的依赖。复制样式必须考虑位置：中间列、末列和合计行的边框未必相同，不能永远从左边一格复制。

示例通过明确的旧合并区域执行扩展，没有假设插入列会自动调整全部依赖。openpyxl 的工作表编辑文档说明了移动、插入等操作对依赖关系的处理限制。复杂模板应把需要更新的范围列成清单，逐项维护。

公式字符串与计算结果是两件事

带空格、中文或特殊字符的工作表引用，最好统一通过 quote_sheetname 构造。这样也能处理名称里的单引号，避免手写引号遗漏。公式名称及参数分隔符仍需要符合工作簿格式约定。

另一个容易误判的点是 data_only=True。它读取的是文件中已有的公式缓存，不会触发计算。刚由 openpyxl 写入的公式可能没有缓存，读到 None 并不能直接说明公式写错；旧缓存存在，也不能证明它反映了最新输入。

openpyxl 本身不执行公式计算，这一点在公式文档中有明确说明。需要确认最终结果时，应在可信的电子表格计算环境中重新计算，并核对结果；给工作簿设置“打开时重算”只是一项请求，仍不等于已经完成计算。

从文件容器检查到实际阅读

我会分层验证导出结果：

1. 文件容器：XLSX 的 ZIP 结构是否完整，是否能重新加载。
2. 工作表结构：名称、行列数、合并区域、打印与筛选范围是否正确。
3. 内容规则：零值、空值、耗时单位、分组与小计是否符合业务口径。
4. 公式：引用目标是否存在，重新计算后的结果是否合理。
5. 显示效果：标题是否覆盖全宽，新增列是否被截断，分页是否可读。

纯导出测试可以用合成数据快速覆盖前几层。数据库驱动的接口测试则验证查询、权限与下载响应。之前的任务里，有过数据库依赖不可用、部分接口测试无法执行的情况；此时应该分别记录已通过的纯导出测试和被阻塞的接口测试，不能合并成“导出已全面验证”。

最后仍要打开或渲染代表性文件。XML 里范围正确，不能代替实际查看字体、换行和打印页。特别是新增列之后，横向缩放可能让所有文字变得过小，需要从读者角度重新看整页。

让模板结构可以被检查

这次经历之后，我更愿意把关键列号、标题行和打印边界集中定义，避免同一个末列散落在多个函数中。但“集中一个常量”也不能自动解决所有问题，分组样式和跨表引用仍需要各自验证。

Excel 导出的可靠性来自数据、结构、计算和显示四个层面。把这四层拆开，新增两列才会成为一个可解释、可复查的改动，而不是等用户打开文件后再发现边缘问题。