Share via

Schnellstart: Senden einer Popupbenachrichtigung (HTML)

  • Artikel

[ Dieser Artikel richtet sich an Windows 8.x- und Windows Phone 8.x-Entwickler, die Windows-Runtime-Apps schreiben. Wenn Sie für Windows 10 entwickeln, finden Sie weitere Informationen unter neueste Dokumentation]

Hinweis  Sie verwenden nicht JavaScript? Siehe Schnellstart: Senden einer Popupbenachrichtigung (XAML).

 

Eine Popupbenachrichtigung ist eine auf dem Bildschirm angezeigte Popupbenutzeroberfläche, die es Ihrer App ermöglicht, immer mit dem Benutzer zu kommunizieren, unabhängig davon, ob er gerade eine andere App, die Startseite oder im Fall von Windows den Desktop anzeigt. Diese Schnellstartanleitung führt Sie durch die Schritte zum Definieren und Anzeigen von Popupinhalten. Diese Aktionen werden anhand einer lokalen Benachrichtigung veranschaulicht, da dies die am einfachsten zu implementierende Form einer Benachrichtigung ist. Die folgende Schritte werden erläutert:

  • Angeben einer Vorlage für die Benachrichtigung
  • Abrufen des leeren XML-Inhalts der Vorlage
  • Hinzufügen von Text zur Benachrichtigung
  • Hinzufügen eines Bilds zur Benachrichtigung
  • Festlegen einer Anzeigedauer für die Benachrichtigung
  • Angeben von begleitenden Audioelementen für die Benachrichtigung
  • Bereitstellen von Kontextinformationen, die verwendet werden, wenn die App durch die Benachrichtigung aktiviert wird
  • Senden des Popups als lokale Benachrichtigung

Hinweis  In dieser Anleitung wird der Benachrichtigungsinhalt direkt über das XML-DOM (Dokumentobjektmodell) gesteuert. Über die NotificationsExtensions-Bibliothek steht ein optionaler Ansatz zur Verfügung, bei dem der XML-Inhalt in Form von Objekteigenschaften dargestellt wird, wobei Sie u. a. IntelliSense nutzen können. Weitere Informationen finden Sie unter Schnellstart: Verwenden der NotificationsExtensions-Bibliothek im Code. Die NotificationsExtensions-Variante des Codes in dieser Schnellstartanleitung finden Sie unter Beispiel für Popupbenachrichtigungen.

 

Hinweis  Beim Testen der Codefunktionalität für Popupbenachrichtigungen über Microsoft Visual Studio müssen Sie entweder die Debugeinstellung des lokalen Computers oder des Remotecomputers auf einem Windows x86-, x64- oder Windows-Runtime-Computer verwenden. Die Verwendung der Debugfunktion des Simulators aus Visual Studio ist nicht möglich — Ihr Code wird zwar im Simulator kompiliert und ausgeführt, das Popup wird jedoch nicht angezeigt.

 

Voraussetzungen

Die Ausführungen in diesem Thema setzen Folgendes voraus:

Anweisungen

1. Optional: Deklarieren einer Namespacevariable

In diesem Schritt wird Ihnen ein Kurzname zur Verfügung gestellt, den Sie anstelle des vollständigen Namespacenamens verwenden können. Dies ist das Äquivalent zur "using"-Anweisung in C# oder der "Imports"-Anweisung in Visual Basic. So können Sie den Code vereinfachen.

Hinweis  Im verbleibenden Teil des Codes in diesem Schnellstart wird davon ausgegangen, dass diese Variable deklariert wurde.

 


var notifications = Windows.UI.Notifications;

2. Auswählen einer Vorlage für das Popup und Abrufen der XML-Inhalte

Wählen Sie aus dem vom System bereitgestellten Vorlagenkatalog eine Vorlage aus, die die Anforderungen der gewünschten Inhalte am besten erfüllt. Die vollständige Vorlagenliste finden Sie in der ToastTemplateType-Enumeration. Beachten Sie, dass für jede separate Benachrichtigung, die gesendet wird, eine andere Vorlage verwendet werden kann.

