Guida introduttiva: Aggiunta di controlli e stili WinJS (HTML)

Articolo
03/04/2016

[ 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 ]

La libreria Windows per JavaScript (WinJS) offre un'infrastruttura di qualità elevata che comprende controlli pagina, promesse e associazione dati, avanzate funzionalità dell'interfaccia utente come la virtualizzazione delle raccolte e controlli Windows ad alte prestazioni come ListView, FlipView e SemanticZoom.

Puoi usare WinJS nelle app di Windows Runtime, nei siti Web e quando usi tecnologie per app basate su HTML come Apache Cordova.

Osserva questa funzionalità in azione nella serie sulle funzionalità delle app dall'inizio alla fine: Interfaccia utente delle app di Windows Store, dall'inizio alla fine.

Prerequisiti

Partiamo dal presupposto che tu sappia come creare una semplice app di Windows Store scritta in JavaScript che usi il modello WinJS. Se hai bisogno di aiuto per creare la tua prima app, vedi Creare la prima app di Windows Store con JavaScript.
Partiamo dal presupposto che tu sappia come gestire eventi in un'app di Windows Store in JavaScript. Per sapere qual è il modo migliore per gestire gli eventi, vedi Guida introduttiva: Aggiunta di controlli e gestione degli eventi.

Che cos'è la libreria Windows per JavaScript?

WinJS è una libreria di file CSS e JavaScript. Contiene oggetti JavaScript organizzati in spazi dei nomi progettati per semplificare lo sviluppo di app di grande impatto. In WinJS sono inclusi oggetti che ti aiutano a gestire l'attivazione, ad accedere agli spazi di archiviazione e a definire classi e spazi dei nomi personalizzati.

Per l'elenco completo dei controlli inclusi in WinJS, vedi l'elenco dei controlli.
WinJS offre anche funzionalità di stile sotto forma di stili e classi CSS che puoi usare o sostituire. Per una descrizione dello stile dei controlli, vedi Guida introduttiva: Applicazione di stili ai controlli.

Aggiunta della libreria Windows per JavaScript a una pagina

Per usare la versione più recente di WinJS nella tua app o sito Web:

Scarica la versione più recente dalla pagina per il download di WinJS e copiala nella directory della tua app o del tuo sito Web.
Aggiungi i riferimenti per gli script e gli stili CSS WinJS in ogni pagina dell'app o del sito Web che usa le funzionalità di WinJS.

Questo esempio mostra l'aspetto di questi riferimenti per un'app con i file di WinJS nella directory radice.

    <!-- WinJS style sheets (include one) -->
    <link href="/WinJS/css/ui-dark.css" rel="stylesheet">
    <link href="/WinJS/css/ui-light.css" rel="stylesheet">

    <!-- WinJS code -->
    <script src="/WinJS/js/WinJS.js"></script>

Aggiunta di un controllo WinJS nel markup

Diversamente dai controlli HTML, i controlli WinJS non hanno elementi di markup dedicati: ad esempio, non puoi creare un controllo Rating aggiungendo un elemento <rating />. Per aggiungere un controllo WinJS, devi creare un elemento div e usare l'attributo data-win-control per specificare il tipo di controllo desiderato. Per aggiungere un controllo Rating, imposta l'attributo su "WinJS.UI.Rating".

Devi anche chiamare la funzione WinJS.UI.processAll nel codice JavaScript. WinJS.UI.processAll analizza il markup e crea istanze per tutti i controlli WinJS trovati.

Nell'insieme di esempi riportato di seguito viene mostrato come aggiungere un controllo WinJS a un progetto creato con il modello Applicazione vuota. Se crei un nuovo progetto Applicazione vuota, sarà più facile seguire gli esempi.

Hh465493.wedge(it-it,WIN.10).gif Per creare un nuovo progetto usando il modello Applicazione vuota

Avvia Microsoft Visual Studio.
Nella scheda Pagina iniziale fai clic su Nuovo progetto. Viene aperta la finestra di dialogo Nuovo progetto.
Nel riquadro Installato espandi JavaScript e seleziona il tipo di modello App di Windows Store. I modelli di progetto disponibili per JavaScript vengono visualizzati nel riquadro centrale della finestra di dialogo.
Nel riquadro centrale scegli il modello di progetto Applicazione vuota.
Nella casella di testo Nome immetti un nome per il progetto.
Fai clic su OK per creare il progetto. Ci vorrà qualche istante.

Hh465493.wedge(it-it,WIN.10).gif Per aggiungere un controllo WinJS

Crea l'elemento div in cui desideri posizionare il controllo. Imposta l'attributo data-win-control sul nome completo del controllo da creare. In questo esempio viene creato un controllo Rating nella pagina iniziale dell'app (file default.html).

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Adding WinJS controls and styles</title>

    <!-- WinJS references -->
    <link href="/WinJS/css/ui-dark.css" rel="stylesheet">
    <script src="/WinJS/js/WinJS.js"></script>

    <!-- AddingWinJSControlsAndStyles references -->
    <link href="/css/default.css" rel="stylesheet">
    <script src="/js/default.js"></script>
