GroupDocs.Markdown for .NET 26.3 – 2026年3月发布要点

我们很高兴宣布 GroupDocs.Markdown for .NET 26.3 已于 2026 年 3 月 正式发布。此重大更新引入了重新设计的公共 API、基于自定义 DOM 的 Markdown 渲染器、完整的 Markdown 方言控制、异步支持以及一系列错误修复。它还新增了按 TFM（目标框架）划分的运行时 NuGet 包，并支持 .NET 8 与 .NET 10。

本次发布的新功能

公共 API 变更

新增公共类型

• DocumentInfo — 文档元数据（格式、页数、标题、作者、加密状态）
• MarkdownFlavor — 用于指定目标 Markdown 方言的枚举（GitHub、CommonMark）
• IImageSavingHandler — 用于自定义图片保存回调的接口
• IUriSavingHandler — 用于自定义 URI 保存回调的接口
• GroupDocsMarkdownException — 通用转换异常
• InvalidFormatException — 损坏或无法识别的文件格式
• DocumentProtectedException — 密码错误或缺失

MarkdownConverter 上的新增静态方法

• ToMarkdown(string sourcePath) 以及带 LoadOptions/ConvertOptions 的重载
• ToFile(string sourcePath, string outputPath) 以及带重载
• GetInfo(string sourcePath) 以及带重载
• GetSupportedFormats()
• 异步变体：ToMarkdownAsync、ToFileAsync、GetInfoAsync

MarkdownConverter 上的新增实例方法

• GetDocumentInfo()
• ConvertAsync() 以及重载

ConvertOptions 上的新增属性

• ImageExportStrategy（取代 ExportStrategy）
• UriExportStrategy
• HeadingLevelOffset
• IncludeFrontMatter
• Flavor
• MaxColumns、MaxRows、SheetSeparator、IncludeHiddenSheets

ConvertResult 上的新增属性

• Warnings — 非致命的转换警告

ExportImagesToFileSystemStrategy 与 CustomImagesStrategy 上的新增属性

• ImagesRelativePath — 控制 Markdown 中图片引用写入的路径

CustomImageSavingArgs 上的新增方法

• SetReplacementImage(Stream imageStream) — 替换图片内容

已移除的类型

• IExportStrategy — 已被 IImageExportStrategy 与 IUriExportStrategy 取代
• DocumentConverterOptions — 重命名为 ConvertOptions
• DocumentConverterResult — 重命名为 ConvertResult

破坏性更改

重命名的类型

FileFormat 枚举

原先的族级别值（FileFormat.WordProcessing、FileFormat.Spreadsheet）已被具体格式（FileFormat.Docx、FileFormat.Xlsx 等）取代。新增条目：FileFormat.Txt、FileFormat.Chm。

ConvertOptions 与 LoadOptions 分离

ConvertOptions 不再继承 LoadOptions。密码和格式提示应放在 LoadOptions 中：

var loadOptions = new LoadOptions(FileFormat.Docx) { Password = "secret" };
var convertOptions = new ConvertOptions { HeadingLevelOffset = 1 };
using var converter = new MarkdownConverter("file.docx", loadOptions);
var result = converter.Convert(convertOptions);

图片和 URI 策略拆分

单一的 ExportStrategy 属性被两个强类型属性取代：

var options = new ConvertOptions
{
    ImageExportStrategy = new ExportImagesToFileSystemStrategy("images"),
    UriExportStrategy = new CustomUriExportStrategy(handler)
};

委托被接口取代

CustomImagesStrategy 与 CustomUriExportStrategy 现在接受 IImageSavingHandler 与 IUriSavingHandler 接口，而不是委托回调。

LoadOptions.Extension 与 LoadOptions.MimeType 设为内部

请使用 new LoadOptions(FileFormat.Docx) 而不是直接设置 Extension 或 MimeType。

新特性

基于自定义 DOM 的 Markdown 渲染器

库不再将 Markdown 生成委托给第三方导出器。自定义渲染器逐节点遍历文档对象模型并直接生成 Markdown，提供对输出每个细节的完整控制。

Word / PDF / Ebook / Text / CHM 文档 支持段落、标题（H1‑H6）、粗体、斜体、删除线、行内代码、有序与无序列表（支持嵌套）、表格（GFM 管道语法或 CommonMark 代码块回退）、超链接和图片。

电子表格 通过逐单元格网格遍历、类型化值格式化、工作表分段、列/行截断并使用省略号指示、隐藏工作表过滤以及自定义工作表分隔符进行渲染。

静态便利方法

一行代码完成转换并自动管理资源：

string md = MarkdownConverter.ToMarkdown("report.docx");
MarkdownConverter.ToFile("report.docx", "report.md");
IReadOnlyList<FileFormat> formats = MarkdownConverter.GetSupportedFormats();

异步 API

所有静态和实例方法均提供带 CancellationToken 支持的异步对应版本：

string md = await MarkdownConverter.ToMarkdownAsync("report.docx");
await MarkdownConverter.ToFileAsync("large.pdf", "output.md");
DocumentInfo info = await MarkdownConverter.GetInfoAsync("report.docx");

在不进行转换的情况下检查文档

获取文档元数据而无需完整转换：

DocumentInfo info = MarkdownConverter.GetInfo("report.docx");
Console.WriteLine($"{info.FileFormat}, {info.PageCount} pages, by {info.Author}");

Markdown 方言控制

针对特定 Markdown 方言进行渲染：

var options = new ConvertOptions { Flavor = MarkdownFlavor.GitHub }; // 管道表格、删除线
var options = new ConvertOptions { Flavor = MarkdownFlavor.CommonMark }; // 表格作为代码块

电子表格渲染选项

对电子表格渲染为 Markdown 的方式拥有完整控制：

var options = new ConvertOptions
{
    MaxColumns = 8,
    MaxRows = 50,
    SheetSeparator = "\n---\n",
    IncludeHiddenSheets = false
};

标题层级偏移与 YAML 前置元数据

var options = new ConvertOptions
{
    HeadingLevelOffset = 2,       // # Title  ->  ### Title
    IncludeFrontMatter = true     // 在开头添加 YAML 元数据
};

转换警告与统一错误模型

所有 Convert() 方法在失败时抛异常。ConvertResult 仍会携带非致命警告：

ConvertResult result = converter.Convert();
foreach (string w in result.Warnings)
    Console.WriteLine(w);  // 例如 "Worksheet 'Data' truncated at 50 rows."

图片替换与相对路径

在转换过程中替换图片并控制路径引用：

var strategy = new ExportImagesToFileSystemStrategy("c:/output/images")
{
    ImagesRelativePath = "images"  // ![](images/img-001.png)
};

目录（Table of Contents）渲染

包含目录的文档将渲染为简洁的列表，而不是原始字段代码：

- Introduction
- 1.  Executive Summary
- 2.  Company Overview

代码示例

string md = MarkdownConverter.ToMarkdown("report.docx");
MarkdownConverter.ToFile("report.docx", "report.md");
IReadOnlyList<FileFormat> formats = MarkdownConverter.GetSupportedFormats();

如何获取更新

NuGet

通过 NuGet 升级到最新的 GroupDocs.Markdown 包（例如 Install-Package GroupDocs.Markdown）。

资源

• License
• Free Support Forum