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

Questa guida introduttiva illustra come aggiornare un riquadro secondario di un'app inviando una notifica locale. Vedrai che la procedura è identica a quella necessaria per inviare una notifica al riquadro principale dell'app, salvo che nel passaggio finale. L'unica differenza tra le due procedure è che nel caso dei riquadri secondari devi usare uno strumento di aggiornamento del riquadro specifico per i riquadri secondari (CreateTileUpdaterForSecondaryTile).

Per vedere il codice qui riportato nel contesto di un esempio completo, vedi l'Esempio di riquadri secondari. L'esempio è disponibile nelle versioni JavaScript, C#, C++ e Visual Basic.

Un'app deve sempre enumerare i propri riquadri secondari all'avvio, perché potrebbero essere state effettuate aggiunte o eliminazioni non ancora rilevate. Se un utente elimina un riquadro secondario, Windows semplicemente lo rimuove. È compito dell'app rilasciare le risorse che erano usate dal riquadro secondario. Quando Windows copia riquadri secondari attraverso il cloud, le notifiche correnti di riquadro o di badge sul riquadro secondario, le notifiche pianificate, i canali di notifica push e gli URI (Uniform Resource Identifier) usati con le notifiche periodiche non vengono copiati insieme al riquadro secondario e devono essere reimpostati.

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 riportato in questa guida introduttiva usando NotificationsExtensions, vedi l'Esempio di riquadri secondari.

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 secondario esistente per l'app. Per altre informazioni, vedi Guida introduttiva: Aggiunta di un riquadro secondario.
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 presente in questa guida introduttiva presuppone che la variabile sia stata dichiarata.

var notifications = Windows.UI.Notifications;

2. Recupera un modello di riquadro vuoto

Qualsiasi modello di riquadro può essere usato per un riquadro secondario. In questo caso useremo il semplice modello di solo testo TileWide310x150Text04.


var wideTemplate = notifications.TileTemplateType.tileWide310x150Text04;                       
var tileXml = notifications.TileUpdateManager.getTemplateContent(wideTemplate);

3. Assegna testo alla notifica

Il modello TileWide310x150Text04 contiene un singolo elemento di testo, a cui assegniamo una stringa.


var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].appendChild(tileXml.createTextNode("This text was delivered through a notification"));

4. Crea la versione media della notifica

È consigliabile fornire sempre un'associazione per ciascuna dimensione di riquadro supportata dell'app in qualsiasi payload della notifica inviato a un riquadro. Nell'ambito dell'operazione di aggiunta, l'utente può selezionare la dimensione del riquadro secondario tra le opzioni che metti a disposizione. Fornendo un'associazione in ciascuna notifica per ciascuna di tali opzioni di dimensioni garantisce che la notifica venga visualizzata, indipendentemente dalle dimensioni del riquadro. Se supporti anche un riquadro secondario di grandi dimensioni, ripeti questo passaggio e il passaggio successivo per uno dei modelli grandi.

Nota Tutti i riquadri, inclusi i riquadri secondari, vengono aggiunti come riquadri medi in Windows Phone 8.1, e l'utente può in seguito ridimensionarli.


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

var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("This text was delivered through a notification"));

5. Aggiungi la notifica media al payload della notifica estesa

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

6. Crea il pacchetto XML finale come notifica di riquadro

var tileNotification = new notifications.TileNotification(tileXml);

7. Crea uno strumento di aggiornamento del riquadro secondario

Fin qui la procedura è identica a quella per le notifiche di riquadro standard. Ma in questo passaggio usiamo il metodo createTileUpdaterForSecondaryTile, specifico dei riquadri secondari. Il metodo richiede l'ID univoco del riquadro secondario di destinazione. In questo esempio ipotizziamo che alla schermata Start sia attualmente aggiunto un riquadro secondario il cui ID è archiviato nella variabile appbarTileId.

var updater = notifications.TileUpdateManager.createTileUpdaterForSecondaryTile(appbarTileId);

8. Invia la notifica al riquadro secondario

updater.update(tileNotification);

9. Facoltativo: aggiornamento del logo del riquadro secondario

Quando crei il riquadro secondario devi fornire un'immagine del logo. L'immagine del logo, così denominata perché normalmente consiste nel logo di un'app, è un'immagine che occupa tutto il riquadro e viene visualizzata al suo interno prima che vengano ricevute notifiche. Se una notifica viene rimossa o scade, nel riquadro viene ripristinata l'immagine del logo. In alcuni scenari può essere necessario modificare l'immagine del logo predefinita, ad esempio se si desidera segnalare una variazione nel contenuto aggiunto senza inviare un aggiornamento completo mediante una notifica. In questo passaggio vedrai come modificare il logo per il riquadro secondario con ID archiviato nella variabile appbarTileId usando un'immagine contenuta nell'archivio locale dell'app. Questo esempio fa riferimento alla classe Windows.Foundation.Uri.


var tileToUpdate = new Windows.UI.StartScreen.SecondaryTile("SecondaryTile.01");
var uriUpdatedLogo = new Windows.Foundation.Uri("ms-appdata:///local/NewSecondaryTileDefault.png");
tileToUpdate.logo = uriUpdatedLogo;
tileToUpdate.updateAsync();

Riepilogo e passaggi successivi

In questa guida introduttiva hai inviato una notifica a un riquadro secondario associato alla tua app. Hai visto che tra l'invio di una notifica al riquadro principale dell'app e a uno dei riquadri secondari esiste solo una minima differenza. Hai inoltre aggiornato l'immagine del logo predefinita del riquadro secondario.

L'aggiornamento del riquadro secondario è stato inviato come notifica locale. Puoi anche esplorare gli altri metodi di recapito delle notifiche: pianificato, periodico e push. Per altre informazioni, vedi Recapito di notifiche.