Guida introduttiva: Invio di una notifica di tipo avviso popup (HTML)

Articolo
12/11/2015

[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]

Nota Se non usi JavaScript, vedi Guida introduttiva: Invio di una notifica di tipo avviso popup (XAML).

Una notifica di tipo avviso popup è un'interfaccia utente popup che viene visualizzata sullo schermo per consentire all'app di comunicare con l'utente, che si trova in un'altra applicazione, nella schermata Start o, nel caso di Windows sul desktop. Questa guida introduttiva illustra i passaggi necessari per definire e visualizzare il contenuto di un avviso popup. Queste operazioni vengono mostrate usando una notifica locale, che è la notifica più facile da implementare. Descriviamo le seguenti procedure:

Specifica di un modello per la notifica
Recupero del contenuto XML vuoto del modello
Aggiunta di testo alla notifica
Aggiunta di un'immagine alla notifica
Impostazione della durata per la notifica
Specifica dell'audio associato alla notifica
Inserimento di informazioni contestuali usate quando l'app è attivata dalla notifica
Invio di un avviso popup come una notifica locale

Nota In questa Guida introduttiva manipolerai il contenuto della notifica direttamente mediante XML Document Object Model (DOM). Un approccio alternativo è disponibile tramite la libreria NotificationsExtensions, che presenta il contenuto XML come proprietà dell'oggetto, incluso Intellisense. Per altre informazioni, vedi Guida introduttiva: Uso della raccolta NotificationsExtensions nel codice. Per vedere il codice nella Guida introduttiva usando NotificationsExtenstions, vedi Esempio di notifiche per avvisi popup.

Nota Durante i test della funzionalità del codice per le notifiche per avvisi popup tramite Microsoft Visual Studio, devi usare l'impostazione di debug Computer locale o Computer remoto in un computer che esegue Windows x86, x64 o Windows Runtime. Non puoi usare l'opzione della funzione di debug del simulatore Visual Studio, poiché il codice verrà compilato ed eseguito nel simulatore ma l'avviso popup non verrà visualizzato.

Prerequisiti

Per comprendere questo argomento, avrai bisogno:

