Skapa en widgetmall med Adaptive Cards Designer

För en Adaptive Card-widget definierar du användargränssnittet och interaktionerna med en Adaptive Cards JSON-mall och, om du vill, en separat JSON-datalast. Den här artikeln vägleder dig genom en mall för räknewidget med databindning och villkorsstyrd layout. Windows widgetar kan också visa HTML från en URL. Mer information finns i Webbwidgetleverantörer.

En räknarwidget

Exemplet i den här artikeln är en enkel räknarwidget som visar ett heltalsvärde och gör att användaren kan öka värdet genom att klicka på en knapp i widgetens användargränssnitt. Den här exempelmallen använder databindning för att automatiskt uppdatera användargränssnittet baserat på datakontexten.

Appar måste implementera en widgetprovider för att generera och uppdatera widgetmallen och/eller data och skicka dem till widgetvärden. Artikeln Implementera en widgetprovider i en win32-app innehåller stegvisa riktlinjer för att implementera widgetprovidern för den räknarwidget som vi genererar i stegen nedan.

Den Adaptive Cards Designer

Adaptive Cards Designer är ett onlineverktyg för att redigera kort-JSON och förhandsgranska dess layout och databindning. Öppna designern för att arbeta med mallen.

Important

Designer använder sina egna renderings- och värdalternativ. Anta inte att funktioner som den erbjuder stöds av Widgets Board eller att den tillhandahåller Windows-specifika $host värden. Den här genomgången är inte beroende av en värdförinställning eller en värddataredigerare. Testa den slutliga mallen i en Windows widgetprovider för varje storlek och tema som stöds.

Bilderna nedan illustrerar kortets layout, inte det aktuella designergränssnittet.

Börja med ett tomt kort

Redigeraren för kortpayload innehåller JSON-definitionen för kortet. Ersätt innehållet med det här blanka kortet:

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

Exempeldataredigeraren innehåller en valfri JSON-datakontext. Information om hur du binder dessa data till mallen finns i Adaptive Cards Template Language.

Windows egenskaper för widgetvärdar

Widgets Board tillhandahåller värdegenskaper för värden vid körning. Referera till dem i malluttryck via $host, till exempel ${$host.widgetSize}. Dessa egenskaper är separata från leverantörens datalast. Om du lägger till ett widgetSize fält i exempeldata anges inte $host.widgetSize.

Fastighet	Värde	Beskrivning
host.widgetSize	"liten", "mellan" eller "stor"	Storleken på den fästa widgeten.
host.hostTheme	"ljus" eller "mörk"	Det aktuella temat för enheten där Widgets Board visas.
host.isSettingsPayload	sant eller falskt	När det här värdet är sant har användaren klickat på knappen Anpassa widget i snabbmenyn för widgeten. Du kan använda det här egenskapsvärdet för att visa gränssnittselement för anpassningsinställningar. Det här är en alternativ metod för att använda IWidgetProvider2.OnCustomizationRequested för att ändra JSON-nyttolasten i widgetproviderappen. Mer information finns i Implementera widgetanpassning.
host.isHeaderSupported	sant eller falskt	När det här värdet är sant stöds sidhuvudanpassning. Mer information finns i isHeaderSupported.
host.isHeader	sant eller falskt	När det här värdet är sant begär hosten en nyttolast specifikt för rendering av widgethuvudet.
host.isWebSupported	sant eller falskt	När det här värdet är falskt stöder hosten för närvarande inte att ladda en widgets webbinnehåll. När detta inträffar visar webbwidgetar återställnings-JSON-nyttolasten som tillhandahålls av widgetprovidern, men det här värdet kan användas för att ytterligare anpassa innehållet. Mer information finns i Webbwidgetproviders
host.isUserContextAuthenticated	sant eller falskt	När det här värdet är falskt är den enda åtgärd som stöds Action.OpenUrl. Värdet för isUserContextAuthenticated kan användas för att justera widgetinnehåll på lämpligt sätt, med tanke på interaktivitetsbegränsningarna.

