QuillDelta2Markdown 0.1.0

QuillDelta2Markdown

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

功能概览

• 行内格式：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 失败时是否抛异常

支持映射

行内格式

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

块级格式

嵌入对象

自定义嵌入处理器

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 数组