Popup

Los elementos emergentes son una forma 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.

.NET MAUI Community Toolkit proporciona 2 enfoques para crear un Popup que se puede mostrar en una aplicación .NET MAUI. Estos enfoques dependerán del caso de uso. Esta página se centra en la forma más sencilla de Popup : simplemente representar una superposición en una aplicación. Para obtener un enfoque más avanzado, habilitando la capacidad de devolver un resultado de Popup, consulte Popup : Devolver un resultado.

Mostrar una ventana emergente

El .NET MAUI Community Toolkit proporciona varios enfoques para mostrar un Popup en una aplicación .NET MAUI.

1. En un ContentPage, llama al método de extensión this.ShowPopupAsync() y pasa un View para mostrar en el elemento emergente
   • Nota: Para personalizar aún más un elemento emergente, consulte la documentación de PopupOptions.
2. Devolver un resultado de Popup
   • Consulte la documentación de Elemento emergente - Resultados devueltos.
3. Uso del PopupService
   • Consulte la documentación de PopupService.

En la documentación a continuación se muestra la manera más sencilla de mostrar un Popup mediante la extensión del método .ShowPopupAsync(). Este método devuelve un Task<IPopupResult> que se completará cuando se cierre la ventana emergente. El PopupOptions proporcionado es opcional.

public class MainPage : ContentPage
{
    // ...

    async void DisplayPopupButtonClicked(object? sender, EventArgs e)
    {
        await this.ShowPopupAsync(new Label
        {
            Text = "This is a very important message!"
        }, new PopupOptions
        {
            CanBeDismissedByTappingOutsideOfPopup = false,
            Shape = new RoundRectangle
            {
                CornerRadius = new CornerRadius(20, 20, 20, 20),
                StrokeThickness = 2,
                Stroke = Colors.LightGray
            }
        })

        /**** Alternatively, Shell.Current can be used to display a Popup

        await Shell.Current.ShowPopupAsync(new Label
        {
            Text = "This is a very important message!"
        }, new PopupOptions
        {
            CanBeDismissedByTappingOutsideOfPopup = false,
            Shape = new RoundRectangle
            {
                CornerRadius = new CornerRadius(20, 20, 20, 20),
                StrokeThickness = 2,
                Stroke = Colors.LightGray
            }
        })
        ****/
    }
}

Como alternativa, se puede crear un Popup en XAML o C# y pasarlo a ShowPopupAsync().

Creación de una ventana emergente en XAML

La manera más fácil de crear un Popup es agregar un nuevo .NET MAUI ContentView (XAML) a tu proyecto. Esto creará 2 archivos: un archivo *.xaml y un archivo *.xaml.cs .

Reemplace el contenido de *.xaml por lo siguiente:

<ContentView
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    x:Class="MyProject.SimplePopup"
    Padding="10">

    <Label Text="This is a very important message!" />
    
</ContentView>

Los valores predeterminados de HorizontalOptions y VerticalOptions darán lugar a que Popup se muestre en el centro de la página que superpone.

Aparecerá un elemento emergente con un valor predeterminado Padding de 15. Para mejorar el aspecto de SimplePopup, se ha agregado un valor de 10 a Padding.

Presentación de una ventana emergente creada en XAML

Una vez creado el Popup en XAML, se puede presentar a través del uso de los métodos de extensión Popup usados en un Page, Shell o una INavigation, o a través de la implementación IPopupService de este conjunto de herramientas.

En el ejemplo siguiente se muestra cómo crear instancias y mostrar el SimplePopup creado en el ejemplo anterior a través de un método de extensión en un ContentPage.

using CommunityToolkit.Maui.Views;

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

        await this.ShowPopupAsync(popup, PopupOptions.Empty, token);
    }
}

Creación de un elemento emergente

Hay dos maneras diferentes en las que se puede cerrar un Popup:

