如何使用 Python 设置 Excel 单元格数字格式

在自动化报表生成与数据处理场景中，数值的展示方式直接影响文档的可读性与专业性。千分位分隔、货币符号、百分比显示、日期格式化等效果，均通过 Excel 的数字格式机制实现。本文将介绍如何通过 Python 代码精确控制 Excel 单元格的数字显示格式，示例基于 Free Spire.XLS for Python 免费库实现。

一、环境准备

1.1 库安装

通过 pip 安装免费版本：

bash 复制代码

pip install spire.xls.free

安装完成后，在 Python 脚本中导入相关模块即可使用：

python 复制代码

from spire.xls import *
from spire.xls.common import *

1.2 核心概念

Excel 的数字格式作用于数值型数据 ，仅改变显示外观，不改变单元格的实际存储值。设置格式涉及两个核心属性：

NumberValue ：写入单元格的原始数值（必须为数值类型）
NumberFormat ：格式代码字符串，定义数值的显示规则

注意：若通过 Text 属性写入数字字符串，数字格式将不会生效。必须使用 NumberValue 赋值，才能保证格式正确应用。

二、常用数字格式分类与代码

Excel 数字格式代码遵循四段式结构：正数格式;负数格式;零值格式;文本格式，各段用分号分隔。实际使用中可根据需求省略部分段落。以下分类介绍高频场景。

2.1 常规数值与小数位数

控制小数点后的保留位数，以及是否显示千分位分隔符。

格式代码	原始值	显示效果	说明
`0`	1234.56	1235	整数，四舍五入
`0.00`	1234.5	1234.50	固定两位小数
`#,##0`	1234567	1,234,567	千分位分隔，无小数
`#,##0.00`	1234.567	1,234.57	千分位 + 两位小数

代码示例：

python 复制代码

sheet.Range["D2"].NumberValue = 1234567.89
sheet.Range["D2"].NumberFormat = "#,##0.00"

2.2 货币格式

在数值前添加货币符号，通常配合千分位与小数位使用。

格式代码	显示效果
`¥#,##0.00`	¥1,234.56
`$#,##0.00`	$1,234.56
`€ #,##0.00`	€ 1,234.56

代码示例：

python 复制代码

sheet.Range["D4"].NumberValue = 9999.99
sheet.Range["D4"].NumberFormat = "¥#,##0.00"

2.3 百分比格式

将小数乘以 100 后以百分比形式展示。

格式代码	原始值	显示效果
`0%`	0.123	12%
`0.00%`	0.12345	12.35%

代码示例：

python 复制代码

sheet.Range["D6"].NumberValue = 0.12345
sheet.Range["D6"].NumberFormat = "0.00%"

2.4 日期与时间格式

Excel 内部以序列值存储日期（1900-01-01 对应数值 1），通过格式代码转换为可读日期。

格式代码	原始值	显示效果
`yyyy-mm-dd`	45566	2024-10-01
`yyyy年m月d日`	45566	2024年10月1日
`m/d/yyyy`	45566	10/1/2024
`hh:mm:ss`	0.625	15:00:00
`h:mm AM/PM`	0.625	3:00 PM
`yyyy-mm-dd hh:mm`	45566.625	2024-10-01 15:00

代码示例：

python 复制代码

sheet.Range["D8"].NumberValue = 45566
sheet.Range["D8"].NumberFormat = "yyyy-mm-dd"
`sheet.Range[`"D9"`].NumberValue = `0.625
`
sheet.Range[`"D9"`].NumberFormat = `"hh:mm:ss"
`
`

2.5 科学计数法

适用于极大或极小数值的紧凑展示。

格式代码	原始值	显示效果
`0.00E+00`	1234567	1.23E+06
`0.00E-00`	0.0000123	1.23E-05

2.6 分数格式

以分数形式显示小数。

格式代码	原始值	显示效果
`# ?/?`	0.75	3/4
`# ??/??`	0.333	1/3

2.7 条件颜色格式

根据数值正负自动显示不同颜色，方括号内指定颜色名称。

格式代码	原始值	显示效果
`[Green]#,##0;[Red]-#,##0`	正数绿色，负数红色
`[Red]#,##0.00`	全部显示为红色

代码示例：

python 复制代码

sheet.Range["D12"].NumberValue = -1234.56
sheet.Range["D12"].NumberFormat = "[Green]#,##0.00;[Red]-#,##0.00"

2.8 自定义文本前缀/后缀

