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

Applies to Windows and Windows Phone

WinJS fournit un ensemble de nouveaux contrôles conçus pour les applications du Windows Store en JavaScript, tels que les contrôles WinJS.UI.DatePicker, WinJS.UI.FlipView, WinjS.UI.ListView et WinJS.UI.Rating. Elle comprend également deux feuilles de style (l’une avec un modèle de couleurs foncées, l’autre avec un modèle de couleurs claires) qui donne à votre application l’apparence de Windows 8.

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.

Attention  Les procédures décrites dans cet article utilisent les contrôles DatePicker et Rating, qui ne sont pas pris en charge sur Windows Phone 8.1. Pour obtenir une liste complète des contrôles WinJS pris en charge sur Windows Phone 8.1, voir Modifications apportées aux API WinJS sur Windows Phone 8.1.

Prérequis

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 des applications du Windows Store en JavaScript. WinJS comprend des objets qui vous permettent de gérer les opérations d’activation, d’accès au stockage et de définir vos propres classes et espaces de noms. Elle comprend également un ensemble de contrôles :

ContrôleDescription

AppBar

Affiche les commandes.

BackButton

Bouton qui offre une navigation vers l’arrière à l’utilisateur.

DatePicker

Permet à l’utilisateur de sélectionner une date.

FlipView

Affiche une collection d’éléments, un à la fois.

Flyout

Affiche un message nécessitant une action de la part de l’utilisateur. (À la différence d’une boîte de dialogue, un objet Flyout ne crée pas de fenêtre distincte.)

ListView

Affiche une collection d’éléments dans une disposition en grille ou en liste.

HtmlControl

Affiche une page HTML.

ItemContainer

Crée un élément sur lequel l’utilisateur peut appuyer, et qu’il peut balayer et faire glisser.

Menu

Menu volant permettant d’afficher des commandes.

NavBar

Type d’objet AppBar qui affiche des commandes de navigation.

PageControl

Ensemble de code HTML, JavaScript et CSS qui décrit une page. Vous pouvez naviguer jusqu’à un contrôle PageControl ou l’utiliser comme contrôle personnalisé.

Rating

Permet à l’utilisateur d’évaluer un élément.

Repeater

Génère du code HTML à partir d’un ensemble de données et d’un modèle.

SearchBox

Permet à l’utilisateur d’effectuer des requêtes de recherche et de sélectionner des suggestions.

SemanticZoom

Permet à l’utilisateur d’effectuer un zoom entre deux affichages différents fournis par deux contrôles enfants. Un contrôle enfant fournit l’affichage en zoom arrière, tandis que l’autre fournit l’affichage en zoom avant.

SettingsFlyout

Octroie à l’utilisateur un accès rapide et contextuel aux paramètres de l’application.

TimePicker

Permet à l’utilisateur de sélectionner une heure.

ToggleSwitch

Active et désactive un élément.

Tooltip

Affiche une info-bulle qui prend en charge du contenu riche (tel que des images et du texte mis en forme) pour afficher davantage d’informations sur un objet.

ViewBox

Ajuste un seul élément enfant pour remplir l’espace disponible sans le redimensionner. Le contrôle réagit aux modifications de la taille du conteneur et aux modifications de la taille de l’élément enfant. Par exemple, ce contrôle réagit si une demande de support entraîne une modification des proportions.

x-ms-webview

Affiche le contenu HTML. Utilisez ce contrôle pour afficher des pages Web dans votre application.

 

(Pour la liste complète des contrôles, voir la liste de 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

WinJS ne peut être utilisé que si votre application contient les fichiers de la bibliothèque WinJS et que chaque page qui utilise des fonctionnalités de WinJS possède les références CSS et de script adéquates.


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

    <!-- WinJS code -->
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

Lorsque vous utilisez Microsoft Visual Studio pour créer une application du Windows Store en JavaScript, les fichiers dont vous avez besoin sont automatiquement inclus. L’exemple suivant illustre la page default.html d’un projet qui utilise le modèle Application vide.


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

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

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

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).gifPour créer un projet à l’aide du modèle Application vide

  1. Lancez Visual Studio.

  2. Sous l’onglet Page de démarrage, cliquez sur Nouveau projet. La boîte de dialogue Nouveau projet s’ouvre.

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

  4. Dans le volet central, sélectionnez le modèle de projet Application vide.

  5. Dans la zone de texte Nom, entrez un nom pour votre projet.

  6. Cliquez sur OK pour créer le projet. L’opération ne prend qu’un instant.

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

  1. 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="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet">
        <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
        <script src="//Microsoft.WinJS.2.0/js/ui.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>
    
    
  2. 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 :

  1. 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.
  2. 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).gifPour gérer l’événement de modification d’un contrôle d’évaluation

  1. 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>
    
    
  2. 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>";
    
        }
    
    
    
  3. 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).gifPour créer un contrôle WinJS dans du code

  1. Dans votre balisage, créez l’élément destiné à héberger votre contrôle.
    
    <div id="hostElement"></div>
    
    
  2. 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");
    
    
  3. 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éé :

    Contrôle d’évaluation créé dans du code

    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.

Exemples

Rubriques associées

Liste des contrôles
Contrôles par fonction
Informations de référence des API Windows Runtime et bibliothèque Windows pour JavaScript

 

 

Afficher:
© 2014 Microsoft