Démarrage rapide : épinglage d’une vignette secondaire
Réduire la table des matières
Développer la table des matières
Langage: HTML | XAML

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

[ 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 C#/VB/C++ ? Voir Démarrage rapide : épinglage d’une vignette secondaire (HTML).
 

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 :

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. Facultatif : Ajouter des espaces de noms

Pour simplifier votre code, ajoutez les lignes suivantes aux fichiers .cs de votre projet qui contiennent le code se trouvant dans le reste de ce guide de démarrage rapide (ou votre version de ce code). L’ensemble du code figurant dans cette rubrique suppose que vous avez ajouté ces lignes et il ne pourra pas être compilé sans cela. Windows.UI.StartScreen contient les objets de vignette secondaire et Windows.UI.Xaml.Controls est utilisé avec les barres et les boutons de l’application.



using Windows.UI.StartScreen;
using Windows.UI.Xaml.Controls;

2. 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 façon de créer une barre de l’application, voir Démarrage rapide : ajout de barres de l’application.

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.

Sur Windows, lorsque l’utilisateur sélectionne votre bouton Épingler/Détacher, un menu volant s’affiche pour lui demander de confirmer. Pour éviter que la barre de l’application ne soit masquée pendant que le menu volant s’affiche, affectez à la propriété IsSticky la valeur True.

Le code suivant est ajouté à la page .xaml de votre projet pour laquelle le reste du code présenté dans cette rubrique constitue le code-behind.



<Page.BottomAppBar>
    <CommandBar x:Name="SecondaryTileCommandBar" Padding="10,0,10,0" IsSticky="True" IsOpen="True">
        <AppBarButton x:Name="PinUnPinCommandButton" Icon="Pin" Label="Pin" />
    </CommandBar>
</Page.BottomAppBar>

3. Fournir un ID unique pour votre vignette secondaire



public const string appbarTileId = "MySecondaryTile";

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



private void ToggleAppBarButton(bool showPinButton)
{
    if (showPinButton)
    {
        this.PinUnPinCommandButton.Label = "Pin to Start";
        this.PinUnPinCommandButton.Icon = new SymbolIcon(Symbol.Pin);
    }
    else
    {
        this.PinUnPinCommandButton.Label = "Unpin from Start";
        this.PinUnPinCommandButton.Icon = new SymbolIcon(Symbol.UnPin);
    }

    this.PinUnPinCommandButton.UpdateLayout();
}

5. 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 ToggleAppBarButton 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 pinToAppBar_Click à 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.



void Init()
{
    ToggleAppBarButton(!SecondaryTile.Exists(MainPage.appbarTileId));
    this.PinUnPinCommandButton.Click += this.pinToAppBar_Click;
}

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


string displayName = "Secondary tile pinned through app bar";
string tileActivationArguments = MainPage.appbarTileId + " was pinned at=" + DateTime.Now.ToLocalTime().ToString();
Uri square150x150Logo = new Windows.Foundation.Uri("ms-appx:///Assets/square150x150Tile-sdk.png");
TileSize newTileDesiredSize = 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.



SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId, 
                                                displayName, 
                                                tileActivationArguments,
                                                square150x150Logo, 
                                                TileSize.Square150x150);

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



secondaryTile.VisualElements.ShowNameOnSquare150x150Logo = true;                       
secondaryTile.VisualElements.ForegroundText = ForegroundText.Dark;                        
secondaryTile.VisualElements.Square30x30Logo = new 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 (« sender ») 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é.



Windows.Foundation.Rect rect = MainPage.GetElementRect((FrameworkElement)sender);
Windows.UI.Popups.Placement 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.


bool isPinned = await secondaryTile.RequestCreateForSelectionAsync(rect, placement);

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.

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 le code que le gestionnaire appellera de façon asynchrone pour détacher la vignette. De nouveau, cet appel affiche une boîte de dialogue de confirmation au lieu de détacher véritablement la vignette de l’écran d’accueil. En cas d’approbation, Windows supprime la vignette secondaire de l’écran d’accueil.

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.
 


SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId);
bool isUnpinned = await secondaryTile.RequestDeleteForSelectionAsync(rect, placement);

Enfin, nous rétablissons la propriété IsSticky de la barre de l’application sur false afin de pouvoir masquer le menu volant.



rootPage.BottomAppBar.IsSticky = false;

Le gestionnaire d’événements pinToAppBar_Click complet est illustré ici. Notez que le gestionnaire appelle ToggleAppBarButton après les opérations d’épinglage et de détachement. Si l’opération échoue, le bouton ne bascule pas entre les deux états.



async void pinToAppBar_Click(object sender, RoutedEventArgs e)
{
#if WINDOWS_APP
    this.SecondaryTileCommandBar.IsSticky = true;
#endif
    
    if (SecondaryTile.Exists(MainPage.appbarTileId))
    {
        // Unpin
        SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId);
    
        Windows.Foundation.Rect rect = MainPage.GetElementRect((FrameworkElement)sender);
        Windows.UI.Popups.Placement placement = Windows.UI.Popups.Placement.Above;
        
        bool isUnpinned = await secondaryTile.RequestDeleteForSelectionAsync(rect, placement);
    
        ToggleAppBarButton(isUnpinned);
    }
    else
    {
        // Pin
        Uri square150x150Logo = new Uri("ms-appx:///Assets/square150x150Tile-sdk.png");
        string tileActivationArguments = MainPage.appbarTileId + " was pinned at = " + DateTime.Now.ToLocalTime().ToString();
        string displayName = "Secondary tile pinned through app bar";
    
        TileSize newTileDesiredSize = TileSize.Square150x150;
    
        SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId,
                                                        displayName, 
                                                        tileActivationArguments,
                                                        square150x150Logo,
                                                        newTileDesiredSize);
    
        Uri square30x30Logo = new Uri("ms-appx:///images/square30x30Tile-sdk.png");
        secondaryTile.VisualElements.Square30x30Logo = new Uri("ms-appx:///images/square30x30Tile-sdk.png");
        secondaryTile.VisualElements.ShowNameOnSquare150x150Logo = true;
        secondaryTile.VisualElements.ForegroundText = ForegroundText.Dark;
    
        Windows.Foundation.Rect rect = MainPage.GetElementRect((FrameworkElement)sender);
        Windows.UI.Popups.Placement placement = Windows.UI.Popups.Placement.Above;

#if WINDOWS_APP
        bool isPinned = await secondaryTile.RequestCreateForSelectionAsync(rect, placement);

        ToggleAppBarButton(!isPinned);
#endif

#if WINDOWS_PHONE_APP
       await secondaryTile.RequestCreateAsync();
#endif
    }

#if WINDOWS_APP
    this.BottomAppBar.IsSticky = false;
#endif
}

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.

Rubriques associées

Exemple de vignettes secondaires
Vue d’ensemble des vignettes secondaires
Démarrage rapide : envoi de notifications à une vignette secondaire
Recommandations et liste de vérification sur les vignettes secondaires
SecondaryTile class

 

 

Afficher:
© 2017 Microsoft