Démarrage rapide : épinglage d’une vignette secondaire (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de 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 ]

Remarque Vous n’utilisez pas JavaScript ? Voir Démarrage rapide : épinglage d’une vignette secondaire (XAML).

Cette rubrique vous guide tout au long de la procédure de création d’une vignette secondaire pour une application et son épinglage à l’écran d’accueil.

Prérequis

Conditions préalables à la compréhension de cette rubrique :

Bonnes connaissances des termes et des concepts liés aux vignettes secondaires. Pour plus d’informations, voir Vue d’ensemble des vignettes secondaires.
Aptitude à créer une application élémentaire Windows Store en JavaScript à l’aide des API Windows Runtime. Pour plus d’informations, voir Créer votre première application du Windows Store en JavaScript.
Compréhension de l’utilisation de Microsoft Visual Basic pour créer du code pour une application du Windows Store en HTML.

Important Pour voir le code fourni dans cette rubrique utilisé dans un exemple complet, voir Exemple de vignettes secondaires. L’exemple est fourni dans les versions JavaScript, C#, C++ et Visual Basic.

Instructions

1. Ajouter une barre de l’application avec un bouton Épingler/Détacher

Sur Windows, vous présentez normalement une opportunité d’épinglage à l’utilisateur par le biais d’un bouton Épingler à l’écran d’accueil dans votre barre de l’application. Pour plus d’informations sur la création d’une barre de l’application, voir Démarrage rapide : ajout d’une barre de l’application avec des commandes.

Remarque Dans les applications du Windows Phone Store, l’épinglage s’effectue généralement par l’intermédiaire d’un menu contextuel, et non via un bouton sur une barre de l’application.

L’exemple suivant déclare une barre de l’application avec un bouton. Le code suivant est ajouté à la page .html de votre projet auquel le reste du code présenté dans cette rubrique s’applique.


<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. Fournir un ID unique pour votre vignette secondaire


var appbarTileId = "MySecondaryTile";

3. Créer une fonction pour définir le bouton en tant que bouton d’épinglage ou de détachement

L’action de votre bouton d’épinglage bascule entre l’épinglage et le détachement de la vignette secondaire. Dans cet exemple, nous créons une fonction permettant de définir le bouton de façon appropriée, à l’aide d’icônes fournies par le système pour que l’apparence soit homogène avec les autres applications. Cette fonction est appelée dans le cadre du code d’initialisation de votre application, à chaque ouverture de la barre de l’application et immédiatement après une opération Épingler/Détacher réussie.

La ligne finale de cette fonction définit la propriété WinJS.UI.sticky de la barre de l’application sur false, ce qui permet de masquer la barre de l’application.


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. Afficher le bouton approprié et affecter un gestionnaire de clic du bouton

Dans cet exemple, dans le cadre de l’initialisation de l’application, nous utilisons la fonction setAppbarButton de l’étape précédente pour vérifier si la vignette secondaire est déjà épinglée et définir le texte du bouton en conséquence.

Nous affectons ensuite le gestionnaire appbarButtonClicked à l’événement click du bouton d’épinglage. Nous vous montrerons comment implémenter le gestionnaire d’événements dans la prochaine étape.

Appelez le code indiqué dans cette étape, avec toute autre initialisation que vous devez effectuer, dans le cadre de l’initialisation de votre application chaque fois que cette application est lancée.


document.getElementById("pinUnpinFromAppbar").disabled = false;
setAppbarButton();

id("commandButton").addEventListener("click", appbarButtonClicked, false);

5. Créer et épingler la vignette secondaire dans le gestionnaire d’événements du bouton

Cet exemple implémente une fonction unique qui peut être appelée par le gestionnaire d’événements de clic du bouton d’épinglage. Cette fonction collecte plusieurs étapes qui conduisent à la demande d’épinglage :

