Erstellen einer Widgetvorlage mit dem Adaptive Karten Designer

Definieren Sie für ein Adaptive Card-Widget die Benutzeroberfläche und Interaktionen mit einer Adaptive Karten JSON-Vorlage und optional eine separate JSON-Datenpayload. Dieser Artikel führt Sie durch eine Zähl-Widget-Vorlage mit Datenbindung und bedingtem Layout. Windows Widgets können auch HTML aus einer URL anzeigen; für dieses Inhaltsformat siehe Web-Widget-Anbieter.

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 Onlinetool zum Bearbeiten von JSON-Karten und zum Anzeigen einer Vorschau des Layouts und der Datenbindung. Öffnen Sie den Designer, um an der Vorlage zu arbeiten.

Important

Der Designer verwendet eigene Renderer- und Hostoptionen. Gehen Sie nicht davon aus, dass Funktionen, die es bietet, vom Widgets Board unterstützt werden oder dass es Windows-spezifische $host Werte bereitstellt. Diese exemplarische Vorgehensweise hängt nicht von einer Hostvoreinstellung oder einem Hostdaten-Editor ab. Testen Sie die endgültige Vorlage in einem Windows Widgetanbieter für jede unterstützte Größe und jedes Design.

Die folgenden Bilder veranschaulichen das Kartenlayout, nicht die aktuelle Designer-Schnittstelle.

Beginnen Sie mit einer leeren Karte

Der Card-Payload-Editor enthält die JSON-Definition der Karte. Ersetzen Sie den Inhalt durch diese leere Karte:

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

Der Beispieldaten-Editor enthält einen optionalen JSON-Datenkontext. Informationen zum Binden dieser Daten an die Vorlage finden Sie unter Adaptive Karten Template Language.

Windows-Widgethosteigenschaften

Das Widgets Board stellt Hosteigenschaften zur Laufzeit bereit. Verweisen Sie auf sie mit $host in Vorlagenausdrücken, z. B. ${$host.widgetSize}. Diese Eigenschaften sind von der Datennutzlast Ihres Anbieters getrennt; das Hinzufügen eines widgetSize Felds zu den Beispieldaten legt $host.widgetSize nicht fest.

Eigentum Wert Beschreibung
Host.Widget-Größe "klein", "mittel" oder "groß" Die Größe des angehefteten Widgets.
host.hostTheme "hell" oder "dunkel" Das aktuelle Design des Geräts, auf dem das Widgets Board angezeigt wird.
host.isSettingsPayload wahr oder falsch Wenn dieser Wert "true" ist, hat der Benutzer im Kontextmenü des Widgets auf die Schaltfläche " Widget anpassen " geklickt. Sie können diesen Eigenschaftswert verwenden, um Ui-Elemente der Anpassungseinstellungen anzuzeigen. Dies ist eine alternative Methode zum Verwenden von IWidgetProvider2.OnCustomizationRequested , um die JSON-Nutzlast in der Widgetanbieter-App zu ändern. Weitere Informationen finden Sie unter Implementieren der Widgetanpassung.
host.isHeaderSupported wahr oder falsch Wenn dieser Wert "true" ist, wird die Headeranpassung unterstützt. Weitere Informationen finden Sie unter isHeaderSupported.
host.isHeader wahr oder falsch Wenn dieser Wert wahr ist, fordert der Host eine Nutzlast speziell für das Rendern des Widgetheaders an.
host.isWebSupported wahr oder falsch Wenn dieser Wert falsch ist, unterstützt der Host das Laden des Webinhalts eines Widgets derzeit nicht. In diesem Fall zeigen Web-Widgets die vom Widgetanbieter bereitgestellte Fallback-JSON-Nutzlast an, aber dieser Wert kann verwendet werden, um den Inhalt weiter anzupassen. Weitere Informationen finden Sie unter Web Widget-Anbieter
host.isUserContextAuthenticated wahr oder falsch Wenn dieser Wert "false" ist, ist die einzige unterstützte Aktion "Action.OpenUrl". Der Wert von isUserContextAuthenticated kann verwendet werden, um Widgetinhalte entsprechend anzupassen, je nach den Interaktivitätseinschränkungen.

