Erstellen einer Widgetvorlage mit dem Adaptive Karten Designer

Die Benutzeroberfläche und Interaktion für Windows Widgets werden mithilfe von Adaptive Karten implementiert. Jedes Widget stellt eine visuelle Vorlage und optional eine Datenvorlage bereit, die mithilfe von JSON-Dokumenten definiert wird, die dem Adaptive Karten Schema entsprechen. Dieser Artikel führt Sie durch die Schritte zum Erstellen einer einfachen Widgetvorlage.

Ein Zähl-Widget

Das Beispiel in diesem Artikel ist ein einfaches Zähl-Widget, das einen ganzzahligen Wert anzeigt und es dem Benutzer ermöglicht, den Wert zu erhöhen, indem er auf eine Schaltfläche in der Benutzeroberfläche des Widgets klickt. In dieser Beispielvorlage wird die Datenbindung verwendet, um die Benutzeroberfläche basierend auf dem Datenkontext automatisch zu aktualisieren.

Apps müssen einen Widgetanbieter implementieren, um die Widgetvorlage und/oder die Daten zu generieren und zu aktualisieren und an den Widgethost zu übergeben. Der Artikel "Implementieren eines Widgetanbieters" in einer win32-App enthält schrittweise Anleitungen für die Implementierung des Widgetanbieters für das Zähl-Widget, das wir in den folgenden Schritten generieren werden.

Der Adaptive Karten-Designer

Der Adaptive Karten Designer ist ein interaktives Onlinetool, das das Generieren von JSON-Vorlagen für Adaptive Karten erleichtert. Mithilfe des Designers können Sie die gerenderten visuellen Elemente und das Datenbindungsverhalten in Echtzeit sehen, während Sie Ihre Widgetvorlage erstellen. Folgen Sie dem Link, um den Designer zu öffnen, der für alle Schritte in dieser Schritt-für-Schritt-Anleitung verwendet wird.

Erstellen einer leeren Vorlage aus einer Voreinstellung

Wählen Sie oben auf der Seite im Dropdownmenü " Host-App auswählen " die Option Widgets Board aus. Dadurch wird die Containergröße für die adaptive Karte auf eine Größe festgelegt, die für Widgets unterstützt wird. Beachten Sie, dass Widgets kleine, mittlere und große Größen unterstützen. Die Größe der Standardvorlagenvoreinstellung ist die richtige Größe für ein kleines Widget. Machen Sie sich keine Sorgen, wenn der Inhalt die Rahmen überläuft, da wir ihn durch Inhalt ersetzen, der so konzipiert ist, dass er in das Widget passt.

Unten auf der Seite befinden sich drei Texteditoren. Der als Card Payload Editor bezeichnete enthält die JSON-Definition der Benutzeroberfläche Ihres Widgets. Der Editor mit der Bezeichnung "Beispieldaten-Editor " enthält JSON, der einen optionalen Datenkontext für Ihr Widget definiert. Der Datenkontext wird dynamisch an die adaptive Karte gebunden, wenn das Widget gerendert wird. Weitere Informationen zur Datenbindung in Adaptive Karten finden Sie unter Adaptive Karten Template Language.

Der dritte Text-Editor ist als Beispiel-Hostdaten-Editor bezeichnet. Beachten Sie, dass dieser Editor unter den anderen beiden Editoren der Seite reduziert werden kann. Klicken Sie in diesem Falls auf das Pluszeichen +, um den Editor zu erweitern. Widgethost-Apps können Hosteigenschaften angeben, die Sie in Ihrer Widgetvorlage verwenden können, um unterschiedliche Inhalte basierend auf den aktuellen Eigenschaftswerten dynamisch anzuzeigen. Das Widgets Board unterstützt die folgenden Host-Eigenschaften.

Mit den Dropdownmenüs "Containergröße " und " Design " neben dem Dropdownmenü " Host-App auswählen " oben auf der Seite können Sie diese Eigenschaften festlegen, ohne den JSON-Code des Beispielhosts im Editor manuell zu bearbeiten.

Erstellen einer neuen Karte

Klicken Sie in der oberen linken Ecke der Seite auf "Neue Karte". Wählen Sie im Dialogfeld "Erstellen " die Option "Leere Karte" aus. Nun sollte eine leere adaptive Karte angezeigt werden. Sie werden auch feststellen, dass das JSON-Dokument im Beispieldaten-Editor leer ist.

Das von uns erstellte Zähl-Widget ist sehr einfach, nur bestehend aus vier TextBlock-Elementen und einer Aktion vom Typ "Action.Execute", die die Schaltfläche des Widgets definiert.

Hinzufügen von TextBlock-Elementen

Fügen Sie vier TextBlock-Elemente hinzu, indem Sie sie aus dem Bereich "Kartenelemente " auf der linken Seite auf die leere adaptive Karte im Vorschaubereich ziehen. An diesem Punkt sollte die Widgetvorschau wie das folgende Bild aussehen. Der Inhalt überläuft erneut außerhalb der Widgetrahmen, dies wird jedoch in den folgenden Schritten behoben.

Implementierung eines konditionalen Layouts

