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

一、环境准备

1.1 库安装

通过 pip 安装免费版本：

pip install spire.xls.free

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

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

1.2 核心概念

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

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

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

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

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

2.1 常规数值与小数位数

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

代码示例：

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

2.2 货币格式

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

代码示例：

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

2.3 百分比格式

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

代码示例：

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

2.4 日期与时间格式

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

代码示例：

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 科学计数法

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

2.6 分数格式

以分数形式显示小数。

2.7 条件颜色格式

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

代码示例：

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

2.8 自定义文本前缀/后缀

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

三、完整示例代码

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

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;"-";@

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

五、注意事项与常见问题

1. 数值类型必须正确

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

2. 格式代码区分区域设置

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

3. 日期序列值基准

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

4. 免费版限制

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

5. 格式继承与覆盖

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

六、总结

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