Sage.MarkdownRenderer 1.0.0.1

Sage.MarkdownRenderer

简介

Sage.MarkdownRenderer 是一个基于WebView2封装的Markdown渲染库，支持直接解析Markdown字符串并在WebView2控件中渲染。该库提供了丰富的功能和灵活的配置选项，使开发者能够轻松地在Windows应用程序中展示美观的Markdown内容。

本库基于最新的.NET技术构建，支持AOT编译，并提供了全面的主题支持和自定义选项，让您的应用程序能够呈现专业、美观的Markdown文档。

主要特性

• 丰富的Markdown支持：支持标准Markdown语法及多种扩展

  • 表情符号和笑脸 (Emoji and Smiley) - 支持标准Emoji表情符号
  • 数学公式 (Mathematics) - 支持LaTeX数学公式渲染
  • 表格 (Tables) - 支持复杂表格布局和格式化
  • 任务列表 (Task Lists) - 支持可交互的任务列表
  • 媒体链接 (Media Links) - 自动识别媒体链接
  • 图片和图片标题 (Figures) - 支持图片标题和描述
  • 脚注 (Footers) - 支持文档脚注功能
  • 定义列表 (Definition Lists) - 支持术语定义列表
  • 缩写 (Abbreviations) - 支持缩写词展开
  • 引用 (Citations) - 支持学术引用和参考文献
  • 自定义容器 (Custom Containers) - 支持自定义内容容器
  • 强调扩展 (Emphasis Extras) - 增强的文本强调语法

• 主题支持：

  • 浅色主题 (Light) - 适合明亮环境和日间使用
  • 深色主题 (Dark) - 适合暗光环境和夜间使用，减轻眼睛疲劳
  • 自动主题 (Auto) - 智能跟随系统设置自动切换，提供最佳视觉体验

• 自定义颜色配置：

  • 可自定义主要颜色、强调颜色、成功/警告/错误/信息颜色
  • 可自定义边框、背景、文本等多种元素的颜色
  • 预定义主题：蓝色、绿色、紫色
  • 支持完全自定义的颜色方案，满足品牌一致性需求

• 安全性和用户体验：

  • 禁用默认右键菜单 - 防止用户执行不必要的操作
  • 禁用开发者工具 - 增强应用安全性
  • 禁用JavaScript弹窗 - 避免干扰用户体验
  • 禁用页面缩放控制 - 保持一致的显示效果
  • 外部链接处理 - 可配置在系统默认浏览器中打开外部链接

• 技术特性：

  • 支持AOT编译 - 提高应用启动速度和运行性能
  • 基于最新的.NET技术 - 利用.NET 9的先进特性
  • 使用WebView2提供高性能渲染 - 基于Chromium引擎的高质量渲染
  • 完善的异步API - 所有操作都支持异步调用，不阻塞UI线程

安装

通过NuGet包管理器安装：

Install-Package Sage.MarkdownRenderer

或使用.NET CLI：

dotnet add package Sage.MarkdownRenderer

使用示例

基本用法

using Sage.MarkdownRenderer;
using Microsoft.Web.WebView2.WinForms;


// 创建WebView2控件
WebView2 webView = new WebView2();
this.Controls.Add(webView);

// 创建MarkdownViewManager，在构造函数中指定要使用的WebView2控件
MarkdownViewManager manager = new MarkdownViewManager(webView);

// 初始化WebView2
await manager.InitializeAsync("./WebView2Data");

// 显示Markdown内容（支持常见的Markdown语法文本）
string markdown = "# Hello World\n\nThis is a **bold** text and *italic* text.";
await manager.ShowMarkdownAsync(markdown);

设置主题

// 设置为深色主题
await manager.SetThemeAsync(ThemeMode.Dark);

// 设置为浅色主题
await manager.SetThemeAsync(ThemeMode.Light);

// 设置为自动主题（跟随系统）
await manager.SetThemeAsync(ThemeMode.Auto);

显示自定义内容

// 显示自定义HTML内容
string title = "自定义标题";
string htmlContent = "<h1>Hello World</h1><p>This is <strong>HTML</strong> content.</p>";
await manager.ShowCustomContentAsync(title, htmlContent);

// 显示空内容提示
await manager.ShowEmptyContentAsync("暂无内容可显示");

