自訂預覽列印 UI
本主題說明如何在列印預覽 UI 中自訂列印選項和設定。 有關列印的更多資訊，請參閱從應用程式列印。
自訂列印選項
預設情況下，列印預覽 UI 顯示 ColorMode、Copies 和 Orientation 列印選項。 除此之外，您還可以將其他幾個常見印表機選項新增至列印預覽 UI：
這些選項在 StandardPrintTaskOptions 類別中定義。 您可以在列印預覽 UI 中顯示的選項清單中新增或移除選項。 您也可以變更它們的顯示順序，並設定向使用者顯示的預設設定。
不過，您以此方式所做的修改只會影響列印預覽 UI。 使用者一律可以透過點選 列印預覽 UI 中的 [更多設定 ] 來存取印表機支援的所有選項。
定義要顯示的選項
當您註冊應用程式以進行列印時（請參閱 從您的應用程式列印），該註冊的一部分包括定義 PrintTaskRequested 事件處理程式。 自定義列印預覽 UI 中顯示的選項的程式代碼會新增至 PrintTaskRequested 事件處理程式。
在 PrintTaskRequested 事件處理程式中建立 PrintTask 之後，您可以取得 DisplayedOptions 清單，其中包含列印預覽 UI 中顯示的選項專案。 您可以插入、附加、移除或重新排序選項來修改此清單。
注意
儘管您的應用程式可以指定要顯示的任何列印選項，但只有所選印表機支援的選項才會顯示在列印預覽 UI 中。 列印 UI 不會顯示所選印表機不支援的選項。
private void PrintTask_Requested(PrintManager sender, PrintTaskRequestedEventArgs args)
{
// Create the PrintTask.
// Defines the title and delegate for PrintTaskSourceRequested.
PrintTask printTask = args.Request.CreatePrintTask("WinUI 3 Printing example", PrintTaskSourceRequested);
// Handle PrintTask.Completed to catch failed print jobs.
printTask.Completed += PrintTask_Completed;
DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
{
InvokePrintingButton.IsEnabled = false;
});
// Customize options displayed in print preview UI.
// Get the list of displayed options.
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(StandardPrintTaskOptions.Copies);
displayedOptions.Add(StandardPrintTaskOptions.Orientation);
displayedOptions.Add(StandardPrintTaskOptions.MediaSize);
displayedOptions.Add(StandardPrintTaskOptions.Collation);
displayedOptions.Add(StandardPrintTaskOptions.Duplex);
// Preset the default value of the print media size option.
printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;
}
指定預設選項
您也可以在列印預覽 UI 中設定選項的預設值。 上一個範例中的下列程式碼行會設定 MediaSize 選項的預設值。
// Preset the default value of the print media size option.
printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;
注意
當您在 DisplayedOptions 清單中設定值時，請使用您從 StandardPrintTaskOptions 取得的名稱（例如 StandardPrintTaskOptions.MediaSize）。
當您設定選項的預設值時，您可以使用 PrintTaskOptions （例如 PrintTaskOptions.MediaSize）。
新增自訂列印選項
在這裡，我們將示範如何建立新的自定義列印選項、定義選項所支援的值清單，然後將選項新增至列印預覽。 在此範例中，自定義列印選項可讓使用者指定是否只列印頁面上的文字、只列印影像或文字和影像。 選項會顯示在下拉式清單中。
為了確保良好的用戶體驗，系統會要求應用程式在 PrintTaskRequestedEventArgs.Request.Deadline 所指定的時間內處理 PrintTaskRequested 事件。 因此，我們只使用 PrintTaskRequested 處理程式來建立列印工作。 當要求列印文件來源時，可以完成列印設定自定義。 在這裡，我們使用 Lambda 表達式 來定義 PrintTaskSourceRequestedHandler 內嵌，這可讓您更輕鬆地存取 PrintTask。
首先，取得 PrintTaskOptionDetails 物件及其 DisplayedOptions 清單。 您可以使用此選項，將新的列印選項新增至列印預覽UI。
接下來，若要在下拉式清單中呈現自定義列印選項，請呼叫 PrintTaskOptionDetails.CreateItemListOption 來建立 PrintCustomItemListOptionDetails 物件。 建立新的列印選項，並初始化選項值的清單。 最後，將新選項新增至 DisplayedOptions 清單，並指派 OptionChanged 事件的處理程式。 由於您只是在預設選項清單結尾新增列印選項，因此您不需要清除 DisplayedOptions 清單;只要新增選項即可。
private void PrintTask_Requested(PrintManager sender, PrintTaskRequestedEventArgs args)
{
// Create the PrintTask.
PrintTask printTask = null;
printTask = args.Request.CreatePrintTask("WinUI 3 Printing example", sourceRequestedArgs =>
{
PrintTaskSourceRequestedDeferral deferral =
sourceRequestedArgs.GetDeferral();
PrintTaskOptionDetails printDetailedOptions =
PrintTaskOptionDetails.GetFromPrintTaskOptions(printTask.Options);
IList<string> displayedOptions = printDetailedOptions.DisplayedOptions;
// Create a new list option.
PrintCustomItemListOptionDetails pageFormat =
printDetailedOptions.CreateItemListOption("PageContent", "Page content");
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;
sourceRequestedArgs.SetSource(printDocumentSource);
deferral.Complete();
});
// Handle PrintTask.Completed to catch failed print jobs.
printTask.Completed += PrintTask_Completed;
DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
{
InvokePrintingButton.IsEnabled = false;
});
}
這些選項會依照附加順序顯示在列印預覽 UI 中，第一個選項會顯示在視窗頂端。 在此範例中，自訂選項會新增到最後，以便它顯示在選項清單的底部。 但是，您可以將其放在清單中的任何位置; 自訂列印選項不需要最後新增。
當使用者在自定義選項中變更選取的選項時，請使用選取的選項來更新列印預覽影像。 更新列印預覽版面配置之後，呼叫 InvalidatePreview 方法來重新繪製列印預覽 UI 中的影像，如下所示。
void PrintDetailedOptions_OptionChanged(PrintTaskOptionDetails sender,
PrintTaskOptionChangedEventArgs args)
{
string optionId = args.OptionId as string;
if (string.IsNullOrEmpty(optionId))
{
return;
}
if (optionId == "PageContent")
{
PrintCustomItemListOptionDetails pageContentOption =
(PrintCustomItemListOptionDetails)sender.Options["PageContent"];
string pageContentValue = pageContentOption.Value.ToString();
if (pageContentValue == "PicturesOnly")
{
pageLayoutOption = PageLayoutOption.Images;
}
else if (pageContentValue == "TextOnly")
{
pageLayoutOption = PageLayoutOption.Text;
}
else
{
pageLayoutOption = PageLayoutOption.TextAndImages;
}
DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
{
printDocument.InvalidatePreview();
});
}
}
若要支援在您的頁面中使用自定義選項，請為可用的選項和頁面層級變數新增列舉，以保存選取的選項。
internal enum PageLayoutOption : int
{
Text = 1,
Images = 2,
TextAndImages = 3
}
PageLayoutOption pageLayoutOption = PageLayoutOption.TextAndImages;
然後，在 Paginate 處理程式中使用選取的選項，您可以在其中新增列印預覽的內容。
private void PrintDocument_Paginate(object sender, PaginateEventArgs e)
{
// Clear the cache of preview pages.
printPreviewPages.Clear();
// Get the PrintTaskOptions.
PrintTaskOptions printingOptions = ((PrintTaskOptions)e.PrintTaskOptions);
// Get the page description to determine the size of the print page.
PrintPageDescription pageDescription = printingOptions.GetPageDescription(0);
// Create the print layout.
StackPanel printLayout = new StackPanel();
printLayout.Width = pageDescription.PageSize.Width;
printLayout.Height = pageDescription.PageSize.Height;
printLayout.BorderBrush = new Microsoft.UI.Xaml.Media.SolidColorBrush(Microsoft.UI.Colors.DimGray);
printLayout.BorderThickness = new Thickness(48);
// Use the custom print layout options to determine
// which elements to add to the print page.
if (pageLayoutOption == PageLayoutOption.Images ||
pageLayoutOption == PageLayoutOption.TextAndImages)
{
Image printImage = new Image();
printImage.Source = printContent.Source;
printImage.Width = pageDescription.PageSize.Width / 2;
printImage.Height = pageDescription.PageSize.Height / 2;
printLayout.Children.Add(printImage);
}
if (pageLayoutOption == PageLayoutOption.Text ||
pageLayoutOption == PageLayoutOption.TextAndImages)
{
TextBlock imageDescriptionText = new TextBlock();
imageDescriptionText.Text = imageDescription.Text;
imageDescriptionText.FontSize = 24;
imageDescriptionText.HorizontalAlignment = HorizontalAlignment.Center;
imageDescriptionText.Width = pageDescription.PageSize.Width / 2;
imageDescriptionText.TextWrapping = TextWrapping.WrapWholeWords;
printLayout.Children.Add(imageDescriptionText);
}
// Add the print layout to the list of preview pages.
printPreviewPages.Add(printLayout);
// Report the number of preview pages created.
PrintDocument printDocument = (PrintDocument)sender;
printDocument.SetPreviewPageCount(printPreviewPages.Count,
PreviewPageCountType.Intermediate);
}