在数值前后附加固定文本，同时保持数值可计算性。文本需用双引号包裹。

格式代码	原始值	显示效果
`"合计："#,##0" 元"`	5000	合计：5,000 元
`0" 件"`	120	120 件

三、完整示例代码

以下示例在同一张工作表中集中演示多种数字格式效果：

python 复制代码

from spire.xls import *
from spire.xls.common import *

# 创建工作簿

workbook = Workbook()

sheet = workbook.Worksheets.get_Item(0)

sheet.Name = "数字格式示例"


# 设置列宽

sheet.SetColumnWidth(2, 22)

sheet.SetColumnWidth(3, 15)

sheet.SetColumnWidth(4, 20)


# 表头

sheet.Range["B2"].Text = "格式说明"

sheet.Range["C2"].Text = "原始值"

sheet.Range["D2"].Text = "显示结果"

header_style = sheet.Range["B2:D2"].Style

header_style.Font.IsBold = True

header_style.HorizontalAlignment = HorizontalAlignType.Center


# 示例数据与格式

examples = [

("两位小数", 1234.567, "0.00"),

("千分位分隔", 1234567.89, "#,##0.00"),

("人民币货币", 9999.99, "¥#,##0.00"),

("美元货币", 9999.99, "$#,##0.00"),

("百分比两位", 0.12345, "0.00%"),

("日期格式", 45566, "yyyy-mm-dd"),

("时间格式", 0.625, "hh:mm:ss"),

("科学计数法", 1234567, "0.00E+00"),

("正负分色", -1234.56, "[Green]#,##0.00;[Red]-#,##0.00"),

("文本前缀", 5000, '"合计："#,##0" 元"'),

]


# 逐行写入

for i, (desc, value, fmt) in enumerate(examples, start=3):

sheet.Range[f"B{i}"].Text = desc

sheet.Range[f"C{i}"].NumberValue = value

sheet.Range[f"C{i}"].NumberFormat = "General"

sheet.Range[f"D{i}"].NumberValue = value

sheet.Range[f"D{i}"].NumberFormat = fmt


# 自动调整列宽

sheet.AllocatedRange.AutoFitColumns()

# 保存文件
`
workbook.SaveToFile(`"number_format_demo.xlsx"`, ExcelVersion.Version2016)`
`
workbook.Dispose()`
`
`

运行后将生成 number_format_demo.xlsx 文件，C 列为原始通用格式数值，D 列为应用格式后的显示效果。

四、格式代码语法规则

4.1 占位符含义

0 ：数字占位符。若对应位无数字则显示 0，强制补位。
# ：数字占位符。若对应位无数字则不显示，不补零。
? ：数字占位符。用于对齐分数的小数点。
. ：小数点位置标记。
, ：千分位分隔符，或数值缩放（末尾逗号表示除以 1000）。

4.2 分段规则

格式代码最多分为四段，以分号分隔：

复制代码

正数格式;负数格式;零值格式;文本格式

只写一段：应用于所有数值
写两段：第一段用于正数和零，第二段用于负数
写三段：分别对应正、负、零
写四段：增加文本格式规则

示例：#,##0.00;[Red]-#,##0.00;"-";@

含义：正数正常显示千分位两位小数；负数红色并带负号；零值显示为短横线；文本保持原样。

五、注意事项与常见问题

数值类型必须正确

只有通过 NumberValue 写入的数值才能应用数字格式。若使用 Text 属性写入字符串形式的数字，格式代码不会生效。
格式代码区分区域设置

部分格式符号（如千分位、日期分隔符）受系统区域设置影响。跨地区使用时建议采用标准格式代码。
日期序列值基准

Excel 默认以 1900-01-01 为序列值 1。设置日期格式前需确认数值对应的日期是否正确。
免费版限制

Free 版本存在工作表数量与行数限制，适用于小型文件处理场景。大规模数据处理需评估是否满足业务需求。
格式继承与覆盖

单元格级别的 NumberFormat 设置会覆盖列或行级别的默认格式。批量设置时，可对整个 Range 统一赋值以提升效率。

六、总结

通过 NumberFormat 属性配合格式代码，可以在 Python 中精确控制 Excel 单元格的数值显示效果。掌握常用格式代码与分段规则后，即可实现货币、百分比、日期、条件颜色等多种专业展示效果，满足报表自动化的各类排版需求。在实际项目中，建议将常用格式封装为常量或配置项，以提升代码的可维护性与复用性。