1. 项目缘起：从“合并单元格”这个看似简单的需求说起
在数据处理和报表生成的日常工作中，我们经常会遇到一个看似简单、实则暗藏玄机的需求：填充数据到合并单元格，并最终导出为Excel文件。无论是生成财务报表、制作人员花名册，还是汇总项目进度表，合并单元格都是美化表格、清晰展示层级关系的常用手段。然而，当我们需要用程序（比如Python、Java）自动化填充这些表格时，合并单元格就从“格式”变成了“障碍”。
很多开发者第一次尝试时，可能会直接用pandas的to_excel，或者openpyxl的简单写入，结果发现数据要么只写入了合并区域的左上角单元格，其他区域是空的；要么就是破坏了原有的合并结构，导致格式错乱。更棘手的是，当合并单元格作为表头，需要根据下方数据动态填充时，逻辑就变得更加复杂。网络上相关的热词，如“python处理excel合并单元格”、“el-table 合并单元格 没覆盖数据”，都反映了这是一个普遍存在的痛点。今天，我就结合自己多次踩坑和实战的经验，手把手带你从原理到实践，彻底搞定这个需求，实现一个健壮、通用的“填充数据合并单元格并导出Excel”的解决方案。
2. 核心挑战解析：为什么合并单元格这么“难缠”？
在动手写代码之前，我们必须先理解问题的本质。Excel中的合并单元格，在底层数据模型上，和我们直观看到的“一个大格子”完全不同。
2.1 合并单元格的底层逻辑
一个合并单元格区域（例如A1:B2被合并），在Excel文件内部（如.xlsx的XML结构中）是这样记录的：
- 只有一个“主单元格”存储实际值。通常是合并区域左上角那个单元格（本例中的A1）。这个单元格的
value属性承载了我们在Excel里看到的所有内容。 - 其他单元格在逻辑上被“隐藏”或“标记为空”。B1、A2、B2这三个单元格，虽然视觉上属于合并区域的一部分，但它们本身不存储值。当你用程序读取它们时，返回的是
None或空值。 - 格式和样式通常应用于整个区域。边框、背景色、字体等样式信息会关联到整个合并区域。
这就导致了第一个核心矛盾：我们视觉上认为是一个“大对象”的区域，在程序处理时，必须精确地定位到唯一的“有效写入点”。写错了位置，数据就“消失”了。
2.2 动态填充带来的额外复杂度
我们的需求不仅仅是写入静态数据。更常见的场景是：
- 场景A（表头合并）：我们有一个Excel模板，第一行是合并了A1:D1的“部门销售统计”标题。我们需要读取这个模板，在下方从第2行开始，动态填入各部门各季度的销售数据。
- 场景B（数据行合并）：生成一个人员名单，其中“部门”这一列，同一部门的人员所在行需要合并单元格。我们需要在生成数据的同时，动态创建这些合并。
对于场景A，难点在于如何无损地读取模板中的合并信息，并在正确的位置续写数据。对于场景B，难点在于如何根据数据内容动态计算需要合并的区域，并在写入数据后应用合并格式。这两个场景都要求我们的代码不能是简单的“写入A1单元格”，而必须包含对工作表结构的分析和操作。
注意：很多初学者会试图用“循环遍历合并区域所有坐标并写入相同值”的暴力方法。这在
openpyxl等库中会导致错误或警告，因为试图向一个属于合并区域的非主单元格写入值是不被允许的。正确做法永远是：只向合并区域的主单元格写入一次。
3. 工具选型：为什么是 openpyxl 与 pandas 的组合拳？
面对Excel操作，Python生态中有多个强大的库，如openpyxl、xlrd/xlwt、pandas、xlsxwriter。针对“填充合并单元格并导出”这个需求，我强烈推荐openpyxl+pandas的组合。理由如下：
openpyxl：精细控制的“手术刀”。它是目前处理.xlsx文件功能最全面、最活跃的库之一。其核心优势在于能对工作表进行像素级操作：精确获取每一个合并单元格的范围（ws.merged_cells.ranges）、读写任意单元格的值和样式、创建新的合并区域。这对于我们读取模板合并信息、动态创建合并、向特定主单元格写入数据至关重要。xlrd/xlwt对新版.xlsx支持不佳，xlsxwriter主要用于创建文件而非精细修改。pandas：数据处理的“流水线”。pandas的DataFrame是处理表格数据的利器，能轻松进行数据清洗、转换、计算。虽然pandas的to_excel方法本身对合并单元格支持较弱（它主要将DataFrame输出为规整的网格），但它可以与openpyxl引擎完美配合。我们可以用pandas准备好数据，再用openpyxl进行精细化的“雕琢”。- 分工协作流程：
- 使用
openpyxl加载已有的模板文件，获取其所有合并单元格信息。 - 使用
pandas进行复杂的数据处理，生成最终的DataFrame。 - 将
pandasDataFrame写入一个新的工作表（或文件的特定位置），得到一个规整的数据表。 - 再次使用
openpyxl，将第一步获取的模板合并信息，“移植”或“应用”到新写入的数据区域，并根据需要创建新的合并（如场景B）。 - 最后，用
openpyxl保存文件。
- 使用
这个组合既利用了pandas的数据处理效率，又发挥了openpyxl的格式控制能力，是处理此类混合需求的最佳实践。
4. 实战演练：场景A - 填充带合并表头的模板
假设我们有一个名为report_template.xlsx的模板，其Sheet1中，A1:D1合并为标题“2024年季度报告”，A2:D2是表头“Q1， Q2， Q3， Q4”。我们需要从第3行开始，填入如下数据：
| 区域 | Q1销售额 | Q2销售额 | Q3销售额 | Q4销售额 |
|---|---|---|---|---|
| 华东 | 150 | 180 | 220 | 190 |
| 华北 | 120 | 140 | 160 | 135 |
| 华南 | 200 | 230 | 250 | 240 |
我们的目标是保持A1:D1的合并标题不变，在下方填入数据，并最终保存为新文件。
4.1 步骤详解与代码实现
首先，安装必要的库：pip install openpyxl pandas
import openpyxl from openpyxl import load_workbook import pandas as pd from copy import copy def fill_merged_template(template_path, output_path, data_df, start_row=3): """ 填充带有合并单元格的Excel模板。 Args: template_path (str): 模板文件路径。 output_path (str): 输出文件路径。 data_df (pd.DataFrame): 要填充的数据，DataFrame。 start_row (int): 数据开始写入的行号（基于1的索引，模板中数据区域的首行）。 """ # 1. 加载模板，获取原始合并信息 wb = load_workbook(template_path) ws = wb.active # 假设操作第一个工作表 # 获取模板中所有的合并区域 merged_ranges = list(ws.merged_cells.ranges) # 例如 [<CellRange A1:D1>] print(f"模板中的合并区域: {[str(r) for r in merged_ranges]}") # 2. 将数据写入工作表 # 确定写入的起始单元格 start_cell = ws.cell(row=start_row, column=1) # 使用openpyxl的逐行逐列写入，可以更好地控制格式（但稍慢） # 这里为了清晰，我们遍历DataFrame的行和列 for i, row in enumerate(data_df.itertuples(index=False), start=0): for j, value in enumerate(row, start=0): cell = ws.cell(row=start_row + i, column=1 + j, value=value) # 可选：复制模板中表头行的样式到数据区域 # if i == 0: # 如果是数据第一行 # source_cell = ws.cell(row=start_row-1, column=1+j) # if source_cell.has_style: # cell.font = copy(source_cell.font) # cell.border = copy(source_cell.border) # cell.fill = copy(source_cell.fill) # cell.alignment = copy(source_cell.alignment) # **关键步骤**：在写入数据后，必须重新应用模板中的合并！ # 因为openpyxl在写入大量单元格时，合并信息可能会被“遗忘”或需要重新激活。 # 清除现有的合并信息（避免冲突） ws.merged_cells.ranges.clear() # 重新添加所有之前获取的合并区域 for merged_range in merged_ranges: ws.merged_cells.add(str(merged_range)) # 3. 保存到新文件 wb.save(output_path) print(f"文件已保存至: {output_path}") # 准备数据 data = { '区域': ['华东', '华北', '华南'], 'Q1销售额': [150, 120, 200], 'Q2销售额': [180, 140, 230], 'Q3销售额': [220, 160, 250], 'Q4销售额': [190, 135, 240] } df = pd.DataFrame(data) # 调用函数 fill_merged_template('report_template.xlsx', 'filled_report.xlsx', df, start_row=3)代码核心解读与避坑点：
- 先抓取，后清除，再恢复：这是本方案最关键的逻辑。我们一开始用
list(ws.merged_cells.ranges)将模板的合并信息保存到变量中。在数据写入完成后，调用ws.merged_cells.ranges.clear()清除工作表当前（可能已混乱）的合并信息。最后，用ws.merged_cells.add()将之前保存的合并信息原样添加回去。这一步确保了模板的合并格式在数据写入后得以完美保留。 - 写入位置的精确计算：
start_row参数需要你明确知道模板中数据区的起始行。这通常需要手动查看模板确定。ws.cell(row=start_row + i, column=1 + j)这个计算确保了数据被准确地、逐行逐列地填入网格。 - 样式复制（可选但重要）：注释掉的样式复制代码，展示了如何将模板中表头行（
start_row-1）的样式（字体、边框、填充、对齐）复制到新写入的数据单元格。使用copy()是为了创建样式的深拷贝，避免意外的引用关联。如果你的数据区需要继承模板的格式，这段代码非常有用。 - 性能考量：上述代码使用双重循环写入，对于大数据量（数万行）可能较慢。对于纯数据写入，可以先使用
pandas的to_excel写入到一个新的工作表或临时文件，然后再用openpyxl进行格式合并操作，这样性能更高。但直接循环写入的好处是位置控制绝对精确，且易于理解。
5. 实战演练：场景B - 动态生成并合并数据行
这个场景更复杂，也更具挑战性。假设我们要生成一个员工名单，数据如下：
| 部门 | 姓名 | 工号 |
|---|---|---|
| 研发部 | 张三 | 001 |
| 研发部 | 李四 | 002 |
| 市场部 | 王五 | 003 |
| 市场部 | 赵六 | 004 |
| 市场部 | 孙七 | 005 |
| 人事部 | 周八 | 006 |
我们希望“部门”这一列（A列），相同部门的行合并单元格，效果如下：
- A2:A3 合并，显示“研发部”
- A4:A6 合并，显示“市场部”
- A7:A7 合并（单单元格，但逻辑上仍是一个合并区域），显示“人事部”
5.1 算法思路与代码实现
动态合并的核心在于对数据分组，并计算每个分组在Excel中的行范围。
import openpyxl from openpyxl.styles import Alignment import pandas as pd def export_with_row_merging(data_df, output_path, merge_column_index=0): """ 导出DataFrame，并对指定列中连续相同值进行行合并。 Args: data_df (pd.DataFrame): 源数据。 output_path (str): 输出Excel文件路径。 merge_column_index (int): 需要合并的列的索引（从0开始）。 """ # 1. 创建一个新的工作簿和工作表 wb = openpyxl.Workbook() ws = wb.active ws.title = "员工名单" # 2. 写入表头 for col_idx, column_name in enumerate(data_df.columns, start=1): ws.cell(row=1, column=col_idx, value=column_name) # 可以给表头加粗等样式 ws.cell(row=1, column=col_idx).font = openpyxl.styles.Font(bold=True) # 3. 写入数据，并记录合并信息 current_merge_value = None merge_start_row = 2 # 数据从第2行开始 merge_end_row = 2 for row_idx, row in enumerate(data_df.itertuples(index=False), start=2): # Excel行从2开始 for col_idx, value in enumerate(row, start=1): ws.cell(row=row_idx, column=col_idx, value=value) # 判断是否需要合并 cell_value = row[merge_column_index] # 获取当前行需要判断的列的值 if cell_value == current_merge_value: # 值相同，延长合并区间 merge_end_row = row_idx else: # 值不同，处理上一个合并区间（如果存在） if current_merge_value is not None and merge_start_row < merge_end_row: # 只有起始行小于结束行，才需要合并（多于一行） merge_range = f"{openpyxl.utils.get_column_letter(merge_column_index+1)}{merge_start_row}:{openpyxl.utils.get_column_letter(merge_column_index+1)}{merge_end_row}" ws.merged_cells.add(merge_range) # 设置合并后单元格垂直居中，看起来更美观 ws.cell(row=merge_start_row, column=merge_column_index+1).alignment = Alignment(vertical='center') # 开始新的合并区间 current_merge_value = cell_value merge_start_row = row_idx merge_end_row = row_idx # 4. 循环结束后，处理最后一组可能的合并 if current_merge_value is not None and merge_start_row < merge_end_row: merge_range = f"{openpyxl.utils.get_column_letter(merge_column_index+1)}{merge_start_row}:{openpyxl.utils.get_column_letter(merge_column_index+1)}{merge_end_row}" ws.merged_cells.add(merge_range) ws.cell(row=merge_start_row, column=merge_column_index+1).alignment = Alignment(vertical='center') # 5. 自动调整列宽（可选，提升可读性） for column in ws.columns: max_length = 0 column_letter = column[0].column_letter for cell in column: try: if len(str(cell.value)) > max_length: max_length = len(str(cell.value)) except: pass adjusted_width = (max_length + 2) ws.column_dimensions[column_letter].width = adjusted_width # 6. 保存文件 wb.save(output_path) print(f"动态合并文件已保存至: {output_path}") # 准备数据 employee_data = { '部门': ['研发部', '研发部', '市场部', '市场部', '市场部', '人事部'], '姓名': ['张三', '李四', '王五', '赵六', '孙七', '周八'], '工号': ['001', '002', '003', '004', '005', '006'] } df_employees = pd.DataFrame(employee_data) # 调用函数，合并第0列（‘部门’列） export_with_row_merging(df_employees, 'employee_list_merged.xlsx', merge_column_index=0)算法精髓与注意事项：
- “滑动窗口”式分组：算法本质是一个状态机。它遍历每一行数据，用
current_merge_value记录当前正在处理的部门名，用merge_start_row和merge_end_row记录这个部门出现的起始行和结束行。当遇到一个新部门时，就结算上一个部门的合并区域（如果起始行<结束行，说明该部门有多行，需要合并）。 - 合并区域的坐标计算：
openpyxl.utils.get_column_letter()函数将数字列索引（从1开始）转换为Excel字母列标（如1->‘A’）。合并区域的字符串格式为“起始单元格:结束单元格”，例如“A2:A3”。 - 样式设置：合并单元格后，通常需要设置垂直居中（
Alignment(vertical=‘center’)），这样文字才会在合并后的区域中垂直居中显示。这个样式需要设置在合并区域的主单元格（即起始行那个单元格）上。 - 边界条件处理：循环结束后，必须记得处理最后一组数据。因为最后一组在循环内可能没有触发“值不同”的条件，需要单独合并。
- 扩展到多列合并：上述代码处理的是单列合并。如果需要根据多列组合进行合并（例如“部门”+“小组”都相同时才合并），则需要将
cell_value改为一个元组（如(row[dept_idx], row[team_idx])），并相应修改比较逻辑。
6. 进阶技巧与性能优化
当数据量变大或模板非常复杂时，基础的循环方法可能会遇到性能瓶颈。以下是一些进阶思路：
6.1 使用 pandas 的 Styler 进行初步格式化（有限支持）
pandas的Styler对象可以在导出到Excel时应用一些格式，包括简单的单元格合并（通过set_table_styles实现跨列合并，但对跨行合并支持非常弱且复杂）。对于纯数据展示且合并逻辑简单的场景，可以研究Styler，但它无法处理我们上面提到的复杂动态行合并或读取现有模板合并。
# 这是一个非常有限的例子，仅作展示 styled_df = df.style.set_table_styles([ {'selector': 'th.col0', 'props': [('attribute', 'value')]} # 实际合并操作非常晦涩 ]) # 通常不推荐用Styler处理复杂合并6.2 批量写入与样式应用
对于场景A，如果数据量巨大，先用pandas的to_excel写入数据，再用openpyxl加载文件并应用合并格式，会快得多。
# 伪代码思路 # 1. 用pandas将df写入一个新的excel文件（或同一个文件的新sheet） with pd.ExcelWriter('temp_data.xlsx', engine='openpyxl') as writer: df.to_excel(writer, sheet_name='Data', index=False, startrow=2) # 从第3行开始写 # 2. 用openpyxl加载这个新文件 wb = load_workbook('temp_data.xlsx') ws_data = wb['Data'] # 3. 加载模板文件，获取其合并信息 wb_template = load_workbook('template.xlsx') ws_template = wb_template.active template_merges = list(ws_template.merged_cells.ranges) # 4. 将模板的合并信息应用到数据工作表（注意调整行偏移） for merge_range in template_merges: # 可能需要根据模板和数据表的起始行差异，调整合并区域的行坐标 # 例如，模板标题在1-2行，数据从第3行开始。我们写入数据时也从第3行开始。 # 那么合并区域可以直接应用。 ws_data.merged_cells.add(str(merge_range)) # 5. （可选）复制模板的样式到数据表对应区域 # 6. 保存 wb.save('final_report.xlsx')6.3 处理大型模板与内存优化
对于超大型的Excel文件，openpyxl默认的读取方式会加载所有内容到内存。可以使用read_only模式只读地获取合并信息，再用write_only模式写入数据，最后组合。但这需要更复杂的代码来协调只读和只写的工作表对象。对于绝大多数日常场景（几万行数据以内），前面的方法已经足够高效。
7. 常见问题排查（Q&A）
在实际操作中，你可能会遇到以下问题：
Q1：运行代码后，打开Excel文件提示“发现不可读取的内容”，或者合并单元格消失了？A1：这通常是因为文件损坏或保存格式问题。确保：
- 使用
wb.save(output_path)保存，而不是其他方式。 - 确保在保存前，所有对工作簿的修改（尤其是合并单元格操作）已完成。
- 尝试用
openpyxl重新打开保存的文件，检查合并信息list(ws.merged_cells.ranges)是否还在。
Q2：我想合并的单元格区域，写入数据后，只有左上角有值，其他单元格是空的，但合并还在，这正常吗？A2：这完全正常，也是Excel合并单元格的预期行为。如前所述，只有主单元格存储值。其他单元格物理上就是空的。在Excel界面中点击那些“空”单元格，编辑栏会显示主单元格的值。你的代码是正确的。
Q3：如何判断一个单元格是否属于某个合并区域，以及它是主单元格还是从属单元格？A3：使用ws.merged_cells的属性。
cell = ws[‘B2’] # 判断单元格是否在任意合并区域内 if cell.coordinate in ws.merged_cells: print(f“{cell.coordinate} 在合并区域内”) # 找到它所属的合并区域对象 for range_obj in ws.merged_cells.ranges: if cell.coordinate in range_obj: print(f“它属于合并区域 {range_obj}”) # 判断是否是左上角主单元格 if cell.coordinate == range_obj.min_row, range_obj.min_col: print(“它是主单元格”) else: print(“它是从属单元格”) breakQ4：除了按行合并，如何实现复杂的“多行多列”区域合并（比如合并一个矩阵作为标题）？A4：原理相同。你需要预先定义好这个矩阵的左上角坐标和右下角坐标。例如，要合并C5到F8这个区域，直接使用ws.merged_cells.add(‘C5:F8’)。然后只向C5单元格写入标题内容即可。关键在于提前规划好你的表格布局。
处理Excel合并单元格的自动化，是一个典型的“知其然，更要知其所以然”的任务。理解了合并单元格在程序眼中的本质是“一个主单元格+一串坐标定义”，就掌握了解决问题的钥匙。无论是填充现有模板，还是动态创建合并，核心逻辑都是精确计算和操作这些坐标。openpyxl提供了强大的底层API，而pandas则负责高效的数据处理，两者结合，便能应对绝大多数复杂的报表生成需求。在实际项目中，建议将填充和合并的逻辑封装成独立的函数或类，通过参数灵活控制模板路径、数据起始位置、合并规则等，这样就能构建出一个可复用的、强大的Excel报表自动化工具。
