Notificaciones emergentes

Artículo
04/02/2024

Snackbar es una alerta con tiempo que aparece en la parte inferior de la pantalla de forma predeterminada. Se descarta después de una duración configurable de tiempo. Snackbar es totalmente personalizable y se puede anclar a cualquier IView.

El Snackbar informa a los usuarios de un proceso que una aplicación ha realizado o va a realizar. Aparece temporalmente, hacia la parte inferior de la pantalla.

Inicialización específica de la plataforma

Para acceder a la funcionalidad de Snackbar, se requiere la siguiente configuración específica para la plataforma.

No es necesario realizar ninguna configuración.

Al usar Snackbar es esencial realizar los dos pasos siguientes:

1. Habilitar el uso de snackbar con MauiAppBuilder

Al usar el UseMauiCommunityToolkit use el parámetro options para habilitar el uso de la snackbar en Windows de la siguiente manera:

var builder = MauiApp.CreateBuilder()
  .UseMauiCommunityToolkit(options =>
  {
    options.SetShouldEnableSnackbarOnWindows(true);
  })

Lo anterior registrará automáticamente los controladores necesarios mediante la configuración de eventos de ciclo de vida (OnLaunched y OnClosed).

2. Incluir registros ToastNotification en el archivo Package.appxmanifest

Para controlar las acciones de la snackbar, deberá modificar el archivo Platform\Windows\Package.appxmanifest de la siguiente manera:

En Package.appxmanifest, en la etiqueta de apertura <Package>, agregue los siguientes espacios de nombres XML:

xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"

En Package.appxmanifest, también en la etiqueta de apertura <Package>, actualice IgnorableNamespaces para incluir uap, rescap, com y desktop:

IgnorableNamespaces="uap rescap com desktop"

Ejemplo: etiqueta `<Package>` completada

Este es un ejemplo de una etiqueta de apertura <Package> completada que ha agregado compatibilidad con Snackbar:

<Package
     xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
     xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
     xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
     xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
     xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
     IgnorableNamespaces="uap rescap com desktop">

En Package.appxmanifest, dentro de cada etiqueta <Application>, agregue las siguientes extensiones:

<Extensions>

   <!-- Specify which CLSID to activate when notification is clicked -->
   <desktop:Extension Category="windows.toastNotificationActivation">
       <desktop:ToastNotificationActivation ToastActivatorCLSID="6e919706-2634-4d97-a93c-2213b2acc334" />
   </desktop:Extension>

   <!-- Register COM CLSID -->
   <com:Extension Category="windows.comServer">
       <com:ComServer>
           <com:ExeServer Executable="YOUR-PATH-TO-EXECUTABLE" DisplayName="$targetnametoken$" Arguments="----AppNotificationActivated:"> <!-- Example path to executable: CommunityToolkit.Maui.Sample\CommunityToolkit.Maui.Sample.exe -->
               <com:Class Id="6e919706-2634-4d97-a93c-2213b2acc334" />
           </com:ExeServer>
       </com:ComServer>
   </com:Extension>

</Extensions>

Ejemplo: etiqueta `<Applications>` completada

Este es un ejemplo de una etiqueta <Applications> completada que ahora ha agregado compatibilidad con Snackbar:

<Applications>
  <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="$targetentrypoint$">
      <uap:VisualElements
          DisplayName="$placeholder$"
          Description="$placeholder$"
          Square150x150Logo="$placeholder$.png"
          Square44x44Logo="$placeholder$.png"
          BackgroundColor="transparent">
           <uap:DefaultTile Square71x71Logo="$placeholder$.png" Wide310x150Logo="$placeholder$.png" Square310x310Logo="$placeholder$.png" />
           <uap:SplashScreen Image="$placeholder$.png" />
       </uap:VisualElements>
       <Extensions>

         <desktop:Extension Category="windows.toastNotificationActivation">
             <desktop:ToastNotificationActivation ToastActivatorCLSID="6e919706-2634-4d97-a93c-2213b2acc334" />
         </desktop:Extension>

         <com:Extension Category="windows.comServer">
             <com:ComServer>
                 <com:ExeServer Executable="YOUR-PATH-TO-EXECUTABLE" DisplayName="$targetnametoken$" Arguments="----AppNotificationActivated:"> <!-- Example path to executable: CommunityToolkit.Maui.Sample\CommunityToolkit.Maui.Sample.exe -->
                     <com:Class Id="6e919706-2634-4d97-a93c-2213b2acc334" />
                  </com:ExeServer>
              </com:ComServer>
          </com:Extension>

       </Extensions>
   </Application>
