Anpassen der Benutzeroberfläche für die DruckvorschauCustomize the print preview UI

Wichtige APIsImportant APIs

In diesem Abschnitt wird beschrieben, wie die Druckoptionen und -einstellungen in der Benutzeroberfläche für die Druckvorschau angepasst werden.This section describes how to customize the print options and settings in the print preview UI. Weitere Informationen zur Druckfunktion finden Sie unter Drucken in Apps.For more info about printing, see Print from your app.

Tipp  die meisten Beispiele in diesem Thema basieren auf dem Druck Beispiel.Tip  Most of the examples in this topic are based on the print sample. Laden Sie das Druckbeispiel für die universelle Windows-Plattform (UWP) aus dem Repository Beispiele für Universelle Windows-Plattform auf GitHub herunter, um den vollständigen Code anzuzeigen.To see the full code, download the Universal Windows Platform (UWP) print sample from the Windows-universal-samples repo on GitHub.

 

Anpassen der DruckoptionenCustomize print options

Standardmäßig werden in der Benutzeroberfläche für die Druckvorschau die Druckoptionen ColorMode, Copies und Orientation angezeigt.By default, the print preview UI shows the ColorMode, Copies, and Orientation print options. Neben diesen Optionen sind weitere allgemeine Druckeroptionen verfügbar, die Sie der Benutzeroberfläche für die Druckvorschau hinzufügen können:In addition to those, there are several other common printer options that you can add to the print preview UI:

Diese Optionen werden in der StandardPrintTaskOptions-Klasse definiert.These options are defined in the StandardPrintTaskOptions class. Sie können in der Optionsliste, die in der Druckvorschau-Benutzeroberfläche angezeigt wird, Optionen hinzufügen oder entfernen.You can add to or remove options from the list of options displayed in the print preview UI. Sie können auch die Reihenfolge, in der die Optionen angezeigt werden, und die für den Benutzer angezeigten Standardeinstellungen ändern.You can also change the order in which they appear, and set the default settings that are shown to the user.

Die Änderungen, die Sie auf diese Weise vornehmen, betreffen allerdings nur die Druckvorschau-Benutzeroberfläche.However, the modifications that you make by using this method affect only the print preview UI. Der Benutzer kann stets auf alle vom Drucker unterstützten Optionen zugreifen, indem er in der Druckvorschau-Benutzeroberfläche auf Weitere Einstellungen tippt.The user can always access all of the options that the printer supports by tapping More settings in the print preview UI.

Beachten Sie  obwohl ihre APP beliebige Druckoptionen angeben kann, die angezeigt werden, werden nur die vom ausgewählten Drucker unterstützten Druckoptionen in der Benutzeroberfläche der Seitenansicht angezeigt.Note  Although your app can specify any print options to be displayed, only those that are supported by the selected printer are shown in the print preview UI. In der Druckbenutzeroberfläche werden keine Optionen angezeigt, die der ausgewählte Drucker nicht unterstützt.The print UI won't show options that the selected printer doesn't support.

 

Definieren der anzuzeigenden OptionenDefine the options to display

Wenn der Bildschirm der App geladen wird, wird die App für den Vertrag für „Drucken“ registriert.When the app's screen is loaded, it registers for the Print contract. Im Rahmen dieser Registrierung wird der PrintTaskRequested-Ereignishandler definiert.Part of that registration includes defining the PrintTaskRequested event handler. Der Code zum Anpassen der in der Druckvorschau-Benutzeroberfläche angezeigten Optionen wird dem PrintTaskRequested-Ereignishandler hinzugefügt.The code to customize the options displayed in the print preview UI is added to the PrintTaskRequested event handler.

