Skapa en widgetmall med Adaptive Cards Designer

Användargränssnittet och interaktionen för Windows Widgets implementeras med hjälp av Adaptive Cards. Varje widget innehåller en visuell mall och, om du vill, en datamall som definieras med hjälp av JSON-dokument som överensstämmer med Adaptive Cards schema. Den här artikeln beskriver hur du skapar en enkel widgetmall.

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 interaktivt onlineverktyg som gör det enkelt att generera JSON-mallar för Adaptive Cards. Med hjälp av designern kan du se renderade visuella objekt och databindningsbeteendet i realtid när du skapar widgetmallen. Följ länken för att öppna designern, som kommer att användas för alla steg i den här genomgången.

Skapa en tom mall från en förinställning

Längst upp på sidan går du till listrutan Välj värdapp och väljer Widgets Board. Då anges containerstorleken för adaptivkortet så att den har en storlek som stöds för widgetar. Observera att widgetar stöder små, medelstora och stora storlekar. Storleken på standardmallens förinställning är rätt storlek för en liten widget. Oroa dig inte om innehållet flödar över kantlinjerna eftersom vi kommer att ersätta det med innehåll som är utformat för att passa in i widgeten.

Det finns tre textredigerare längst ned på sidan. Den som är märkt Redigerare för kortnyttolast innehåller JSON-definitionen av ditt widgets användargränssnitt. Redigeraren med etiketten Exempeldataredigeraren innehåller JSON som definierar en valfri datakontext för widgeten. Datakontexten binds dynamiskt till det adaptiva kortet när widgeten återges. Mer information om databindning i Adaptive Cards finns i Adaptive Cards Template Language.

Den tredje textredigeraren har etiketten Exempel på värddataredigeraren. Observera att den här redigeraren kan komprimeras under sidans två andra redigerare. I så fall klickar du på + för att expandera redigeraren. Widgetvärdappar kan ange värdinställningar som du kan använda i widgetmallen för att dynamiskt visa olika innehåll baserat på de aktuella egenskapsvärdena. Widgets Board stöder följande värdegenskaper.

Med listrutorna Containerstorlek och Tema bredvid listrutan Välj värdapp överst på sidan kan du ange dessa egenskaper utan att manuellt redigera exempelvärdens JSON i redigeraren.

Skapa ett nytt kort

I det övre vänstra hörnet på sidan klickar du på Nytt kort. I dialogrutan Skapa väljer du Tomt kort. Nu bör du se ett tomt adaptivt kort. Du kommer också att märka att JSON-dokumentet i exempeldataredigeraren är tomt.

Den räknarwidget som vi kommer att skapa är mycket enkel, endast bestående av 4 TextBlock-element och en åtgärd av typen Action.Execute, som definierar widgetens knapp.

Lägg till TextBlock-element

Lägg till fyra TextBlock-element genom att dra dem från fönstret Kortelement till vänster på sidan till det tomma adaptiva kortet i förhandsgranskningsfönstret. Nu bör widgetförhandsgranskningen se ut som i följande bild. Innehållet flödar över igen utanför widgetens kantlinjer, men detta åtgärdas i följande steg.

Implementera villkorsstyrd layout

Kortnyttolastredigeraren har uppdaterats för att återspegla de TextBlock-element som vi har lagt till. Ersätt JSON-strängen för brödtextobjektet med följande:

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

Nu bör förhandsversionen se ut så här:

Observera att villkorssatserna inte återspeglas i förhandsversionen. Det beror på att designern inte simulerar widgethostens beteende. Starta simuleringen genom att klicka på knappen Förhandsgranskningsläge överst på sidan. Widgetförhandsgranskningen ser nu ut som följande bild:

I listrutan Containerstorlek väljer du "Medium" och observera att förhandsgranskningen växlar till att endast visa TextBlock för medelstorleken. Containern i förhandsversionen ändrar också storlek, vilket visar hur du kan använda förhandsversionen för att se till att användargränssnittet passar i widgetcontainern för varje storlek som stöds.

Binda till datakontexten

Vår exempelwidget använder en anpassad tillståndsegenskap med namnet "count". Du kan se i den aktuella mallen att värdet för den första TextBlock innehåller variabelreferensen $count. När widgeten körs i Widgets Board ansvarar widget-providern för att montera datalasten och skicka den till widgetvärden. Vid designtillfället kan du använda Exempeldataredigeraren för att skapa prototyper för din datanyttolast och se hur olika värden påverkar visningen av widgeten. Ersätt den tomma datanyttolasten med följande JSON.

{"count": "2"}

Observera att förhandsgranskningen nu infogar det angivna värdet för egenskapen count i texten för den första TextBlock.

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

I den här JSON-strängen anger typegenskapen vilken typ av åtgärd som representeras. Widgetar stöder endast åtgärdstypen "Action.Execute". Rubriken innehåller texten som visas på knappen för åtgärden. Verbegenskapen är en appdefinierad sträng som widgetvärden skickar till widgetleverantören för att kommunicera den avsikt som är kopplad till åtgärden. En widget kan ha flera åtgärder, och koden för widgetprovidern kontrollerar verbets värde i begäran för att avgöra vilken åtgärd som ska vidtas.

Den fullständiga widgetmallen

Följande kodlista visar den slutliga versionen av JSON-nyttolasten.

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