Démarrage rapide : ajout de contrôles et de styles WinJS (HTML)

Article
03/04/2016

[ Cet article est destiné aux développeurs Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

La Bibliothèque Windows pour JavaScript (WinJS) fournit une infrastructure haute qualité, notamment des contrôles de page, des promesses et des liaisons de données, des fonctionnalités d’interface utilisateur soignées telles que la virtualisation des collections, ainsi que des contrôles Windows hautes performances comme ListView, FlipView et SemanticZoom.

Vous pouvez utiliser WinJS dans vos applications Windows Runtime, dans vos sites web et lors de l’utilisation de technologies d’application HTML, comme Apache Cordova.

Voir cette fonctionnalité appliquée dans notre série Fonctionnalités d’application de A à Z : Interface utilisateur des applications du Windows Store, de A à Z.

Prérequis

Nous partons du principe que vous savez créer une application élémentaire Windows Store en JavaScript qui utilise le modèle WinJS. Pour obtenir de l’aide lors de la création de votre première application, voir Créer votre première application du Windows Store en JavaScript.
Nous partons du principe que vous savez gérer les événements d’une application du Windows Store en JavaScript. Pour découvrir les meilleures pratiques en matière de gestion des événements, voir Démarrage rapide : ajout de contrôles HTML et gestion des événements.

Qu’est-ce que la bibliothèque Windows pour JavaScript ?

WinJS est une bibliothèque de fichiers CSS et JavaScript. Elle contient des objets JavaScript, organisés en espaces de noms, conçus pour faciliter le développement d’applications attrayantes. WinJS comprend des objets qui vous permettent de gérer les opérations d’activation et d’accès au stockage et de définir vos propres classes et espaces de noms.

Pour découvrir la liste complète des contrôles fournis par WinJS, voir la Liste des contrôles.
WinJS fournit également des fonctionnalités de stylisation sous la forme de classes et de styles CSS que vous pouvez utiliser ou redéfinir. (La stylisation des contrôles est décrite dans Démarrage rapide : application de styles aux contrôles.)

Ajout de la bibliothèque Windows pour JavaScript à votre page

Pour utiliser la dernière version de WinJS dans votre application ou site web :

Téléchargez la dernière version depuis la page Obtenir WinJS (en anglais) et copiez-la dans le répertoire de votre application ou site web.
Ajoutez des références de script et CSS WinJS à chaque page de votre application ou site web qui utilise des fonctionnalités WinJS.

L’exemple ci-après montre à quoi ressemblent ces références pour une application dont les fichiers WinJS résident dans son répertoire racine.

    <!-- 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>

Ajout d’un contrôle WinJS au balisage

À la différence des contrôles HTML, les contrôles WinJS ne possèdent pas d’éléments de balisage dédiés : vous ne pouvez pas créer de contrôle Rating à l’aide d’un élément <rating />, par exemple. Pour ajouter un contrôle WinJS, créez un élément div et utilisez l’attribut data-win-control pour spécifier le type de contrôle souhaité. Pour ajouter un contrôle Rating, affectez à l’attribut la valeur "WinJS.UI.Rating".

Vous devez également appeler la fonction WinJS.UI.processAll dans votre code JavaScript. La fonction WinJS.UI.processAll analyse votre balisage et instancie tous les contrôles WinJS détectés.

La suite d’exemples suivante montre comment ajouter un contrôle WinJS à un projet créé à l’aide du modèle Application vide. Elle est plus aisée à suivre si vous créez un projet à l’aide du modèle Application vide.

Hh465493.wedge(fr-fr,WIN.10).gif Pour créer un projet à l’aide du modèle Application vide

Lancez Microsoft Visual Studio.
Sous l’onglet Page de démarrage, cliquez sur Nouveau projet. La boîte de dialogue Nouveau projet s’ouvre.
Dans le volet Installé, développez JavaScript, puis sélectionnez le type de modèle Application du Windows Store. Les modèles de projets proposés pour JavaScript s’affichent dans le volet central de la boîte de dialogue.
Dans le volet central, sélectionnez le modèle de projet Application vide.
Dans la zone de texte Nom, entrez un nom pour votre projet.
Cliquez sur OK pour créer le projet. L’opération ne prend qu’un instant.

Hh465493.wedge(fr-fr,WIN.10).gif Pour ajouter un contrôle WinJS

Créez l’élément div dans lequel placer le contrôle. Définissez son attribut data-win-control sur le nom qualifié complet du contrôle à créer. L’exemple suivant crée un contrôle Rating dans la page d’accueil de l’application (fichier 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>

Votre code JavaScript doit appeler WinJS.UI.processAll pour initialiser le contrôle Rating que vous avez créé à l’étape précédente. Si vous utilisez le modèle Application vide, le fichier default.js comprend déjà un appel de la fonction 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();
})();