Attribuer les valeurs de propriétés requises pour la création de la vignette secondaire
Créer l’objet de la vignette secondaire
Spécifier d’autres propriétés de la vignette secondaire
Obtenir les coordonnées à l’écran permettant d’afficher le menu volant de confirmation (Windows uniquement)

Certaines propriétés de la vignette secondaire doivent être définies avant que la vignette puisse être épinglée. Si vous tentez d’épingler une vignette secondaire sans avoir défini au moins une de ces propriétés, la tentative échoue. Voici les propriétés requises :

ID unique de la vignette
Nom court (Windows 8.0 uniquement)
Nom d’affichage
Chaîne passée en argument à l’application parente quand la vignette secondaire est activée
Image du logo
Options de la vignette (Windows 8.0 uniquement)

Comme exemple de chaîne d’arguments, cet exemple transmet la date et l’heure auxquelles la vignette secondaire a été épinglée à l’écran d’accueil.

Remarque Sur Windows Phone 8.1, le nom d’affichage n’apparaît jamais sur une vignette secondaire moyenne (150x150). De pus, toutes les vignettes de téléphone sont initialement épinglées en tant que vignettes moyennes, ce qui fait que le paramètre newTileDesiredSize est ignoré sur le téléphone.

Remarque Si vous fournissez le même ID que celui d’une autre vignette secondaire, cette dernière est alors remplacée.


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;

Ensuite, nous créons l’objet de la vignette secondaire. Cette version du constructeur crée une moyenne vignette. Notez que si votre vignette secondaire reçoit des notifications, il est conseillé de déclarer toutes les tailles de vignettes. Vous devez, pour cela, fournir des images de logo par l’intermédiaire de la classe SecondaryTileVisualElements.


var tile = new Windows.UI.StartScreen.SecondaryTile(appbarTileId,
                                                    newTileDisplayName,
                                                    TileActivationArguments,
                                                    square150x150Logo,
                                                    newTileDesiredSize);

À présent que vous possédez un objet de vignette secondaire, vous pouvez spécifier les propriétés de la vignette secondaire qui ne sont pas définies par le biais du constructeur. Cet exemple spécifie la couleur du texte de premier plan et le petit logo. Il spécifie également que le nom d’affichage apparaît sur la vignette.

Remarque Sur Windows Phone 8.1, ni le petit logo ni le nom d’affichage n’apparaissent sur une vignette secondaire moyenne (150x150). Par ailleurs, il n’est pas possible de spécifier la couleur du texte de premier plan. Par conséquent, ces propriétés telles que définies dans cet exemple sont ignorées sur le téléphone.


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

Sur Windows, l’utilisateur doit confirmer l’épinglage d’une vignette secondaire. Dans la boîte de dialogue de confirmation, il peut remplacer le nom d’affichage de la vignette et effectuer une sélection parmi différentes tailles de vignette à épingler. Le menu volant de confirmation doit être affiché près du bouton qui a appelé la demande d’épinglage. Cet exemple récupère le rectangle entourant le bouton d’épinglage et spécifie que la boîte de dialogue de confirmation doit s’afficher au-dessus du bouton.

Remarque Sur Windows Phone 8.1, aucune boîte de dialogue de confirmation ne s’affiche à l’utilisateur. La vignette est simplement épinglée à l’écran d’accueil sous la forme d’une vignette moyenne et sans nom d’affichage. Le code présenté ici est ignoré.


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;

Ensuite, la fonction demande que la vignette secondaire soit épinglée.

Sur Windows Phone 8.1, cet appel épingle la vignette, suspend l’application et place l’utilisateur sur l’écran d’accueil.
Sur Windows, cet appel affiche le menu volant de confirmation qui demande à l’utilisateur l’autorisation d’épingler la vignette. En utilisant le rectangle entourant le bouton d’épinglage, cet exemple affiche le menu volant de confirmation au-dessus de ces coordonnées. En cas d’approbation de l’utilisateur, Windows crée la vignette secondaire et la place sur l’écran d’accueil. L’utilisateur reste dans l’application.