Conoscenza operativa di termini e concetti correlati alle notifiche di tipo avviso popup. Per altre informazioni, vedi Panoramica delle notifiche di tipo avviso popup.
Per inviare o ricevere notifiche di tipo avviso popup, devi impostare su "True" ("Sì" nell'editor del manifesto di Visual Studio) l'opzione Popup supportati nel manifesto dell'app. Per altre informazioni, vedi Come acconsentire esplicitamente all'invio di notifiche di tipo avviso popup.
Familiarità con XML e la relativa manipolazione tramite API Document Object Model (DOM).
Familiarità con lo schema XML per avvisi popup. Per altre informazioni, vedi Schema degli avvisi popup.
Capacità di creare un'app di Windows Store di base in JavaScript usando le API Windows Runtime. Per ulteriori informazioni, vedi Creare la prima app di Windows Store scritta in JavaScript.

Istruzioni

1. Facoltativo: dichiarare una variabile spazio dei nomi

Questa procedura ti fornisce un nome breve da usare al posto del nome completo dello spazio dei nomi. È equivalente all'istruzione "using" in C# o all'istruzione "Imports" in Visual Basic e ti consente di semplificare il codice.

Nota Il resto del codice nella Guida introduttiva presuppone che la variabile sia stata dichiarata.


var notifications = Windows.UI.Notifications;

Scegli un modello dal catalogo di quelli disponibili nel sistema che soddisfa le esigenze del contenuto. Per l'elenco completo dei modelli, vedi l'enumerazione ToastTemplateType. Tieni presente che ogni notifica che invii può usare un modello diverso.

Nota In Windows Phone 8.1 è supportata solo una variazione del modello toastText02. Accetta due stringhe di testo, la prima delle quali resa in grassetto, ma entrambe sulla stessa riga. Per questo motivo devono essere usate solo una stringa breve o due stringhe molto brevi per evitare il concatenamento.

Questo esempio, utilizzabile in Windows, usa il modello toastImageAndText01 che richiede un'immagine e una stringa di testo. Ecco un esempio:

ToastImageAndText01


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

Il metodo getTemplateContent restituisce un elemento XmlDocument. Il codice precedente recupera il seguente scheletro XML per cui dovrai fornire i dettagli nei passaggi successivi tramite funzioni DOM (Document Object Model) standard:


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

3. Fornire contenuto di testo per la notifica

In questo esempio vengono innanzitutto recuperati tutti gli elementi nel modello con un nome di tag di "testo". Il modello toastImageAndText01 contiene solo un'unica stringa di testo che viene assegnata dal codice. Questa stringa può avere un ritorno a capo su un massimo di tre righe, quindi la lunghezza della stringa deve essere impostata di conseguenza per evitare il troncamento.

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

4. Fornire un'immagine per la notifica

Il codice recupera prima tutti gli elementi nel modello con un nome di tag di "immagine". Un modello di avviso popup quale toastImageAndText01 contiene al massimo una immagine. Nota che non tutti i modelli di avviso popup contengono immagini. Alcuni sono solo testo.


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

Puoi usare le immagini dal pacchetto dell'app, dall'archiviazione locale dell'app o dal Web. Per ogni origine immagine sono mostrate versioni di questa procedura. Le immagini devono essere di dimensioni minori di 200 KB e con risoluzione inferiore a 1024x1024 pixel. Per altre informazioni, vedi l'argomento relativo alle dimensioni dei riquadri e delle immagini avviso popup.

Il codice seguente usa un'immagine locale dal pacchetto dell'app. Questo tipo di immagine è incluso nel file della soluzione Visual Studio e viene fornito nel pacchetto dell'app. Queste immagini sono accessibili con il prefisso "ms-appx:///". Come procedura consigliata, assegneremo inoltre un testo alternativo ai fini dell'accessibilità, ad esempio utilità di lettura dello schermo.

Importante L'immagine "redWide.png" usata in questo caso è solo un esempio e non è inclusa in un progetto di Microsoft Visual Studio. Devi sostituire "redWide.png" con il nome di una tua immagine, aggiunta al progetto prima di tentare l'invio di questo avviso popup.


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

Il codice seguente usa un'immagine locale dall'archiviazione locale dell'app. Questo tipo di immagine viene salvato dall'app nello spazio di archiviazione locale. Questo è il percorso restituito da Windows.Storage.ApplicationData.current.localFolder. Queste immagini sono accessibili con il prefisso "ms-appdata:///local/". Inoltre assegneremo un testo facoltativo ai fini dell'accessibilità, ad esempio utilità di lettura dello schermo.


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

Il codice seguente usa un'immagine Web. Queste immagini sono accessibili con il protocollo "http://" che specifica il percorso dell'immagine. Puoi anche usare il protocollo "https://".


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

Puoi usare l'attributo facoltativo baseUri per specificare un percorso radice, quale "https://www.microsoft.com/" combinato con gli URI (Uniform Resource Identifier) relativi agli attributi src dell'immagine. Questo attributo può essere impostato sull'elemento visual (per applicare all'intera notifica) o sull'elemento binding (per applicare all'associazione). Se il valore baseUri è impostato su entrambi, il valore in binding sostituisce il valore in visual.

Se baseUri è impostato su "https://www.microsoft.com/", la riga di codice di esempio:

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

può essere abbreviata come segue:

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

Se vuoi, puoi impostare una durata per la visualizzazione del tuo avviso popup. I valori disponibili sono due: "short" (predefinito) e "long". Usa "long" solo se la notifica è inclusa in uno scenario di chiamata in arrivo o promemoria di calendario. Per altre informazioni, vedi Panoramica delle notifiche di tipo avviso popup.

Nota In Windows Phone 8.1 non sono supportate durate diverse; tutti gli avvisi popup hanno la stessa durata. Se questo attributo è incluso in una notifica di tipo avviso popup del telefono, viene ignorato.

