PrintTask 类

定义

命名空间:

Windows.Graphics.Printing

表示一个打印操作，包括要打印的内容，并提供对描述如何打印内容的信息的访问。

public ref class PrintTask sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class PrintTask final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class PrintTask

Public NotInheritable Class PrintTask

继承

Object Platform::Object IInspectable PrintTask

属性

ContractVersionAttribute MarshalingBehaviorAttribute

Windows 要求

设备系列	Windows 10 (在 10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox 中引入)
API contract	Windows.Foundation.UniversalApiContract (在 v1.0 中引入)

注解

PrintTask 对象表示 UWP 应用的打印操作。 应用负责创建通过 PrintManager 对象上的 PrintTaskRequested 事件请求的 PrintTask 。 若要创建 PrintTask ，必须提供任务的名称，以及用户准备好开始打印时调用的 PrintTaskSourceRequestedHandler 委托。

如果用户决定不打印任务，则无需请求文档源即可完成该任务。

PrintTask 以 Source 属性的形式包含对应用提供的打印文档源的引用。 此对象必须支持 IPrintDocumentSource 接口。

此外 ，PrintTask 包含一个 Options 属性，该属性保存对 PrintTaskOptions 对象的引用。 PrintTaskOptions 对象提供对所需打印内容格式的详细信息的访问。 PrintTaskOptions 还提供允许修改打印用户体验的各个方面的方法。 例如， PrintTaskOptions 允许应用定义哪些受支持的选项显示在打印体验的初始页上。

打印任务在创建后会经历一组特定的状态，应用可以使用这些状态更改向用户提供反馈。 大多数状态转换在 PrintTask 引发的事件中表示。 使用 PrintTaskRequest 对象上的 CreatePrintTask 方法创建打印任务以响应 PrintManager 上的 PrintTaskRequested 事件。 此时无法打印打印任务，因为尚未提供要打印的内容。 通常，当用户单击“设备”超级按钮或应用程序通过 PrintManager 上的 ShowPrintUIAsync 方法启动打印时，将引发 PrintTaskRequested 事件。

系统确定将打印任务后，将调用 PrintTaskSourceRequestedHandler 委托，以实际检索对 Document Source 对象的引用。 此时 ，PrintTask 已完全初始化。 如果用户决定不完成 PrintTask 对象表示的打印，则会引发完成事件，完成类型为 已放弃。

初始化后，打印用户体验负责帮助用户为打印内容选择不同的属性，例如纸张大小或双面打印。 当打印窗口初始化几乎完成时， PrintTask 将引发 Previewing 事件。 此时，用户可以通过打印窗口操作 PrintTaskOptions 对象的内容。 在预览阶段，用户可以随时更改设置的值，下次应用对内容进行分页时，必须考虑到这一点。 PrintTaskOptions 对象提供用于检索打印设置值的基本功能。 有关打印选项的更高级控制，请参阅 PrintTaskOptionDetails。 同样，用户可能会取消此操作，这将导致引发完成事件，完成类型为 “已取消”。

例如，当用户选择通过按打印窗口中的“打印”来实际启动打印时，打印任务将从 “正在预览 ”转换为 “正在提交” 状态，并引发 “提交” 事件。 然后，打印文档源将传递 MakeDocument 命令，并开始将页面提交到打印子系统的过程。 提交页面时，将引发 “进度” 事件。 应用可以选择使用正在进行的事件中的信息，让用户知道要打印的内容量。 将文档提交到打印子系统的过程完成后， PrintTask 将引发 Completion 事件。 此事件指示作业在提交过程中是成功提交、已取消还是失败。

下面是 UWP 打印示例中 的代码片段，演示如何指示默认打印设置的显示顺序：

protected override void PrintTaskRequested(PrintManager sender, PrintTaskRequestedEventArgs e)
{
    PrintTask printTask = null;
    printTask = e.Request.CreatePrintTask("C# Printing SDK Sample", sourceRequestedArgs =>
    {
        IList<string> displayedOptions = printTask.Options.DisplayedOptions;

        // Choose the printer options to be shown.
        // The order in which the options are appended determines the order in which they appear in the UI
        displayedOptions.Clear();
        displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Copies);
        displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Orientation);
        displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.MediaSize);
        displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Collation);
        displayedOptions.Add(Windows.Graphics.Printing.StandardPrintTaskOptions.Duplex);

        // Preset the default value of the printer option
        printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;

        // Print Task event handler is invoked when the print job is completed.
        printTask.Completed += async (s, args) =>
        {
            // Notify the user when the print operation fails.
            if (args.Completion == PrintTaskCompletion.Failed)
            {
                await scenarioPage.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
                {
                    MainPage.Current.NotifyUser("Failed to print.", NotifyType.ErrorMessage);
                });
            }
        };

        sourceRequestedArgs.SetSource(printDocumentSource);
    });
}

若要查看此的完整列表以及使用 PrintTask 的其他打印方案，请参阅 打印 和 UWP 打印示例。

版本历史记录

Windows 版本	SDK 版本	已添加值
1607	14393	IsPreviewEnabled

属性

Is3DManufacturingTargetEnabled	获取或设置一个值，该值指示 PrintTask 是否支持 3D 制造设备，如 3D 打印机。
IsPreviewEnabled	获取或设置一个值，该值指示 PrintTask 是否将显示打印预览。
IsPrinterTargetEnabled	获取或设置一个值，该值指示 PrintTask 是否支持打印机目标。
Options	检索打印任务的 PrintTaskOptions ，该任务定义如何为打印设置内容格式。
Properties	检索一组与 PrintTask 关联的属性。
Source	返回指向应用提供的 对象的指针，该对象表示要打印的内容。 此对象必须支持 IPrintDocumentSource 接口。

事件

Completed	打印任务完成时引发。
Previewing	当打印系统初始化打印预览模式时引发。
Progressing	引发 是为了提供有关已提交到打印子系统进行打印的打印内容的进度信息。
Submitting	当打印任务开始将内容提交到要打印的打印子系统时引发。

另请参阅

• PrintManager
• 打印