Räknarwidgeten använder fyra TextBlock-element och en Action.Execute-åtgärd för sin knapp.

Lägg till TextBlock-element

Lägg till fyra TextBlock-element från designerns elementpalett eller lägg till dem direkt i kortets JSON. Innan villkorsstyrd layout tillämpas har kortet fyra textrader, enligt nedan.

Implementera villkorsstyrd layout

I redigeraren för Card payload ersätter du body-matrisen med följande 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\"}"
    }
]

I Adaptive Cards Mallspråk anger egenskapen $when att det innehållande elementet visas när det associerade värdet utvärderas till true. Om värdet utvärderas till false visas inte det innehållande elementet. I brödtextelementet i vårt exempel visas ett av de tre TextBlock-elementen och de andra två dolda, beroende på värdet för $host.widgetSize egenskapen. Mer information om de villkor som stöds i Adaptive Cards finns i Villkorlig layout med $when.

Utan att utvärdera malluttrycken visar kortet alla fyra textblocken:

När Widgets Board utvärderar mallen med $host.widgetSize inställd på "small"visas endast textblocket med liten storlek tillsammans med antalet:

När du har integrerat mallen med providern ändrar du storlek på den fästa widgeten i Widgets Board och kontrollerar att det matchande textblocket visas. Deklarera varje storlek som du vill testa i widgetprovidermanifestet. En allmän designerförhandsgranskning utan Windows värddata kan inte verifiera dessa villkor.

Binda till datakontexten

I exemplet används en dataegenskap med namnet count, som refereras av ${count} i den första TextBlock. Vid körning skickar providern datanyttolasten till widgetvärden. Under designfasen anger du följande JSON i Exempeldata-redigeraren och aktiverar designerns förhandsgranskning för att kontrollera count-bindningen. Dessa exempeldata anger inte de separata Windows-värddatoregenskaperna.

{"count": "2"}

Med {"count": "2"} som exempeldata ersätter mallexpansionen ${count} med 2 i den första TextBlock. Kontrollera den här kopplingen i Designer när du har aktiverat förhandsgranskning. Kontrollera de separata $host.widgetSize villkoren i Widgets Board enligt beskrivningen ovan.

Ett adaptivt kort är under utveckling. Den första textraden innehåller nu värdet 2 från databäraren.

Lägg till en knapp

Nästa steg är att lägga till en knapp i vår widget. När användaren klickar på knappen i widgetvärden skickar värden en begäran till widgetprovidern. I det här exemplet ökar widgetprovidern antalsvärdet och returnerar en uppdaterad datanyttolast. Eftersom den här åtgärden kräver en widgetprovider kan du inte visa det här beteendet i Adaptive Cards Designer, men du kan fortfarande använda designern för att justera layouten för knappen i användargränssnittet.

Med Adaptive Cards definieras interaktiva element med elementen action. Lägg till följande JSON-block direkt efter brödtextelementet i kortnyttolastredigeraren. Se till att lägga till ett kommatecken efter den avslutande hakparentesen (]) för brödtextelementet, annars rapporterar designern ett formateringsfel.

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

egenskapen type anger Action.Execute, som widgetvärden vidarebefordrar till leverantörens OnActionInvoked-återanrop. Använd Action.OpenUrl för URL-navigering i stället. den anropar inte providerns återanrop. title tillhandahåller knapptexten, och verb är den appdefinierade åtgärd som providern hanterar. När $host.isUserContextAuthenticated är falskt erbjuder du inte Action.Execute-interaktioner . Endast Action.OpenUrl stöds.

Den fullständiga widgetmallen

Följande kodlista visar den slutliga mallen för interaktionen med räkningswidgeten. Knappen Action.Execute kräver en autentiserad användarkontext. Verifiera det i Widgets Board med din leverantör; Designern kör inte leverantörens inkrementshanterare.

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

Exempel på nyttolast för inställningar

Följande kodlista visar ett enkelt exempel på en JSON-nyttolast som använder egenskapen host.isSettingsPayload för att visa annat innehåll när användaren har klickat på knappen Anpassa 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"
}