自訂預覽列印 UI

  • 發行項

本主題說明如何在列印預覽 UI 中自訂列印選項和設定。 有關列印的更多資訊，請參閱從應用程式列印。

提示 本主題中的大多數範例都是以通用 Windows 平台 (UWP) 列印範例為基礎。

重要 API

自訂列印選項

預設情況下，列印預覽 UI 顯示 ColorMode、Copies 和 Orientation 列印選項。 除此之外，您還可以將其他幾個常見印表機選項新增至列印預覽 UI：

這些選項在 StandardPrintTaskOptions 類別中定義。 您可以在列印預覽 UI 中顯示的選項清單中新增或移除選項。 您也可以變更它們的顯示順序，並設定向使用者顯示的預設設定。

但是，使用此方法所做的修改僅會影響列印預覽 UI。 使用者隨時可以透過點擊列印預覽 UI 中的 **更多設定* 來存取印表機支援的所有選項。

注意

儘管您的應用程式可以指定要顯示的任何列印選項，但只有所選印表機支援的選項才會顯示在列印預覽 UI 中。 列印 UI 不會顯示所選印表機不支援的選項。

定義要顯示的選項

當應用程式的螢幕載入時，它會註冊列印合約。 該註冊的一部分包括定義 PrintTaskRequested 事件處理常式。 用於自訂列印預覽 UI 中顯示的選項的程式碼已新增至 **PrintTaskRequested*- 事件處理常式中。

修改 PrintTaskRequested 事件處理常式以包含 printTask.options 指令，這些指令配置要在列印預覽 UI 中顯示的列印設定。對於要顯示自訂列印選項清單的應用程式螢幕，請覆寫說明程式類別中的 * *PrintTaskRequested*- 事件處理常式，以包含指定列印畫面時要顯示的選項的程式碼。

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);
   });
}

重要

呼叫 displayedOptions.clear() 會從列印預覽 UI 中刪除所有列印選項，包括 **更多設定*- 連結。 請務必附加要在列印預覽 UI 上顯示的選項。

指定預設選項

您也可以在列印預覽 UI 中設定選項的預設值。 上一個範例中的下列程式碼行會設定 MediaSize 選項的預設值。

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

新增列印選項

在這裡，我們會說明如何建立新的列印選項、定義選項支援的值清單，然後將選項新增至列印預覽。 與上一節一樣，在 PrintTaskRequested 事件處理常式中新增新的列印選項。

首先，取得 PrintTaskOptionDetails 物件。 這用於將新的列印選項新增至列印預覽 UI。 然後清除列印預覽 UI 中顯示的選項清單，並新增使用者想要從應用程式列印時，您要顯示的選項。 之後，建立新的列印選項，並初始化選項值清單。 最後，新增選項並為 **OptionChanged*- 事件指派處理常式。

protected override void PrintTaskRequested(PrintManager sender, PrintTaskRequestedEventArgs e)
{
   PrintTask printTask = null;
   printTask = e.Request.CreatePrintTask("C# Printing SDK Sample", sourceRequestedArgs =>
   {
         PrintTaskOptionDetails printDetailedOptions = PrintTaskOptionDetails.GetFromPrintTaskOptions(printTask.Options);
         IList<string> displayedOptions = printDetailedOptions.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.ColorMode);

         // Create a new list option
         PrintCustomItemListOptionDetails pageFormat = printDetailedOptions.CreateItemListOption("PageContent", "Pictures");
         pageFormat.AddItem("PicturesText", "Pictures and text");
         pageFormat.AddItem("PicturesOnly", "Pictures only");
         pageFormat.AddItem("TextOnly", "Text only");

         // Add the custom option to the option list
         displayedOptions.Add("PageContent");

         printDetailedOptions.OptionChanged += printDetailedOptions_OptionChanged;

         // 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);
   });
}

這些選項會依照附加順序顯示在列印預覽 UI 中，第一個選項會顯示在視窗頂端。 在此範例中，自訂選項會新增到最後，以便它顯示在選項清單的底部。 但是，您可以將其放在清單中的任何位置; 自訂列印選項不需要最後新增。

當使用者變更自訂選項中的選取選項時，更新列印預覽影像。 呼叫 InvalidatePreview 方法在列印預覽 UI 中重繪影像，如下所示。

async void printDetailedOptions_OptionChanged(PrintTaskOptionDetails sender, PrintTaskOptionChangedEventArgs args)
{
   // Listen for PageContent changes
   string optionId = args.OptionId as string;
   if (string.IsNullOrEmpty(optionId))
   {
         return;
   }

   if (optionId == "PageContent")
   {
         await scenarioPage.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
         {
            printDocument.InvalidatePreview();
         });
   }
}

另請參閱