Ändern Sie den PrintTaskRequested-Ereignishandler, um die printTask.options-Anweisungen einzubeziehen, mit denen die Druckeinstellungen konfiguriert werden, die Sie auf der Benutzeroberfläche für die Druckvorschau anzeigen möchten. Überschreiben Sie für den Bildschirm Ihrer App, in dem Sie eine benutzerdefinierte Liste von Druckoptionen anzeigen möchten, den PrintTaskRequested-Ereignishandler in der Basisklasse, um Code hinzuzufügen, der die Optionen angibt, die bei der Ausgabe des Bildschirms angezeigt werden sollen.Modify the PrintTaskRequested event handler to include the printTask.options instructions that configure the print settings that you want to display in the print preview UI.For the screen in your app for which you want to show a customized list of print options, override the PrintTaskRequested event handler in the helper class to include code that specifies the options to display when the screen is printed.

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

Wichtig  durch den Aufruf von displayedoptions. Clear() werden alle Druckoptionen aus der Benutzeroberfläche der Druckvorschau entfernt, einschließlich des Links Weitere Einstellungen .Important  Calling displayedOptions.clear() removes all of the print options from the print preview UI, including the More settings link. Fügen Sie alle Optionen an, die in der Druckvorschau-Benutzeroberfläche angezeigt werden sollen.Be sure to append the options that you want to show on the print preview UI.

Festlegen der StandardoptionenSpecify default options

Sie können auch die Standardwerte der Optionen in der Druckvorschau-Benutzeroberfläche festlegen.You can also set the default values of the options in the print preview UI. Die folgende Codezeile aus dem letzten Beispiel legt den Standardwert der Option MediaSize fest.The following line of code, from the last example, sets the default value of the MediaSize option.

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

Hinzufügen neuer DruckoptionenAdd new print options

In diesem Abschnitt werden die Erstellung einer neuen Druckoption, die Definition einer Liste von Werten, die von dieser Option unterstützt werden, und das Hinzufügen der Option zur Druckvorschau gezeigt.This section shows how to create a new print option, define a list of values that the option supports, and then add the option to the print preview. Fügen Sie die Druckoption wie im vorherigen Abschnitt gezeigt im PrintTaskRequested-Ereignishandler hinzu.As in the previous section, add the new print option in the PrintTaskRequested event handler.

Rufen Sie zunächst ein PrintTaskOptionDetails-Objekt ab.First, get a PrintTaskOptionDetails object. Dies wird verwendet, um die neue Druckoption zur Benutzeroberfläche für die Druckvorschau hinzuzufügen.This is used to add the new print option to the print preview UI. Löschen Sie dann die Liste der Optionen, die in der Druckvorschau-Benutzeroberfläche angezeigt werden, und fügen Sie die Optionen hinzu, die angezeigt werden sollen, wenn der Benutzer in der App druckt.Then clear the list of options that are shown in the print preview UI and add the options that you want to display when the user wants to print from the app. Anschließend erstellen Sie die neue Druckoption und initialisieren die Liste der Optionswerte.After that, create the new print option and initialize the list of option values. Abschließend fügen Sie die neue Option hinzu und weisen dem OptionChanged-Ereignis einen Handler zu.Finally, add the new option and assign a handler for the OptionChanged event.

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

Die Optionen werden in der Druckvorschau-Benutzeroberfläche in der Reihenfolge angezeigt, in der sie hinzugefügt werden, wobei die erste Option oben im Fenster erscheint.The options appear in the print preview UI in the same order they are appended, with the first option shown at the top of the window. In diesem Beispiel wird die benutzerdefinierte Option als Letztes hinzugefügt, sodass sie am Ende der Optionsliste erscheint.In this example, the custom option is appended last so that it appears at the bottom of the list of options. Sie könnten sie jedoch an einer beliebigen Stelle der Liste platzieren. Benutzerdefinierte Druckoptionen müssen nicht zuletzt hinzugefügt werden.However, you could put it anywhere in the list; custom print options don't need to be added last.

Wenn der Benutzer die ausgewählte Option in Ihrer benutzerdefinierten Druckoption ändert, aktualisieren Sie das Druckvorschaubild.When the user changes the selected option in your custom option, update the print preview image. Rufen Sie die InvalidatePreview-Methode auf, um das Bild in der Druckvorschau-Benutzeroberfläche neu zu zeichnen, wie unten gezeigt.Call the InvalidatePreview method to redraw the image in the print preview UI, as shown below.

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