印刷プレビュー UI のカスタマイズ

2024-09-12

このトピックでは、印刷プレビュー UI で印刷オプションと設定をカスタマイズする方法について説明します。印刷の詳細については、「アプリからの印刷」を参照してください。

重要な API: Windows.Graphics.Printing 名前空間、 PrintTask、 StandardPrintTaskOptions クラス、 Microsoft.UI.Xaml.Printing 名前空間、 PrintDocument クラス

印刷オプションをカスタマイズする

既定では、印刷プレビュー UI には、 ColorMode、 Copies、および Orientation 印刷オプションが表示されます。これに加えて、印刷プレビュー UI に追加できる一般的なプリンターオプションがいくつかあります。

これらのオプションは、 StandardPrintTaskOptions クラスで定義されます。印刷プレビュー UI に表示されるオプションの一覧にオプションを追加または削除できます。表示順序を変更し、ユーザーに表示される既定の設定を設定することもできます。

ただし、この方法で行った変更は、印刷プレビュー UI にのみ影響します。ユーザーは、印刷プレビュー UI で [詳細設定] をタップすることで、プリンターがサポートするすべてのオプションにいつでもアクセスできます。

表示するオプションを定義する

印刷用にアプリを登録する場合 (アプリからの Print を参照)、その登録の一部には、 PrintTaskRequested イベントハンドラーの定義が含まれます。印刷プレビュー UI に表示されるオプションをカスタマイズするコードが、PrintTaskRequested イベントハンドラーに追加されます。

PrintTaskRequested イベントハンドラーで PrintTask を作成すると、印刷プレビュー UI に表示されるオプション項目を含む DisplayedOptions リストを取得できます。この一覧を変更するには、オプションを挿入、追加、削除、または並べ替え直します。

注

アプリでは表示する印刷オプションを指定できますが、選択したプリンターでサポートされている印刷オプションのみが印刷プレビュー 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) を使用します。

カスタム印刷オプションを追加する

ここでは、新しいカスタム印刷オプションを作成し、オプションでサポートされる値の一覧を定義し、オプションを印刷プレビューに追加する方法を示します。この例では、ユーザーがカスタム印刷オプションを使用して、ページ上のテキストのみを印刷するか、画像のみを印刷するか、テキストと画像の両方を印刷するかを指定できます。オプションはドロップダウンリストに表示されます。

優れたユーザーエクスペリエンスを確保するために、システムでは、 PrintTaskRequested イベントを、 PrintTaskRequestedEventArgs.Request.Deadline で指定された時間内に処理する必要があります。そのため、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;

次に、ページ座標ハンドラーで選択したオプションを使用して、印刷プレビューのコンテンツを追加します。

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

次の方法で共有

印刷プレビュー UI のカスタマイズ

印刷オプションをカスタマイズする

表示するオプションを定義する

既定のオプションを指定する

カスタム印刷オプションを追加する

関連項目

フィードバック

その他のリソース