</Applications>

Ejemplo: archivo `Package.appxmanifest` actualizado para admitir `Snackbar`

A continuación se muestra un archivo Package.appxmanifest de ejemplo que se ha actualizado para admitir Snackbar en Windows:

<?xml version="1.0" encoding="utf-8"?>
<Package
    xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
    xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
    xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
    xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
    xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
    IgnorableNamespaces="uap rescap com desktop">

    <Identity Name="maui-package-name-placeholder" Publisher="CN=Microsoft" Version="0.0.0.0" />

    <Properties>
        <DisplayName>$placeholder$</DisplayName>
        <PublisherDisplayName>Microsoft</PublisherDisplayName>
        <Logo>$placeholder$.png</Logo>
    </Properties>

    <Dependencies>
        <TargetDeviceFamily Name="Windows.Universal" MinVersion="10.0.17763.0" MaxVersionTested="10.0.19041.0" />
        <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.19041.0" />
    </Dependencies>

    <Resources>
        <Resource Language="x-generate" />
    </Resources>

    <Applications>
        <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="$targetentrypoint$">
            <uap:VisualElements
                DisplayName="$placeholder$"
                Description="$placeholder$"
                Square150x150Logo="$placeholder$.png"
                Square44x44Logo="$placeholder$.png"
                BackgroundColor="transparent">
                <uap:DefaultTile Square71x71Logo="$placeholder$.png" Wide310x150Logo="$placeholder$.png" Square310x310Logo="$placeholder$.png" />
                <uap:SplashScreen Image="$placeholder$.png" />
            </uap:VisualElements>
            <Extensions>

               <desktop:Extension Category="windows.toastNotificationActivation">
                   <desktop:ToastNotificationActivation ToastActivatorCLSID="6e919706-2634-4d97-a93c-2213b2acc334" />
               </desktop:Extension>

               <com:Extension Category="windows.comServer">
                   <com:ComServer>
                       <com:ExeServer Executable="YOUR-PATH-TO-EXECUTABLE" DisplayName="$targetnametoken$" Arguments="----AppNotificationActivated:"> <!-- Example path to executable: CommunityToolkit.Maui.Sample\CommunityToolkit.Maui.Sample.exe -->
                           <com:Class Id="6e919706-2634-4d97-a93c-2213b2acc334" />
                        </com:ExeServer>
                    </com:ComServer>
                </com:Extension>

            </Extensions>
        </Application>
    </Applications>

    <Capabilities>
        <rescap:Capability Name="runFullTrust" />
    </Capabilities>

</Package>

Para obtener más información sobre cómo controlar la activación: Enviar una notificación del sistema local desde aplicaciones de C#

Sintaxis

El Snackbar se invoca mediante C#.

C#

Para mostrar Snackbar debe crearla, mediante el método estático Make:

using CommunityToolkit.Maui.Alerts;

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();

var snackbarOptions = new SnackbarOptions
{
    BackgroundColor = Colors.Red,
    TextColor = Colors.Green,
    ActionButtonTextColor = Colors.Yellow,
    CornerRadius = new CornerRadius(10),
    Font = Font.SystemFontOfSize(14),
    ActionButtonFont = Font.SystemFontOfSize(14),
    CharacterSpacing = 0.5
};

