Python操作Excel批注：从基础添加到高级自定义的完整指南

如果你经常处理Excel数据，一定见过单元格右上角那个红色小三角------那就是批注（Comment）。批注在团队协作、数据审核、报表说明等场景下特别有用。但手动添加批注效率太低，特别是需要批量处理时。

今天分享一下如何用Python代码操作Excel批注，从最简单的添加文本到高级的富文本格式化、图片背景、位置控制等。

先说说批注的应用场景

在实际工作中，批注主要用在这些地方：

1. 数据审核：标注异常数据、说明计算逻辑
2. 团队协作：留下修改建议、讨论记录
3. 模板说明：解释字段含义、填写规范
4. 审计追踪：记录数据来源、处理过程
5. 可视化增强：用图片批注做品牌标识

理解了用途，才知道什么时候该用批注，什么时候该用其他方式（比如单独的说明Sheet）。

环境准备

在开始编写代码之前，需要先准备好 Python 环境并安装用于操作 Excel 文件的库。本文示例使用的是 Spire.XLS for Python，它可以在不依赖 Microsoft Excel 的情况下创建、读取、编辑和保存 Excel 文件，适合用于服务器端报表处理、批量数据审核和自动化办公场景。

1. 安装 Python 库

可以使用 pip 安装 Spire.XLS for Python：

pip install spire.xls

安装完成后，可以在 Python 脚本中导入相关类：

from spire.xls import Workbook, ExcelVersion

其中：

• Workbook 用于创建或加载 Excel 工作簿；
• ExcelVersion 用于指定保存文件时的 Excel 格式，例如 .xlsx；
• 在涉及颜色、文本旋转、对齐方式等高级设置时，还需要额外导入 Color、ExcelColors、TextRotationType 等类。

2. 准备测试文件

如果示例中使用的是新建工作簿，可以直接运行代码生成 Excel 文件；如果代码中调用了 LoadFromFile() 方法，则需要提前准备一个 Excel 文件，例如：

workbook.LoadFromFile("data.xlsx")

这表示程序会从当前脚本所在目录读取 data.xlsx。如果文件不在同一目录，需要改为完整路径，例如：

workbook.LoadFromFile(r"C:\Users\Administrator\Desktop\data.xlsx")

3. 关于输出文件格式

本文中的示例大多使用以下方式保存结果：

workbook.SaveToFile("output.xlsx", ExcelVersion.Version2013)

这里的 ExcelVersion.Version2013 表示将文件保存为较新的 .xlsx 格式，适合在 Microsoft Excel 2013 及以上版本中打开。如果你需要兼容更早版本，也可以根据实际需求选择其他 Excel 版本参数。

---

一、最基础的：添加批注

添加批注是操作 Excel 批注的基础。通常的流程是：先创建或加载一个工作簿，然后获取目标工作表和单元格，最后通过 AddComment() 方法为单元格添加批注对象。创建批注后，可以设置批注文本、显示状态、大小以及富文本格式。

下面先从最简单的文本批注开始。

1.1 简单文本批注

from spire.xls import Workbook, ExcelVersion

workbook = Workbook()
sheet = workbook.Worksheets[0]

# 在C1单元格添加批注
cell = sheet.Range["C1"]
comment = cell.AddComment()
comment.Text = "这是简单的批注内容"

# 默认批注是隐藏的，鼠标悬停才显示
# 如果想一直显示：
comment.Visible = True

