Anpassen der Benutzeroberfläche für die Druckvorschau

Artikel
09/12/2024

In diesem Thema wird beschrieben, wie Sie die Druckoptionen und -einstellungen in der Druckvorschau-Benutzeroberfläche anpassen. Weitere Informationen zum Drucken finden Sie unter "Drucken aus Ihrer App".

Wichtige APIs: Windows.Graphics.Printing-Namespace, PrintTask, StandardPrintTaskOptions-Klasse, Microsoft.UI.Xaml.Printing-Namespace, PrintDocument-Klasse

Anpassen von Druckoptionen

Standardmäßig zeigt die Druckvorschau-Benutzeroberfläche die Druckoptionen ColorMode, Kopien und Ausrichtung an. Darüber hinaus gibt es mehrere andere gängige Druckeroptionen, die Sie der Druckvorschau-Benutzeroberfläche hinzufügen können:

Diese Optionen werden in der StandardPrintTaskOptions-Klasse definiert. Sie können optionen aus der Liste der Optionen hinzufügen oder entfernen, die in der Druckvorschau-Benutzeroberfläche angezeigt werden. Sie können auch die Reihenfolge ändern, in der sie angezeigt werden, und die Standardeinstellungen festlegen, die dem Benutzer angezeigt werden.

Die änderungen, die Sie auf diese Weise vornehmen, wirken sich jedoch nur auf die Druckvorschau-UI aus. Der Benutzer kann immer auf alle Optionen zugreifen, die der Drucker unterstützt, indem er auf der Druckvorschau-Benutzeroberfläche auf weitere Einstellungen tippt.

Definieren der anzuzeigenden Optionen

Wenn Sie Ihre App für den Druck registrieren (siehe Drucken aus Ihrer App), enthält dieser Teil die Definition des PrintTaskRequested-Ereignishandlers . Der Code zum Anpassen der Optionen, die in der Druckvorschau-Benutzeroberfläche angezeigt werden, wird dem PrintTaskRequested-Ereignishandler hinzugefügt.

Nachdem Sie die PrintTask im PrintTaskRequested-Ereignishandler erstellt haben, können Sie die DisplayedOptions-Liste abrufen, die die Optionselemente enthält, die in der Druckvorschau-Benutzeroberfläche angezeigt werden. Sie können diese Liste ändern, indem Sie Optionen einfügen, anfügen, entfernen oder neu sortieren.

Hinweis

Obwohl Ihre App alle anzuzeigenden Druckoptionen angeben kann, werden nur diejenigen angezeigt, die vom ausgewählten Drucker unterstützt werden, in der Druckvorschau-Benutzeroberfläche angezeigt. Die Druck-UI zeigt keine Optionen an, die der ausgewählte Drucker nicht unterstützt.

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

Angeben von Standardoptionen

Sie können auch die Standardwerte der Optionen in der Druckvorschau-Benutzeroberfläche festlegen. Die folgende Codezeile aus dem letzten Beispiel legt den Standardwert der MediaSize-Option fest.

// Preset the default value of the print media size option.
printTask.Options.MediaSize = PrintMediaSize.NorthAmericaLegal;

Hinweis

Wenn Sie die Werte in der Liste "DisplayedOptions" festlegen, verwenden Sie den Namen, den Sie aus StandardPrintTaskOptions abrufen (z . B. StandardPrintTaskOptions.MediaSize).

Wenn Sie den Standardwert einer Option festlegen, verwenden Sie PrintTaskOptions (z. B . PrintTaskOptions.MediaSize).

Hinzufügen von benutzerdefinierten Druckoptionen

Hier zeigen wir, wie Sie eine neue benutzerdefinierte Druckoption erstellen, eine Liste mit Werten definieren, die von der Option unterstützt werden, und fügen Sie dann die Option zur Seitenansicht hinzu. In diesem Beispiel kann der Benutzer mit der benutzerdefinierten Druckoption angeben, ob nur der Text auf der Seite, nur das Bild oder sowohl der Text als auch das Bild gedruckt werden soll. Die Optionen werden in einer Dropdownliste angezeigt.

Um eine gute Benutzererfahrung sicherzustellen, erfordert das System, dass die App das PrintTaskRequested-Ereignis innerhalb der von PrintTaskRequestedEventArgs.Request.Deadline angegebenen Zeit behandelt. Daher verwenden wir den PrintTaskRequested-Handler nur zum Erstellen der Druckaufgabe. Die Anpassung der Druckeinstellungen kann erfolgen, wenn die Druckdokumentquelle angefordert wird. Hier verwenden wir einen Lambda-Ausdruck , um den PrintTaskSourceRequestedHandler inline zu definieren, der einfacheren Zugriff auf die PrintTask ermöglicht.

Rufen Sie zunächst ein PrintTaskOptionDetails-Objekt und dessen Liste der DisplayedOptions ab. Verwenden Sie diese Option, um der Druckvorschau-Benutzeroberfläche die neue Druckoption hinzuzufügen.

Rufen Sie als Nächstes zum Darstellen der benutzerdefinierten Druckoptionen in einer Dropdownliste PrintTaskOptionDetails.CreateItemListOption auf, um ein PrintCustomItemListOptionDetails -Objekt zu erstellen. Erstellen Sie die neue Druckoption, und initialisieren Sie die Liste der Optionswerte. Fügen Sie schließlich der Liste "DisplayedOptions" die neue Option hinzu, und weisen Sie dem OptionChanged-Ereignis einen Handler zu. Da Sie einfach am Ende der Liste der Standardoptionen eine neue Druckoption hinzufügen, müssen Sie die DisplayedOptions-Liste nicht löschen. fügen Sie einfach die neue Option hinzu.

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

Die Optionen werden in der Druckvorschau-Ui in derselben Reihenfolge angezeigt, in der sie angefügt werden, wobei die erste Option oben im Fenster angezeigt wird. In diesem Beispiel wird die benutzerdefinierte Option zuletzt angefügt, sodass sie am Ende der Liste der Optionen angezeigt wird. Sie könnten es jedoch an einer beliebigen Stelle in der Liste platzieren; Benutzerdefinierte Druckoptionen müssen nicht zuletzt hinzugefügt werden.

Wenn der Benutzer die ausgewählte Option in Ihrer benutzerdefinierten Option ändert, verwenden Sie die ausgewählte Option, um das Druckvorschaubild zu aktualisieren. Rufen Sie nach dem aktualisierten Seitenansichtslayout die InvalidatePreview-Methode auf, um das Bild in der Druckvorschau-Benutzeroberfläche neu zu zeichnen, wie hier gezeigt.

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

Um die Verwendung der benutzerdefinierten Optionen auf Ihrer Seite zu unterstützen, fügen Sie eine Enumeration für die verfügbaren Optionen und eine Variable auf Seitenebene hinzu, um die ausgewählte Option aufzunehmen.

internal enum PageLayoutOption : int
{
    Text = 1,
    Images = 2,
    TextAndImages = 3
}

PageLayoutOption pageLayoutOption = PageLayoutOption.TextAndImages;

Verwenden Sie dann die ausgewählte Option im Paginatenhandler, in dem Sie den Inhalt für die Seitenansicht hinzufügen.

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

Freigeben über

Anpassen der Benutzeroberfläche für die Druckvorschau

Anpassen von Druckoptionen

Definieren der anzuzeigenden Optionen

Angeben von Standardoptionen

Hinzufügen von benutzerdefinierten Druckoptionen

Siehe auch

Zusätzliche Ressourcen