Compartir a través de

Popup

  • Artículo

Los elementos emergentes son una forma muy común de presentar información a un usuario que se relaciona con su tarea actual. Los sistemas operativos proporcionan una manera de mostrar un mensaje y requieren una respuesta del usuario; estas alertas suelen ser restrictivas en términos del contenido que un desarrollador puede proporcionar y también el diseño y la apariencia.

Nota:

Si quiere presentar algo al usuario que es más sutil, consulte nuestras opciones Toast y Snackbar.

La vista Popup permite a los desarrolladores crear su propia interfaz de usuario personalizada y presentarla a sus usuarios.

Creación de un elemento elemento emergente

Se puede crear un Popup en XAML o C#:

XAML

Incluir el espacio de nombres XAML

Para usar el kit de herramientas en XAML, es necesario agregar el siguiente xmlns a la página o vista:

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

Por lo tanto, el siguiente:

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

Se modificaría para incluir el xmlns de la siguiente manera:

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

Definición del elemento emergente

Tenga en cuenta que, si se crea Popup en XAML, también debe tener un archivo de código subyacente de C#. Para comprender por qué esto es necesario, consulte esta página de documentación de .NET MAUI.

La manera más fácil de crear un Popup es agregar un nuevo .NET MAUI ContentView (XAML) al proyecto y, a continuación, cambiar cada uno de los archivos a lo siguiente:

<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

Si el archivo de código subyacente no se crea junto con la llamada a InitializeComponent, se producirá una excepción al intentar mostrar el Popup.

C#

using CommunityToolkit.Maui.Views;

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

Presentación de un elemento emergente

Una vez compilado Popup, se puede presentar a través del uso de nuestros métodos de extensión Popup o a través de la implementación IPopupService de este kit de herramientas.

Importante

Un elemento Popup solo se puede mostrar desde un elemento Page o una implementación que hereda de Page.

using CommunityToolkit.Maui.Views;

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

        this.ShowPopup(popup);
    }
}

Creación de un elemento emergente

Hay dos maneras diferentes de que un Popup pueda cerrarse: mediante programación o pulsando fuera del elemento emergente.

Cierre de un elemento emergente mediante programación

Para cerrar un Popup, el desarrollador debe llamar a Close o CloseAsync en el mismo Popup. Normalmente, esto se realiza respondiendo a una pulsación de botón de un usuario.

Para mejorar el ejemplo de XAML anterior, agregue Button:

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

En el controlador de eventos resultante, llamamos a Close, esto cerrará mediante programación el elemento Popup.

Nota:

Close() es un método de tipo "disparar y olvidar". Se completará y volverá al subproceso que realiza la llamada antes de que el sistema operativo haya descartado Popup de la pantalla. Si necesita pausar la ejecución del código hasta que el sistema operativo haya descartado Popup desde la pantalla, use en su lugar CloseAsync().

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

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

En el controlador de eventos resultante, llamamos a CloseAsync, esto cerrará mediante programación Popup, que permite al autor de la llamada await al método hasta que el sistema operativo haya descartado el elemento Popup de la pantalla.

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

Pulsar fuera del elemento emergente

De forma predeterminada, el usuario puede pulsar fuera del Popup para descartarlo. Esto se puede controlar mediante el uso de la propiedad CanBeDismissedByTappingOutsideOfPopup. Establecer esta propiedad en false impedirá que un usuario pueda descartarlo Popup pulsando fuera de ella.

Devolución de un resultado

Un desarrollador buscará con bastante frecuencia una respuesta de su usuario, la vista Popup permite a los desarrolladores devolver un resultado que se puede esperar y sobre el que se puede actuar.

Podemos mejorar nuestro ejemplo XAML original para mostrar cómo se puede lograr esto:

XAML

Al agregar dos botones nuevos al 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>

A continuación, al agregar los siguientes controladores de eventos en 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);
}

El método Close permite proporcionar un valor object, que será el valor devuelto resultante. Para esperar el resultado, el método ShowPopupAsync debe usarse de la siguiente manera:

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

Nota:

Para controlar la pulsación fuera de un Popup cuando también espera el resultado, puede cambiar el valor que se devuelve a través de la propiedad ResultWhenUserTapsOutsideOfPopup.

Aplicación de estilos

La clase Popup permite el uso de estilos de .NET MAUI para facilitar el uso de configuraciones visuales comunes en varios elementos emergentes.

En el ejemplo siguiente se muestra cómo definir un estilo que se aplica al ejemplo SimplePopup de la sección 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>

Nota:

Al crear un Style que tenga como destino Popup y desee aplicarlo a elementos emergentes personalizados como en el ejemplo SimplePopup, asegúrese de establecer la propiedad ApplyToDerivedTypes en la definición Style.

Propiedades

Propiedad Tipo Descripción
Anchor View Obtiene o establece el delimitador View. El delimitador es donde el elemento emergente se representará más cerca. Cuando se configura un delimitador, el elemento emergente aparecerá centrado sobre ese control o lo más cercano posible.
CanBeDismissedByTappingOutsideOfPopup bool Obtiene o establece un valor que indica si el elemento emergente se puede descartar pulsando fuera del elemento emergente. En Android: cuando es false, se deshabilita el botón Atrás de hardware.
Color Color Obtiene o establece el Color del elemento emergente. Este color establece el color de fondo nativo de Popup, que es independiente de cualquier color de fondo configurado en el objeto Content real.
Content View Obtiene o establece el contenido View que se va a representar en Popup.
HorizontalOptions LayoutAlignment Obtiene o establece LayoutAlignment para colocar horizontalmente Popup en la pantalla.
Result Task<object?> Obtiene el resultado final del Popup descartado.
Size Size Obtiene o establece el Size de la pantalla emergente. El elemento emergente siempre intentará restringir el tamaño real del Popup al tamaño de la vista a menos que se especifique Size. Si Popup usa las propiedades HorizontalOptions o VerticalOptions que no son los valores predeterminados, se requiere esta propiedad Size.
VerticalOptions LayoutAlignment Obtiene o establece LayoutAlignment para colocar verticalmente Popup en la pantalla.

Eventos

Evento Descripción
Closed Se produce cuando se cierra el Popup.
Opened Se produce cuando se abre el Popup.

Ejemplos

Puede encontrar un ejemplo de esta característica en acción en la Aplicación de muestra del kit de herramientas de la comunidad de .NET MAUI.

API

Puede encontrar el código fuente de Popup en el repositorio de GitHub del Kit de herramientas de la comunidad de .NET MAUI.