workbook.SaveToFile("simple_comment.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

就这么简单。但实际项目中，我们通常需要更多控制。

1.2 带作者信息的批注

在团队协作或数据审核场景中，单纯写一句说明往往不够清晰。为了方便后续追踪，通常会在批注中加入作者、审核时间或处理状态等信息。Spire.XLS 不会强制批注必须包含作者字段，因此可以通过文本格式自行组织，例如使用"作者 + 换行 + 批注内容"的形式。

from spire.xls import Workbook, ExcelVersion

workbook = Workbook()
workbook.LoadFromFile("data.xlsx")
sheet = workbook.Worksheets[0]

# 获取要添加批注的单元格
cell = sheet.Range["C1"]

# 设置作者和内容
author = "张三"
text = "这个数据需要进一步核实"

comment = cell.AddComment()
comment.Width = 200
comment.Visible = True

# 格式：作者 + 换行 + 内容
comment.Text = f"{author}:\n{text}"

# 让作者名字加粗显示
font = workbook.CreateFont()
font.FontName = "Tahoma"
font.IsBold = True
comment.RichText.SetFont(0, len(author), font)

workbook.SaveToFile("comment_with_author.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

为什么要区分作者？ 多人协作时，一眼就能看出是谁留的言。

---

二、富文本批注：让内容更有层次

普通批注所有文字都一样，但有时候需要强调重点、区分不同部分。这时候用富文本。

当批注内容较长，或者需要突出"警告""已审核""待确认"等不同信息时，普通纯文本批注的可读性会比较有限。此时可以使用富文本批注，为批注中的不同文本片段设置不同字体、颜色、字号或加粗效果。

富文本批注的核心思路是：先设置完整的批注文本，再通过 RichText.SetFont() 方法为指定字符范围应用字体样式。

2.1 多颜色文本

下面的示例演示如何在同一个批注中使用多种颜色。实际开发中，这种方式常用于区分提示类型，例如用醒目的颜色标记"注意"或"警告"，再用较柔和的颜色显示具体说明。

from spire.xls import Workbook, ExcelVersion

workbook = Workbook()
workbook.LoadFromFile("template.xlsx")
sheet = workbook.Worksheets[0]

# 创建不同颜色的字体
font_orange = workbook.CreateFont()
font_orange.FontName = "Arial"
font_orange.Size = 11
font_orange.KnownColor = ExcelColors.Orange

font_blue = workbook.CreateFont()
font_blue.KnownColor = ExcelColors.LightBlue

font_green = workbook.CreateFont()
font_green.KnownColor = ExcelColors.LightGreen

# 添加批注并设置富文本
cell = sheet.Range["B12"]
comment = cell.Comment

comment.RichText.Text = "注意：此数据已审核通过"

# 前4个字用绿色（"注意："）
comment.RichText.SetFont(0, 4, font_green)

# 后面的字用蓝色
comment.RichText.SetFont(5, 12, font_blue)

workbook.SaveToFile("rich_text_comment.xlsx", ExcelVersion.Version2007)
workbook.Dispose()

实际效果：

• "注意："显示为绿色（警示作用）
• "此数据已审核通过"显示为蓝色（信息性内容）

2.2 复杂格式化示例

from spire.xls import Workbook, ExcelVersion, Color

workbook = Workbook()
sheet = workbook.Worksheets[0]

# 创建多种字体样式
font_title = workbook.CreateFont()
font_title.FontName = "Calibri"
font_title.Color = Color.get_Firebrick()  # 深红色
font_title.IsBold = True
font_title.Size = 12

font_body = workbook.CreateFont()
font_body.FontName = "Calibri"
font_body.Color = Color.get_Blue()
font_body.Size = 12

# 添加详细批注
cell = sheet.Range["G5"]
comment = cell.Comment
comment.IsVisible = True
comment.Height = 150
comment.Width = 300

comment.RichText.Text = "产品说明：\nSpire.XLS是一个独立的Excel组件，支持转换、数据处理、图表等功能。"

# 标题部分加粗红色
comment.RichText.SetFont(0, 4, font_title)

# 正文部分蓝色
comment.RichText.SetFont(5, 50, font_body)

workbook.SaveToFile("formatted_comment.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

适用场景：技术文档、产品说明、需要分层展示的信息。

---

三、读取和编辑现有批注

有时候需要读取已有批注进行分析，或者批量修改。

除了创建批注，在实际项目中也经常需要读取和修改已有批注。例如，审核完成后需要提取所有批注意见生成报告，或者根据新的业务规则批量更新批注内容。读取批注时，可以通过单元格的 Comment 属性获取批注对象；编辑批注时，则可以直接修改其 Text 或 RichText 内容。

3.1 读取批注内容

from spire.xls import Workbook

workbook = Workbook()
workbook.LoadFromFile("with_comments.xlsx")
sheet = workbook.Worksheets[0]

# 读取A1单元格的批注
comment_text = sheet.Range["A1"].Comment.Text
print(f"批注内容：{comment_text}")

# 如果批注有富文本，可以获取RTF格式
rich_text = sheet.Range["A2"].Comment.RichText.RtfText
print(f"富文本格式：{rich_text}")

workbook.Dispose()

应用场景：

• 提取所有批注生成审核报告
• 分析批注中的关键词
• 导出批注到数据库

3.2 批量读取所有批注

from spire.xls import Workbook

workbook = Workbook()
workbook.LoadFromFile("reviewed_data.xlsx")
sheet = workbook.Worksheets[0]

# 遍历所有有批注的单元格
comments_info = []

for row in range(1, sheet.AllocatedRange.RowCount + 1):
    for col in range(1, sheet.AllocatedRange.ColumnCount + 1):
        cell = sheet.Range[row, col]
        
        if cell.Comment is not None:
            info = {
                'cell': f"{chr(64+col)}{row}",  # 如 "A1"
                'author': cell.Comment.Text.split(':')[0] if ':' in cell.Comment.Text else '',
                'content': cell.Comment.Text,
                'visible': cell.Comment.Visible
            }
            comments_info.append(info)

# 输出所有批注信息
for info in comments_info:
    print(f"单元格 {info['cell']}: {info['content']}")

workbook.Dispose()

3.3 编辑批注

from spire.xls import Workbook, ExcelVersion

workbook = Workbook()
workbook.LoadFromFile("existing_comments.xlsx")
sheet = workbook.Worksheets[0]

# 方式1：直接修改第一个批注
comment = sheet.Comments[0]
comment.Text = "批注内容已更新 - 2024年审核"

# 方式2：修改特定单元格的批注
sheet.Range["B5"].Comment.Text = "数据已修正"

workbook.SaveToFile("updated_comments.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

---

四、删除批注

批注通常用于审核、说明或临时沟通。当文件进入最终发布、归档或对外分享阶段时，可能需要删除部分或全部批注，避免无关说明影响阅读，或者防止内部审核信息被外部用户看到。

删除批注可以通过批注集合 sheet.Comments 完成，也可以先定位到具体单元格，再删除该单元格上的批注。

清理不需要的批注：

from spire.xls import Workbook, ExcelVersion

workbook = Workbook()
workbook.LoadFromFile("with_comments.xlsx")
sheet = workbook.Worksheets[0]

# 方式1：删除特定批注
comments = sheet.Comments
if comments.Count > 0:
    comments[1].Remove()  # 删除第二个批注

# 方式2：删除所有批注
while sheet.Comments.Count > 0:
    sheet.Comments[0].Remove()

workbook.SaveToFile("no_comments.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

实际场景：

• 发布最终版前清理审核批注
• 归档时移除临时注释
• 根据条件批量删除（如只保留最近一个月的批注）

---

五、高级定制：让批注更专业

基础批注主要解决"能不能添加说明"的问题，而高级定制则更关注"批注是否易读、是否符合版式要求、是否适合报表展示"。在一些正式报表、模板文件或自动生成的审核文档中，可能需要控制批注的大小、位置、显示状态、背景图片和文字方向。

这些设置可以让批注不仅仅是简单备注，而成为报表说明和数据审核流程的一部分。

5.1 控制批注位置和大小

默认的批注位置可能不理想，可以精确控制：

from spire.xls import Workbook, ExcelVersion, CommentVAlignType, CommentHAlignType

workbook = Workbook()
sheet = workbook.Worksheets[0]

# 添加批注
cell = sheet.Range["G5"]
cell.Text = "查看批注"
comment = cell.Comment

comment.IsVisible = True
comment.Height = 150  # 高度
comment.Width = 300   # 宽度

# 设置绝对位置（相对于工作表左上角）
comment.Top = 20   # 距离顶部20像素
comment.Left = 40  # 距离左侧40像素

# 设置文本对齐方式
comment.VAlignment = CommentVAlignType.Center  # 垂直居中
comment.HAlignment = CommentHAlignType.Justified  # 水平两端对齐

comment.RichText.Text = "这是一个精确定位的批注，\n可以控制大小、位置和对齐方式。"

workbook.SaveToFile("positioned_comment.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

为什么要控制位置？

• 避免批注遮挡重要数据
• 多个批注时合理布局
• 打印时批注位置可预测

5.2 设置批注背景图片

除了文本样式，批注的外观也可以进一步定制。例如，在企业模板或品牌化报表中，可以将图片设置为批注背景，用于显示 Logo、提示图标或其他视觉标识。实现时需要先读取图片文件流，然后通过 comment.Fill.CustomPicture() 方法将图片应用到批注中。

想让批注更有品牌感？可以加背景图：

from spire.xls import Workbook, ExcelVersion
from System.IO import FileStream, FileMode

workbook = Workbook()
sheet = workbook.Worksheets[0]

# 在单元格添加文本
cell = sheet.Range["C6"]
cell.Text = "公司Logo"

# 添加批注
comment = cell.AddComment()

# 加载图片作为背景
image_stream = FileStream("logo.png", FileMode.Open)
comment.Fill.CustomPicture(image_stream, "logo.png")

comment.Visible = True

workbook.SaveToFile("comment_with_image.xlsx", ExcelVersion.Version2010)
workbook.Dispose()

应用场景：

• 企业模板中加入公司Logo
• 用图标区分不同类型的批注
• 品牌化的报表系统

5.3 批注文本旋转

from spire.xls import Workbook, ExcelVersion, TextRotationType

workbook = Workbook()
sheet = workbook.Worksheets[0]

cell = sheet.Range["D10"]
comment = cell.AddComment()

comment.Text = "这段文字可以旋转显示"
comment.TextRotation = TextRotationType.LeftToRight  # 从左到右

# 其他选项：
# TextRotationType.RightToLeft  # 从右到左
# TextRotationType.TopToBottom  # 从上到下

comment.Visible = True

workbook.SaveToFile("rotated_comment.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

适用场景：特殊排版需求、多语言文档、竖排文字。

5.4 显示/隐藏批注

from spire.xls import Workbook, ExcelVersion

workbook = Workbook()
workbook.LoadFromFile("with_comments.xlsx")
sheet = workbook.Worksheets[0]

# 显示所有批注
for comment in sheet.Comments:
    comment.Visible = True

# 或者只显示特定的批注
sheet.Range["A1"].Comment.Visible = True
sheet.Range["B2"].Comment.Visible = False  # 隐藏这个

workbook.SaveToFile("visibility_control.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

实际应用：

• 审核模式：显示所有批注
• 最终版：隐藏批注（但不删除，保留历史记录）
• 打印前：隐藏批注避免干扰

---

六、实战案例：自动化审核系统

前面的示例分别介绍了批注的添加、读取、编辑、删除和样式设置。接下来通过一个完整案例，把这些操作组合起来，模拟一个简单的数据审核流程：程序从 CSV 文件读取销售数据，将数据写入 Excel，并根据业务规则自动识别异常值，为异常单元格添加批注和背景色。

这个案例更接近真实项目中的使用方式，适合用于报表审核、数据质量检查、异常数据标记等场景。

最后来个完整的例子：从CSV导入数据，自动标记异常值并添加批注。

from spire.xls import Workbook, ExcelVersion, Color
import csv

def create_review_report(csv_file: str, output_file: str):
    """
    从CSV创建Excel报表，自动添加审核批注
    """
    
    workbook = Workbook()
    sheet = workbook.Worksheets[0]
    sheet.Name = "销售数据审核"
    
    # 创建字体样式
    font_warning = workbook.CreateFont()
    font_warning.Color = Color.get_Red()
    font_warning.IsBold = True
    
    font_info = workbook.CreateFont()
    font_info.Color = Color.get_Blue()
    
    # 读取CSV数据
    with open(csv_file, 'r', encoding='utf-8') as f:
        reader = csv.reader(f)
        headers = next(reader)
        
        # 写入表头
        for col, header in enumerate(headers, 1):
            sheet.Range[1, col].Value = header
        
        # 写入数据并检查异常
        row_num = 2
        for row in reader:
            for col, value in enumerate(row, 1):
                sheet.Range[row_num, col].Value = value
            
            # 假设第3列是销售额，检查异常值
            try:
                sales = float(row[2])
                
                # 销售额超过10000，添加警告批注
                if sales > 10000:
                    cell = sheet.Range[row_num, 3]
                    comment = cell.AddComment()
                    
                    comment.Text = f"警告：销售额 {sales:.2f} 超出正常范围\n请核实数据准确性"
                    comment.Width = 250
                    comment.Visible = True
                    
                    # 设置警告样式
                    comment.RichText.SetFont(0, 2, font_warning)
                    comment.RichText.SetFont(3, len(comment.Text), font_info)
                    
                    # 高亮单元格
                    cell.Style.Color = Color.get_LightYellow()
                    
            except (ValueError, IndexError):
                pass
            
            row_num += 1
    
    # 自动调整列宽
    sheet.AllocatedRange.AutoFitColumns()
    
    # 添加说明批注
    title_cell = sheet.Range["A1"]
    title_comment = title_cell.AddComment()
    title_comment.Text = "审核说明：\n- 红色批注：数据异常需核实\n- 黄色背景：已标记的高值\n- 请审核后移除此批注"
    title_comment.Width = 300
    title_comment.Height = 150
    title_comment.Visible = True
    
    workbook.SaveToFile(output_file, ExcelVersion.Version2013)
    workbook.Dispose()
    
    print(f"审核报表已生成：{output_file}")

# 使用示例
create_review_report("sales_data.csv", "sales_review.xlsx")

这个例子展示了：

• 自动检测：根据业务规则识别异常
• 智能批注：不同情况不同提示
• 视觉提示：颜色+批注双重标记
• 可追溯：保留审核痕迹

---

七、一些实用建议

1. 什么时候用批注，什么时候不用？

适合用批注：

• 临时性的审核意见
• 单元格级别的说明
• 需要隐藏/显示的注释

不适合用批注：

• 长篇大论的说明（用单独的Sheet）
• 永久性的重要信息（放在单元格或页眉页脚）
• 结构化数据（用额外的列）

2. 批注的性能考虑

• 大量批注（几百个以上）会影响文件打开速度
• 富文本批注比普通文本占用更多空间
• 图片背景的批注会显著增加文件大小

建议：

• 定期清理不需要的批注
• 发布最终版前移除审核批注
• 大量说明用单独的工作表

3. 批注的最佳实践

✅ 要做：

• 批注内容简洁明了
• 加上作者和时间戳
• 重要的批注设为可见
• 定期整理和清理

❌ 不要做：

• 用批注存储重要数据
• 批注内容过长（超过100字考虑其他方式）
• 忘记移除临时批注
• 批注中包含敏感信息（批注容易被忽略而泄露）

4. 批注 vs 其他方案对比

需求	推荐方案	原因
单元格说明	批注	不占用单元格空间
长篇文档	单独Sheet	更易阅读和管理
数据验证提示	数据验证功能	输入时即时提示
公式说明	命名范围+说明	更结构化
版本历史	单独的历史Sheet	便于追踪

---

八、常见问题

Q1: 如何批量导出所有批注？

A: 遍历所有单元格，提取批注内容保存到文本文件或数据库：

comments_export = []
for row in range(1, max_row + 1):
    for col in range(1, max_col + 1):
        cell = sheet.Range[row, col]
        if cell.Comment:
            comments_export.append({
                'location': f"{chr(64+col)}{row}",
                'text': cell.Comment.Text
            })

# 保存到CSV或数据库

Q2: 批注会影响打印吗？

A: 默认情况下，批注不会打印出来。如果需要打印批注：

• 在Excel中：页面布局 → 打印标题 → 批注设置为"工作表末尾"
• 用代码：需要设置页面设置（具体API取决于库的版本）

Q3: 能保护批注不被修改吗？

A: 可以保护工作表，但这样也会锁定单元格。更好的做法是：

• 完成审核后移除批注
• 或将批注内容复制到受保护的Sheet

---

总结

批注是个被低估的Excel功能。用得好，能大幅提升协作效率和数据质量。通过本文的例子，你应该掌握了：

1. 基础操作：添加、读取、编辑、删除批注
2. 富文本格式化：多颜色、多字体、分层展示
3. 高级定制：位置控制、背景图片、文本旋转
4. 自动化应用：批量处理、智能标记、审核系统
5. 最佳实践：何时用、怎么用、注意事项

核心原则：批注是用来辅助理解的，不是用来存储数据的。保持批注简洁、相关、及时清理，才能真正发挥它的价值。

希望这篇文章对你有帮助！如果有其他Excel自动化需求，欢迎交流讨论。