Das Zähl-Widget verwendet vier TextBlock-Elemente und eine Action.Execute-Aktion für seine Schaltfläche.

Hinzufügen von TextBlock-Elementen

Fügen Sie vier TextBlock-Elemente aus der Elementpalette des Designers hinzu, oder fügen Sie sie direkt im Karten-JSON hinzu. Bevor das bedingte Layout angewendet wird, weist die Karte vier Textzeilen auf, wie unten dargestellt.

Eine adaptive Karte wird ausgeführt. Es zeigt ein Widget mit vier Zeilen mit dem Text New TextBlock. Die vier Textzeilen überlaufen den unteren Rand des Widgets.

Implementierung eines konditionalen Layouts

Ersetzen Sie im Card payload-Editor das body-Array durch das folgende Fragment:

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

Ohne Auswertung der Vorlagenausdrücke zeigt die Karte alle vier Textblöcke an:

Eine adaptive Karte wird ausgeführt. Es zeigt ein Widget mit vier Zeilen, die den in der JSON-Nutzlast angegebenen Text enthalten, der im vorherigen Schritt gezeigt wird. Statt Elemente bedingt auszublenden, sind alle Elemente sichtbar und überlaufen den unteren Rand des Bilds.

Wenn das Widgets Board die Vorlage auswertet, wenn $host.widgetSize auf "small" gesetzt ist, wird neben der Anzahl nur der Textblock in kleiner Größe angezeigt:

Eine adaptive Karte wird ausgeführt. Es zeigt ein Widget mit zwei Zeilen, die den in der JSON-Nutzlast angegebenen Text enthalten. Nur der TextBlock für die kleine Größe wird gerendert.

Nachdem Sie die Vorlage mit Ihrem Anbieter integriert haben, ändern Sie die Größe des angehefteten Widgets im Widgets Board, und überprüfen Sie, ob der entsprechende Textblock angezeigt wird. Deklarieren Sie jede Größe, die Sie im Widgetanbietermanifest testen möchten. Eine generische Designervorschau ohne Windows Hostdaten kann diese Bedingungen nicht überprüfen.

Binden an den Datenkontext

Im Beispiel wird eine Dateneigenschaft mit dem Namen count verwendet, auf die durch im ersten ${count} verwiesen wird. Zur Laufzeit sendet der Anbieter die Payload an den Widgethost. Geben Sie zur Entwurfszeit den folgenden JSON-Code im Editor Sample data ein, und aktivieren Sie die Vorschau des Designers, um die count-Bindung zu überprüfen. Diese Beispieldaten liefern nicht die separaten Windows Hosteigenschaften.

{"count": "2"}

Mit {"count": "2"} als Beispieldaten ersetzt die Vorlagenerweiterung ${count} durch 2 im ersten TextBlock. Überprüfen Sie diese Bindung im Designer, nachdem Sie die Vorschau aktiviert haben. Überprüfen Sie die separaten $host.widgetSize Bedingungen im Widgets Board, wie oben beschrieben.

Eine adaptive Karte wird erstellt. Die erste Textzeile enthält nun den Wert 2 aus der Datenlast.

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

Die Typeigenschaft legt Action.Execute fest, die der Widgethost an den OnActionInvoked-Rückruf Ihres Anbieters weiterleitet. Verwenden Sie stattdessen Action.OpenUrl für die URL-Navigation; es ruft diesen Anbieterrückruf nicht auf. Der Titel liefert den Schaltflächentext, und das Verb ist der von der App definierte Vorgang, den der Anbieter verarbeitet. Wenn $host.isUserContextAuthenticated "false" ist, bieten Sie keine Action.Execute-Interaktionen an. Nur Action.OpenUrl wird unterstützt.

Die letzte adaptive Karte. Eine blaue Schaltfläche mit dem Text

Die vollständige Widgetvorlage

Die folgende Codeauflistung zeigt die endgültige Vorlage für die Interaktion mit Zähl-Widgets. Die Schaltfläche "Action.Execute " erfordert einen authentifizierten Benutzerkontext. Überprüfen Sie sie im Widgets Board mit Ihrem Provider; Der Designer führt den Increment-Handler Ihres Providers nicht aus.

{
    "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 Einstellungs-Payload

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.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"
}
  • Zuletzt aktualisiert um