QuillDelta2Markdown

一个轻量的 .NET 库，用于将 Quill Delta JSON（ops）转换为 Markdown。

安装

使用 .NET CLI：

dotnet add package QuillDelta2Markdown

或使用 NuGet 包管理器：

Install-Package QuillDelta2Markdown

功能概览

• 行内格式：bold、italic、underline、strike、code、link、script(super/sub)
• 块级格式：header、blockquote、code-block、list（ordered / bullet / checked / unchecked）
• 列表缩进：支持 indent（每级 4 个空格）
• 嵌入对象：image、video、formula
• 可扩展：支持自定义嵌入处理器与未知嵌入回退策略
• 双调用模式：Convert（便捷）与 TryConvert（显式错误处理）

快速开始

using QuillDelta2Markdown.Conversion;
using QuillDelta2Markdown.Options;

var converter = new QuillDeltaMarkdownConverter(new QuillMarkdownConverterOptions
{
	Logger = Console.WriteLine
});

var deltaJson = """
{
  "ops": [
	{ "insert": "Hello ", "attributes": { "bold": true } },
	{ "insert": "Quill" },
	{ "insert": "\n", "attributes": { "header": 2 } },
	{ "insert": { "image": "https://example.com/a.png" }, "attributes": { "alt": "logo" } },
	{ "insert": "\n" }
  ]
}
""";

var markdown = converter.Convert(deltaJson);
Console.WriteLine(markdown);

输出示例：

## **Hello **Quill

![logo](https://example.com/a.png)

API

IQuillDeltaMarkdownConverter

• string Convert(string deltaJson)
  • 转换失败时默认返回空字符串，并通过 Logger 输出错误
  • 若配置 ThrowOnParseError = true，转换失败会抛出异常
• bool TryConvert(string deltaJson, out string markdown, out string? error)
  • 成功返回 true
  • 失败返回 false，并通过 error 返回错误原因

QuillMarkdownConverterOptions

• IList<IEmbedHandler> EmbedHandlers
  • 注册自定义嵌入处理器
• Action<string>? Logger
  • 接收错误/警告日志
• Func<string, JsonElement, string>? UnknownEmbedFormatter
  • 定义未知嵌入类型的回退文本
• bool ThrowOnParseError
  • Convert 失败时是否抛异常

支持映射

行内格式

Quill 属性	Markdown 输出
bold: true	**text**
italic: true	*text*
underline: true	<u>text</u>
strike: true	~~text~~
code: true	`text`
script: "super"	^text^
script: "sub"	~text~
link: "https://..."	[text](https://...)

说明：如 color、background、font、size、align 等样式目前不会输出为 Markdown。

块级格式

Quill 属性	Markdown 输出
header: 1..6	# 到 ######
blockquote: true	> text
code-block: true	三反引号代码块
list: "ordered"	1. text（自动递增）
list: "bullet"	- text
list: "checked"	- [x] text
list: "unchecked"	- [ ] text
indent: n	左侧缩进 n * 4 空格

嵌入对象

Quill embed	Markdown/HTML 输出
{ "image": "url" }	
{ "video": "url" }	<video src="url" controls></video>
{ "formula": "E=mc^2" }	$ E=mc^2 $（多行为 $$ ... $$）

自定义嵌入处理器

using System.Text.Json;
using QuillDelta2Markdown.Abstractions;
using QuillDelta2Markdown.Conversion;
using QuillDelta2Markdown.Options;

public sealed class MentionHandler : IEmbedHandler
{
	public string Type => "mention";

	public bool TryConvert(JsonElement embedValue, IReadOnlyDictionary<string, JsonElement> attributes, out string markdown)
	{
		markdown = string.Empty;
		if (embedValue.ValueKind != JsonValueKind.String)
		{
			return false;
		}

		markdown = $"@{embedValue.GetString()}";
		return true;
	}
}

var options = new QuillMarkdownConverterOptions();
options.EmbedHandlers.Add(new MentionHandler());
var converter = new QuillDeltaMarkdownConverter(options);

未知嵌入回退

默认未知嵌入会输出为：[unsupported-embed:<type>]。

你可以自定义回退格式：

var converter = new QuillDeltaMarkdownConverter(new QuillMarkdownConverterOptions
{
	UnknownEmbedFormatter = (type, value) => $"[unknown:{type}]"
});

错误处理建议

• 业务流程中建议优先使用 TryConvert，可避免异常控制流
• 工具型/脚本型场景可使用 Convert + ThrowOnParseError = true

限制说明

• 该库面向 document 型 Delta（insert）；delete/retain 会被忽略并记录警告
• 输入 JSON 必须包含 ops 数组