syncfusion-wpf-markdown-viewer

实现 WPF SfMarkdownViewer

SfMarkdownViewer 可将 Markdown 内容（包括标题、列表、链接、图片、表格、代码块和引用块）渲染为带样式的 WPF 视觉元素。可用它来显示文档、发行说明、帮助内容、README 文件或任何基于 Markdown 的内容，无需使用外部渲染引擎。

何时使用此技能

• 用户需要在 WPF 应用中渲染或预览 Markdown 内容
• 从硬编码字符串、应用程序内置资源或应用程序控制的本地文件加载 Markdown
• 显示来自可信且由应用程序拥有的来源的文档、变更日志或帮助文本
• 使用 URL 验证和允许列表拦截超链接导航
• 在验证输入长度和类型后渲染 Mermaid 流程图

⚠️ 不适用范围： 不要使用此技能直接从任意第三方 URL 或未经验证的用户输入加载 Markdown。请先在应用程序代码中获取、验证并清理内容。

快速开始

<Window
    x:Class="GettingStarted.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:markdown="clr-namespace:Syncfusion.UI.Xaml.Markdown;assembly=Syncfusion.SfMarkdownViewer.WPF"
    xmlns:system="clr-namespace:System;assembly=mscorlib">
    <Grid>
        <markdown:SfMarkdownViewer Source="# Hello World&#10;&#10;This is **bold** and *italic* text." />
    </Grid>
</Window>

using Syncfusion.UI.Xaml.Markdown;

SfMarkdownViewer markdownViewer = new SfMarkdownViewer();
markdownViewer.Source = "# Hello World\n\nThis is **bold** and *italic* text.";
this.Content = markdownViewer;

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装 NuGet 包（Syncfusion.SfMarkdownViewer.Wpf）
• 必需的程序集引用（3 个程序集）
• 导入 XAML 命名空间
• 通过 XAML 和 C# 添加控件
• 通过 Source 属性传入内嵌 Markdown 字符串
• SfSkinManager 主题支持

加载内容

📄 阅读： references/loading-content.md

• 从原始 Markdown 字符串加载
• 从应用程序控制的本地文件路径加载
• 通过应用程序代码从远程 URL 加载（获取 → 验证来源 → 检查 content-type → 赋值字符串）
• XAML CDATA 字符串源模式
• 决策指南：选择要使用的源类型
• 加载远程内容的安全要求

事件

📄 阅读： references/events.md

• HyperlinkClicked 事件
• MarkdownHyperlinkClickedEventArgs（Url、Cancel）
• 默认取消模式——始终先取消，再有选择地允许通过验证的 URL
• 基于允许列表验证应用内的 app:// 路由
• 屏蔽非 HTTPS 外部协议

Mermaid 图表

📄 阅读： references/mermaid-diagrams.md

• MermaidBlockTemplate 属性
• 在 DataTemplate 中嵌入 SfDiagram
• 渲染前验证 DataContext（Mermaid 字符串）——长度限制和类型允许列表
• FlowchartLayout 配置
• LoadDiagramFromMermaid() 的用法
• Mermaid 支持所需的依赖项

关键属性

属性	类型	用途
Source	string	原始 Markdown 字符串、文件路径或 HTTP/HTTPS URL
MermaidBlockTemplate	DataTemplate	用于渲染 mermaid 代码块的自定义模板

关键事件

事件	参数	用途
HyperlinkClicked	MarkdownHyperlinkClickedEventArgs	用户点击渲染后的 Markdown 中的超链接时触发

常见用例

• 应用内文档： 将 Markdown 作为硬编码字符串或应用程序内置资源文件嵌入；直接赋值给 Source
• 发行说明面板： 加载随应用程序内置的本地 .md 文件（而非来自用户输入的路径），并将其文本赋值给 Source
• 远程文档： 在应用程序代码中从应用程序拥有的 HTTPS 端点获取 Markdown，验证 HTTP 响应的来源和 content-type，然后将清理后的字符串赋值给 Source——绝不要将第三方 URL 直接传给 Source
• 帮助查看器： 渲染来自可信且由应用程序控制的来源的上下文 Markdown 帮助字符串
• 图表查看器： 使用 MermaidBlockTemplate 和 SfDiagram 渲染流程图；调用 LoadDiagramFromMermaid() 前验证 Mermaid DataContext 字符串（长度和类型前缀）
• 受控导航： 以默认取消方式处理 HyperlinkClicked；根据明确的允许列表验证 app:// 路由，并且只允许 https:// 外部链接

安全注意事项

风险	缓解措施
远程 URL 加载不受信任的第三方 Markdown	在应用代码中获取内容；在赋值给 Source 前验证来源（允许列表中的基础 URL）和内容类型
Markdown 中的超链接导致意外导航	在 HyperlinkClicked 中默认取消；根据固定的允许列表验证 app:// 路由；仅允许 https:// 外部链接
不受信任的 Markdown 中的 Mermaid 代码块触发图表渲染	验证 DataContext 字符串：检查是否为非空、限制长度，并在调用 LoadDiagramFromMermaid() 前将图表类型前缀限制在允许列表中
将用户提供的 URL 传递给 Source	切勿直接接受用户输入或第三方数据中的 URL；始终先在应用代码中验证来源