自定义配置选项

// 创建自定义配置
var options = new MarkdownViewManagerOptions
{
    Theme = ThemeMode.Auto,// 默认主题
    AutoLoadWelcomePage = false, // 自动加载欢迎页面（如果未false 可以手动调用LoadInitialPageAsync加载）
    DefaultEmptyText = "暂无内容", // 默认空内容提示
    DisableDefaultContextMenu = false, // 启用默认右键菜单
    DisableDevTools = false, // 开发者工具
    DisableScriptDialogs = false, // 脚本对话框
    DisableZoomControl = false, // 缩放控制
    InjectSecurityScripts = true, // 注入安全脚本
    UseExternalBrowserForLinks = true, // 使用外部浏览器打开链接
    InterceptUIKeyboard = false,// 拦截UI键盘事件（F5 CARL+F5 WebView2默认支持的键盘按键）
};


// 使用自定义配置创建管理器，如果不传递默认为缺省配置
var manager = new MarkdownViewManager(webView, options);

// 此外还支持快速创建配置
// 创建默认配置
var defaultOptions = MarkdownViewManagerOptions.CreateDefault();

// 创建开发配置
var devOptions = MarkdownViewManagerOptions.CreateForDevelopment();

// 创建高安全配置
var highSecOptions = MarkdownViewManagerOptions.CreateHighSecurity();


## 常见问题解答

### Q: 如何在应用程序中嵌入WebView2运行时？

A: WebView2提供了两种分发模式：固定版本运行时和常青版本运行时。对于需要嵌入WebView2运行时的应用程序，建议使用固定版本运行时，可以通过以下步骤实现：

1. 在项目中添加WebView2运行时NuGet包：

Install-Package Microsoft.Web.WebView2.Runtime.X64

2. 在应用程序安装过程中，将运行时文件复制到应用程序目录。