Der Kartennutzlast-Editor wurde aktualisiert, um die von uns hinzugefügten TextBlock-Elemente widerzuspiegeln. Ersetzen Sie die JSON-Zeichenfolge für das Body-Objekt durch Folgendes:

"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\"}"
    }
]

In der Adaptive Karten Vorlagensprache gibt die eigenschaft $when an, dass das enthaltende Element angezeigt wird, wenn der zugeordnete Wert als "true" ausgewertet wird. Wenn der Wert als falsch ausgewertet wird, wird das enthaltende Element nicht angezeigt. Im Body-Element in unserem Beispiel wird eines der drei TextBlock-Elemente angezeigt, und die anderen beiden ausgeblendet, je nach Wert der $host.widgetSize Eigenschaft. Weitere Informationen zu den in Adaptive Karten unterstützten Bedingungen finden Sie unter Conditional layout with $when.

Nun sollte die Vorschau wie die folgende Abbildung aussehen:

Beachten Sie, dass die bedingten Anweisungen nicht in der Vorschau angezeigt werden. Dies liegt daran, dass der Designer das Verhalten des Widgethosts nicht simuliert. Klicken Sie oben auf der Seite auf die Schaltfläche " Vorschaumodus ", um die Simulation zu starten. Die Widgetvorschau sieht nun wie in der folgenden Abbildung aus:

Wählen Sie im Dropdownmenü " Containergröße " die Option "Mittel" aus, und beachten Sie, dass die Vorschau wechselt, um nur den TextBlock für die mittlere Größe anzuzeigen. Der Container in der Vorschau ändert auch die Größe und zeigt, wie Sie die Vorschau verwenden können, um sicherzustellen, dass Ihre Benutzeroberfläche für jede unterstützte Größe in den Widgetcontainer passt.

Binden an den Datenkontext

Unser Beispiel-Widget verwendet eine benutzerdefinierte Zustandseigenschaft namens "count". Sie können in der aktuellen Vorlage sehen, dass der Wert für den ersten TextBlock den Variablenverweis $countenthält. Wenn das Widget im Widgets Board ausgeführt wird, ist der Widgetanbieter dafür verantwortlich, die Datennutzlast zusammenzustellen und an den Widgethost zu übergeben. Zur Entwurfszeit können Sie den Beispieldaten-Editor verwenden, um Ihre Datennutzlast zu prototypieren und zu sehen, wie sich unterschiedliche Werte auf die Anzeige Ihres Widgets auswirken. Ersetzen Sie die leere Datennutzlast durch den folgenden JSON-Code.

{"count": "2"}

Beachten Sie, dass die Vorschau nun den für die Count-Eigenschaft angegebenen Wert in den Text für den ersten TextBlock einfügt.

Hinzufügen einer Schaltfläche

Der nächste Schritt besteht darin, unserem Widget eine Schaltfläche hinzuzufügen. Wenn der Benutzer auf die Schaltfläche klickt, sendet der Host im Widgethost eine Anforderung an den Widget-Anbieter. In diesem Beispiel erhöht der Widgetanbieter den Zählerwert und gibt eine aktualisierte Datennutzlast zurück. Da für diesen Vorgang ein Widgetanbieter erforderlich ist, können Sie dieses Verhalten im Adaptive Karten-Designer nicht anzeigen, aber Sie können den Designer weiterhin verwenden, um das Layout Ihrer Schaltfläche in der Benutzeroberfläche anzupassen.

Mit Adaptive Karten werden interaktive Elemente mit action-Elementen definiert. Fügen Sie den folgenden JSON-Block direkt nach dem Body-Element im Kartennutzlast-Editor hinzu. Achten Sie darauf, nach der schließenden Klammer (]) des Textkörperelements ein Komma hinzuzufügen, oder der Designer meldet einen Formatierungsfehler.

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

In dieser JSON-Zeichenfolge gibt die Typeigenschaft den Typ der Aktion an, die dargestellt wird. Widgets unterstützen nur den Aktionstyp "Action.Execute". Der Titel enthält den Text, der auf der Schaltfläche für die Aktion angezeigt wird. Die Verb-Eigenschaft ist eine appdefinierte Zeichenfolge, die der Widgethost an den Widgetanbieter sendet, um die mit der Aktion verknüpfte Absicht zu kommunizieren. Ein Widget kann mehrere Aktionen haben, und der Widgetanbietercode überprüft den Wert des Verbs in der Anforderung, um zu bestimmen, welche Aktion ausgeführt werden soll.

Die vollständige Widgetvorlage

Die folgende Codeauflistung zeigt die endgültige Version der JSON-Nutzlast.

{
    "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"
    }
  ]
}

Beispiel für die Einstellungsnutzlast

Die folgende Codeauflistung zeigt ein einfaches Beispiel für eine JSON-Nutzlast, die die Eigenschaft host.isSettingsPayload verwendet, um unterschiedliche Inhalte anzuzeigen, wenn der Benutzer auf die Schaltfläche " Widget anpassen " geklickt hat.

{
    "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.Submit",
    "title": "Increment",
    "verb": "inc",
    "$when": "${!$host.isSettingsPayload}"
    },
    {
    "type": "Action.Submit",
    "title": "Update Setting",
    "verb": "setting",
    "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}