Open-XML-SDK 处理 Excel 注释的完整指南

前言

在使用 Open-XML-SDK 处理 Excel 文件时，添加注释是一个常见但容易出错的功能。许多开发者会遇到注释在代码中创建了但在 Excel 中不显示的问题。本文将深入解析如何正确使用 Open-XML-SDK 为 Excel 单元格添加注释。

核心问题分析

在 Open-XML-SDK 中创建 Excel 注释时，开发者常犯的错误包括：

1. 仅创建了注释部分(WorksheetCommentsPart)而忽略了必要的 VML 绘图部分
2. 没有正确初始化工作表数据(SheetData)
3. 使用了过时的 API 方法(如 Close() 而非 Dispose())
4. 没有为注释关联实际的单元格

完整解决方案

1. 基础结构搭建

首先需要创建基本的 Excel 文档结构：

using (MemoryStream memoryStream = new MemoryStream())
{
    using (SpreadsheetDocument spreadsheet = SpreadsheetDocument.Create(memoryStream, SpreadsheetDocumentType.Workbook))
    {
        WorkbookPart workbookPart = spreadsheet.AddWorkbookPart();
        workbookPart.Workbook = new Workbook();
        
        // 创建工作表部分
        WorksheetPart worksheetPart = workbookPart.AddNewPart<WorksheetPart>();
        worksheetPart.Worksheet = new Worksheet(new SheetData());
        
        // 添加工作表引用
        workbookPart.Workbook.AppendChild(new Sheets());
        workbookPart.Workbook.GetFirstChild<Sheets>().AppendChild(
            new Sheet() { Id = workbookPart.GetIdOfPart(worksheetPart), SheetId = 1, Name = "测试工作表" });
    }
}

2. 添加注释的正确方式

完整的注释添加需要三个关键部分：

1. WorksheetCommentsPart - 存储注释内容
2. VmlDrawingPart - 处理注释的视觉呈现
3. 实际单元格数据 - 注释必须关联到存在的单元格

// 添加注释部分
WorksheetCommentsPart commentsPart = worksheetPart.AddNewPart<WorksheetCommentsPart>();
commentsPart.Comments = CreateComments();

// 添加VML绘图部分
VmlDrawingPart vmlDrawingPart = worksheetPart.AddNewPart<VmlDrawingPart>();
vmlDrawingPart.AddPart(commentsPart);
GenerateVmlDrawingPart(vmlDrawingPart);

// 在工作表中引用VML绘图
worksheetPart.Worksheet.Append(
    new LegacyDrawing() { Id = worksheetPart.GetIdOfPart(vmlDrawingPart) });

3. 创建注释内容

注释内容需要包含作者信息和具体的注释列表：

private static Comments CreateComments()
{
    Comments comments = new Comments();
    
    // 添加作者信息
    Authors authors = new Authors();
    authors.Append(new Author() { Text = "当前用户" });
    comments.Append(authors);
    
    // 添加注释列表
    CommentList commentList = new CommentList();
    Comment comment = new Comment() 
    { 
        Reference = "A1", 
        AuthorId = 0,
        ShapeId = 0
    };
    
    // 设置注释文本样式和内容
    CommentText commentText = new CommentText();
    Run run = new Run();
    run.Append(new RunProperties(
        new FontSize() { Val = 9 },
        new Color() { Indexed = 81 },
        new RunFont() { Val = "Tahoma" }
    ));
    run.Append(new Text() { Text = "这是一个示例注释" });
    commentText.Append(run);
    comment.Append(commentText);
    
    commentList.Append(comment);
    comments.Append(commentList);
    
    return comments;
}

4. 创建VML绘图部分

VML绘图部分负责注释的视觉呈现：

private static void GenerateVmlDrawingPart(VmlDrawingPart vmlDrawingPart)
{
    var vmlDrawing = new Vml.ShapeLayout() 
    { 
        Ext = EditExtensionsValues.Edit 
    };
    
    var shape = new Vml.Shape()
    {
        Id = "_x0000_s1025",
        Type = "#_x0000_t202",
        Style = "position:absolute; margin-left:59.25pt;margin-top:1.5pt;width:96pt;height:55.5pt;z-index:1",
        FillColor = "#ffffe1",
        InsetMode = InsetMarginValues.Auto
    };
    
    vmlDrawing.Append(shape);
    vmlDrawingPart.RootElement = vmlDrawing;
}

高级技巧

1. 多行注释处理：在注释文本中使用\n实现换行
2. 样式自定义：通过修改RunProperties调整字体、颜色等样式
3. 注释定位：通过调整VML Shape的margin和position属性控制注释框位置
4. 线程注释：对于新版Excel，考虑使用更现代的线程注释功能

常见问题排查

1. 注释不显示：

   • 检查是否同时创建了CommentsPart和VmlDrawingPart
   • 确认注释关联的单元格确实存在
   • 验证VML绘图部分是否正确关联

2. 样式异常：

   • 检查字体名称是否有效
   • 确认颜色值格式正确

3. 性能问题：

   • 对于大量注释，考虑批量处理
   • 重用样式定义减少重复代码

总结

通过Open-XML-SDK为Excel添加注释需要理解Excel文件结构的多个组成部分的协作关系。正确实现需要同时处理内容部分(CommentsPart)和呈现部分(VmlDrawingPart)，并确保它们与工作表数据的正确关联。掌握这些核心概念后，开发者可以灵活地实现各种复杂的注释需求。