return new WinJS.Promise(function (complete, error, progress) {
    tile.requestCreateForSelectionAsync(buttonCoordinates, placement).done(function (isCreated) {
        if (isCreated) {
            complete(true);
        } else {
            complete(false);
        }
    });
});

Remarque Sur Windows Phone 8.1, un appel à RequestCreateAsync ou RequestCreateForSelectionAsyncferme l’application et place l’utilisateur sur l’écran d’accueil. Tout code qui suit la méthode RequestCreateAsync ou RequestCreateForSelectionAsync n’est donc pas exécuté. Par conséquent, dans les projets Windows Phone 8.1, vous devez écouter l’événement Suspending pour pouvoir effectuer toute opération, telle que l’enregistrement de l’état de l’application, qui doit être exécutée avant la fermeture de l’application.

Les fonctions appbarButtonClicked et pinByElementAsync complètes de l’exemple de vignettes secondaires sont présentées ici.


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. Créer une fonction de détachement

Lorsque la vignette secondaire est épinglée, le bouton d’épinglage devient un bouton de détachement et le gestionnaire d’événements de clic de ce bouton détache la vignette. Cet exemple fournit la fonction que le gestionnaire appelle pour détacher la vignette. Comme paramètres, la fonction accepte l’objet du bouton d’épinglage, à nouveau dans le but de placer le menu volant de confirmation, et l’ID unique de la vignette secondaire. Comme dans la fonction d’épinglage, l’appel de détachement retourne un objet Promise.

Remarque Toute vignette secondaire peut également être détachée par le biais de la barre de l’application de l’écran d’accueil. Vous avez l’option de vous appuyer sur cette méthode pour le détachement, auquel cas vous n’avez pas besoin d’implémenter de fonctionnalités de détachement ni de fournir un bouton de détachement.

Remarque Sur Windows Phone 8.1, l’utilisateur n’est pas invité à confirmer le détachement d’une vignette secondaire. Le détachement d’une vignette secondaire sur le téléphone est identique au détachement de toute autre vignette. Le code présenté ici est ignoré.


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. Implémenter le gestionnaire d’événements pour votre bouton

Lorsque l’utilisateur sélectionne votre bouton sur la barre de l’application, un menu volant demande à l’utilisateur de confirmer. Pour garantir que la barre de l’application ne disparaît pas lorsque le menu volant apparaît, vous devez définir la propriété WinJS.UI.sticky de la barre de l’application. De même, vérifiez que le parent de votre menu volant est correctement attribué. Cet exemple appelle les fonctions setAppbarButton, pinByElementAsync et unpinByElementAsync que nous avons définies aux étapes précédentes.

Notez que le gestionnaire appelle setAppbarButton aussi bien en cas de succès que d’échec des opérations d’épinglage et de détachement. Si l’opération a réussi, le bouton bascule entre épinglage et détachement. Si l’opération a échoué, le bouton demeure en l’état. Dans les deux cas, la fonction doit être appelée pour rétablir la propriété WinJS.UI.sticky sur false, afin que la barre de l’application puisse être masquée.


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

Récapitulatif et étapes suivantes

Dans cette rubrique de démarrage rapide, vous avez défini un bouton sur une barre de l’application, qui permet à un utilisateur d’épingler ou de détacher une vignette secondaire. Vous avez créé la vignette secondaire, défini un grand nombre de ses propriétés et présenté la boîte de dialogue de confirmation à l’utilisateur qui entraîne l’ajout final de la vignette secondaire à l’écran d’accueil.

Après avoir épinglé une vignette secondaire, la vignette de l’application parente crée un URI (Uniform Resource Identifier) de canal afin de pouvoir communiquer avec la vignette secondaire. Pour plus d’informations, voir Démarrage rapide : envoi d’une notification à une vignette secondaire.