如何用python-docx保留格式导出含ABC/XYZ表头的DataFrame至Word表格

要还原你提供的DataFrame格式，核心是利用python-docx的单元格合并功能（merge()方法）来实现多层表头的布局。以下是具体实现步骤和代码：

1. 明确表格结构 #

你的DataFrame是行索引+多层列表头的结构：

• 左上角的ABC是行索引列的跨行表头
• 右上角的XYZ是右侧数据列的跨行表头
• 下方的2010/2011/2012/3 YEARS是子表头

对应的Word表格需要创建数据行数+2行（2行表头）、数据列数+1列（包含行索引列）。

2. 完整代码实现 #

from docx import Document
from docx.enum.text import WD_ALIGN_PARAGRAPH
import pandas as pd

# 构造你的DataFrame（已有DataFrame可跳过此步）
data = {
    ('ABC', '2010'): ['A', 'B', 'C', 'D', 'E'],
    ('ABC', '2011'): ['A', 'B', 'C', 'D', 'E'],
    ('ABC', '2012'): ['A', 'B', 'C', 'D', 'E'],
    ('XYZ', '3 YEARS'): ['A', 'B', 'C', 'D', 'E']
}
df = pd.DataFrame(data, index=['ROW1', 'ROW2', 'ROW3', 'ROW4', 'ROW5'])

# 创建Word文档
doc = Document()

# 添加表格：行数=数据行+2层表头，列数=数据列+行索引列
table = doc.add_table(rows=df.shape[0]+2, cols=df.shape[1]+1)
table.style = 'Table Grid'  # 启用表格边框

# --- 处理顶层表头（ABC和XYZ）---
# 合并左上角单元格放置ABC（跨行合并第1-2行的第1列）
abc_cell = table.rows[0].cells[0]
abc_cell.merge(table.rows[1].cells[0])
abc_cell.text = 'ABC'
abc_cell.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER  # 居中对齐

# 合并右上角单元格放置XYZ（跨行合并第1-2行的第5列）
xyz_cell = table.rows[0].cells[4]
xyz_cell.merge(table.rows[1].cells[4])
xyz_cell.text = 'XYZ'
xyz_cell.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER

# --- 处理子表头（2010/2011/2012）---
sub_hdr_cells = table.rows[1].cells
sub_hdr_cells[1].text = '2010'
sub_hdr_cells[2].text = '2011'
sub_hdr_cells[3].text = '2012'

# 子表头居中对齐
for cell in sub_hdr_cells[1:4]:
    cell.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER

# --- 填充行索引和数据内容 ---
for row_idx, (df_idx, df_row) in enumerate(df.iterrows(), start=2):
    table_cells = table.rows[row_idx].cells
    # 填充行索引（ROW1-ROW5）
    table_cells[0].text = df_idx
    table_cells[0].paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER
    # 填充数据列
    for col_idx, val in enumerate(df_row.values, start=1):
        table_cells[col_idx].text = str(val)
        table_cells[col_idx].paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER

# 保存文档
doc.save('formatted_table.docx')

关键说明 #

• 单元格合并：通过cell.merge(target_cell)实现跨列/跨行合并，完美对应DataFrame的表头层级
• 对齐设置：用WD_ALIGN_PARAGRAPH.CENTER让所有内容居中，还原原DataFrame的排版
• 表格样式：Table Grid样式自动添加边框，让表格结构更清晰

内容的提问来源于stack exchange，提问作者ImNotSureAboutStats