如何在 xlwings 中正确读取受保护 Excel 工作表中的单元格批注

在使用 xlwings 处理密码保护的 Excel 文件时，很多人会踩的一个坑是：直接调用 range.note 去读取批注，结果返回 None，明明单元格里明明有批注，却死活读不出来。这其实不是 bug，而是 .note 这个属性本身就比较“浅”——它是 xlwings 封装的一个轻量级只读接口，不会穿透 Excel 的保护层。而真正的批注对象，藏得更深，需要通过底层的 COM 接口才能访问。

那该怎么办？核心思路是：绕过外层封装，直接调用 Excel 应用程序的原生 API。具体来说，就是使用 .api.Comment.Text() 方法。注意大小写和括号，它直接跟 Excel 的 COM 对象对话，只要工作簿已经用密码成功打开，就能正常读取，不受保护限制。下面是一个标准示例：

import xlwings as xw

PATH = r'C:/Users/Hendo/Pictures/Sample.xlsx'
psw = '1234'

wb = xw.Book(PATH, password=psw)
sheet = wb.sheets['Sheet1']

# ✅ 正确：通过 COM 接口读取批注文本
try:
    comment_text = sheet.range('H15').api.Comment.Text()
    print("批注内容:", comment_text)
except AttributeError:
    print("H15 单元格无批注")

print("单元格值:", sheet.range('H15').value)

有几个关键点需要留意：

• 这个方法只适用于 Windows 系统 + Excel 桌面版，因为依赖 COM 接口。
• 确保 Excel 已安装，并且 xlwings 的后端是默认的 app。
• 如果单元格没有批注，.api.Comment 会直接抛出 AttributeError，所以必须用 try/except 兜底。
• 默认返回的是纯文本内容。如果你还需要作者、时间等元信息，可以访问 cmt.Author、cmt.Date 等属性，下面批量方案里有具体写法。

如果你需要一次性提取全工作簿所有批注，包括位置、作者和内容，可以参考这个批量遍历的版本：

import xlwings as xw

excel_file = r'C:/Users/Hendo/Pictures/Sample.xlsx'

with xw.App(visible=False) as app:
    wb = xw.Book(excel_file, password='1234')  # ⚠️ 密码必须传入此处！

    for sheet in wb.sheets:
        print(f"---- 工作表 '{sheet.name}' ----")

        # 检查该表是否存在批注
        if sheet.api.Comments.Count > 0:
            for cmt in sheet.api.Comments:
                addr = cmt.Parent.Address.replace('$', '')  # 如 'H15'
                try:
                    text = cmt.Text()
                    author = cmt.Author
                    print(f"? 单元格: {addr}")
                    print(f"? 作者: {author}")
                    print(f"? 内容: {text}")
                    print("-" * 40)
                except Exception as e:
                    print(f"[警告] 读取 {addr} 批注失败: {e}")
        else:
            print("→ 本工作表无批注")

    wb.close()

总结下来，就几条核心原则：

• ❌ 别用 range.note 处理受保护工作表的批注，它拿不到数据。
• ✅ 坚持走 .api.Comment.Text() 路线，并配合异常处理。
• ? 密码必须在 xw.Book(..., password=...) 中传入，否则 API 调用会失败。
• ? 批量处理时，建议关闭 visible=True，并显式调用 close() 关闭工作簿，避免后台 Excel 进程残留。