Настройка пользовательского интерфейса предварительной версии печати

Статья
09/12/2024

В этом разделе описывается настройка параметров и параметров печати в пользовательском интерфейсе предварительного просмотра печати. Дополнительные сведения о печати см. в разделе "Печать" из приложения.

Важные API: пространство имен Windows.Graphics.Print, PrintTask, класс StandardPrintTaskOptions, пространство имен Microsoft.UI.Xaml.Printing, класс PrintDocument

Настройка параметров печати

По умолчанию в пользовательском интерфейсе предварительного просмотра печати отображаются параметры печати ColorMode, "Копии" и "Ориентация". Помимо них, есть несколько других распространенных параметров принтера, которые можно добавить в пользовательский интерфейс предварительного просмотра печати:

Эти параметры определены в классе StandardPrintTaskOptions . Можно добавить или удалить параметры из списка параметров, отображаемых в пользовательском интерфейсе предварительного просмотра печати. Вы также можете изменить порядок их отображения и задать параметры по умолчанию, отображаемые пользователю.

Однако изменения, которые вы делаете таким образом, влияют только на пользовательский интерфейс предварительного просмотра печати. Пользователь всегда может получить доступ ко всем параметрам, поддерживаемым принтером, нажав кнопку "Дополнительные параметры " в пользовательском интерфейсе предварительного просмотра печати.

Определение параметров для отображения

При регистрации приложения для печати (см. печать из приложения), часть этой регистрации включает определение обработчика событий PrintTaskRequested . Код для настройки параметров, отображаемых в пользовательском интерфейсе предварительного просмотра печати, добавляется в обработчик событий PrintTaskRequested.

После создания PrintTask в обработчике событий PrintTaskRequested можно получить список DisplayedOptions, содержащий элементы параметров, отображаемые в пользовательском интерфейсе предварительного просмотра печати. Этот список можно изменить, вставляя, добавляя, удаляя или перезаписывая параметры.

Примечание.

Хотя приложение может указать любые параметры печати, которые будут отображаться, отображаются только те, которые поддерживаются выбранным принтером, отображаются в пользовательском интерфейсе предварительного просмотра печати. Пользовательский интерфейс печати не отображает параметры, которые выбранный принтер не поддерживает.

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

Указание параметров по умолчанию

Можно также задать значения по умолчанию параметров в пользовательском интерфейсе предварительного просмотра печати. Следующая строка кода из последнего примера задает значение по умолчанию параметра 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 только для создания задачи печати. Параметры печати можно настроить при запросе источника документа печати. Здесь мы используем лямбда-выражение для определения встроенной строки PrintTaskSourceRequestedHandler, что упрощает доступ к PrintTask.

Сначала получите объект PrintTaskOptionDetails и его список DisplayedOptions. Этот параметр используется для добавления нового параметра печати в пользовательский интерфейс предварительного просмотра печати.

Затем, чтобы представить настраиваемые параметры печати в раскрывающемся списке, вызовите 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;
    });
}

Параметры отображаются в пользовательском интерфейсе предварительного просмотра печати в том же порядке, что и вверху окна. В этом примере настраиваемый параметр добавляется последним, чтобы он отображался в нижней части списка параметров. Тем не менее, вы можете поместить его в любое место в списке; Параметры настраиваемой печати не нужно добавлять последнее.

Когда пользователь изменяет выбранный параметр в пользовательском параметре, используйте выбранный параметр, чтобы обновить изображение предварительного просмотра печати. После обновления макета предварительного просмотра печати вызовите метод InvalidatePreview для перераспределения изображения в пользовательском интерфейсе предварительного просмотра печати, как показано здесь.

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

Поделиться через

Настройка пользовательского интерфейса предварительной версии печати

Настройка параметров печати

Определение параметров для отображения

Указание параметров по умолчанию

Добавление настраиваемых параметров печати

См. также

Дополнительные ресурсы