Créer un modèle de widget avec le Concepteur de Cartes adaptatives

Pour un widget de carte adaptative, définissez l’interface utilisateur et les interactions avec un modèle JSON Cartes adaptatives et, éventuellement, une charge utile de données JSON distincte. Cet article vous guide à travers un modèle de widget de comptage avec la liaison de données et la disposition conditionnelle. Windows widgets peuvent également afficher du code HTML à partir d’une URL ; pour ce format de contenu, consultez les fournisseurs de widgets web.

Widget de comptage

L’exemple de cet article est un widget de comptage simple qui affiche une valeur entière et permet à l’utilisateur d’incrémenter la valeur en cliquant sur un bouton dans l’interface utilisateur du widget. Cet exemple de modèle utilise la liaison de données pour mettre à jour automatiquement l’interface utilisateur en fonction du contexte de données.

Les applications doivent implémenter un fournisseur de widgets pour générer et mettre à jour le modèle de widget et/ou les données et les transmettre à l’hôte du widget. L’article Implémenter un fournisseur de widgets dans une application win32 fournit des instructions pas à pas pour implémenter le fournisseur de widgets pour le widget de comptage que nous allons générer dans les étapes ci-dessous.

Concepteur de cartes adaptatives

Le Cartes adaptatives Designer est un outil en ligne pour modifier le json de la carte et afficher un aperçu de sa disposition et de sa liaison de données. Ouvrez le Designer pour travailler sur le modèle.

Important

Le Designer utilise ses propres options de renderer et d’hôte. Ne partez pas du principe que les fonctionnalités qu'elle offre sont prises en charge par le panneau Widgets ou qu'elle fournit des valeurs spécifiques $host à Windows. Ce guide pas à pas ne dépend pas d’un préréglage d’hôte ou d’un éditeur de données hôte. Testez le modèle final dans un fournisseur de widgets Windows pour chaque taille et thème pris en charge.

Les images ci-dessous illustrent la disposition de la carte, et non l’interface actuelle de Designer.

Commencez par une carte vierge

L’éditeur de charge utile de la carte contient la définition JSON de la carte. Remplacez son contenu par cette carte vide :

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": []
}

L’éditeur données d’exemple contient un contexte de données JSON facultatif. Pour plus d’informations sur la liaison de ces données au modèle, consultez Cartes adaptatives Template Language.

Propriétés de l’hôte de widgets Windows

Le tableau des widgets fournit les propriétés de l’hôte au moment de l’exécution. Référencez-les via $host dans les expressions de modèle, telles que ${$host.widgetSize}. Ces propriétés sont distinctes de la charge utile des données de votre fournisseur ; l’ajout d’un champ widgetSize aux exemples de données ne définit pas $host.widgetSize.

Propriété Valeur Description
host.widgetSize « small », « medium », ou « large » Taille du widget épinglé.
host.hostTheme « clair » ou « sombre » Thème actuel de l’appareil sur lequel la carte widgets s’affiche.
host.isSettingsPayload vrai ou faux Lorsque cette valeur est true, l’utilisateur a cliqué sur le bouton Personnaliser le widget dans le menu contextuel du widget. Vous pouvez utiliser cette valeur de propriété pour afficher les éléments de l’interface utilisateur des paramètres de personnalisation. Il s’agit d’une méthode alternative à l’utilisation de IWidgetProvider2.OnCustomizationRequested pour modifier la charge utile JSON dans l’application du fournisseur de widgets. Pour plus d’informations, consultez Implémentation de la personnalisation du widget.
host.isHeaderSupported vrai ou faux Lorsque cette valeur est true, la personnalisation de l’en-tête est prise en charge. Pour plus d’informations, consultez isHeaderSupported.
host.isHeader vrai ou faux Lorsque cette valeur est true, l’hôte demande une charge utile spécifiquement pour le rendu de l’en-tête du widget.
host.isWebSupported vrai ou faux Lorsque cette valeur est false, l’hôte ne prend actuellement pas en charge le chargement du contenu web d’un widget. Lorsque cela se produit, les widgets web affichent la charge utile JSON de secours fournie par le fournisseur de widgets, mais cette valeur peut être utilisée pour personnaliser davantage le contenu. Pour plus d’informations, consultez fournisseurs de widgets web
host.isUserContextAuthenticated vrai ou faux Lorsque cette valeur est false, la seule action prise en charge est Action.OpenUrl. La valeur de isUserContextAuthenticated peut être utilisée pour ajuster le contenu du widget de manière appropriée, en fonction des limitations d’interactivité.

Le widget de comptage utilise quatre éléments TextBlock et une action Action.Execute pour son bouton.

Ajouter des éléments TextBlock

Ajoutez quatre éléments TextBlock à partir de la palette d’éléments du Concepteur ou ajoutez-les directement dans la carte JSON. Avant l’application de la disposition conditionnelle, la carte comporte quatre lignes de texte, comme illustré ci-dessous.

Carte adaptative en cours. Il affiche un widget avec quatre lignes contenant le texte New TextBlock. Les quatre lignes de texte dépassent la bordure inférieure du widget.

Implémentation de la disposition conditionnelle

Dans l’éditeur de payload de carte, remplacez le tableau body par le fragment suivant :

"body": [
    {
        "type": "TextBlock",
        "text": "You have clicked the button ${count} times"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if medium",
        "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if small",
        "$when": "${$host.widgetSize==\"small\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if large",
        "$when": "${$host.widgetSize==\"large\"}"
    }
]