1. Una ventana emergente se puede cerrar de forma programada
2. Se puede cerrar una ventana emergente cuando un usuario toca fuera de la ventana emergente.
   • Nota Para evitar que una ventana emergente se cierre cuando un usuario toca fuera de ella, establezca PopupOptions.CanBeDismissedByTappingOutsideOfPopup en false.

1. Cierre de un elemento emergente mediante programación

Existen 3 opciones para cerrar un Popup de forma programática.

1. En un ContentPage, utiliza el método de extensión this.ClosePopupAsync().
2. En una aplicación que usa Shell, utilice el método de extensión Shell.Current.ClosePopupAsync()
3. Utilice el PopupService
   • Consulte la documentación de PopupService.

En el ejemplo siguiente, se muestra cómo usar this.ClosePopupAsync() en .ContentPage Para obtener información sobre cómo usar PopupService para cerrar un elemento emergente, consulte la documentación de PopupService.

using CommunityToolkit.Maui.Views;

public class MyPage : ContentPage
{
    public async Task DisplayAutomaticallyClosingPopup(Timespan displayTimeSpan, CancellationToken token)
    {
        var popup = new SimplePopup();

        // This Popup is closed programmatically after 2 seconds
        this.ShowPopup(popup, new PopupOptions
        {
            CanBeDismissedByTappingOutsideOfPopup = false
        });

        await Task.Delay(TimeSpan.FromSeconds(displayTimeSpan), token);

        await this.ClosePopupAsync(token);

        /**** Alternatively, Shell.Current can be used to close a Popup
        Shell.Current.ShowPopup(popup, new PopupOptions
        {
            CanBeDismissedByTappingOutsideOfPopup = false
        });

        await Task.Delay(TimeSpan.FromSeconds(displayTimeSpan), token);

        await Shell.Current.ClosePopupAsync(token);
        ***/

    }
}

2. 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 PopupOptions.CanBeDismissedByTappingOutsideOfPopup. Establecer esta propiedad en false impedirá que un usuario pueda descartarlo Popup pulsando fuera de ella. Consulte PopupOptions para obtener más detalles.

PopupOptions

Los PageOverlayColor, Shape, Shadow se pueden personalizar para elemento emergente. Consulte PopupOptions para obtener más detalles.

Establecer valores predeterminados de ventana emergente

Para anular los valores predeterminados de cada Popup en su aplicación, puede llamar a .SetPopupDefaults() y .SetPopupOptionsDefaults() al inicializar .NET MAUI Community Toolkit.

El DefaultPopupSettings dado se aplicará como valor predeterminado para cada Popup en tu aplicación, y el DefaultPopupOptionsSettings se aplicará como valor predeterminado para PopupOptions cada vez que se llame a .ShowPopup().

.UseMauiCommunityToolkit(static options =>
{
  options.SetPopupDefaults(new DefaultPopupSettings
  {
	  CanBeDismissedByTappingOutsideOfPopup = true,
	  BackgroundColor = Colors.Orange,
	  HorizontalOptions = LayoutOptions.End,
	  VerticalOptions = LayoutOptions.Start,
	  Margin = 72,
	  Padding = 4
  });
  options.SetPopupOptionsDefaults(new DefaultPopupOptionsSettings
  {
	  CanBeDismissedByTappingOutsideOfPopup = true,
	  OnTappingOutsideOfPopup = async () => await Toast.Make("Popup Dismissed").Show(CancellationToken.None),
	  PageOverlayColor = Colors.Orange,
	  Shadow = null,
	  Shape = null
  });
})

Eventos

La Popup clase proporciona los siguientes eventos a los que se puede suscribir.

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.

Interfaz de Programación de Aplicaciones (API)

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

Recursos adicionales

• IPopupService
• Popup - Devolver un resultado
• PopupOptions - Personalización de un Popup comportamiento y apariencia
• Popup - Combinación de funciones de ventana emergente para proporcionar un ejemplo completo