Si vous n’utilisez pas le modèle Application vide ou que vous ajoutez le contrôle à une page que vous avez créée vous-même, vous devrez peut-être ajouter un appel de la fonction WinJS.UI.processAll.

Si vous avez ajouté le contrôle à la page d’accueil de votre application (qui est généralement le fichier default.html), ajoutez un appel de la fonction WinJS.UI.processAll dans votre gestionnaire d’événements onactivated, comme illustré dans l’exemple précédent.
Si vous avez ajouté le contrôle à un contrôle de page, vous n’avez pas besoin d’ajouter d’appel de la fonction WinJS.UI.processAll, car le contrôle de page effectue cette opération automatiquement.
Si vous avez ajouté le contrôle à une page qui n’est pas la page d’accueil de votre application, gérez l’événement DOMContentLoaded et utilisez le gestionnaire pour appeler la fonction WinJS.UI.processAll.
```
function initialize() {
    WinJS.UI.processAll();
}

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

La fonction WinJS.UI.processAll traite le document et active tous les contrôles WinJS que vous avez déclarés dans le balisage.

Lorsque vous exécutez l’application, le contrôle Rating apparaît à l’endroit où vous avez positionné l’élément hôte div.

Contrôle d’évaluation

Définition des propriétés d’un contrôle WinJS dans le balisage

Lorsque vous créez un contrôle HTML, vous pouvez définir ses propriétés à l’aide d’attributs dédiés. Par exemple, pour définir les propriétés type, min et max d’un contrôle input, vous pouvez définir les attributs type, min et max dans votre balisage :

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

À la différence des contrôles HTML, les contrôles WinJS ne possèdent pas de balises d’élément ou d’attribut dédiées ; par exemple, vous ne pouvez pas créer un contrôle Rating et définir ses propriétés à l’aide du balisage suivant :

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

À la place, vous utilisez l’attribut data-win-options pour définir une propriété dans le balisage. Cet attribut prend une chaîne qui contient une ou plusieurs paires propriété/valeur :

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

L’exemple suivant définit la propriété maxRating d’un contrôle Rating sur 10.

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

Lorsque vous exécutez l’application, le contrôle Rating ressemble à ceci :

Le contrôle d’évaluation montre un système d’évaluation à 10 étoiles.

Pour définir plusieurs propriétés, séparez-les par une virgule :

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

L’exemple suivant définit deux propriétés du contrôle Rating.

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

Lorsque vous exécutez l’application, le contrôle Rating ressemble désormais à ceci :

Le contrôle d’évaluation montre une évaluation de 6 étoiles sur 10.

Si la valeur de la propriété est elle-même une chaîne, placez-la entre des guillemets d’un autre type (' ou ") que ceux que vous avez utilisés pour définir l’attribut data-win-options. L’exemple suivant montre comment définir la propriété current du contrôle TimePicker :

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

Contrôle TimePicker affichant l’heure 10:29 AM.

Pour déterminer si une propriété est prise en charge par un contrôle WinJS, reportez-vous à sa page de référence.

Récupération d’un contrôle que vous avez créé dans le balisage

Vous pouvez également définir par programme les propriétés d’un contrôle WinJS. Pour accéder au contrôle dans du code, récupérez l’élément hôte, puis utilisez sa propriété winControl pour récupérer le contrôle. Dans les exemples précédents, l’élément hôte du contrôle Rating est "ratingControlHost".


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

Dans certains cas, vous pouvez souhaiter récupérer et manipuler le contrôle dès qu’il est disponible. La méthode WinJS.UI.processAll étant asynchrone, tout code qui la suit peut s’exécuter avant la fin de l’exécution de la fonction WinJS.UI.processAll. Par conséquent, n’essayez pas de manipuler le contrôle immédiatement, car il se peut qu’il ne soit pas disponible :


WinJS.UI.processAll();

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

La fonction WinJS.UI.processAll retourne un objet WinJS.Promise qui vous permet d’appeler une fonction lorsque la méthode WinJS.UI.processAll prend fin. Cet exemple définit une fonction d’achèvement qui récupère le contrôle et définit sa propriété averageRating sur 3.


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

La section suivante explique comment ajouter des détecteurs d’événement à un contrôle WinJS.

Gestion des événements pour les contrôles WinJS

À l’image des contrôles HTML, la procédure par défaut pour attacher des détecteurs d’événement pour un contrôle WinJS consiste à utiliser la fonction addEventListener. Toutefois, la récupération d’un contrôle WinJS diffère légèrement de la récupération d’un contrôle HTML.

Pour gérer un événement :

Dans votre code JavaScript, récupérez l’élément hôte du contrôle et utilisez sa propriété winControl pour récupérer le contrôle.
Appelez la fonction addEventListener du contrôle, puis spécifiez un événement et un gestionnaire d’événements.

L’exemple suivant montre comment gérer l’événement change d’un contrôle Rating.

Hh465493.wedge(fr-fr,WIN.10).gif Pour gérer l’événement de modification d’un contrôle d’évaluation

Dans votre fichier HTML, ajoutez un paragraphe et attribuez-lui un ID ayant pour valeur "outputParagraph". Votre détecteur d’événement sera redirigé vers ce paragraphe.

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

Dans votre code JavaScript, créez une fonction de gestionnaire d’événements appelée ratingChanged qui prend un paramètre. L’exemple suivant crée un gestionnaire d’événements qui affiche les propriétés et les valeurs contenues dans l’objet événement.


    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>";

    }

Utilisez la propriété winControl pour récupérer le contrôle dans son élément hôte et appelez la fonction addEventListener pour ajouter votre gestionnaire d’événements. L’exemple suivant récupère le contrôle dès qu’il est créé et ajoute le gestionnaire d’événements :

    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); 
            }));
        }
    };

Lorsque vous exécutez l’application et que vous modifiez l’évaluation, une liste de propriétés et de valeurs relatives à l’événement est créée.

Sortie de l’événement de modification

Ajout d’un contrôle WinJS dans du code

Les exemples précédents ont montré comment créer un contrôle WinJS et manipuler celui-ci dans votre balisage, mais vous pouvez également créer un contrôle WinJS à l’aide d’un code JavaScript.

Hh465493.wedge(fr-fr,WIN.10).gif Pour créer un contrôle WinJS dans du code

Dans votre balisage, créez l’élément destiné à héberger votre contrôle.
```
<div id="hostElement"></div>
```
Dans votre code (de préférence dans votre gestionnaire d’événements DOMContentLoaded), récupérez l’élément hôte.
```
var hostElement = document.getElementById("hostElement");
```
Créez votre contrôle en appelant son constructeur et en transmettant l’élément hôte à ce dernier. Cet exemple crée un contrôle Rating :
```
var ratingControl = new WinJS.UI.Rating(hostElement); 
```
Lorsque vous exécutez le programme, il affiche l’objet Rating que vous avez créé :

Il est inutile d’appeler WinJS.UI.processAll ; vous ne devez appeler WinJS.UI.processAll que lorsque vous créez un contrôle WinJS dans le balisage.

Récapitulatif et étapes suivantes

Vous avez appris à créer des contrôles WinJS, à définir leurs propriétés et à attacher des gestionnaires d’événements.

La rubrique suivante, Démarrage rapide : application de styles aux contrôles, explique comment utiliser des feuilles de style en cascade (CSS) et les fonctionnalités de stylisation améliorées des applications du Windows Store en JavaScript. Pour plus d’informations sur des contrôles spécifiques, voir les rubriques Liste des contrôles et Contrôles par fonction.