</head>
<body>

    <p>Create a WinJS control in markup</p>

    <div id="ratingControlHost" data-win-control="WinJS.UI.Rating">
    </div>

</body>
</html>

Il codice JavaScript deve chiamare WinJS.UI.processAll per inizializzare il controllo Rating creato nel passaggio precedente. Se stai usando il modello Applicazione vuota, il file default.js include già una chiamata a WinJS.UI.processAll:

(function () {
    "use strict";

    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;
    WinJS.strictProcessing();

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // TODO: This application has been newly launched. Initialize
                // your application here.
            } else {
                // TODO: This application has been reactivated from suspension.
                // Restore application state here.
            }
            args.setPromise(WinJS.UI.processAll());
        }
    };

    app.oncheckpoint = function (args) {
        // TODO: This application is about to be suspended. Save any state
        // that needs to persist across suspensions here. You might use the
        // WinJS.Application.sessionState object, which is automatically
        // saved and restored across suspension. If you need to complete an
        // asynchronous operation before your application is suspended, call
        // args.setPromise().
    };

    app.start();
})();

Se non stai usando il modello Applicazione vuota o se stai aggiungendo il controllo a una pagina creata autonomamente, potrebbe essere necessario aggiungere una chiamata a WinJS.UI.processAll.

Se hai aggiunto il controllo alla pagina iniziale dell'app, (in genere il file default.html), aggiungi una chiamata a WinJS.UI.processAll nel gestore di eventi onactivated, come illustrato nell'esempio precedente.
Se hai aggiunto il controllo a un controllo Page, non devi aggiungere una chiamata a WinJS.UI.processAll perché la chiamata viene aggiunta automaticamente dal controllo Page.
Se hai aggiunto il controllo a una pagina diversa dalla pagina iniziale dell'app, gestisci l'evento DOMContentLoaded e usa il gestore per chiamare WinJS.UI.processAll.
```
function initialize() {
    WinJS.UI.processAll();
}

document.addEventListener("DOMContentLoaded", initialize(), false);
```

La funzione WinJS.UI.processAll elabora il documento e attiva gli eventuali controlli WinJS dichiarati nel markup.

Quando esegui l'app, il controllo Rating viene visualizzato nel punto in cui è stato posizionato l'elemento host div.

Controllo Rating

Impostazione delle proprietà di un controllo WinJS nel markup

Quando crei un controllo HTML, puoi impostarne le proprietà usando attributi dedicati. Ad esempio, per impostare le proprietà type, min e max di un controllo input, puoi impostare gli attributi type, min e max nel markup:

<input type="range" min="0" max="20" />

Diversamente dai controlli HTML, i controlli WinJS non hanno tag di elementi o attributi dedicati, pertanto non puoi creare un controllo Rating e impostarne le proprietà usando questo markup:

<!-- Not valid markup. -->
<rating maxRating="10" averageRating="6" />

Per impostare una proprietà nel markup, devi usare l'attributo data-win-options. Accetta una stringa che contiene una o più coppie proprietà-valore:

data-win-options="{propertyName: propertyValue}"

In questo esempio, la proprietà maxRating di un controllo Rating viene impostata su 10.

<div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
    data-win-options="{maxRating: 10}">
</div>

Quando esegui l'app, il controllo Rating assume questo aspetto:

Il controllo Rating visualizza un sistema di classificazione a 10 stelle.

Per impostare più di una proprietà, separale con una virgola:

data-win-options="property1Name: property1Value, property2Name: property2Value"

Nell'esempio successivo vengono impostate due proprietà per il controllo Rating.

<div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
    data-win-options="{maxRating: 10, averageRating: 6}">
</div>

Quando esegui l'app, il controllo Rating assume questo aspetto:

Il controllo Rating visualizza una classificazione di 6 stelle su 10.

