Python 写入 XLSX 文件:创建、DataFrame 导出与安全追加
Python 写入 XLSX 文件:创建、DataFrame 导出与安全追加
把一段数据变成一份 XLSX 文件,Python 里通常分三步:建工作簿、写单元格、保存。真正需要花心思的是这三步之外的细节:数据来源是几个字面量、一张 DataFrame 还是一份已有报表;单元格要不要带类型和格式;文件是新建的,还是要在原表后面继续追加。不同场景对应的写法并不一样。
本文按场景给出可运行的示例:先用 openpyxl 和 Spire.XLS for Python 各写一个最小文件,再把 pandas DataFrame 以两种方式导出,接着演示文本、数字、日期、公式等类型的写入,然后处理最容易出错的追加场景,最后补上基础格式和多工作表。所有代码在发布前实际运行并核对过输出,示例基于 Spire.XLS for Python 16.8.2 与 pandas 3.1.1。
Spire.XLS for Python 是一套独立处理工作簿的 API:除创建和编辑外,内置公式计算引擎,支持把工作簿转换为 PDF、HTML 和图片,并可读写 XLS、XLSX、XLSB、XLSM、ODS 等格式,全程不需要安装 Microsoft Excel。本文聚焦写入部分;当任务从生成一个文件扩展成一条处理流水线时,用的就是同一套 API。
快速导航
1. 快速上手创建 XLSX 文件
先安装用到的库,按需取用即可,pip 对大小写不敏感:
1 | pip install Spire.XLS # Spire.XLS 示例使用 |
用 Spire.XLS 写入
1 | from spire.xls import Workbook, ExcelVersion |
这段代码有两个值得留意的细节。新建的 Workbook() 默认带三张空表(Sheet1 到 Sheet3),示例先清掉再添加一张”产品”表,保存出来的文件里就只有实际写入的内容。值通过带类型的属性写入:字符串用 Text,数字用 NumberValue。这种显式赋值让单元格类型完全可控,适合构建混合数据类型的报表。SaveToFile 按指定格式落盘,Dispose 释放工作簿占用的资源,长时间运行的脚本记得调用。
用 openpyxl 写入
1 | from openpyxl import Workbook |
Workbook() 建好的文件自带一张活动表。给 ws["A1"] 赋值即写入,openpyxl 会根据 Python 值推断单元格类型:字符串落成文本,29.9 落成数字。wb.save 负责写文件。本文示例统一输出到脚本同级的 output/ 目录,运行前先建好这个目录,或者改成自己的路径。
2. 把 pandas DataFrame 导出为 XLSX 文件
多数 XLSX 文件的数据源头是一张 pandas DataFrame。导出有两条路,对应不同的后续工作。
方案 A:让 pandas 直接写文件
1 | import pandas as pd |
index=False 去掉行号列,表头从第一行开始;ExcelWriter 的 datetime_format 把日期列统一成 YYYY-MM-DD 显示。类型在写入过程中保持不变:整数、浮点数、日期、布尔值各归其位,None 和 NaN 落成空单元格。两个显示上的坑也一并处理:pandas 默认把日期写成”日期 + 时间”共 19 个字符,窄列里只会显示 ###;列宽也是默认值。示例用 datetime_format 和三行列宽代码解决。
1 | summary = df[["姓名", "分数"]].groupby("姓名", as_index=False).min() |
方案 B:把 DataFrame 交给 Spire.XLS 写入
文件只需要存在时,方案 A 到此为止。后续还要改单元格、设样式、算公式,或者把工作簿转成 PDF,Spire.XLS 可以用同一套 API 接着做。pandas 的写入引擎只支持 openpyxl 和 XlsxWriter,所以这里先桥接:df.values.tolist() 把 DataFrame 转成 Python 数据的嵌套列表,再交给 Spire.XLS 逐格写入。示例沿用方案 A 定义的 df:
1 | from datetime import datetime |
内层循环是一个小型类型分派器,分支顺序是刻意的。bool 要写在 int 前面,因为 Python 里 bool 是 int 的子类,否则 True 会写成数字 1。pd.Timestamp 继承自 datetime,日期列会走进这个分支,经 DateTime.Parse 写入并附带 NumberFormat,Excel 里看到的是日期而不是序列号。pd.isna 覆盖 pandas 的全部缺失值标记,包括 None、NaN、pd.NA 和 pd.NaT,命中的单元格留空。整数、浮点数和布尔值在文件里保持原类型。示例处理的是常见标量值,其他 pandas 数据类型需要补充对应的转换。
更多导出场景和参数说明,见官方教程在 Python 中将 Pandas DataFrame 导出到 Excel。
3. 向单元格写入不同类型的数据
数据是零散的几个值而不是一张表时,直接写单元格。赋给哪个属性决定单元格的类型,这是两个库日常使用中差别最大的地方。下面两段代码各自独立,先建工作簿,再写单元格,最后保存。
Spire.XLS:
1 | from spire.xls import Workbook, ExcelVersion, DateTime |
openpyxl:
1 | from datetime import datetime |
Spire.XLS 按类型使用专用属性:字符串用 Text,数字用 NumberValue,日期用 DateTimeValue,布尔值用 BooleanValue,公式用 Formula。openpyxl 则根据赋的 Python 值自动推断。NumberFormat 控制显示格式,示例里数字用 #,##0.00,日期用 yyyy-mm-dd。
日期有一个容易浪费时间的细节:DateTimeValue 接收 Spire 的 DateTime 对象而不是 Python 的 datetime。把它和 Workbook 类一起导入(from spire.xls import DateTime),用 DateTime.Parse("2026-11-19 15:30:00") 或 DateTime.get_Now() 构造;DateTime(年, 月, 日) 这种构造形式在这个包里不可用。
公式方面,两个库写入的都是公式表达式本身。写公式和算公式是两回事:Excel 打开文件时会按自动计算得到结果,openpyxl 自身不做计算。Spire.XLS 可以算,保存前调用 wb.CalculateAllValue(),计算结果随文件一起落盘,openpyxl 以 data_only=True 读取时能直接拿到值,不必打开 Excel。
添加超链接(Spire.XLS):
1 | from spire.xls import Workbook, ExcelVersion |
二维列表写入时,openpyxl 有捷径:ws.append(row) 一次写一行。Spire.XLS 则按行循环,套用 DataFrame 示例里的类型分派逻辑,把每个值赋给 sheet.Range[row, col]。列表与字典的各种转换形态,在将 Python 列表转换为 Excel 表格(3 种实用场景)一文中有专门讲解。
4. 向已有文件追加数据
追加是最容易出错的操作,原因是一个共同盲区:openpyxl 的 ws.max_row 和 Spire.XLS 的 sheet.LastRow 都按”已分配单元格”计数,只设过格式但没有内容的行同样计入。一张数据到第 2 行、格式刷到第 9 行的表,两个属性都会返回 9。直接往 max_row + 1 写,新记录会落到离表格七行远的空白区里。
两个库的解法一致:选一列作为记录的标志位,比如订单号或时间戳,从表头往下扫描,找到最后一个非空单元格,从它的下一行开始写。下面两段示例都这样做,并且兼容记录之间出现空行的情况。
Spire.XLS 动态追加(源文件中含格式行与空行,已实测):
1 | from datetime import datetime |
函数接收源路径、目标路径和新行。它从第 2 行开始扫描关键列,第 1 行视为表头;AllocatedRange.LastRow 因为包含格式行,只用作扫描上界。遇到关键列为空会继续向下确认,数据可能在空档之后恢复。新行从 last_data_row + 1 写入,None 留空,字符串经 str() 转换,其余值按类型分派到 BooleanValue、NumberValue、DateTimeValue 或 Text。函数返回新的末行行号。只有表头没有记录的空表,第一条记录落在第 2 行。
openpyxl 同思路的实现(已实测):
1 | from openpyxl import load_workbook |
同样按第 1 列扫描,max_row 限定循环范围,只有真正有内容的单元格才更新 last,判断条件与 Spire.XLS 版本一致。两个示例都把 1005、陈晨、77.7 写到现有数据的下一行,各自保存到独立的输出文件。
pandas 的 mode="a" 实际做什么。 pd.ExcelWriter(path, mode="a", engine="openpyxl", if_sheet_exists=...) 并不会把行追加到表尾,引擎读取现有工作簿后整体重写。"overlay" 保留同名工作表,新 DataFrame 从左上角第一行开始写入;由于 to_excel() 默认带表头,表头和前几行会被覆盖。"replace" 先清空同名工作表再写入。引擎不支持的内容(如图表)会在这个过程中丢失。要在现有数据下方加记录,上面按关键列扫描的方式才可靠。
5. 写入时设置格式与管理多个工作表
一份报表通常需要这几样:加粗表头、数字格式、合适的列宽,再加一张汇总表。两个库都能覆盖,下面的示例从零构建一份小报表,可独立运行。
Spire.XLS:
1 | from spire.xls import Workbook, ExcelVersion, Color, HorizontalAlignType |
表头区域 A1:B1 一次赋值完成样式设置,金额单元格使用货币 NumberFormat。AllocatedRange.AutoFitColumns() 一次调整所有已用列的宽度;工作表级的 AutoFitColumn() 一次只调一列,需要单独控制某列时用它。当格式规则要跟随单元格的值自动变化时,就是条件格式的领域,参见使用 Python 设置 Excel 格式:从基础到专业应用。
openpyxl:
1 | from openpyxl import Workbook |
openpyxl 侧对应地在单元格上设置字体和填充,number_format 控制显示,create_sheet 添加汇总表,与 Spire.XLS 的 wb.Worksheets.Add("汇总") 一一对应。
6. 常见问题
怎么把 pandas DataFrame 导出为 XLSX 文件?
单表用 df.to_excel("文件.xlsx", index=False);导出多张工作表时把多次 to_excel 放进同一个 pd.ExcelWriter 上下文。导出之后还要设置格式、计算公式或转 PDF 的,用 df.values.tolist() 转成 Python 数据后交给 Spire.XLS 写入,见第 2 节方案 B。pandas 的写入引擎只有 openpyxl 和 XlsxWriter,不存在 engine="spire" 这种用法。
追加数据会覆盖原有内容吗?
写固定单元格(如 Range["A5"])会覆盖该单元格的现有内容。按关键列扫描定位最后一条记录、从下一行写入的方式不会覆盖,第 4 节的两个示例都是这种实现。另外 pandas 的 mode="a" 配合 if_sheet_exists="overlay" 会从工作表左上角开始覆写,表头行也在覆盖范围内。
Python 列表怎么写进 XLSX 文件?
openpyxl 每行调用一次 ws.append(row);Spire.XLS 逐格赋值,走带类型的属性。字典列表等更复杂的列表形态,见第 3 节链接的列表转换专题。
写入公式后读文件取不到值,为什么?
两个库写入的都是公式表达式,Excel 打开文件时才会计算。Spire.XLS 默认保存的公式不带缓存值:保存前调用 wb.CalculateAllValue(),openpyxl 用 data_only=True 读取时就能拿到计算结果。
一个 XLSX 文件里怎么写多个工作表?
openpyxl 用 wb.create_sheet("汇总");Spire.XLS 用 wb.Worksheets.Add("汇总"),新建的工作簿记得先用 wb.Worksheets.Clear() 清掉默认的三张空表;pandas 在同一个 ExcelWriter 上下文里用不同的 sheet_name 多次写入。
7. 总结
写 XLSX 文件是一组可复用的动作:建工作簿、写带类型的值、保存;文件已存在时,先找到最后一条记录再动笔。本文覆盖了这些动作最常见的变体,也把默认空表、公式缓存值、格式行撑大 max_row 这几个容易踩的坑落到了代码里。生成的报表需要导出为 PDF 或图片时,同一套 Spire.XLS API 可以直接完成。如需在无功能限制的环境下运行本文全部示例,可申请临时许可证。
















