Open-XML-SDK 处理 Excel 注释的注意事项

背景介绍

在使用 Open-XML-SDK 处理 Excel 文件时，添加注释是一个常见的需求。许多开发者会遇到注释在代码中看似添加成功，但在实际打开 Excel 文件时却无法显示的问题。

核心问题分析

通过分析开发者提供的代码示例，我们可以发现几个关键问题点：

1. 缺少 VML 绘图部分：Excel 注释不仅需要 WorksheetCommentsPart，还需要对应的 VmlDrawingPart 来定义注释的视觉呈现。

2. 单元格未正确创建：注释必须关联到具体的单元格，如果 SheetData 中没有实际创建对应的单元格，注释将无法显示。

3. 过时的 API 使用：代码中使用了已被移除的 SpreadsheetDocument.Close() 方法，应当改用 Dispose() 方法。

解决方案

1. 完整注释创建流程

要正确创建 Excel 注释，需要以下几个步骤：

1. 创建 WorksheetCommentsPart 并设置注释内容
2. 创建 VmlDrawingPart 定义注释的视觉样式
3. 确保目标单元格已存在
4. 在 Worksheet 中建立关联关系

2. 现代 Excel 注释处理建议

对于较新版本的 Excel，推荐使用线程式注释(Threaded Comments)而非传统注释。线程式注释提供了更好的协作体验和更丰富的功能。

3. 资源管理最佳实践

使用 Open-XML-SDK 时，应当注意：

• 使用 using 语句或显式调用 Dispose() 来释放资源
• 避免直接调用已被弃用的 Close() 方法
• 确保所有部件都正确保存

实现示例

以下是创建传统注释的关键代码结构：

// 创建工作簿和基本结构
using (var spreadsheet = SpreadsheetDocument.Create(stream, SpreadsheetDocumentType.Workbook))
{
    // 添加工作簿部分
    WorkbookPart workbookPart = spreadsheet.AddWorkbookPart();
    
    // 创建工作表部分
    WorksheetPart worksheetPart = workbookPart.AddNewPart<WorksheetPart>();
    
    // 1. 创建并填充 WorksheetCommentsPart
    var commentsPart = worksheetPart.AddNewPart<WorksheetCommentsPart>();
    // 填充注释内容...
    
    // 2. 创建并关联 VmlDrawingPart
    var vmlDrawingPart = worksheetPart.AddNewPart<VmlDrawingPart>();
    // 定义VML绘图内容...
    
    // 3. 确保目标单元格存在
    var sheetData = new SheetData();
    // 添加单元格...
    
    // 4. 在工作表中建立关联
    worksheetPart.Worksheet = new Worksheet(
        new SheetData(),
        new LegacyDrawing { Id = worksheetPart.GetIdOfPart(vmlDrawingPart) }
    );
}

常见问题排查

1. 注释不显示：

   • 检查是否同时创建了 WorksheetCommentsPart 和 VmlDrawingPart
   • 确认目标单元格已正确创建
   • 验证关联关系是否正确建立

2. 文件损坏或无法打开：

   • 确保正确使用了资源释放模式
   • 检查所有部件的ID引用是否正确

3. 注释样式异常：

   • 检查VML绘图部分的定义是否完整
   • 验证字体、颜色等样式属性设置

总结

使用 Open-XML-SDK 处理 Excel 注释需要注意完整的创建流程和各部分之间的关联关系。现代 Excel 开发中，建议优先考虑线程式注释的实现方式。通过遵循正确的API使用方式和资源管理实践，可以避免大多数常见的注释显示问题。