Nota Poiché la durata predefinita è "short", questo attributo è in genere aggiunto solo per impostare la durata su "long".


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

Per altre informazioni sull'audio dell'avviso popup, vedi Catalogo delle opzioni audio per gli avvisi popup.

Per impostazione predefinita, Windows riproduce un breve suono quando viene visualizzato l'avviso popup. Puoi facoltativamente specificare un suono diverso, in un insieme di suoni fornito dal sistema, o di non riprodurre alcun suono. In Windows Phone 8.1 puoi specificare un suono personalizzato. Per altre informazioni, vedi Catalogo delle opzioni audio per gli avvisi popup.

Un modello recuperato attraverso getTemplateContent non contiene un elemento audio, pertanto devi definirlo e aggiungerlo al payload XML. Il file audio viene specificato tramite il prefisso "ms-winsoundevent:" oppure, in Windows Phone 8.1, un percorso che usa il prefisso "ms-appx:///" o "ms-appdata:///". In questo esempio viene creato un elemento audio e viene selezionato l'elemento toast che sarà l'elemento padre.


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

In questo esempio viene specificato un suono non predefinito.

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

In questo esempio viene specificato che non deve essere riprodotto alcun suono.

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

Nel caso di una notifica di tipo avviso popup di lunga durata, il suono può essere riprodotto a ciclo continuo anziché riprodotto una sola volta. La riproduzione a ciclo continuo dell'audio è valida solo per gli avvisi popup di lunga durata. I suoni specifici da usare con la riproduzione a ciclo continuo sono inclusi nell'insieme di suoni di sistema. In questo esempio viene specificato un suono da riprodurre a ciclo continuo.

Nota Dal momento che non supporta avvisi popup di lunga durata, Windows Phone 8.1 non supporta audio a ciclo continuo.


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

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

Quando hai definito l'elemento audio, devi associarlo al payload XML dell'avviso popup come figlio dell'elemento toast, come mostrato qui.

toastNode.appendChild(audio);

7. Specificare i parametri di avvio dell'app

Quando l'utente fa clic sulla notifica di tipo avviso popup, si aspetta che l'app venga avviata con una visualizzazione correlata al contenuto della notifica. A questo scopo, usa l'attributo launch dell'elemento toast, che fornisce una stringa passata dall'avviso popup all'app quando quest'ultima viene avviata tramite l'avviso popup. Questa stringa non ha un formato specifico ed è definita dall'app. La tua app deve verificare che questa stringa, specificata come argomento, definisca la visualizzazione o il funzionamento di conseguenza ogni volta che viene attivata.


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

Nota In Silverlight per Windows Phone 8.1 il valore della stringa di avvio viene aggiunto all'URI della pagina di avvio predefinita. Ad esempio, se specifichi la stringa di avvio "?conversation=71", l'URI risultante sarà simile a /MainPage.xaml?conversation=71. Di conseguenza, la stringa di avvio deve anche essere una stringa di query valida. In caso contrario, viene generata un'eccezione.

var toast = new notifications.ToastNotification(toastXml);

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

Nota In Silverlight per Windows Phone 8.1, un avviso popup non viene visualizzato se l'app in primo piano corrente è il chiamante del metodo ToastNotifier.Show. In questo caso, l'avviso popup deve essere usato principalmente da un agente in background.

Nota: Il colore di sfondo applicato alla notifica di tipo avviso popup è quello dichiarato per il riquadro dell'app nel manifesto dell'app stessa. Per altre informazioni, vedi Guida introduttiva: Creazione di un riquadro predefinito tramite l'editor del manifesto di Visual Studio.

Riepilogo e passaggi successivi

In questa guida introduttiva hai inviato la notifica di tipo avviso popup locale all'utente.

In questa Guida introduttiva è stato inviato un avviso popup come una notifica locale, ovvero il tipo più semplice di notifica da implementare e che consente di vedere rapidamente i risultati. Ora puoi anche esplorare gli altri metodi di recapito delle notifiche di tipo avviso popup: pianificato e push. Per altre informazioni, vedi Recapito di notifiche.