Guida introduttiva: Aggiunta di un riquadro secondario (HTML)
[ 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: Aggiunta di un riquadro secondario (XAML).
Questo argomento illustra i passaggi necessari per creare un riquadro secondario per un'app e aggiungerlo alla schermata Start.
Prerequisiti
Per comprendere questo argomento, devi disporre di:
- Conoscenza operativa di termini e concetti correlati ai riquadri secondari. Per altre informazioni, vedi la panoramica dei riquadri secondari.
- 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.
- Conoscenza dell'uso di Microsoft Visual Basic per creare codice per un'app di Windows Store basata su HTML.
Importante 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.
Istruzioni
1. Aggiunta di una barra dell'app con un pulsante di aggiunta/rimozione
In Windows puoi offrire solitamente agli utenti la possibilità di aggiungere elementi tramite il pulsante Aggiungi a Start nella barra dell'app. Per informazioni sulla creazione di una barra dell'app, vedi Guida introduttiva: Aggiunta di una barra dell'app con comandi.
Nota Per le app di Windows Phone Store, l'aggiunta viene eseguita di solito attraverso un menu di scelta rapida anziché mediante un pulsante sulla barra dell'app.
L'esempio seguente dichiara una barra dell'app con un pulsante. Questo codice viene aggiunto alla pagina .html del tuo progetto al quale si applica il resto del codice in questo argomento.
<div id="pinUnpinFromAppbar" data-win-control="WinJS.UI.AppBar" data-win-options="">
<button
data-win-control="WinJS.UI.AppBarCommand"
data-win-options="{id:'commandButton',section:'global'}">
</button>
</div>
2. Fornire un ID univoco per il riquadro secondario
var appbarTileId = "MySecondaryTile";
3. Creare una funzione per impostare il pulsante in modo che consenta l'aggiunta o la rimozione
Il pulsante attiva/disattiva l'azione di aggiunta e rimozione del riquadro secondario. In questo esempio, creiamo una funzione per impostare il pulsante in modo appropriato utilizzando icone fornite dal sistema per un aspetto coerente con le altre app. Questa funzione viene chiamata nell'ambito del codice di inizializzazione dell'app, tutte le volte che si apre la barra dell'app e immediatamente dopo un'operazione di aggiunta/rimozione eseguita correttamente.
La riga finale di questa funzione imposta la proprietà WinJS.UI.sticky della barra dell'app su false, che consente di chiudere la barra dell'app.
function setAppbarButton() {
var commandButton = appBar.getCommandById("commandButton").winControl;
if (Windows.UI.StartScreen.SecondaryTile.exists(appbarTileId)) {
commandButton.label = "Unpin from Start";
commandButton.icon = "unpin";
} else {
commandButton.label = "Pin to Start";
commandButton.icon = "pin";
}
document.getElementById("pinUnpinFromAppbar").winControl.sticky = false;
}
4. Visualizzazione del pulsante appropriato e assegnazione di un gestore dei clic del pulsante
In questo esempio relativo all'inizializzazione dell'app, utilizziamo la funzione setAppbarButton dell'ultimo passaggio per verificare se il riquadro secondario sia stato già aggiunto e per impostare di conseguenza il testo del pulsante.
Assegnamo quindi il gestore appbarButtonClicked all'evento click del pulsante di aggiunta. Ti mostreremo come implementare il gestore di eventi nel prossimo passaggio.
Richiama il codice mostrato in questo passaggio, insieme a qualsiasi altra operazione di inizializzazione che devi eseguire, nell'ambito dell'inizializzazione dell'app ogni volta che questa viene avviata.
document.getElementById("pinUnpinFromAppbar").disabled = false;
setAppbarButton();
id("commandButton").addEventListener("click", appbarButtonClicked, false);
5. Creazione e aggiunta del riquadro secondario nel gestore degli eventi del pulsante
In questo esempio viene implementata una singola funzione che può essere richiamata dal gestore dell'evento click del pulsante di aggiunta. Questa funzione raccoglie vari passaggi che hanno portato alla richiesta di aggiunta:
- Assegna i valori delle proprietà che sono necessari per la creazione del riquadro secondario
- Crea l'oggetto riquadro secondario
- Specifica altre proprietà del riquadro secondario
- Ottiene le coordinate della schermata usate per visualizzare il riquadro a comparsa di conferma (solo Windows)
È necessario impostare alcune delle proprietà del riquadro secondario prima di poterlo aggiungere. In assenza di queste proprietà non riuscirai ad aggiungere un riquadro secondario. Ecco le proprietà necessarie:
- ID univoco per il riquadro
- Nome breve (solo Windows 8.0)
- Nome visualizzato
- Stringa di argomento passata all'applicazione padre quando viene attivato il riquadro secondario
- Immagine logo
- Opzioni riquadro (solo Windows 8.0)
Quale stringa argomento di esempio, in questo esempio viene passata l'ora in cui il riquadro secondario è stato aggiunto alla schermata Start.
Nota In Windows Phone 8.1, il nome visualizzato non viene mai mostrato su un riquadro secondario medio (150x150). Inoltre, tutti i riquadri del telefono vengono aggiunti inizialmente come riquadri medi, perciò il parametro newTileDesiredSize viene ignorato sul telefono.
Nota Se fornisci lo stesso ID di un riquadro secondario esistente, quest'ultimo verrà sovrascritto.
var currentTime = new Date();
var appbarTileId = "SecondaryTile.AppBar";
var newTileDisplayName = "Secondary tile pinned through app bar";
var TileActivationArguments = appbarTileId + " was pinned at " + currentTime;
var square150x150Logo = new Windows.Foundation.Uri("ms-appx:///Images/square150x150Tile-sdk.png");
var newTileDesiredSize = Windows.UI.StartScreen.TileSize.square150x150;
Creiamo quindi l'oggetto riquadro secondario. Questa versione del costruttore crea un riquadro medio. Se il riquadro secondario è abilitato alla ricezione di notifiche, ti consigliamo di dichiarare tutte le dimensioni di riquadri. Per questo scopo, fornisci le immagini del logo attraverso la classe SecondaryTileVisualElements.
var tile = new Windows.UI.StartScreen.SecondaryTile(appbarTileId,
newTileDisplayName,
TileActivationArguments,
square150x150Logo,
newTileDesiredSize);
Quando è stato creato un oggetto riquadro secondario, puoi specificarne le proprietà che non sono state impostate dal costruttore. Questo esempio specifica il colore del testo in primo piano e la scelta del logo piccolo e imposta la visualizzazione del nome visualizzato sul riquadro.
Nota In Windows Phone 8.1, su un riquadro secondario medio (150x150) non vengono mostrati né il logo piccolo né il nome visualizzato e non è possibile specificare il colore del testo in primo piano, pertanto tali proprietà impostate nell'esempio vengono ignorate sul telefono.
tile.visualElements.showNameOnSquare150x150Logo = true;
tile.visualElements.foregroundText = Windows.UI.StartScreen.ForegroundText.light;
tile.visualElements.square30x30Logo = new Windows.Foundation.Uri("ms-appx:///Images/square30x30Tile-sdk.png");
In Windows, l'utente deve confermare l'operazione prima dell'aggiunta di un riquadro secondario. Nella finestra di dialogo di conferma, l'utente può ignorare il nome visualizzato del riquadro e scegliere tra diverse dimensioni di riquadri da aggiungere. Il riquadro a comparsa di conferma deve essere visualizzato accanto al pulsante che ha richiamato la richiesta di aggiunta. Questo esempio recupera il rettangolo di delimitazione del pulsante di aggiunta e specifica che la finestra di dialogo di conferma debba essere visualizzata sul pulsante.
Nota In Windows Phone 8.1, non viene visualizzata una finestra di dialogo per la conferma dell'utente; il riquadro viene semplicemente aggiunto alla schermata Start come riquadro medio e senza nome visualizzato. Il codice visualizzato qui verrà ignorato.
var element = document.getElementById("commandButton");
var selectionRect = element.getBoundingClientRect();
var buttonCoordinates = { x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height };
var placement = Windows.UI.Popups.Placement.above;
Successivamente la funzione richiede che il riquadro secondario venga aggiunto.
- In Windows Phone 8.1, questa chiamata aggiunge il riquadro, sospende l'app e visualizza la schermata Start.
- In Windows, invece, visualizza il riquadro a comparsa di conferma in cui viene chiesta all'utente l'autorizzazione ad aggiungere il riquadro. Usando il rettangolo di delimitazione del pulsante di aggiunta, in questo esempio viene visualizzato il riquadro a comparsa di conferma su tali coordinate. Quando l'utente fornisce l'approvazione, Windows crea il riquadro secondario e lo posiziona nella schermata Start. L'app rimane aperta.
return new WinJS.Promise(function (complete, error, progress) {
tile.requestCreateForSelectionAsync(buttonCoordinates, placement).done(function (isCreated) {
if (isCreated) {
complete(true);
} else {
complete(false);
}
});
});
Nota In Windows Phone 8.1, una chiamata a RequestCreateAsync o a RequestCreateForSelectionAsync chiude l'app e visualizza la schermata Start. Per questo motivo, il codice che segue la chiamata RequestCreateAsync o RequestCreateForSelectionAsync non verrà eseguito. Pertanto, nei progetti di Windows Phone 8.1, devi ascoltare l'evento Suspending in modo da poter eseguire qualsiasi operazione necessaria prima della chiusura dell'app, come salvare lo stato dell'app.
Le funzioni appbarButtonClicked e pinByElementAsync complete dell'esempio di riquadri secondari sono mostrate qui.
function appbarButtonClicked() {
document.getElementById("pinUnpinFromAppbar").winControl.sticky = true;
if (WinJS.UI.AppBarIcon.unpin === document.getElementById("commandButton").winControl.icon) {
unpinByElementAsync(document.getElementById("commandButton"), appbarTileId).done(function (isDeleted) {
if (isDeleted) {
WinJS.log && WinJS.log("Secondary tile was successfully unpinned.", "sample", "status");
setAppbarButton();
} else {
WinJS.log && WinJS.log("Secondary tile was not unpinned.", "sample", "error");
setAppbarButton();
}
});
} else {
pinByElementAsync(document.getElementById("commandButton"), appbarTileId, "Appbar pinned secondary tile").done(function (isCreated) {
if (isCreated) {
WinJS.log && WinJS.log("Secondary tile was successfully pinned.", "sample", "status");
setAppbarButton();
} else {
WinJS.log && WinJS.log("Secondary tile was not pinned.", "sample", "error");
setAppbarButton();
}
});
}
}
function pinByElementAsync(element, newTileID, newTileDisplayName) {
var square150x150Logo = new Windows.Foundation.Uri("ms-appx:///Images/square150x150Tile-sdk.png");
var square30x30Logo = new Windows.Foundation.Uri("ms-appx:///Images/square30x30Tile-sdk.png");
var currentTime = new Date();
var TileActivationArguments = newTileID + " was pinned at=" + currentTime;
var tile = new Windows.UI.StartScreen.SecondaryTile(newTileID,
newTileDisplayName,
TileActivationArguments,
square150x150Logo,
Windows.UI.StartScreen.TileSize.square150x150);
tile.visualElements.foregroundText = Windows.UI.StartScreen.ForegroundText.light;
tile.visualElements.square30x30Logo = square30x30Logo;
tile.visualElements.showNameOnSquare150x150Logo = true;
var selectionRect = element.getBoundingClientRect();
return new WinJS.Promise(function (complete, error, progress) {
tile.requestCreateForSelectionAsync({ x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height }, Windows.UI.Popups.Placement.above).done(function (isCreated) {
if (isCreated) {
complete(true);
} else {
complete(false);
}
});
});
}
6. Creare una funzione di rimozione
Se il riquadro secondario è già stato aggiunto, il pulsante di aggiunta diventa un pulsante di rimozione e il gestore dell'evento click del pulsante rimuove il riquadro. In questo esempio viene fornita la funzione che il gestore richiama per rimuovere il riquadro. Come parametri, la funzione accetta l'oggetto pulsante di aggiunta, sempre per mostrare il riquadro a comparsa di conferma, e l'ID univoco del riquadro secondario. Come per la funzione di aggiunta, la chiamata di rimozione restituisce un oggetto Promise.
Nota Qualsiasi riquadro secondario può essere rimosso anche tramite la barra dell'app nella schermata Start. Puoi scegliere di usare tale metodo per la rimozione, in tal caso non dovrai implementare la funzionalità di rimozione o fornire un pulsante di rimozione.
Nota In Windows Phone 8.1, al'utente non viene richiesta la conferma della rimozione di un riquadro secondario. Un riquadro secondario viene rimosso sul telefono esattamente allo stesso modo in cui si rimuove un qualsiasi altro riquadro. Il codice visualizzato qui verrà ignorato.
function unpinByElementAsync(element, unwantedTileID) {
var selectionRect = element.getBoundingClientRect();
var buttonCoordinates = { x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height };
var placement = Windows.UI.Popups.Placement.above;
var tileToDelete = new Windows.UI.StartScreen.SecondaryTile(unwantedTileID);
return new WinJS.Promise(function (complete, error, progress) {
tileToGetDeleted.requestDeleteForSelectionAsync(buttonCoordinates, placement).done(function (isDeleted) {
if (isDeleted) {
complete(true);
} else {
complete(false);
}
});
});
}
7. Implementare il gestore eventi per il pulsante
Quando l'utente seleziona il pulsante sulla barra dell'app, viene visualizzato un riquadro a comparsa che richiede conferma all'utente. Per assicurarti che la barra dell'app non sia nascosta mentre viene visualizzato il riquadro a comparsa, devi impostare la proprietà WinJS.UI.sticky della barra dell'app. Verifica inoltre che l'elemento padre del riquadro a comparsa sia assegnato correttamente. In questo esempio vengono chiamate le funzioni setAppbarButton, pinByElementAsync e unpinByElementAsync che abbiamo definito nei passaggi precedenti.
Tieni presente che il gestore richiama setAppbarButton sia che l'operazione venga conclusa correttamente che in caso di errore per le operazioni di aggiunta e rimozione. Se l'operazione viene eseguita correttamente, il pulsante passa dalla funzione di aggiunta a quella di rimozione e viceversa. Se l'operazione ha esito negativo, il pulsante rimane invariato. In entrambi i casi, la funzione deve essere richiamata per ripristinare la proprietà WinJS.UI.sticky su false in modo che la barra dell'app possa essere chiusa.
function appbarButtonClicked() {
document.getElementById("pinUnpinFromAppbar").winControl.sticky = true;
if (WinJS.UI.AppBarIcon.unpin === document.getElementById("commandButton").winControl.icon) {
unpinByElementAsync(document.getElementById("commandButton"), appbarTileId).done(function (isDeleted) {
if (isDeleted) {
WinJS.log && WinJS.log("Secondary tile was successfully unpinned.", "sample", "status");
setAppbarButton();
} else {
WinJS.log && WinJS.log("Secondary tile was not unpinned.", "sample", "error");
setAppbarButton();
}
});
} else {
pinByElementAsync(document.getElementById("commandButton"), appbarTileId, "App bar pinned secondary tile", "A secondary tile that was pinned by the user from the app bar").done(function (isCreated) {
if (isCreated) {
WinJS.log && WinJS.log("Secondary tile was successfully pinned.", "sample", "status");
setAppbarButton();
} else {
WinJS.log && WinJS.log("Secondary tile was not pinned.", "sample", "error");
setAppbarButton();
}
});
}
}
Riepilogo e passaggi successivi
In questa Guida introduttiva hai definito un pulsante nella barra dell'app con cui l'utente può aggiungere o rimuovere un riquadro secondario. Hai creato il riquadro secondario, definito molte delle proprietà e mostrato la finestra di dialogo di conferma all'utente che determina la successiva aggiunta del riquadro secondario alla schermata Start.
Dopo aver aggiunto un riquadro secondario, il riquadro dell'app padre crea un URI (Uniform Resource Identifier) del canale in modo che possa comunicare con il riquadro secondario. Per altre informazioni, vedi Guida introduttiva: Invio di notifiche a un riquadro secondario.
Argomenti correlati
Panoramica dei riquadri secondari
Guida introduttiva: Invio di una notifica a un riquadro secondario