本文详解如何在使用 xlsxwriter 创建带格式化表头的 Excel 表格时，正确应用 rotation: -90 实现列标题垂直显示，避免因混用 to_excel() 与 add_table() 导致文件损坏或格式失效。
本文详解如何在使用 `xlsxwriter` 创建带格式化表头的 excel 表格时，正确应用 `rotation: -90` 实现列标题垂直显示，避免因混用 `to_excel()` 与 `add_table()` 导致文件损坏或格式失效。
在使用 pandas.ExcelWriter 配合 xlsxwriter 引擎导出大型表格（如 40 行 × 69 列）时，常因列宽受限（如设为 width=5）导致长文本表头严重换行或截断。此时将表头文字顺时针旋转 90°（即 rotation=-90）是提升可读性的常用方案。但直接调用 worksheet.write() 修改已由 df.to_excel() 自动生成的表头，极易引发 Excel 文件结构冲突——表现为打开时提示“已损坏，尝试修复”，且原始标题被重置为默认名（如 Column1）。
根本原因在于：pandas.DataFrame.to_excel() 与 xlsxwriter.Worksheet.add_table() 是两种互斥的写入机制。前者生成普通单元格区域，后者创建结构化 Excel 表（支持筛选、样式带状等），二者混合操作会破坏 .xlsx 的内部 XML 结构。官方文档明确指出：若使用 add_table()，应完全绕过 to_excel()，改用 data.values.tolist() 手动传入数据。
✅ 正确做法是：
- 完全弃用
df.to_excel()； - 使用
worksheet.add_table()并显式指定"data"字段； - 在
"columns"列表中为特定列（尤其是长文本列）单独配置"header_format"，而非全局设置； - 注意列索引顺序必须与
data.columns严格一致。
以下是经过验证的完整示例：
Excel XLSX Formula Cleanup
下载
诊断并修复涉及公式、命名范围、Power Query 刷新、数据透视表、VBA/宏保存等问题的 Microsoft Excel XLSX 工作簿
import pandas as pd
data = pd.DataFrame(
[[1, 2], [3, 4]],
columns=["short", "Veeeeeeeeeeeeeeeeeeeeeeeeery long"]
)
with pd.ExcelWriter("rotated_headers.xlsx", engine="xlsxwriter") as writer:
workbook = writer.book
# 定义垂直旋转格式：-90° 表示顺时针转90°（文字从上到下）
rotate_format = workbook.add_format({
"rotation": -90,
"valign": "bottom", # 垂直对齐底部，避免文字悬浮
"text_wrap": False, # 禁用自动换行，确保旋转后紧凑显示
})
worksheet = workbook.add_worksheet("Data")
rows, cols = data.shape # 注意：shape 返回 (行数, 列数)，非 (列数, 行数)
# 构建列配置 —— 每列可独立设置 header 和 header_format
column_settings = [
{"header": "short"},
{
"header": "Veeeeeeeeeeeeeeeeeeeeeeeeery long",
"header_format": rotate_format
}
]
# 关键：显式传入 data.values.tolist()，禁用 to_excel()
worksheet.add_table(
0, 0, # 起始位置：A1（第0行，第0列）
rows, cols - 1, # 结束位置：含数据共 rows+1 行（含表头）、cols 列
{
"data": data.values.tolist(),
"columns": column_settings,
"banded_rows": True,
"autofilter": True, # 可选：启用自动筛选
}
)
? 注意事项：
-
rotation=-90是唯一可靠实现“纵向文字”的方式；rotation=90为逆时针，视觉效果不同；rotation=270等效于-90，但建议统一用-90。 - 必须配合
valign="bottom"，否则旋转后文字可能贴顶显示，影响阅读。 - 不要同时调用
data.to_excel(writer, ...)和add_table()，否则必然触发 Excel 修复警告。 - 若需保留索引列，需手动将其加入
data.reset_index().values.tolist()并同步扩展column_settings。 - 表格区域起止坐标需精确计算：
add_table(first_row, first_col, last_row, last_col, ...)中last_row = len(data)（不含表头），因表头占第 0 行，数据从第 1 行开始。
该方案不仅解决表头旋转问题，还为后续添加公式、条件格式、自定义列宽等高级功能提供稳定基础。
