Notificação do sistema

Artigo
05/20/2024

Toast é um alerta cronometrado que aparece na parte inferior da tela. Ele é descartado automaticamente após uma duração configurável do tempo.

Ele fornece comentários simples para o usuário sobre uma operação em um pequeno alerta.

Inicialização específica da plataforma

Para acessar a funcionalidade Toast, a configuração específica da plataforma a seguir é necessária.

Nenhuma confiuração é necessária.

Ao usar Snackbar, é essencial executar as duas etapas a seguir:

1. Habilitar o uso de snackbar com o MauiAppBuilder

Ao usar o UseMauiCommunityToolkit, use o parâmetro options para habilitar o uso de snackbar no Windows da seguinte maneira:

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

Isso registrará automaticamente os manipuladores necessários configurando eventos de ciclo de vida (OnLaunched e OnClosed).

2. Incluir registros ToastNotification no arquivo Package.appxmanifest

Para lidar com as ações de snackbar, você precisará modificar o arquivo Platform\Windows\Package.appxmanifest da seguinte maneira:

Em Package.appxmanifest, na marca <Package> de abertura, adicione os seguintes Namespaces XML:

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

Em Package.appxmanifest, também na marca <Package> de abertura, atualize IgnorableNamespaces para incluir uaprescapcom e desktop:

IgnorableNamespaces="uap rescap com desktop"

Exemplo: Marca `<Package>` concluída

Aqui está um exemplo de uma marca <Package> de abertura concluída que adicionou suporte para 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">

Em Package.appxmanifest, dentro de cada marca <Application>, adicione as seguintes extensões:

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

Exemplo: Marca `<Applications>` concluída

Aqui está um exemplo de uma marca <Applications> concluída que agora tem suporte para 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>

Exemplo: Arquivo `Package.appxmanifest` atualizado para dar suporte a `Snackbar`

Veja abaixo um arquivo de exemplo Package.appxmanifest que foi atualizado para dar suporte a Snackbar no 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 obter mais informações sobre como lidar com a ativação: Enviar uma notificação do sistema local de aplicativos C#

Sintaxe

C#

Para exibir o Toast, primeiro crie-o usando o método estático Toast.Make() e, em seguida, exiba-o usando seu método Show().

using CommunityToolkit.Maui.Alerts;

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();

string text = "This is a Toast";
ToastDuration duration = ToastDuration.Short;
double fontSize = 14;

var toast = Toast.Make(text, duration, fontSize);

await toast.Show(cancellationTokenSource.Token);

Ao chamar Toast.Make(), seu parâmetro string text é necessário. Todos os outros parâmetros são opcionais. Seu parâmetro opcional ToastDuration duration usa a duração padrão de ToastDuration.Short. Seu parâmetro opcional double fontSize usa o valor padrão de 14.0.

A captura de tela a seguir mostra o Toast resultante:

Android
iOS

Captura de tela de uma Notificação do sistema no Android

Propriedades

Propriedade	Type	Descrição	Valor padrão
Texto	`string`	Texto exibido no `Toast`.	Obrigatório
Duration	`ToastDuration`	Duração do `Toast` exibido.	`ToastDuration.Short`
TextSize	`double`	Tamanho da fonte do texto.	`14.0`

ToastDuration

A enumeração ToastDuration define os seguintes membros:

Short - Exibir o Toast por 2 segundos
Long – Exibir o Toast por 3,5 segundos

Esses valores aderem às constantes definidas na API android.widget.Toast.

Métodos

Método	Descrição
Mostrar	Exibir o `Toast` solicitado. Se um `Toast` for exibido no momento, ele será descartado automaticamente antes que o `Toast` solicitado seja exibido.
Ignorar	Descarte o toast atual.

Observação

Você pode exibir apenas um Toast de cada vez. Se você chamar o método Show uma segunda vez, o primeiro Toast será descartado automaticamente.

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 Toast pode ser encontrado no repositório GitHub do .NET MAUI Community Toolkit.

Detalhes da implementação e limitação para diferentes plataformas

A API permite substituir os métodos existentes com sua própria implementação ou criar seu próprio Toast, implementando a interface IToast.
O Toast é implementado no Android, criado pelo Google. Outras plataformas usam um contêiner implementado personalizado (UIView para iOS e MacCatalyst, ToastNotification no Windows).
O Toast no Tizen não pode ser personalizado com suas propriedades Duration e TextSize.

Partilhar via