如何为MigraDoc生成的PDF图片添加Alt Text

MigraDoc本身确实没有内置的图片Alt Text属性，也不直接支持无障碍标记，但可以通过MigraDoc标记图片+PDFSharp后处理的方式实现，核心是利用PDFSharp的UAManager操作PDF的结构树，而非通过XGraphics修改页面。

关键步骤与代码示例 #

1. MigraDoc阶段：标记图片

在添加图片时，用Tag属性给每个图片设置唯一标识，后续用来匹配PDF中的对应图片：

// MigraDoc添加图片并标记
var image = section.AddImage(@"assets/watch.png");
image.Tag = "watch-preview-alt"; // 唯一标识，方便后续定位

// 可选：记录图片的位置信息（比如BoundingBox），用于更精准匹配
var imageBounds = image.Renderer.FormatInfo.Bounds;
// 将Tag和Bounds存入字典，比如 Dictionary<string, Rectangle> imageTagMap = new();
imageTagMap.Add((string)image.Tag, imageBounds);

2. 生成PDF流并加载到PDFSharp

先让MigraDoc生成PDF字节流，再用PDFSharp打开进行后处理：

// 从MigraDoc获取PDF字节流
byte[] pdfBytes;
using (var ms = new MemoryStream())
{
    var renderer = new PdfDocumentRenderer(true);
    renderer.Document = migraDocDocument;
    renderer.RenderDocument();
    renderer.PdfDocument.Save(ms);
    pdfBytes = ms.ToArray();
}

// 用PDFSharp打开PDF并启用修改模式
using (var pdfDoc = PdfReader.Open(new MemoryStream(pdfBytes), PdfDocumentOpenMode.Modify))
{
    var uaManager = new UAManager(pdfDoc);

3. 遍历页面，为图片添加Alt Text

通过UAManager获取页面的结构构建器，找到对应图片并关联结构元素，设置替代文本：

foreach (var page in pdfDoc.Pages)
    {
        var structureBuilder = uaManager.GetStructureBuilder(page);
        
        // 遍历页面资源中的图片
        foreach (var imageName in page.Resources.Images.Elements.Keys)
        {
            var pdfImage = page.Resources.Images[imageName];
            
            // 根据之前记录的Tag和位置匹配图片
            foreach (var entry in imageTagMap)
            {
                // 这里可以通过位置或Tag精准匹配，示例用Tag匹配
                if (entry.Key == "watch-preview-alt")
                {
                    // 创建Figure结构元素（PDF无障碍规范中图片对应的结构类型）
                    var figureElement = structureBuilder.CreateElement(PdfStructureElementName.Figure);
                    figureElement.AlternativeText = "红色智能手表，表盘显示时间为10:05";
                    
                    // 将PDF图片对象关联到结构元素
                    structureBuilder.MapObjectToElement(pdfImage.Reference, figureElement);
                }
            }
        }
    }

    // 保存处理后的无障碍PDF
    pdfDoc.Save(@"output/accessible_with_alt_text.pdf");
}

你之前踩坑的关键原因 #

• 错误尝试用XGraphics修改已有页面：XGraphics主要用于生成新内容，而非修改已有PDF的无障碍结构树，直接操作UAManager和结构元素才是正确路径。
• 未正确关联MigraDoc标记与PDF图片：需要在MigraDoc阶段记录图片的唯一标识或位置，才能在PDFSharp中精准定位到要添加Alt Text的图片。

内容的提问来源于stack exchange，提问作者AJ Morris