Windows-universal-samples 之 Printing 示例:UWP 应用打印支持完整实战指南
Windows-universal-samples 之 Printing 示例:UWP 应用打印支持完整实战指南
导读
本文以 Windows-universal-samples 仓库中的 Printing 示例 为核心,系统讲解 UWP 应用如何接入 Windows 打印体系:从注册打印契约、驱动分页与预览,到自定义标准打印选项、添加应用专属打印设置、按页码范围打印、打印与文档无关的备用内容(照片),以及禁用打印预览与按设备能力隐藏打印按钮。读完本文,你将掌握基于 PrintManager、PrintDocument 与 XAML RichTextBlockOverflow 文本流式分页的完整打印实现路径,并可直接对照仓库中的 C#/C++ 双语言源码落地到自己的应用。
示例概览:六大打印场景
Printing 示例演示了 UWP 应用添加打印支持的六种能力,分别对应仓库中的六个 Scenario 页面(C# 版位于 Samples/Printing/cs,C++ 版位于 Samples/Printing/cpp):
| 场景 | 文件 | 演示能力 |
|---|---|---|
| 场景 1:基础打印 | Scenario1Basic.xaml(.cs/.cpp) |
通过应用 UX 添加打印支持,注册打印契约并调用系统打印 UI |
| 场景 2:标准选项定制 | Scenario2StandardOptons.xaml(.cs) / Scenario2StandardOptions(C++) |
自定义打印对话框中向用户展示的打印机设置项及其顺序、默认值 |
| 场景 3:自定义选项 | Scenario3CustomOptions.xaml(.cs/.cpp) |
使用 PrintCustomItemListOptionDetails、PrintCustomToggleOptionDetails 添加应用专属打印选项 |
| 场景 4:页码范围 | Scenario4PageRange.xaml(.cs/.cpp) |
使用自定义打印模板打印用户指定的页面范围,含范围校验与错误提示 |
| 场景 5:打印照片 | Scenario5Photos.xaml(.cs/.cpp) |
打印不属于当前文档的备用内容(6 张照片),含尺寸/缩放/旋转控制 |
| 场景 6:禁用预览 | Scenario6DisablePreview.xaml(.cs/.cpp) |
通过 PrintTask.IsPreviewEnabled = false 关闭打印预览 |
原 README 还提到一个 JavaScript 版本的 Printing 示例(已归档至 archived 目录),说明该 API 曾面向 JS 开放,如今示例以 C#/C++ 为主。
系统要求与构建运行
- 系统要求:Windows 10 build 14393 及以上版本(即支持 UWP 打印 API 的 Windows 10 周年更新及后续版本)。
- 构建:下载整个 Samples 压缩包后务必解压全部内容(示例依赖根目录的 SharedContent 共享依赖);用 Visual Studio 打开对应语言子目录下的 .sln 解决方案文件(C# 为 Printing.sln,C++ 为 Printing.sln),按 Ctrl+Shift+B 或 Build > Build Solution 编译。
- 运行:按 F5 或 Debug > Start Debugging 调试运行;按 Ctrl+F5 或 Debug > Start Without Debugging 免调试运行。
打印基础:注册契约与三大事件
所有场景共享同一个 PrintHelper.cs(C++ 版对应 PrintHelper.cpp),它封装了 UWP 打印的核心流程,是理解本示例的钥匙。
注册与注销
RegisterForPrinting() 完成两件事:创建 PrintDocument 并挂接其三大事件,以及通过 PrintManager.GetForCurrentView() 获取当前视图的打印管理器并订阅 PrintTaskRequested:
public virtual void RegisterForPrinting()
{
printDocument = new PrintDocument();
printDocumentSource = printDocument.DocumentSource;
printDocument.Paginate += CreatePrintPreviewPages;
printDocument.GetPreviewPage += GetPrintPreviewPage;
printDocument.AddPages += AddPrintPages;
PrintManager printMan = PrintManager.GetForCurrentView();
printMan.PrintTaskRequested += PrintTaskRequested;
}
对应的 UnregisterForPrinting() 逐一解除事件订阅并清空承载打印页的隐藏画布(PrintCanvas)。每个 Scenario 页面在 OnNavigatedTo 中注册、在 OnNavigatedFrom 中注销,例如 Scenario1Basic.xaml.cs。
打印契约的三种事件回调
| 事件 | 职责 | 关键 API |
|---|---|---|
Paginate |
分页:根据打印机页面描述创建全部预览页,并上报页数 | GetPageDescription(0)、SetPreviewPageCount |
GetPreviewPage |
按需提供某一页的 UIElement 用于预览 |
SetPreviewPage(pageNumber, element) |
AddPages |
提交最终打印的全部页面 | AddPage(element)、AddPagesComplete() |
文本流式分页原理
场景 1~4 采用 XAML 的文本流式分页方案:第一页 PageToPrint.xaml 中的 RichTextBlock(TextContent)通过 OverflowContentTarget 绑定到 FirstLinkedContainer,再链到 ContinuationPageLinkedContainer。当文字超出首页容量时,RichTextBlockOverflow.HasOverflowContent 为 true,代码便通过 ContinuationPage.xaml 生成续页,把文本"流"到下一页:
lastRTBOOnPage = AddOnePrintPreviewPage(null, pageDescription);
while (lastRTBOOnPage.HasOverflowContent && lastRTBOOnPage.Visibility == Visibility.Visible)
{
lastRTBOOnPage = AddOnePrintPreviewPage(lastRTBOOnPage, pageDescription);
}
分页时通过 PrintTaskOptions.GetPageDescription(0) 获取打印机纸张尺寸 PageSize 与可成像区域 ImageableRect,据此计算打印边距与内容区尺寸:
double marginWidth = Math.Max(printPageDescription.PageSize.Width - printPageDescription.ImageableRect.Width,
printPageDescription.PageSize.Width * ApplicationContentMarginLeft * 2);
double marginHeight = Math.Max(printPageDescription.PageSize.Height - printPageDescription.ImageableRect.Height,
printPageDescription.PageSize.Height * ApplicationContentMarginTop * 2);
默认边距系数为 ApplicationContentMarginLeft = 0.075(内容占宽 85%)、ApplicationContentMarginTop = 0.03(内容占高 94%);若打印机 ImageableRect 比应用设定的边距更小,则以打印机实际可成像区域为准(取两者较大值)。
调用打印 UI 与失败反馈
ShowPrintUIAsync() 调用 PrintManager.ShowPrintUIAsync(),并捕获异常通过 MainPage.Current.NotifyUser 提示。PrintTaskRequested 处理器中通过 e.Request.CreatePrintTask("C# Printing SDK Sample", sourceRequested => sourceRequested.SetSource(printDocumentSource)) 创建打印任务并提交文档源;同时订阅 printTask.Completed,当 args.Completion == PrintTaskCompletion.Failed 时在 UI 线程上提示"Failed to print."。系统要求在 PrintTaskRequestedEventArgs.Request.Deadline 期限内完成该回调,因此示例刻意让该回调只负责创建任务,复杂的选项定制推迟到文档源请求阶段。
场景 1:最简打印入口
Scenario1Basic.xaml.cs 是最简实现:OnNavigatedTo 中先通过 PrintManager.IsSupported() 检测设备是否支持打印——不支持则隐藏打印按钮(InvokePrintingButton.Visibility = Visibility.Collapsed)并提示用户,支持则注册打印。随后创建 PageToPrint 并调用 PreparePrintContent 将其加入隐藏的 PrintCanvas,强制走一遍布局(InvalidateMeasure() + UpdateLayout())以便链接容器正确分配内容。点击打印按钮后调用 printHelper.ShowPrintUIAsync() 弹出系统打印对话框。
关键点:即使设备不支持打印,注册事件处理器也无害——"Printing-related event handlers will never be called if printing is not supported"。这套"检测能力 → 隐藏按钮 → 照常注册"的模式就是 README 所述"Removing the Print button if the device does not support printing"场景的实现。
场景 2:定制标准打印选项
Scenario2StandardOptons.xaml.cs 通过派生 StandardOptionsPrintHelper 覆写 PrintTaskRequested,利用 printTask.Options.DisplayedOptions 控制打印对话框中展示的标准选项及其顺序(追加顺序即 UI 显示顺序):
IList<string> displayedOptions = printTask.Options.DisplayedOptions;
displayedOptions.Clear();
displayedOptions.Add(StandardPrintTaskOptions.Copies);
displayedOptions.Add(StandardPrintTaskOptions.Orientation);
displayedOptions.Add(StandardPrintTaskOptions.MediaSize);
displayedOptions.Add(StandardPrintTaskOptions.Collation);
displayedOptions.Add(StandardPrintTaskOptions.Duplex);
// Preset the default value of the printer option
printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;
这里涉及的 StandardPrintTaskOptions 常用项包括:Copies(份数)、Orientation(方向)、MediaSize(纸张)、Collation(逐份打印)、Duplex(双面)、ColorMode(颜色)、CustomPageRanges(自定义页码范围)等。代码同时演示了如何预设默认值(将默认纸张设为美式 Legal)。
场景 3:添加应用专属打印选项
Scenario3CustomOptions.xaml.cs 是自定义选项的完整范例,使用命名空间 Windows.Graphics.Printing.OptionDetails 中的类型:
三种自定义选项控件
- 列表选项
PrintCustomItemListOptionDetails:CreateItemListOption("PageContent", "Pictures")创建"内容类型"下拉("Pictures and text" / "Pictures only" / "Text only"),并用AddItem(id, displayName)注册候选项,最后把选项 ID 加入DisplayedOptions使其显示。 - 开关选项
PrintCustomToggleOptionDetails:CreateToggleOption("Header", "Show header")创建布尔开关,通过Description属性向用户解释功能含义("Display a header on the first page"),TrySetValue(showHeader)设置默认值。 - 带图标与描述的列表选项:
margins.AddItem("WideMargins", "Wide", "Each margin is 20% of the paper size", await wideMarginsIconTask)——AddItem支持传入图标流(IRandomAccessStreamWithContentType)与描述文本。三个边距图标资源来自共享目录下的 wideMargins.svg、moderateMargins.svg、narrowMargins.svg。
选项变更驱动预览刷新
printDetailedOptions.OptionChanged += printDetailedOptions_OptionChanged 订阅选项变化事件:当 PageContent、Margins 或 Header 变化时,根据新值调整 ApplicationContentMarginTop/Left(宽 0.2 / 中 0.1 / 窄 0.05)、showHeader 与内容显示标志,并通过 printDocument.InvalidatePreview() 使预览失效、触发重新分页。代码还展示了动态错误提示:选择窄边距时设置 marginsOption.WarningText = "Narrow margins may not be supported by some printers",取消时清空。
按选项重构打印内容
覆写 AddOnePrintPreviewPage 在首页生成时根据 ShowText/ShowImage 标志切换网格列宽(GridUnitType.Star)、隐藏图片或文本、折叠头部,从而让"仅图片/仅文本/图文混合"真正反映到打印版面;覆写 CreatePrintPreviewPages 则先从 PrintTaskOptionDetails.Options["PageContent"].Value 解析出用户选择,转换为位标志枚举 DisplayContent(Text=1、Images=2、TextAndImages=3)后再调用基类分页。整个 PrintTaskRequested 使用 sourceRequestedArgs.GetDeferral() 延迟完成,确保在异步加载 SVG 图标流之后再 SetSource 与 deferral.Complete()。
场景 4:按页码范围打印
Scenario4PageRange.xaml.cs 演示自定义打印模板打印指定页范围:
启用范围选项
将 StandardPrintTaskOptions.CustomPageRanges 加入 DisplayedOptions,并通过 printTask.Options.PageRangeOptions 开放三种范围输入能力:
printTask.Options.PageRangeOptions.AllowCurrentPage = true;
printTask.Options.PageRangeOptions.AllowAllPages = true;
printTask.Options.PageRangeOptions.AllowCustomSetOfPages = true;
范围过滤与边界处理
覆写 AddPrintPages 读取 e.PrintTaskOptions.CustomPageRanges(IList<PrintPageRange>):
- 空列表 = 全部页面:
customPageRanges.Count == 0时逐页AddPage。 - 按范围过滤:遍历每个
PrintPageRange,从FirstPageNumber到LastPageNumber逐页添加;"当前页"是"自定义页集合"的特例,系统会把"Current page"选择转换为包含当前页的CustomPageRanges;对开放式区间(如"6-"),LastPageNumber取应用上次通过SetPreviewPageCount上报的页数。 - 越界与重复:用户输入文档中不存在的页码会被忽略(
pageRange.FirstPageNumber <= printPreviewPages.Count检查);重复输入同一页(如3-4;1;1)会按次数重复打印。页码是 1 基,而内部列表是 0 基,因此取页时用printPreviewPages[i - 1]。
范围校验与用户提示
ValidatePageRangeOption 在每次分页后及选项变化时被调用:若所有范围都超出文档页数,设置 pageRangeOption.ErrorText = "Those pages are not present in the document";若部分页码不存在,则设置 WarningText = "One of the ranges contains pages that are not present in the document"。示例注释明确说明:这类校验并非必需,不做校验的应用只需静默忽略不存在的页码即可。
场景 5:打印备用内容(照片)
Scenario5Photos.xaml.cs 展示如何打印不属于当前文档的内容——6 张照片(ms-appx:///Assets/photo{n}.jpg),并带来更精细的打印引擎实现。
照片尺寸与缩放选项
自定义选项 photoSize(Full Page / 4×6 / 5×7 / 8×10 英寸)与 scaling(Shrink To Fit / Crop),默认方向设为横向 printTask.Options.Orientation = PrintOrientation.Landscape。照片物理尺寸按 96 DPI 换算成像素:如 4×6 英寸即 4 * 96 × 6 * 96 像素。
版面计算与异步生成
CreatePrintPreviewPages 构造 PageDescription(页尺寸、边距、可视区、照片显示区、是否裁剪),基于打印机 ImageableRect 计算居中打印区域;若照片尺寸超出可视区(如在小纸上选 8×10),则显示 ErrorText = "Photo doesn’t fit on the selected paper" 并改用 PreviewUnavailable.xaml 作为"预览不可用"占位页(虚线边框 + "Preview unavailable" 字样),同时只上报 1 页预览。若版面参数未变化则跳过重建(currentPageDescription.Equals 优化)。
GetPrintPreviewPage 与 AddPrintPages 采用异步按需生成:页面由 GeneratePageAsync 在后台构造——读取位图、按纸张横竖方向旋转(BitmapRotation.Clockwise90/270Degrees)、按 Stretch.None 原尺寸或缩放居中排版。代码用一个 requestCount 请求票据解决异步竞态:分页时 Interlocked.Increment,若异步生成完成前发生了新的分页(票据过期),则丢弃结果不调用 SetPreviewPage。打印任务完成后还会 ClearPageCollection 并重置尺寸/缩放/版面描述为默认值,避免影响下次打印。
与文本流式方案的分工
场景 1~4 的 PreparePrintContent 以"首页 + 文本溢出续页"为模型,场景 5 不走该路径(PhotoSize.SizeFullPage 时照片铺满整页),因此 Scenario5Photos 的 OnNavigatedTo 只注册打印、不调用 PreparePrintContent——这正是 PrintHelper.cs 注释"Scenario 5 uses a different approach"的含义。
场景 6:禁用打印预览
Scenario6DisablePreview.xaml.cs 的关键一行:
// Choose not to show the preview by setting the property on PrintTask
printTask.IsPreviewEnabled = false;
设置后系统打印对话框不再展示预览。由于预览被禁用,Paginate 与 GetPreviewPage 事件不会被触发,分页工作整体转移到 AddPages 事件中完成:DisablePreviewPrintHelper.AddPrintPages 同步执行与 AddOnePrintPreviewPage 等价的 AddOnePrintPage 逻辑(同样基于 RichTextBlockOverflow.HasOverflowContent 循环生成续页),收集到 printPages 列表后逐页 AddPage 并 AddPagesComplete()。
设备能力检测与打印按钮兜底
六个场景页面统一采用如下"能力检测 + 兜底"模板(README 所述"Removing the Print button if the device does not support printing"的具体实现):
if (PrintManager.IsSupported())
{
MainPage.Current.NotifyUser("Print contract registered, use the Print button to print.", NotifyType.StatusMessage);
}
else
{
InvokePrintingButton.Visibility = Visibility.Collapsed;
MainPage.Current.NotifyUser("Printing is not supported.", NotifyType.ErrorMessage);
}
即使设备不支持打印也照常注册事件处理器(这些处理器永远不会被调用),从而保持代码路径统一、避免运行时分支。
双语言实现对照
示例同时提供 C# 与 C++(cppcx)两套完整实现,文件结构一一对应:C# 版在 Samples/Printing/cs,C++ 版在 Samples/Printing/cpp。两套代码共享同一组 XAML 视图页面(PageToPrint、ContinuationPage、PreviewUnavailable),核心 PrintHelper 类分别以 PrintHelper.cs 与 PrintHelper.cpp 实现,API 调用模式完全对齐(如 PrintManager::GetForCurrentView()、PrintDocument::DocumentSource、Paginate/GetPreviewPage/AddPages 事件委托)。共享资源(边距图标 SVG、示例图片 print_1.png)统一放在 Samples/Printing/shared 目录,通过项目文件(Printing.csproj / Printing.vcxproj)链接进两个工程。构建/运行方式与 README 描述一致:直接打开各自语言的 .sln 即可。
小结:把打印能力落地到自己的 UWP 应用
从本示例可以提炼出一套可复用的 UWP 打印接入模板:
- 注册:创建
PrintDocument,订阅Paginate/GetPreviewPage/AddPages,用PrintManager.GetForCurrentView()订阅PrintTaskRequested,在导航进入/离开时注册/注销。 - 内容准备:将可打印页面加入隐藏的
PrintCanvas强制布局;长文本用RichTextBlock.OverflowContentTarget+RichTextBlockOverflow链式续页,利用HasOverflowContent循环生成全部页面。 - 尺寸适配:读取
GetPageDescription(0)的PageSize与ImageableRect,以Math.Max权衡打印机可成像区域与应用边距,动态设置"纸面"与"可打印区"。 - 选项定制:通过
DisplayedOptions增删标准选项并排序;用CreateItemListOption/CreateToggleOption添加自定义选项;订阅OptionChanged配合InvalidatePreview()让设置即时生效。 - 特殊需求:页码范围用
PageRangeOptions.Allow*开启并校验CustomPageRanges;备用内容打印可绕过文本流式方案、按需异步生成页面;不需要预览时设置PrintTask.IsPreviewEnabled = false;不支持打印的设备上隐藏入口按钮。
依赖关系方面,示例依赖仓库根目录的 SharedContent 共享模板与资源,构建前务必确保该目录随仓库一同解压。以上全部代码与资源均可直接在仓库中查阅对应文件,作为自己实现打印功能的起点。