Hinweis  Unter Windows Phone 8.1 wird nur eine Variante der Vorlage toastText02 unterstützt. Sie akzeptiert zwei Textzeichenfolgen, von denen die erste fett formatiert ist. Da aber beide Zeichenfolgen in derselben Zeile angezeigt werden, sollten Sie zum Vermeiden einer Verkettung nur eine kurze Zeichenfolge oder zwei sehr kurze Zeichenfolgen verwenden.

In diesem Beispiel für Windows wird die Vorlage toastImageAndText01 verwendet, für die ein Bild und eine Textzeichenfolge erforderlich sind. Hier sehen Sie ein Beispiel:

ToastImageAndText01


var template = notifications.ToastTemplateType.toastImageAndText01;
var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);

Die getTemplateContent-Methode gibt ein XmlDocument zurück. Der obige Code ruft das folgende XML-Skelett ab, dessen Details Sie in den folgenden Schritten mithilfe standardmäßiger DOM (Document Object Model)-Funktionen bereitstellen:


<toast>
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</toast>

3. Angeben des Textinhalts für die Benachrichtigung

Dieses Beispiel ruft zuerst alle Elemente in der Vorlage mit dem Tagnamen "text" ab. Die Vorlage "toastImageAndText01" enthält nur eine einzige Textzeichenfolge, die vom Code zugewiesen wird. Diese Zeichenfolge kann über maximal drei Zeilen umgebrochen werden. Damit der Text nicht abgeschnitten wird, sollte die Länge der Zeichenfolge daher entsprechend festgelegt werden.

   
var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].appendChild(toastXml.createTextNode("Hello World!"));

4. Angeben eines Bilds für die Benachrichtigung

Dieser Code ruft zuerst alle Elemente in der Vorlage mit dem Tagnamen "image" ab. Eine Popupvorlage wie "toastImageAndText01" enthält maximal ein Bild. Beachten Sie, dass nicht alle Popupvorlagen Bilder enthalten. Einige enthalten ausschließlich Text.


var toastImageElements = toastXml.getElementsByTagName("image");

Die verwendeten Bilder können aus dem App-Paket, dem lokalen Speicher der App oder aus dem Web stammen. Für jede Bildquelle wird eine eigene Version dieses Schritts gezeigt. Bilder müssen kleiner als 200 KB sein und weniger als 1024 x 1024 Pixel aufweisen. Weitere Informationen finden Sie unter Größe von Kachel- und Popupbildern.

Der folgende Code verwendet ein lokales Bild aus dem App-Paket. Dieser Bildtyp ist in Ihrer Visual Studio-Projektmappendatei enthalten und wird als Teil Ihrer App verpackt. Der Zugriff auf diese Bilder erfolgt mit dem Präfix "ms-appx:///". Aus Gründen der Barrierefreiheit, beispielsweise zur Unterstützung eines Bildschirmleseprogramms, wird außerdem alternativer Text zugewiesen.

Wichtig  Das hier verwendete Bild "redWide.png" dient nur als Beispiel und ist nicht in einem Microsoft Visual Studio-Projekt enthalten. Sie müssen "redWide.png" durch den Namen eines eigenen Bilds ersetzen, das Sie dem Projekt vor dem Senden dieses Popups hinzugefügt haben.

 


