Toast

2024-05-21

Toast ist eine zeitlich festgelegte Warnung, die unten auf dem Bildschirm angezeigt wird. Sie wird nach einer konfigurierbaren Zeitdauer automatisch ausgeblendet.

Sie bietet dem Benutzer eine einfache Rückmeldung zu einem Vorgang in Form einer kurzen Benachrichtigung.

Plattformspezifische Initialisierung

Um auf die Funktion Toast zugreifen zu können, ist die folgende plattformspezifische Einrichtung erforderlich.

Es ist kein Setup erforderlich.

Bei der Verwendung von Snackbar ist es wichtig, die folgenden beiden Schritte auszuführen:

1. Aktivieren der Snackbar-Nutzung mit dem MauiAppBuilder

Bei Verwendung von UseMauiCommunityToolkit verwenden Sie den Parameter options, um die Verwendung der Snackbar unter Windows wie folgt zu aktivieren:

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

Im obigen Abschnitt werden die erforderlichen Handler automatisch registriert, indem Lebenszyklusereignisse (OnLaunched und OnClosed) konfiguriert werden.

2. Einfügen von ToastNotification-Registrierungen in Ihre Package.appxmanifest-Datei

Um die Snackbar-Aktionen zu behandeln, müssen Sie die Platform\Windows\Package.appxmanifest-Datei wie folgt ändern:

Fügen Sie in Package.appxmanifest im öffnenden <Package>-Tag die folgenden XML-Namespaces hinzu:

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

Aktualisieren Sie in Package.appxmanifest, auch im öffnenden <Package>-Tag, IgnorableNamespaces, um uaprescapcom und desktop aufzunehmen:

IgnorableNamespaces="uap rescap com desktop"

Beispiel: `<Package>`-Tag abgeschlossen

Nachfolgend sehen Sie ein Beispiel für ein abgeschlossenes Eröffnungstag <Package>, das zusätzliche Unterstützung für Snackbar bietet:

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

Fügen Sie in Package.appxmanifest innerhalb jedes <Application>-Tags die folgenden Erweiterungen hinzu:

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

Beispiel: `<Applications>`-Tag abgeschlossen

Nachfolgend sehen Sie ein Beispiel für ein abgeschlossenes <Applications>-Tag, das nun zusätzliche Unterstützung für Snackbar bietet:

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

Beispiel: `Package.appxmanifest` Datei zur Unterstützung von `Snackbar` aktualisiert

Nachfolgend finden Sie eine Beispieldatei Package.appxmanifest, die für die Unterstützung von Snackbar unter Windows aktualisiert wurde:

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

Weitere Informationen zur Behandlung der Aktivierung: Senden einer lokalen Popupbenachrichtigung aus C#-Apps

Syntax

C#

Um eine solche Toast-Benachrichtigung anzuzeigen, erstellen Sie sie zunächst erst mit der statischen Methode Toast.Make(). Anschließend können Sie sie mit der zugehörigen Show()-Methode anzeigen.

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

Beim Aufrufen von Toast.Make() ist der Parameter string text erforderlich. Alle anderen Parameter sind optional. Der optionale Parameter ToastDuration duration verwendet die Standarddauer von ToastDuration.Short. Der optionale Parameter double fontSize verwendet den Standardwert von 14.0.

Im folgenden Screenshot wird die resultierende Popupbenachrichtigung gezeigt:

Android
iOS

Screenshot eines Toasts unter Android

Eigenschaften

Eigenschaft	Typ	BESCHREIBUNG	Standardwert
Text	`string`	Text, der in der `Toast` angezeigt wird.	Erforderlich
Duration	`ToastDuration`	Angezeigte Dauer für `Toast`.	`ToastDuration.Short`
TextSize	`double`	Schriftgrad für Text.	`14.0`

ToastDuration

Die ToastDuration-Enumeration definiert die folgenden Members:

Short – Toast 2 Sekunden lang anzeigen
Long – Toast 3,5 Sekunden lang anzeigen

Diese Werte entsprechen den in der android.widget.Toast API definierten Konstanten.

Methoden

Methode	Beschreibung
Anzeigen	Anzeigen der angeforderten `Toast`. Wenn gerade eine `Toast` angezeigt wird, wird sie automatisch ausgeblendet, bevor die gewünschte `Toast` angezeigt wird.
Schließen	Schließen Sie der aktuellen Popupbenachrichtigung.

Hinweis

Sie können jeweils nur jeweils eine Toast anzeigen. Wenn Sie die Show-Methode ein zweites Mal aufrufen, wird die erste Toast automatisch ausgeblendet.

Beispiele

Sie finden ein Beispiel für dieses Feature in Aktion in der Beispielanwendung für das .NET MAUI Community Toolkit.

API

Sie finden den Quellcode für Toast über das GitHub-Repository für das .NET MAUI Community Toolkit.

Details zur Implementierung und Einschränkung für verschiedene Plattformen

Die API ermöglicht es, vorhandene Methoden mit Ihrer eigenen Implementierung außer Kraft zu setzen oder ihre eigene Popupbenachrichtigung zu erstellen, indem Sie die IToast-Schnittstelle implementieren.
Die Popupbenachrichtigung wird unter Android implementiert, das von Google erstellt wurde. Andere Plattformen verwenden einen benutzerdefinierten Container (UIView für iOS und MacCatalyst, ToastNotification unter Windows).
Popupbenachrichtigungen auf Tizen können nicht mit den Eigenschaften Duration und TextSize angepasst werden.