Dans le langage de modèle Cartes adaptatives, la propriété $when spécifie que l’élément conteneur est affiché lorsque la valeur associée est évaluée à true. Si la valeur est false, l’élément conteneur n’est pas affiché. Dans l’élément body de notre exemple, l’un des trois éléments TextBlock s’affiche et les deux autres masqués, en fonction de la valeur de la $host.widgetSize propriété. Pour plus d’informations sur les conditions prises en charge dans Cartes adaptatives, consultez la mise en page conditionnelle avec $when.

Sans évaluer les expressions de modèle, la carte affiche les quatre blocs de texte :

Carte adaptative en cours. Il affiche un widget avec quatre lignes contenant le texte spécifié dans la charge utile JSON indiquée à l’étape précédente. Au lieu de masquer les éléments de manière conditionnelle, tous les éléments sont visibles et dépassent la bordure inférieure de l’image.

Lorsque le tableau des widgets évalue le modèle avec $host.widgetSize défini sur "small", seul le bloc de texte de petite taille apparaît à côté du nombre :

Carte adaptative en cours. Il affiche un widget avec deux lignes contenant le texte spécifié dans la charge utile JSON. Seul le TextBlock pour la petite taille est rendu.

Après avoir intégré le modèle à votre fournisseur, redimensionnez le widget épinglé dans le panneau Widgets et vérifiez que le bloc de texte correspondant s’affiche. Déclarez chaque taille que vous souhaitez tester dans le manifeste du fournisseur de widgets. Une préversion du Designer générique sans données d’hôte Windows ne peut pas vérifier ces conditions.

Lier au contexte des données

L’exemple utilise une propriété de données nommée count, référencée par ${count} dans le premier TextBlock. Au moment de l’exécution, le fournisseur envoie la charge utile de données à l’hôte du widget. Au moment de la conception, entrez les données JSON suivantes dans l’éditeur des exemples de données et activez l’aperçu du Designer pour vérifier la liaison de données count. Cet exemple de données ne fournit pas les propriétés d'hôte Windows distinctes.

{"count": "2"}

Avec {"count": "2"} comme exemple de données, l’extension de modèle remplace ${count} par 2 dans le premier TextBlock. Vérifiez cette liaison dans le Designer après avoir activé l’aperçu. Vérifiez les conditions distinctes $host.widgetSize dans le tableau des widgets, comme décrit ci-dessus.

Carte adaptative en cours. La première ligne de texte inclut désormais la valeur 2 de la charge utile de données.

Ajouter un bouton

L’étape suivante consiste à ajouter un bouton à notre widget. Dans l’hôte du widget, lorsque l’utilisateur clique sur le bouton, l’hôte effectue une demande au fournisseur de widgets. Pour cet exemple, le fournisseur de widgets incrémente la valeur de nombre et retourne une charge utile de données mise à jour. Étant donné que cette opération nécessite un fournisseur de widgets, vous ne pourrez pas afficher ce comportement dans le Concepteur Cartes adaptatives, mais vous pouvez toujours utiliser le concepteur pour ajuster la disposition de votre bouton dans votre interface utilisateur.

Avec Cartes adaptatives, les éléments interactifs sont définis avec des éléments action. Ajoutez le bloc suivant de JSON directement après l’élément body dans l’éditeur de payload de carte. Veillez à ajouter une virgule après le crochet fermant (]) de l’élément ou le concepteur signalera une erreur de mise en forme.

,
"actions": [                                                      
    {                                                               
        "type": "Action.Execute",                               
        "title": "Increment",                                   
        "verb": "inc"                                           
    }                                                               
]

La propriété type sélectionne Action.Execute, que l’hôte du widget transfère au rappel OnActionInvoked de votre fournisseur. Utilisez Action.OpenUrl pour la navigation d’URL à la place ; il n’appelle pas cette fonction de rappel du fournisseur. Le titre fournit le texte du bouton et verb est l’opération définie par l’application que le fournisseur gère. Lorsque la valeur de $host.isUserContextAuthenticated est false, n’offre pas d’interactions Action.Execute ; seul Action.OpenUrl est pris en charge.

Carte adaptative finale. Un bouton bleu avec l’incrément de texte s’affiche après les deux lignes de texte.

Modèle de widget complet

La liste de codes suivante montre le modèle final pour l’interaction du widget de comptage. Son bouton Action.Execute nécessite un contexte utilisateur authentifié. Validez-le dans le tableau des widgets avec votre fournisseur ; le Designer n’exécute pas le gestionnaire d’incrémentation de votre fournisseur.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
    {
      "type": "TextBlock",
      "text": "You have clicked the button ${count} times"
    },
    {
      "type": "TextBlock",
       "text": "Rendering Only if Small",
      "$when": "${$host.widgetSize==\"small\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Medium",
      "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Large",
      "$when": "${$host.widgetSize==\"large\"}"
    }
    ],
   "actions": [
    {
      "type": "Action.Execute",
      "title": "Increment",
      "verb": "inc"
    }
  ]
}

Exemple de charge utile des paramètres

La liste de codes suivante montre un exemple simple de charge utile JSON qui utilise la propriété host.isSettingsPayload pour afficher un contenu différent lorsque l’utilisateur a cliqué sur le bouton Personnaliser le widget .

{
    "type": "AdaptiveCard",
    "body": [
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Content payload",
                "$when": "${!$host.isSettingsPayload}"
            }
        ]
    },
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Settings payload",
                "$when": "${$host.isSettingsPayload}"
            }
        ]
    }
],
"actions": [
    {
        "type": "Action.Execute",
        "title": "Increment",
        "verb": "inc",
        "$when": "${!$host.isSettingsPayload}"
    },
    {
        "type": "Action.Execute",
        "title": "Update Setting",
        "verb": "setting",
        "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}