syncfusion-uwp-pdf-viewer

实现 UWP PDF 查看器（SfPdfViewerControl）

Syncfusion SfPdfViewerControl 是一款原生 UWP 控件，可用于查看、批注、搜索和打印 PDF 文档。它默认使用 Windows 渲染引擎（Windows.Data.Pdf），并支持可选的 PDFium 渲染器。

安全须知 ⚠️

从不受信任或用户提供的来源加载 PDF 时，务必先验证超链接和内容，再允许导航。 PDF 可能包含恶意超链接，将用户引导至不受信任的网站，或执行非预期操作。务必使用 HyperlinkPointerPressed 事件验证超链接，检查并授权导航目标后再允许跳转。验证代码示例请参阅 references/bookmarks-and-hyperlinks.md。

何时使用此技能

在以下情况下使用此技能：

• 在 UWP 应用中查看和浏览 PDF 文档
• 从流、StorageFile 对象或字节数组加载 PDF
• 添加和管理批注（高亮、下划线、删除线、墨迹、形状、自由文本、弹出批注、图章）
• 在 PDF 文档中搜索和选择文本
• 浏览页面、书签和超链接（对不受信任来源进行适当验证）
• 使用自定义质量和预览设置打印 PDF 文档
• 创建与 PDF 查看器命令关联的自定义工具栏
• 配置缩放、视图模式、滚动条和进度环
• 本地化查看器 UI
• 将 PDF 页面导出为图像，或使用 PDFium 自定义渲染器

组件概述

SfPdfViewerControl 是一款功能全面的 UWP PDF 查看和管理控件，具备以下功能：

• 文档管理： 从 PdfLoadedDocument、Stream 或 StorageFile 加载（同步和异步，支持 CancellationToken）；保存带批注的文档；卸载和释放
• 批注： 文本标记（高亮、下划线、删除线）、形状（矩形、椭圆、线条）、支持 Windows Ink Canvas 的墨迹、弹出批注（便笺）、自由文本、自由文本标注和自定义图章批注
• 文本操作： 可自定义颜色的文本选择；支持同步和异步文本搜索，并可导航至上一个或下一个结果
• 导航和 UI： 页面导航命令、书签、超链接处理、缩放和视图模式、缩略图视图、分别适用于桌面和移动设备的工具栏布局、滚动条和进度环自定义
• 实用工具和高级功能： 将页面导出为图像（GetPage、GetPages、ExportAsImage）、访问垂直和水平偏移量、通过 IPdfRenderer 接口使用 PDFium 自定义渲染器、显示页码

文档和导航指南

入门和设置

📄 阅读： references/getting-started.md

• 介绍所需程序集、NuGet 包、通过 XAML 或代码添加控件、ItemsSource 绑定以及 DocumentLoaded 事件
• 介绍同步和异步加载方法、页数读取、保存（Save/SaveAsync）、卸载和释放

文档操作

📄 阅读： references/viewing-pdf.md

• 介绍如何使用同步和异步方式，从 PdfLoadedDocument、Stream 和 StorageFile 对象加载 PDF
• 介绍异步加载对 CancellationToken 的支持、保存带批注的文档，以及查看器的卸载和释放模式

页面导航和查看

📄 阅读： references/page-navigation.md

• 介绍以编程方式浏览页面、内置导航命令（FirstPage、LastPage、NextPage、PreviousPage）以及 XAML 命令绑定
• 介绍 PageChanged 事件、页数、页面间距、偏移量集合，以及切换页码显示

放大和视图模式

📄 阅读： references/magnification.md

• 介绍通过 ZoomTo 控制缩放、放大和缩小命令，以及视图模式选项（FitWidth、Normal、OnePage）
• 介绍 MinimumZoomPercentage、切换缩略图视图，以及读取当前缩放值

文本搜索

📄 阅读： references/text-operations.md

• 介绍同步和异步文本搜索、向前／向后浏览结果，以及 SearchNextCommand/SearchPreviousCommand
• 介绍如何使用 GetTextCoordinates 获取所有文本匹配项在页面上的位置

文本选择

📄 阅读： references/text-operations.md

• 介绍如何启用文本选择、自定义选择高亮颜色，以及 TextSelectionCompleted 事件
• 介绍如何将选中的文本复制到剪贴板

注释

📄 阅读： references/annotations.md

• 涵盖所有支持的注释类型：文本标记（高亮、下划线、删除线）、形状（矩形、椭圆、直线）、使用 Windows Ink Canvas 的墨迹、弹出注释、自由文本、自由文本标注和自定义印章
• 介绍注释事件（Added、Tapped、Selected、Removed、MovedOrResized）、删除注释、AnnotationCollection、撤销／重做，以及 IsDocumentEdited 属性

打印

📄 阅读： references/printing.md

• 介绍 Print 方法、PrintCommand，以及支持 CancellationToken 的异步打印
• 涵盖 QualityFactor、自定义或禁用打印预览对话框，以及通过 PrinterSettings 设置文档名称

书签与超链接

📄 阅读： references/bookmarks-and-hyperlinks.md

• 介绍如何通过 GoToBookmark 跳转到书签，以及如何从 PdfLoadedDocument 获取书签集合
• **🔒 必需 — 超链接验证：**提供了通过 HyperlinkPointerPressed 事件检查和验证超链接的关键代码示例。允许导航前，务必验证不可信 PDF 中超链接的来源，以防恶意重定向和注入攻击。安全实现模式请参阅参考文档。

本地化

📄 阅读： references/localization.md

• 涵盖如何在应用清单中设置默认语言，以及如何添加 .resw 资源文件以本地化 UI 字符串
• 介绍支持的资源文件名，以及如何更改上下文菜单语言

手势事件与交互

📄 阅读： references/utilities.md

• 涵盖超链接的指针事件（HyperlinkPointerPressed、HyperlinkPointerMoved），用于自定义交互处理
• 介绍如何使用 PageChanged 和 DocumentLoaded 事件来驱动导航后和加载后的工作流

实用工具与高级功能

📄 阅读： references/utilities.md

• 涵盖如何将 PDF 页面导出为 BitmapImage 对象（GetPage、GetPages）和图像流（ExportAsImage）
• 介绍如何访问垂直／水平滚动偏移量、如何通过 IPdfRenderer 使用 PDFium 自定义渲染器，以及 ShowPageNumber 和 VerticalScrollBarWidth 属性