Pop-up

Pop-ups são uma maneira muito comum de apresentar informações a um usuário relacionado à tarefa atual. Os sistemas operacionais fornecem uma maneira de mostrar uma mensagem e exigir uma resposta do usuário, esses alertas normalmente são restritivos em termos do conteúdo que um desenvolvedor pode fornecer e também o layout e a aparência.

Observação

Se você quiser apresentar algo ao usuário que seja mais sutil, confira nossas opções do Toast e do Snackbar.

O Modo de Exibição Popup permite que os desenvolvedores criem sua própria interface do usuário personalizada e a apresentem aos usuários.

Como criar um Pop-up

Um Popup pode ser criado no XAML ou em C#:

XAML

Incluir o namespace XAML

Para usar o kit de ferramentas no XAML, o xmlns a seguir precisa ser adicionado à sua página ou exibição:

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

Portanto, o seguinte:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

Seria modificado para incluir o xmlns conforme o seguinte:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

Como definindo seu Pop-up

Observe que, se um Popup for criado no XAML, ele também deverá ter um arquivo code behind do código C#. Para entender por quê isso é necessário, consulte essa página de documentação do .NET MAUI.

A maneira mais fácil de criar um Popup é adicionar um novo .NET MAUI ContentView (XAML) ao seu projeto e, em seguida, alterar cada um dos arquivos para o seguinte:

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               x:Class="MyProject.SimplePopup">

    <VerticalStackLayout>
        <Label Text="This is a very important message!" />
    </VerticalStackLayout>
    
</toolkit:Popup>

public partial class SimplePopup : Popup
{
    public SimplePopup()
    {
        InitializeComponent();
    }
}

Importante

Se o arquivo code behind não for criado junto com a chamada para InitializeComponent, isso irá gerar uma exceção ao tentar exibir seu Popup.

C#

using CommunityToolkit.Maui.Views;

var popup = new Popup
{
    Content = new VerticalStackLayout
    {
        Children = 
        {
            new Label
            {
                Text = "This is a very important message!"
            }
        }
    }
};

Apresentando um pop-up

Um vez que o Popup for criado, ele poderá ser apresentado por meio do uso de nossos métodos de extensão Popup ou por meio da implementação de IPopupService desse kit de ferramentas.

Importante

Um Popup só pode ser exibida de umPage ou de uma implementação herdada de Page.

using CommunityToolkit.Maui.Views;

public class MyPage : ContentPage
{
    public void DisplayPopup()
    {
        var popup = new SimplePopup();

        this.ShowPopup(popup);
    }
}

Como fechar um Pop-up

Há duas maneiras diferentes de fechar um Popup: programaticamente ou tocando fora do pop-up.

Como fechando um Pop-up programaticamente

Para fechar um Popup, um desenvolvedor deve chamar Close ou CloseAsync no próprio Popup. Normalmente, isso é executado respondendo a um botão pressionado por um usuário.

Podemos aprimorar o exemplo XAML anterior adicionando um OKButton:

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               x:Class="MyProject.SimplePopup">

    <VerticalStackLayout>
        <Label Text="This is a very important message!" />
        <Button Text="OK" 
                Clicked="OnOKButtonClicked" />
    </VerticalStackLayout>
    
</toolkit:Popup>

No manipulador de eventos resultante, chamamos Close. Isso fechará programaticamente o Popup.

Observação

Close() é um método fire-and-forget. Ele será concluído e retornará ao thread de chamada antes que o sistema operacional ignore o Popup da tela. Se você precisar pausar a execução do código até que o sistema operacional tenha ignorado o Popup da tela, use CloseAsync() em vez disso.

public partial class MySimplePopup : Popup
{
    // ...

    void OnOKButtonClicked(object? sender, EventArgs e) => Close();
}

No manipulador de eventos resultante, chamamos CloseAsync. Isso fechará programaticamente o Popup, permitindo o chamador ao método await até que o sistema operacional tenha ignorado o Popup da tela.

public partial class MySimplePopup : Popup
{
    // ...

    async void OnOKButtonClicked(object? sender, EventArgs e) 
    {
        var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

         await CloseAsync(token: cts.Token);
         await Toast.Make("Popup Dismissed By Button").Show();
    }
}

Como tocar fora do Pop-up

Por padrão, um usuário pode tocar fora do Popup para ignorá-lo. Isso pode ser controlado por meio do uso da propriedade CanBeDismissedByTappingOutsideOfPopup. Definir essa propriedade como false irá impedir que um usuário seja capaz de fora dela.

Como retornar um resultado

Um desenvolvedor geralmente buscará uma resposta de seu usuário. O modo de exibição Popup permite que os desenvolvedores retornem um resultado que pode ser aguardado e atuado.

Podemos aprimorar nosso exemplo XAML original para mostrar como isso pode ser feito:

