Erstellen einer Widgetvorlage mit dem Designer für adaptive Karten

2025-06-10

Hinweis

Einige Informationen beziehen sich auf vorab veröffentlichte Produkte, die vor der kommerziellen Veröffentlichung erheblich geändert werden können. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Von Bedeutung

Das in diesem Thema beschriebene Feature ist ab Build 25217 in Dev Channel-Vorschaubuilds von Windows verfügbar. Informationen zu Vorabversionen von Windows finden Sie unter Windows 10 Insider Preview.

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

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 Designer für adaptive Karten

Der Designer für adaptive Karten ist ein interaktives Onlinetool, das das Generieren von JSON-Vorlagen für adaptive Karten vereinfacht. 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 Anleitung verwendet wird.

Erstellen Sie eine leere Vorlage aus einer Voreinstellung

Wählen Sie oben auf der Seite aus der Dropdownliste Host-App auswählen 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 mit beschriftete Card Payload-Editor 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 adaptiven Karten finden Sie in der Vorlagensprache für adaptive Karten.

Der dritte Text-Editor wird Beispiel-Hostdaten-Editorbezeichnet. Beachten Sie, dass dieser Editor unterhalb der beiden anderen Editoren der Seite eingeklappt 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 Hosteigenschaften.

Eigentum	Wert	BESCHREIBUNG
host.widgetSize	"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.istBenutzerkontextAuthentifiziert	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.

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.

Neue Karte erstellen

Klicken Sie in der oberen linken Ecke der Seite auf "Neue Karte". Wählen Sie im Dialogfeld ErstellenLeere Karteaus. 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 für Kartenelemente auf der linken Seite der Seite auf die leere Adaptive Karte im Vorschaubereich ziehen. An diesem Punkt sollte die Widgetvorschau wie das folgende Bild aussehen. Der Inhalt läuft erneut über die Grenzen des Widgets hinaus, und dies wird in den folgenden Schritten behoben.

Eine adaptive Karte ist in Bearbeitung. Sie zeigt ein Widget mit vier Zeilen, die den Text

Bedingtes Layout implementieren

Der Kartennutzlast-Editor wurde aktualisiert, um die hinzugefügten TextBlock--Elemente widerzuspiegeln. Ersetzen Sie die JSON-Zeichenfolge für den -Körper des-Objekts 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 Vorlagensprache für adaptive Karten gibt die $when Eigenschaft 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, abhängig vom Wert der $host.widgetSize-Eigenschaft. Weitere Informationen zu den in Adaptiven Karten unterstützten Bedingungen finden Sie in Bedingtes Layout mit $when.

Nun sollte die Vorschau wie die folgende Abbildung aussehen:

Eine adaptive Karte in Bearbeitung. 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 überlappen den unteren Bildrand.

Beachten Sie, dass die bedingten Ausdrücke nicht in der Vorschau widergespiegelt 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:

Eine adaptive Karte ist in Bearbeitung. Sie zeigt ein Widget mit zwei Zeilen, die den in der JSON-Nutzlast angegebenen Text enthalten. Nur der TextBlock der kleinen Version wird gerendert.

Wählen Sie im Dropdownmenü Containergröße "Mittel" aus, und beachten Sie, dass die Vorschau nur den Textblock- für die mittlere Größe anzeigt. 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 in der Widget-Tafel ausgeführt wird, ist der Widget-Anbieter dafür verantwortlich, das Datenpaket zusammenzustellen und an den Widget-Host zu übergeben. In der Entwurfsphase können Sie den Beispieldaten-Editor verwenden, um Ihre Datenstruktur zu prototypisieren 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 in der count-Eigenschaft angegebenen Wert in den Text für das erste TextBlockeinfügt.

Eine adaptive Karte ist in Bearbeitung. Die erste Textzeile enthält nun den Wert 2 aus dem Datensatz.

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 eine Anforderung an den Widget-Anbieter. In diesem Beispiel erhöht der Widgetanbieter den Zählerwert und gibt einen aktualisierten Dateninhalt zurück. Da für diesen Vorgang ein Widgetanbieter erforderlich ist, können Sie dieses Verhalten im Designer für adaptive Karten nicht anzeigen, aber Sie können den Designer weiterhin verwenden, um das Layout Ihrer Schaltfläche in der Benutzeroberfläche anzupassen.

Bei adaptiven Karten werden interaktive Elemente mit Aktion Elementen definiert. Fügen Sie den folgenden JSON-Block direkt nach dem Body Element im Karten-Payload-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 Typ--Eigenschaft 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 app-definierte Zeichenfolge, die der Widget-Host an den Widget-Anbieter 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 endgültige adaptive Karte. Eine blaue Schaltfläche mit dem Text

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

Freigeben über

Ein Zähl-Widget