toastImageElements[0].setAttribute("src", "ms-appx:///images/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

Der folgende Code verwendet ein lokales Bild aus dem lokalen Speicher der App. Dieser Bildtyp wurde von Ihrer App in ihrem lokalen Speicher gespeichert. Es handelt sich dabei um den von Windows.Storage.ApplicationData.current.localFolder zurückgegebenen Speicherort. Der Zugriff auf diese Bilder erfolgt mithilfe des Präfix "ms-appdata:///local/". Erneut wird aus Gründen der Barrierefreiheit, beispielsweise zur Unterstützung eines Bildschirmleseprogramms, alternativer Text zugewiesen.


toastImageElements[0].setAttribute("src", "ms-appdata:///local/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

Der folgende Code verwendet ein Webbild. Der Zugriff auf diese Bilder erfolgt mithilfe des Protokolls "http://", um den Bildpfad anzugeben. Sie können auch "https://" verwenden.


toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

Mit dem optionalen baseUri-Attribut können Sie einen Stammpfad (z. B. "https://www.microsoft.com/") angeben, der mit allen in den src-Attributen eines Bilds angegebenen relativen URIs (Uniform Resource Identifier) kombiniert wird. Dieses Attribut kann entweder für das visual-Element (damit es für die ganze Benachrichtigung gilt) oder für das binding-Element (damit es nur für diese Bindung gilt) festgelegt werden. Wenn baseUri für beide Elemente festgelegt wird, überschreibt der Wert in binding den Wert in visual.

Wenn baseUri auf "https://www.microsoft.com/" festgelegt wurde, kann folgende Zeile im Beispielcode:

toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");

wie folgt verkürzt werden:

toastImageElements[0].setAttribute("src", "redWide.png");

5. Optional: Angeben einer Popupanzeigedauer

Sie können eine Anzeigedauer für Ihr Popup festlegen. Zwei Werte stehen zur Verfügung: "short" (Standardwert) und "long". Verwenden Sie den Wert "long" nur, wenn Ihre Benachrichtigung Teil eines Szenarios wie einem eingehenden Anruf oder einer Kalendererinnerung ist. Weitere Informationen finden Sie unter Übersicht über Popupbenachrichtigungen.

Hinweis  Unter Windows Phone 8.1 wird nur eine Popupdauer unterstützt. Alle Popups werden gleich lang angezeigt. In einer Popupbenachrichtigung für Smartphones wird dieses Attribut ignoriert.

Hinweis  Da standardmäßig der Wert "short" verwendet wird, wird dieses Attribut üblicherweise nur hinzugefügt, um die Dauer auf "long" festzulegen.

 


var toastNode = toastXml.selectSingleNode("/toast");
toastNode.setAttribute("duration", "long");

6. Optional: Angeben von Popupaudio

Weitere Informationen zu Audiooptionen für Popups finden Sie unter Katalog mit Audiooptionen für Popups.

Standardmäßig gibt Windows einen kurzen Sound wieder, wenn Ihr Popup angezeigt wird. Sie können optional einen anderen der im System verfügbaren Sounds auswählen oder gar keinen Sound verwenden. Unter Windows Phone 8.1 können Sie einen benutzerdefinierten Sound angeben. Weitere Informationen finden Sie unter Katalog mit Audiooptionen für Popups.

Da eine über getTemplateContent abgerufene Vorlage kein audio-Element enthält, müssen Sie es definieren und Ihrer XML-Nutzlast hinzufügen. Die Audiodatei wird mit dem Präfix „ms-winsoundevent“ bzw. auf dem Windows Phone 8.1 mit einem Pfad mit dem Präfix „ms-appx:///“ oder „ms-appdata:///“ angegeben. In diesem Beispiel wird ein audio-Element erstellt und das zugehörige übergeordnete toast-Element ausgewählt.


var toastNode = toastXml.selectSingleNode("/toast");                        
var audio = toastXml.createElement("audio");

In diesem Beispiel wird ein nicht standardmäßiger Sound verwendet.

audio.setAttribute("src", "ms-winsoundevent:Notification.IM");

In diesem Beispiel wird kein Sound wiedergegeben.

audio.setAttribute("silent", "true");

Bei einer Popupbenachrichtigung mit langer Anzeigedauer kann der Sound in einer Schleife statt nur einmal wiedergegeben werden. Audioschleifen können nur für Popupbenachrichtigungen mit langer Anzeigedauer verwendet werden. In den Systemsounds sind spezielle Sounds für Schleifen verfügbar. In diesem Beispiel wird eine Soundschleife verwendet.

Hinweis  Da Windows Phone 8.1 keine Unterstützung für lange Popups bietet, werden Audioschleifen nicht unterstützt.


toastNode.setAttribute("duration", "long");

var audio = toastXml.createElement("audio");
audio.setAttribute("src", "ms-winsoundevent:Notification.Looping.Alarm");
audio.setAttribute("loop", "true");

Nachdem Sie das Audioelement definiert haben, müssen Sie es wie hier gezeigt als untergeordnetes Element des toast-Elements an die XML-Nutzlast Ihres Popups anfügen.

toastNode.appendChild(audio);

7. Angeben von App-Startparametern

Wenn der Benutzer auf Ihre Popupbenachrichtigung klickt, erwartet er, dass die App mit einer Ansicht gestartet wird, die mit der Benachrichtigung in Zusammenhang steht. Verwenden Sie hierzu das launch-Attribut des Popupelements. Dieses Attribut stellt eine Zeichenfolge bereit, die das Popup an die App übergibt, wenn die App über das Popup gestartet wird. Die Zeichenfolge besitzt kein bestimmtes Format und wird von der App definiert. Ihre App muss bei jeder Aktivierung nach dieser Zeichenfolge als Argument suchen, um ihre Darstellung oder ihr Verhalten entsprechend anzupassen.


toastXml.selectSingleNode("/toast").setAttribute("launch", '{"type":"toast","param1":"12345","param2":"67890"}');

Hinweis  In Windows Phone Silverlight 8.1 wird der Wert der Startzeichenfolge an die URI der standardmäßigen Startseite angefügt. Wenn Sie die z. B. die Startzeichenfolge "?conversation=71" angeben, führt dies zu einer URI wie z. B. /MainPage.xaml?conversation=71. Daher muss derSstartzeichenfolge auch eine gültige Zeichenfolge sein. Andernfalls wird eine Ausnahme ausgelöst.

8. Erstellt die Popupbenachrichtigung auf der Grundlage des angegebenen XML-Inhalts.

var toast = new notifications.ToastNotification(toastXml);

9. Sendet Ihre Popupbenachrichtigung.

 
 var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
 toastNotifier.show(toast);

Hinweis  In Windows Phone Silverlight 8.1 wird kein Popup angezeigt, wenn die aktuelle Vordergrund-App des Aufrufers die ToastNotifier.Show Methode ist. In diesem Fall sollte das Popup in erster Linie für einen Hintergrund-Agent verwendet werden.

Hinweis: Für Ihre Popupbenachrichtigung wird die Hintergrundfarbe verwendet, die im App-Manifest für die App-Kachel deklariert wurde. Weitere Informationen finden Sie unter Schnellstart: Erstellen einer Standardkachel im Manifest-Editor von Visual Studio.

Zusammenfassung und nächste Schritte

Im dieser Schnellstartanleitung haben Sie Ihre lokale Popupbenachrichtigung an den Benutzer gesendet.

Das Popup wurde in dieser Schnellstartanleitung als lokale Benachrichtigung gesendet, da diese Form der Benachrichtigung am einfachsten zu implementieren ist und Ihnen die Möglichkeit bietet, die Ergebnisse schnell zu sehen. Als Nächstes sollten Sie sich mit den anderen Methoden zum Übermitteln von Benachrichtigungen befassen: geplante Benachrichtigung, regelmäßige Benachrichtigung und Pushbenachrichtigung. Weitere Informationen finden Sie unter Zustellen von Benachrichtigungen.

Verwandte Themen

Beispiele

Beispiel für Popupbenachrichtigungen

Beispiel für das Senden von Popupbenachrichtigungen über Desktop-Apps

Szenarien für Reversi-Beispielfeatures: Popupbenachrichtigungen

Konzept

Übersicht über Popupbenachrichtigungen

Popupvorlagenkatalog

Katalog mit Audiooptionen für Popups

Anweisungen

Schnellstart: Senden einer Pushbenachrichtigung

Behandeln der Aktivierung über eine Popupbenachrichtigung

Abonnieren von Popupbenachrichtigungen

Planen einer Popupbenachrichtigung

Schnellstart: Senden einer Popupbenachrichtigung auf dem Desktop

Aktivieren einer Desktop-Popupbenachrichtigung über eine AppUserModelID

Bewährte Methoden

Richtlinien und Prüfliste für Popupbenachrichtigungen

Referenz

XML-Schema für Popups

ToastNotification

ToastNotificationManager

ToastNotifier