Se il valore della proprietà è un valore stringa, racchiudilo tra virgolette diverse (' o %%anp;quot;) rispetto a quelle usate per impostare l'attributo data-win-options. In questo esempio viene descritto come impostare la proprietà current del controllo TimePicker che accetta una stringa:

<div id="timepicker" data-win-control="WinJS.UI.TimePicker" 
    data-win-options="{current: '10:29 am'}">
</div>

Controllo TimePicker che visualizza l'orario delle 10:29.

Per scoprire se una proprietà è supportata da un determinato controllo WinJS, vedi la relativa pagina di riferimento.

Recupero di un controllo creato nel markup

Puoi anche impostare le proprietà di un controllo WinJS a livello di programmazione. Per accedere al controllo nel codice, recupera l'elemento host e usa la relativa proprietà winControl per recuperare il controllo. Negli esempi precedenti, l'elemento host del controllo Rating è "ratingControlHost".


var control = document.getElementById("ratingControlHost").winControl;

In alcuni casi, potresti avere la necessità di recuperare e modificare il controllo non appena è disponibile. Tieni presente che il metodo WinJS.UI.processAll è asincrono, pertanto il codice che lo segue potrebbe essere eseguito prima del completamento di WinJS.UI.processAll. Di conseguenza, non cercare di modificare immediatamente il controllo perché potrebbe non essere disponibile:


WinJS.UI.processAll();

// Don't do this:
var control = document.getElementById("ratingControlHost").winControl; 
control.averageRating = 3;

WinJS.UI.processAll restituisce un oggetto WinJS.Promise che puoi usare per chiamare una funzione quando il metodo WinJS.UI.processAll è completato. Nell'esempio riportato di seguito viene definita una funzione di completamento che recupera il controllo e imposta la relativa proprietà averageRating su 3.


// Do this instead:
WinJS.UI.processAll().then(function () {
    var control = document.getElementById("ratingControlHost").winControl;
    control.averageRating = 3; 
});

Nella sezione successiva viene descritto come aggiungere listener di eventi a un controllo WinJS.

Gestione di eventi per i controlli WinJS

Come per i controlli HTML, il modo preferito per associare listener di eventi a un controllo WinJS è usare la funzione addEventListener. Il recupero di un controllo WinJS è tuttavia leggermente diverso da quello di un controllo HTML.

Per gestire un evento:

Nel codice JavaScript recupera l'elemento host del controllo e usa la relativa proprietà winControl per recuperare il controllo.
Chiama la funzione addEventListener del controllo e specifica un evento e un gestore di eventi.

Nell'esempio seguente viene illustrato come gestire l'evento change di un controllo Rating.

Hh465493.wedge(it-it,WIN.10).gif Per gestire l'evento di modifica di un controllo Rating

Nel file HTML aggiungi un paragrafo e assegnagli un ID di "outputParagraph". Il listener di eventi eseguirà l'output in questo paragrafo.

        <p>Create a WinJS control in markup</p>

        <div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
            data-win-options="{maxRating: 10, averageRating: 6}">
        </div>

        <!-- This paragraph will be used to demonstrate event handling. -->
        <p id="outputParagraph"></p>

Nel codice JavaScript, crea una funzione del gestore di eventi denominata ratingChanged che accetta un parametro. Nell'esempio seguente viene creato un gestore di eventi che visualizza le proprietà e i valori contenuti nell'oggetto evento.


    function ratingChanged(event) {

        var outputParagraph = document.getElementById("outputParagraph");
        var output = event.type + ": <ul>";
        var property;
        for (property in event) {
            output += "<li>" + property + ": " + event[property] + "</li>";
        }

        outputParagraph.innerHTML = output + "</ul>";

    }

Usa la proprietà winControl per recuperare il controllo dal relativo elemento host e chiama la funzione addEventListener per aggiungere il gestore di eventi. In questo esempio viene recuperato il controllo non appena viene creato e viene aggiunto il gestore di eventi:

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // TODO: This application has been newly launched. Initialize
                // your application here.
            } else {
                // TODO: This application has been reactivated from suspension.
                // Restore application state here.
            }
            args.setPromise(WinJS.UI.processAll().then(function () {
                var control = document.getElementById("ratingControlHost").winControl;
                control.addEventListener("change", ratingChanged, false); 
            }));
        }
    };

Quando esegui l'applicazione e modifichi la classificazione, viene creato un elenco di proprietà e valori delle informazioni sull'evento.

Output dell'evento di modifica.

Aggiunta di un controllo WinJS nel codice

Negli esempi precedenti è stato descritto come creare e modificare un controllo WinJS creato nel markup, ma puoi creare un controllo WinJS anche usando il codice JavaScript.

Hh465493.wedge(it-it,WIN.10).gif Per creare un controllo WinJS nel codice

Crea l'elemento che ospiterà il controllo nel markup.
```
<div id="hostElement"></div>
```
Nel codice, preferibilmente nel gestore dell'evento DOMContentLoaded, recupera l'elemento host.
```
var hostElement = document.getElementById("hostElement");
```
Crea il controllo chiamandone il costruttore e passando l'elemento host al costruttore. Questo esempio crea un controllo Rating:
```
var ratingControl = new WinJS.UI.Rating(hostElement); 
```
Quando esegui il programma, viene visualizzato l'oggetto Rating creato:

Non è necessario chiamare WinJS.UI.processAll—è sufficiente chiamare WinJS.UI.processAll quando crei un controllo WinJS nel markup.

Riepilogo e passaggi successivi

Hai imparato a creare i controlli WinJS, a impostarne le proprietà e ad associare i gestori di eventi.

Nell'argomento successivo, Guida introduttiva: Applicazione di stili ai controlli, viene descritto come usare i fogli di stile CSS (Cascading Style Sheet) e le funzionalità di stile avanzate delle app di Windows Store in JavaScript. Per altre informazioni sui controlli specifici, vedi gli argomenti Elenco dei controlli e Controlli per funzione.