Compartilhar via

Personalizar a interface do usuário para visualização de impressão

  • Artigo

Este tópico descreve como personalizar as opções e configurações de impressão na interface do usuário de visualização de impressão. Para obter mais informações sobre impressão, consulte Imprimir do seu aplicativo.

Personalizar opções de impressão

Por padrão, a interface do usuário de visualização de impressão mostra as opções de impressão ColorMode, Copies e Orientation. Além dessas, há várias outras opções comuns de impressora que você pode adicionar à interface do usuário de visualização de impressão:

Essas opções são definidas na classe StandardPrintTaskOptions . Você pode adicionar ou remover opções da lista de opções exibidas na interface do usuário de visualização de impressão. Você também pode alterar a ordem em que eles aparecem e definir as configurações padrão que são mostradas ao usuário.

No entanto, as modificações feitas dessa maneira afetam apenas a interface do usuário de visualização de impressão. O usuário sempre pode acessar todas as opções compatíveis com a impressora tocando em Mais configurações na interface do usuário de visualização de impressão.

Defina as opções a serem exibidas

Quando você registra seu aplicativo para impressão (consulte Imprimir do seu aplicativo), parte desse registro inclui a definição do manipulador de eventos PrintTaskRequested . O código para personalizar as opções exibidas na interface do usuário de visualização de impressão é adicionado ao manipulador de eventos PrintTaskRequested.

Depois de criar o PrintTask no manipulador de eventos PrintTaskRequested , você pode obter a lista DisplayedOptions , que contém os itens de opção mostrados na interface do usuário de visualização de impressão. Você pode modificar essa lista inserindo, anexando, removendo ou reordenando opções.

Observação

Embora seu aplicativo possa especificar qualquer opção de impressão a ser exibida, somente aquelas com suporte na impressora selecionada são mostradas na interface do usuário de visualização de impressão. A interface do usuário de impressão não mostrará opções que a impressora selecionada não dá suporte.

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

Especificar opções padrão

Você também pode definir os valores padrão das opções na interface do usuário de visualização de impressão. A linha de código a seguir, do último exemplo, define o valor padrão da opção MediaSize .

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

Observação

Ao definir os valores na lista DisplayedOptions, você usa o nome obtido de StandardPrintTaskOptions (por exemplo, StandardPrintTaskOptions.MediaSize).

Ao definir o valor padrão de uma opção, você usa PrintTaskOptions (por exemplo, PrintTaskOptions.MediaSize).

Adicionar opções de impressão personalizadas

Aqui, demonstramos como criar uma nova opção de impressão personalizada, definir uma lista de valores compatíveis com a opção e, em seguida, adicionar a opção à visualização de impressão. Neste exemplo, a opção de impressão personalizada permite que o usuário especifique se deseja imprimir apenas o texto na página, apenas a imagem ou o texto e a imagem. As opções são apresentadas em uma lista suspensa.

Para garantir uma boa experiência do usuário, o sistema exige que o aplicativo manipule o evento PrintTaskRequested dentro do tempo especificado por PrintTaskRequestedEventArgs.Request.Deadline. Portanto, usamos o manipulador PrintTaskRequested apenas para criar a tarefa de impressão. A personalização das configurações de impressão pode ser feita quando a origem do documento de impressão é solicitada. Aqui, usamos uma expressão lambda para definir o PrintTaskSourceRequestedHandler embutido, que fornece acesso mais fácil ao PrintTask.

Primeiro, obtenha um objeto PrintTaskOptionDetails e sua lista de DisplayedOptions. Use isso para adicionar a nova opção de impressão à interface do usuário de visualização de impressão.

Em seguida, para apresentar as opções de impressão personalizadas em uma lista suspensa, chame PrintTaskOptionDetails.CreateItemListOption para criar um objeto PrintCustomItemListOptionDetails . Crie a nova opção de impressão e inicialize a lista de valores de opção. Por fim, adicione a nova opção à lista DisplayedOptions e atribua um manipulador para o evento OptionChanged . Como você está apenas adicionando uma nova opção de impressão no final da lista de opções padrão, não é necessário limpar a lista DisplayedOptions; basta adicionar a nova opção.

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

As opções aparecem na interface do usuário de visualização de impressão na mesma ordem em que são anexadas, com a primeira opção mostrada na parte superior da janela. Neste exemplo, a opção personalizada é acrescentada por último para que apareça na parte inferior da lista de opções. No entanto, você pode colocá-lo em qualquer lugar da lista; As opções de impressão personalizadas não precisam ser adicionadas por último.

Quando o usuário alterar a opção selecionada em sua opção personalizada, use a opção selecionada para atualizar a imagem de visualização de impressão. Depois que o layout de visualização de impressão for atualizado, chame o método InvalidatePreview para redesenhar a imagem na interface do usuário de visualização de impressão, conforme mostrado aqui.

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

Para dar suporte ao uso das opções personalizadas em sua página, adicione uma enumeração para as opções disponíveis e uma variável de nível de página para manter a opção selecionada.

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

PageLayoutOption pageLayoutOption = PageLayoutOption.TextAndImages;

Em seguida, use a opção selecionada no manipulador de paginação em que você adiciona o conteúdo para a visualização de impressão.

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

Confira também