XAML

Adicionando dois novos botões ao XAML:

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               x:Class="MyProject.SimplePopup">

    <VerticalStackLayout>
        <Label Text="This is a very important message! Do you agree?" />
        <Button Text="Yes" 
                Clicked="OnYesButtonClicked" />
        <Button Text="No"
                Clicked="OnNoButtonClicked" />
    </VerticalStackLayout>
    
</toolkit:Popup>

Em seguida, adicione os seguintes manipuladores de eventos no C#:

async void OnYesButtonClicked(object? sender, EventArgs e)
{
    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
    await CloseAsync(true, cts.Token);
}

async void OnNoButtonClicked(object? sender, EventArgs e)
{
    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
    await CloseAsync(false, cts.Token);
}

O método Close permite que um valor object seja fornecido. Esse será o valor retornado resultante. Para aguardar o resultado, o método ShowPopupAsync deve ser usado da seguinte maneira:

using CommunityToolkit.Maui.Views;

public class MyPage : ContentPage
{
    public async Task DisplayPopup()
    {
        var popup = new SimplePopup();

        var result = await this.ShowPopupAsync(popup, CancellationToken.None);

        if (result is bool boolResult)
        {
            if (boolResult)
            {
                // Yes was tapped
            }
            else
            {
                // No was tapped
            }
        }
    }
}

Observação

Para lidar com o toque fora de um Popup enquanto também aguarda o resultado, você pode alterar o valor retornado por meio da propriedade ResultWhenUserTapsOutsideOfPopup.

Estilo

A classe Popup permite o uso de Estilosdo .NET MAUI para facilitar o compartilhamento de configurações visuais comuns em vários pop-ups.

O exemplo a seguir mostra como definir um estilo que se aplica ao exemplo SimplePopup da seção anterior.

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               xmlns:popups="clr-namespace:CommunityToolkit.Maui.Sample.Views.Popups"
               x:Class="MyProject.SimplePopup">

    <toolkit:Popup.Resources>
        <Style TargetType="{x:Type popups:SimplePopup}">
            <Setter Property="Size" Value="100,200" />
            <Setter Property="Color" Value="Green" />
            <Setter Property="HorizontalOptions" Value="Center" />
            <Setter Property="VerticalOptions" Value="Start" />
            <Setter Property="CanBeDismissedByTappingOutsideOfPopup" Value="True" />
        </Style>
    </toolkit:Popup.Resources>

    <VerticalStackLayout>
        <Label Text="This is a very important message! Do you agree?" />
        <Button Text="Yes" 
                Clicked="OnYesButtonClicked" />
        <Button Text="No"
                Clicked="OnNoButtonClicked" />
    </VerticalStackLayout>
    
</toolkit:Popup>

Observação

Ao criar um Style que se destina ao Popup, você deseja que ele se aplique a pop-ups personalizados como o exemploSimplePopup. Certifique-se de definir a propriedade ApplyToDerivedTypes na definição Style.

Propriedades

Propriedade	Type	Descrição
Anchor	View	Obtém ou define a âncora View. A Âncora é onde o pop-up será renderizado mais próximo. Quando uma Âncora é configurada, o pop-up será exibido centralizado sobre esse controle ou o mais próximo possível.
CanBeDismissedByTappingOutsideOfPopup	bool	Obtém ou define um valor que indica se o pop-up pode ser descartado tocando fora do pop-up. No Android – quando false, o botão voltar do hardware está desabilitado.
Color	Color	Obtém ou define o Pop-up Color. Essa cor define a cor da tela de fundo nativa do Popup, que é independente de qualquer cor de plano de fundo configurada no Content real.
Content	View	Obtém ou define o conteúdo View a ser renderizado no Popup.
HorizontalOptions	LayoutAlignment	Obtém ou define o LayoutAlignment para posicionar o Popup horizontalmente na tela.
Result	Task<object?>	Obtém o resultado final do Popup ignorado.
Size	Size	Obtém ou define a Size da Exibição Pop-up. O Pop-up sempre tentará restringir o tamanho real do Popup ao tamanho da Exibição, a menos que um Size seja especificado. Se o Popup usa as propriedades HorizontalOptions ou VerticalOptions que não são os padrões, a propriedade Size será necessária.
VerticalOptions	LayoutAlignment	Obtém ou define o LayoutAlignment para posicionar verticalmente o Popup na tela.

Eventos

Evento	Descrição
Closed	Ocorre quando o Popup é fechado.
Opened	Ocorre quando o Popup é aberto.

Exemplos

Você pode encontrar um exemplo desse recurso na prática em Aplicativo de exemplo do Kit de Ferramentas da Comunidade do .NET MAUI.

API

O código-fonte do Popup pode ser encontrado no repositório GitHub do .NET MAUI Community Toolkit.