string text = "This is a Snackbar";
string actionButtonText = "Click Here to Dismiss";
Action action = async () => await DisplayAlert("Snackbar ActionButton Tapped", "The user has tapped the Snackbar ActionButton", "OK");
TimeSpan duration = TimeSpan.FromSeconds(3);

var snackbar = Snackbar.Make(text, action, actionButtonText, duration, snackbarOptions);

await snackbar.Show(cancellationTokenSource.Token);

Al llamar a Snackbar.Make(), se requiere su parámetro string text. Todos los demás parámetros son opcionales.

En la captura de pantalla siguiente se muestra la barra de aperitivos resultante:

Android
iOS

Captura de pantalla de una Snackbar en Android

También hay un método de extensión, que delimitará el Snackbar a cualquier VisualElement:

await MyVisualElement.DisplaySnackbar("Snackbar is awesome. It is anchored to MyVisualElement");

Advertencia

Snackbar en Windows no se puede anclar a VisualElement y siempre se muestra como una notificación predeterminada de Windows.

SnackBar contiene dos eventos:

public static event EventHandler Shown
public static event EventHandler Dismissed

También contiene la propiedad public static bool IsShown { get; }.

Snackbar.Shown += (s, e) => { Console.WriteLine(Snackbar.IsShown); };
Snackbar.Dismissed += (s, e) => { Console.WriteLine(Snackbar.IsShown); };

Propiedades

Propiedad	Tipo	Descripción
Texto	`string`	Mensaje de texto. Obligatorio
Action	`Action`	Acción que se va a invocar en el botón de acción haga clic.
ActionButtonText	`string`	Texto del botón de acción.
Delimitador	`IView`	`Snackbar` delimitador. `Snackbar` aparece cerca de esta vista. Cuando `null`, el `Snackbar` aparecerá en la parte inferior de la pantalla.
Duration	`TimeSpan`	`Snackbar` duración.
VisualOptions	`SnackbarOptions`	`Snackbar` opciones visuales.

SnackbarOptions

El SnackbarOptions permite personalizar el estilo de Snackbar predeterminado.

Propiedades

Propiedad	Tipo	Descripción	Default value
CharacterSpacing	`double`	Espaciado de caracteres de mensaje.	`0.0d`
Fuente	`Font`	Fuente del mensaje.	`Font.SystemFontOfSize(14)`
TextColor	`Color`	Color del texto del mensaje.	`Colors.Black`
ActionButtonFont	`Font`	Fuente del botón de acción.	`Font.SystemFontOfSize(14)`
ActionButtonTextColor	`Color`	Color de texto del botón de acción.	`Colors.Black`
BackgroundColor	`Color`	Color de fondo.	`Colors.LightGray`
CornerRadius	`CornerRadius`	Radio de esquina.	`new CornerRadius(4, 4, 4, 4)`

Métodos

método	Descripción
Mostrar	Muestra el objeto solicitado`Snackbar`. Esto descartará cualquier que se muestre actualmente `Snackbar`.
Descartar	Descarte el solicitado`Snackbar`.

Nota:

Solo puede mostrar 1 Snackbar al mismo tiempo. Si llama al método Show una segunda vez, el primer Snackbar se descartará automáticamente antes de que se muestre el segundo Snackbar.

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 Snackbar en el repositorio de GitHub del Kit de herramientas de la comunidad de .NET MAUI.

Compartir a través de

Notificaciones emergentes

Inicialización específica de la plataforma

1. Habilitar el uso de snackbar con MauiAppBuilder

2. Incluir registros ToastNotification en el archivo Package.appxmanifest

Ejemplo: etiqueta `<Package>` completada

Ejemplo: etiqueta `<Applications>` completada

Ejemplo: archivo `Package.appxmanifest` actualizado para admitir `Snackbar`

Sintaxis

C#

Propiedades

SnackbarOptions

Propiedades

Métodos

Ejemplos

API

Recursos adicionales