Guida introduttiva: Invio di un aggiornamento di riquadro (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 un aggiornamento di riquadro (XAML).

Un riquadro inizia come riquadro predefinito, definito nel manifesto e visualizzato alla prima installazione dell'app. Dopo l'installazione dell'app puoi modificare il contenuto del riquadro tramite le notifiche.Questa guida introduttiva illustra i passaggi necessari per definire il nuovo contenuto del riquadro, inviarlo al riquadro e rimuoverlo quando non è più necessario. 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
Creazione di pacchetti con diverse versioni di notifica per varie dimensioni di riquadro in un unico payload
Impostazione di una scadenza per la notifica
Invio dell'aggiornamento al riquadro come notifica locale

Per una dimostrazione pratica di questa funzionalità, vedi gli argomenti della serie Funzionalità delle app dall'inizio alla fine: Interfaccia utente delle app di Windows Store, dall'inizio alla fine

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 NotificationsExtensions, vedi Esempio di riquadri e badge dell'app.

Prerequisiti

Per comprendere questo argomento, avrai bisogno di:

Conoscenza operativa di termini e concetti correlati a riquadri e notifiche. Per altre informazioni, vedi Riquadri, notifiche e avvisi.
Familiarità con lo schema XML per riquadri. Per altre informazioni, vedi Schema del riquadro.
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.
Un riquadro predefinito esistente per l'app, definito nel manifesto dell'app. Per altre informazioni, vedi Guida introduttiva: Creazione di un riquadro predefinito tramite l'editor del manifesto di Visual Studio.
Familiarità con XML e la relativa manipolazione tramite API Document Object Model (DOM).

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;

2. Selezionare un modello per il riquadro e recuperarne il contenuto XML

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

Questo esempio usa il modello TileWide310x150ImageAndText01 che richiede un'immagine e una stringa di testo. Ecco un esempio:

TileWide310x150ImageAndText01


var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.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.

Nota Quando viene evocato in un sistema Windows 8, il metodo getTemplateContent restituisce la versione 1 del modello. Quando questo metodo viene chiamato in un sistema Windows 8.1, restituisce un modello di versione 2 o un modello di versione 3 nel caso dei modelli solo per Windows Phone. Se un'app specifica nel proprio manifesto la compatibilità con Windows 8, il metodo restituirà il modello di versione 1, indipendentemente dalla versione di Windows in uso. In questo argomento useremo la versione 2 del modello.


<tile>
    <visual version="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</tile>

3. Fornire contenuto di testo per la notifica

Il codice recupera prima tutti gli elementi nel modello con un nome di tag di "testo". Il modello TileWide310x150ImageAndText01 contiene solo un'unica stringa di testo che viene assegnata dal codice. Questa stringa può avere un ritorno a capo su un massimo di due righe, perciò la lunghezza della stringa deve essere impostata di conseguenza per evitare il troncamento.


var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));

4. Fornire un'immagine per la notifica

Il codice recupera prima tutti gli elementi nel modello con un nome di tag di "immagine". Il modello TileWide310x150ImageAndText01 contiene una singola immagine. Nota che non tutti i modelli di riquadro contengono immagini. Alcuni sono solo testo.

Importante L'immagine "redWide.png" utilizzata in questo caso è solo un esempio e non è inclusa in un progetto Microsoft Visual Studio. Devi sostituire "redWide.png" con il nome di una immagine effettiva che hai aggiunto al progetto prima di tentare l'invio di questa notifica. In caso contrario, la notifica non verrà recapitata.


var tileImageAttributes = tileXml.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. In una notifica di tipo riquadro contenente più immagini, gli elementi immagine possono usare qualsiasi combinazione di quei tipi di origine immagine. Le immagini usate nei modelli 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.