3. 在初始化WebView2时，指定运行时路径：
```csharp
var options = new CoreWebView2EnvironmentOptions();
var environment = await CoreWebView2Environment.CreateAsync(null, "./WebView2Runtime", options);
await webView.EnsureCoreWebView2Async(environment);

Q: 如何处理Markdown中的本地图片？

A: 默认情况下，WebView2只能访问网络图片。要显示本地图片，可以使用以下方法：

1. 将图片转换为Base64编码并嵌入Markdown：

string imagePath = "path/to/image.png";
byte[] imageBytes = File.ReadAllBytes(imagePath);
string base64Image = Convert.ToBase64String(imageBytes);
string imageFormat = Path.GetExtension(imagePath).TrimStart('.');
string markdown = $"![图片描述](data:image/{imageFormat};base64,{base64Image})";

2. 或者使用虚拟主机功能映射本地文件夹：

await webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
    "localfiles", "C:\\Images", CoreWebView2HostResourceAccessKind.Allow);

// 然后在Markdown中使用：![图片描述](https://localfiles/image.png)

Q: 如何在Markdown中使用数学公式？

A: Sage.MarkdownRenderer已内置MathJax支持，可以直接在Markdown中使用LaTeX语法：

行内公式: $E=mc^2$

块级公式:
$$
\frac{\partial f}{\partial x} = \lim_{h \to 0} \frac{f(x+h) - f(x)}{h}
$$

自定义颜色配置

using Sage.MarkdownRenderer.Html;
using Sage.MarkdownRenderer.WebView;

// 创建颜色配置
var colorConfig = new ColorConfig
{
    // 基础颜色
    PrimaryColor = "#007bff",      // 主要颜色（链接、按钮等）
    AccentColor = "#0056b3",       // 强调颜色（悬停效果等）
    SuccessColor = "#28a745",     // 成功颜色
    WarningColor = "#ffc107",     // 警告颜色
    ErrorColor = "#dc3545",       // 错误颜色
    InfoColor = "#17a2b8",        // 信息颜色
    
    // 边框和分隔线颜色
    BorderColor = "#dee2e6",                // 边框颜色
    BlockquoteBorderColor = "#007bff",      // 引用块左边框颜色
    HorizontalRuleColor = "#dee2e6",        // 水平分隔线颜色
    
    // 代码相关颜色
    InlineCodeBackground = "#f8f9fa",       // 行内代码背景色
    InlineCodeColor = "#e83e8c",            // 行内代码文字颜色
    CodeBlockBackground = "#f8f9fa",        // 代码块背景色
    
    // 表格颜色
    TableHeaderBackground = "#f8f9fa",      // 表格表头背景色
    TableEvenRowBackground = "#f8f9fa",     // 表格偶数行背景色
    TableHoverBackground = "#f2f2f2",       // 表格悬停行背景色
    
    // 列表颜色
    ListMarkerColor = "#007bff"              // 列表标记颜色
};

// 使用预定义的主题
// ColorConfig.BlueTheme - 蓝色主题
// ColorConfig.GreenTheme - 绿色主题
// ColorConfig.PurpleTheme - 紫色主题
var purpleTheme = ColorConfig.PurpleTheme;

自定义HTML模板配置

using Sage.MarkdownRenderer.Html;
using Sage.MarkdownRenderer.WebView;

// 创建HTML模板配置
var templateConfig = new HtmlTemplateConfig
{
    // 基础内容配置
    Title = "文档标题",                // 页面标题
    Content = "<p>HTML内容</p>",     // 页面主体内容
    ShowWelcomeLayout = false,        // 是否显示欢迎页面布局
    
    // 主题和外观配置
    Theme = ThemeMode.Light,          // 主题模式
    FontFamily = "Microsoft YaHei, -apple-system, BlinkMacSystemFont, Segoe UI, Arial, sans-serif", // 字体族设置
    FontSize = 14,                    // 基础字体大小（像素）
    MaxWidth = 800,                   // 最大宽度限制（像素）
    ColorConfig = colorConfig,        // 自定义颜色配置
    
    // 交互和行为配置
    ShowScrollbar = true,             // 是否显示滚动条
    EnableAnimation = true,           // 是否启用动画效果
    EnableHoverAnimations = true,     // 是否启用悬停动画效果
    EnableCodeCopy = true,            // 是否启用代码复制功能
    EnableResponsive = true,          // 是否启用响应式布局
    EnablePrintStyles = true,         // 是否启用打印样式
    
    // 自定义CSS
    CustomCss = @"
        /* 减少页面顶部间距 */
        body {
            padding-top: 10px !important;
        }
        
        /* 移除第一个元素的顶部边距 */
        body > h1:first-child,
        body > h2:first-child,
        body > h3:first-child,
        body > h4:first-child,
        body > h5:first-child,
        body > h6:first-child,
        body > p:first-child {
            margin-top: 0 !important;
        }
        
        /* 减少标题的默认边距 */
        h1, h2, h3, h4, h5, h6 {
            margin-top: 1em !important;
        }
        
        h1:first-child, h2:first-child, h3:first-child {
            margin-top: 0 !important;
        }"
};

使用自定义配置显示Markdown内容

// 创建WebViewManager
WebViewManager manager = new WebViewManager(webView);
await manager.InitializeAsync("./WebView2Data");

// Markdown内容
string markdown = "# Hello World\n\nThis is a **bold** text and *italic* text.";

// 转换Markdown为HTML
var markdownHtml = Markdig.Markdown.ToHtml(markdown, new Markdig.MarkdownPipelineBuilder().UseAdvancedExtensions().Build());

// 创建HTML模板配置
var config = new HtmlTemplateConfig
{
    Title = "自定义配置示例",
    Content = markdownHtml,
    Theme = ThemeMode.Dark,
    ColorConfig = ColorConfig.PurpleTheme,
    CustomCss = "body { font-size: 16px; }"
};

// 创建HTML
var html = HtmlTemplateBuilder.CreateTemplate(config);

// 显示自定义内容
await manager.ShowCustomContentAsync(config.Title, html);

注意事项

• 使用前需要确保已安装WebView2运行时
• 初始化时需要提供一个有效的用户数据文件夹路径
• 渲染大型Markdown文档时可能需要一定的加载时间
• 外部链接会在默认浏览器中打开，而不是在WebView2控件中

许可证

本项目采用Apache-2.0许可证。详情请参阅LICENSE文件。

作者

• LiuPengLai
• 甲壳虫科技

贡献

欢迎提交问题和建议，帮助我们改进这个库！