tileImageAttributes[0].setAttribute("src", "ms-appx:///images/redWide.png");
tileImageAttributes[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.


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

Il codice seguente usa un'immagine Web. Queste immagini sono accessibili con il protocollo "http://" o "https://" che specifica il percorso dell'immagine. La funzionalità internetClient dell'app deve essere dichiarata nel manifesto affinché l'app possa usare le immagini Web.


tileImageAttributes[0].setAttribute("src", "https://www.contoso.com/redWide.png");
tileImageAttributes[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.contoso.com/", la riga di codice di esempio:


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

può essere abbreviata come segue:


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

5. Includere associazioni delle notifiche per più dimensioni dei riquadri nel payload

L'utente può ridimensionare il riquadro in qualsiasi momento nella schermata Start e non hai modo di conoscere lo stato del riquadro (piccolo, medio, esteso o grande) quando invii una notifica. Se alla dimensione del riquadro non è associato un modello corrispondente nella notifica, la notifica non verrà visualizzata. Quindi è consigliabile includere sempre versioni della notifica nel payload per tutte le dimensioni di riquadri animati (medio, esteso, grande) per cui hai fornito un'immagine del logo nel manifesto.

Nota In Windows Phone 8.1, i riquadri grandi non sono supportati nel telefono.

Questo esempio definisce una notifica media di solo testo usando la stessa stringa di testo usata nella notifica estesa.

       
var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);

var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));

Aggiungi quindi il riquadro medio al payload del riquadro esteso. Recupera l'elemento binding che definisce il riquadro medio nel payload squareTileXml. Aggiungi l'elemento binding come elemento di pari livello del riquadro esteso.


var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

I passaggi precedenti aggiungono due elementi binding in un singolo elemento visual nel payload XML. Ecco il risultato:


<tile>
    <visual visual="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src="ms-appx:///images/redWide.png"/>
            <text id="1">Hello World! My very own tile notification</text>
        </binding>

        <binding template="TileSquare150x150Text04" fallback="TileSquareText04">
            <text id="1">Hello World! My very own tile notification</text>
        </binding>
    </visual>
</tile>

6. Creare la notifica in base al contenuto XML specificato


var tileNotification = new notifications.TileNotification(tileXml);

7. Impostare una scadenza per la notifica

Per impostazione predefinita, il riquadro locale e le notifiche badge non scadono, mentre le notifiche push, periodiche e pianificate scadono dopo tre giorni. È consigliabile impostare una scadenza, in particolare per le notifiche relative ai riquadri locali e per le notifiche badge, usando un'ora utile per l'app. Il contenuto del riquadro non deve persistere più a lungo di quanto appropriato. In questo caso, la notifica scadrà e verrà rimossa dal riquadro entro dieci minuti.


var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

8. Inviare la notifica al riquadro dell'app.


notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

9. Facoltativo: cancella la notifica di tipo riquadro

In questo esempio viene illustrato come cancellare una notifica di tipo riquadro tramite una chiamata locale. Tieni presente che se il contenuto è vincolato al tempo, è consigliabile impostare una scadenza per la notifica piuttosto che cancellarla in modo esplicito. La seguente riga di codice cancella la notifica corrente dal riquadro dell'app.


notifications.TileUpdateManager.createTileUpdaterForApplication().clear();

Per un riquadro con coda notifiche abilitata e notifiche in coda, la chiamata al metodo clear determina lo svuotamento della coda.

Tieni presente che non puoi cancellare una notifica dal cloud. Una chiamata locale al metodo clear cancella il riquadro indipendentemente dall'origine delle relative notifiche, ma le notifiche periodiche o push possono aggiornare solo il riquadro con il nuovo contenuto.

Riepilogo e passaggi successivi

In questa guida introduttiva abbiamo definito e inviato contenuto al riquadro dell'app tramite una notifica, che è stata rimossa dopo 10 minuti. Nel codice seguente vengono riepilogati i passaggi precedenti, dalla scelta di un modello all'invio di una notifica. Viene usata un'immagine del pacchetto dell'app.

Per provare questo codice in un esempio personalizzato, posizionalo in una funzione che viene attivata da un pulsante nell'interfaccia utente dell'esempio. Ad esempio, puoi posizionare il pulsante nel file default.html. Ricorda di sostituire il nome dell'immagine.


var notifications = Windows.UI.Notifications;

var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));

var tileImageAttributes = tileXml.getElementsByTagName("image");
tileImageAttributes[0].setAttribute("src", "ms-appx:///assets/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");

var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);
var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));

var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

var tileNotification = new notifications.TileNotification(tileXml);

var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

Dopo aver eseguito il tuo primo aggiornamento del riquadro, puoi espandere la funzionalità del riquadro abilitando una coda notifiche.

La Guida introduttiva ha inviato un aggiornamento del riquadro come notifica locale. Puoi anche esplorare gli altri metodi di recapito delle notifiche: pianificato, periodico e push. Per altre informazioni, vedi Recapito di notifiche.