Een widgetsjabloon maken met de Adaptieve kaarten Designer

De gebruikersinterface en interactie voor Windows Widgets worden geïmplementeerd met behulp van Adaptieve kaarten. Elke widget biedt een visuele sjabloon en, optioneel, een gegevenssjabloon die is gedefinieerd met behulp van JSON-documenten die voldoen aan het Adaptieve kaarten schema. In dit artikel wordt u begeleid bij de stappen voor het maken van een eenvoudige widgetsjabloon.

Een widget tellen

Het voorbeeld in dit artikel is een eenvoudige telwidget waarmee een geheel getal wordt weergegeven en waarmee de gebruiker de waarde kan verhogen door te klikken op een knop in de gebruikersinterface van de widget. In deze voorbeeldsjabloon wordt gegevensbinding gebruikt om de gebruikersinterface automatisch bij te werken op basis van de gegevenscontext.

Apps moeten een widgetprovider implementeren om de widgetsjabloon en/of gegevens te genereren en bij te werken en deze door te geven aan de widgethost. Het artikel Een widgetprovider implementeren in een Win32-applicatie biedt stapsgewijze richtlijnen voor het implementeren van de widgetprovider voor de tel-widget die we in de volgende stappen zullen genereren.

De Adaptieve kaarten Designer

De Adaptieve kaarten Designer is een online interactief hulpprogramma waarmee u eenvoudig JSON-sjablonen kunt genereren voor Adaptieve kaarten. Met behulp van de ontwerpfunctie kunt u de weergegeven visuals en het gedrag van gegevensbinding in realtime zien terwijl u uw widgetsjabloon bouwt. Volg de koppeling om de ontwerpfunctie te openen. Deze wordt gebruikt voor alle stappen in dit scenario.

Een lege sjabloon maken op basis van een voorinstelling

Kies bovenaan de pagina in de vervolgkeuzelijst Host-app selecteren de optie Widgetsbord. Hiermee stelt u de containergrootte voor de adaptieve kaart in op een grootte die wordt ondersteund voor widgets. Houd er rekening mee dat widgets kleine, middelgrote en grote grootten ondersteunen. De grootte van de standaardsjabloonvoorinstelling is de juiste grootte voor een kleine widget. U hoeft zich geen zorgen te maken als de inhoud de randen overloopt, omdat we deze vervangen door inhoud die is ontworpen om binnen de widget te passen.

Er zijn drie teksteditors onder aan de pagina. De ene gelabelde Card Payload Editor bevat de JSON-definitie van de gebruikersinterface van uw widget. De editor met het label Sample Data Editor bevat JSON waarmee een optionele gegevenscontext voor uw widget wordt gedefinieerd. De gegevenscontext is dynamisch gebonden aan de adaptieve kaart wanneer de widget wordt weergegeven. Zie Adaptieve kaarten Template Language voor meer informatie over gegevensbinding in Adaptieve kaarten.

De derde teksteditor heeft het label Sample Host Data Editor. Houd er rekening mee dat deze editor kan samenvouwen onder de andere twee editors van de pagina. Als dat zo is, klikt u op de + om de editor uit te vouwen. Widgethost-apps kunnen hosteigenschappen opgeven die u in uw widgetsjabloon kunt gebruiken om dynamisch verschillende inhoud weer te geven op basis van de huidige eigenschapswaarden. Het widgetsbord ondersteunt de volgende hosteigenschappen.

Met de vervolgkeuzelijst Containergrootte en Thema selecteren naast de vervolgkeuzelijst Host-app selecteren boven aan de pagina kunt u deze eigenschappen instellen zonder de JSON van de voorbeeldhost handmatig te bewerken in de editor.

Een nieuwe kaart maken

Klik in de linkerbovenhoek van de pagina op Nieuwe kaart. Selecteer Lege kaart in het dialoogvenster Maken. U ziet nu een lege adaptieve kaart. U ziet ook dat het JSON-document in de voorbeeldgegevenseditor leeg is.

De telwidget die we gaan maken, is zeer eenvoudig, alleen bestaande uit 4 TextBlock-elementen en één actie van het type Action.Execute, waarmee de knop van de widget wordt gedefinieerd.

TextBlock-elementen toevoegen

Voeg vier TextBlock-elementen toe door ze vanuit het deelvenster Kaartelementen aan de linkerkant van de pagina naar de lege adaptieve kaart in het voorbeeldvenster te slepen. Op dit moment moet het voorbeeld van de widget eruitzien als de volgende afbeelding. De inhoud loopt opnieuw over buiten de widgetranden, maar dit wordt opgelost in de volgende stappen.

Voorwaardelijke indeling implementeren

De Card Payload Editor is bijgewerkt om de TextBlock-elementen die we hebben toegevoegd weer te geven. Vervang de JSON-tekenreeks voor het hoofdtekstobject door het volgende:

"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 de Adaptieve kaarten sjabloontaal geeft de eigenschap $when aan dat het element dat bevat, wordt weergegeven wanneer de bijbehorende waarde waar is. Als de waarde onwaar oplevert, wordt het bijbehorende element niet weergegeven. In het hoofdtekstelement in ons voorbeeld wordt een van de drie TextBlock-elementen weergegeven en de andere twee verborgen, afhankelijk van de waarde van de $host.widgetSize eigenschap. Zie Conditionele indeling met $when voor meer informatie over de voorwaarden die worden ondersteund in Adaptieve kaarten.

Het voorbeeld ziet er nu als volgt uit:

Houd er rekening mee dat de voorwaardelijke uitspraken niet worden weergegeven in de weergave. Dit komt doordat de ontwerper het gedrag van de widgethost niet simuleert. Klik op de knop Voorbeeldmodus boven aan de pagina om de simulatie te starten. Het voorbeeld van de widget ziet er nu als volgt uit:

Selecteer 'Medium' in het Containergrootte dropdownmenu en merk op dat de weergave verandert om alleen de TextBlock voor de gemiddelde grootte te tonen. De container in de preview wijzigt ook de grootte en laat zien hoe u de preview kunt gebruiken om ervoor te zorgen dat uw gebruikersinterface binnen de widgetcontainer past voor elke ondersteunde grootte.

Verbinden met de gegevenscontext

In onze voorbeeldwidget wordt een aangepaste statuseigenschap met de naam 'count' gebruikt. U kunt in de huidige sjabloon zien dat de waarde voor het eerste TextBlock de variabelereferentie $countbevat. Wanneer de widget wordt uitgevoerd in de Widgets Board, is de widgetprovider verantwoordelijk voor het samenstellen van de datapayload en het doorgeven ervan aan de widgethost. Tijdens het ontwerp kunt u de Voorbeeldgegevenseditor gebruiken om uw nettolading van uw gegevens te prototypen en te zien hoe verschillende waarden van invloed zijn op de weergave van uw widget. Vervang de lege nettolading van gegevens door de volgende JSON.

{"count": "2"}

In de voorbeeldweergave wordt nu de waarde ingevoegd die is opgegeven voor de eigenschap count in de tekst voor het eerste TextBlock.

Een knop toevoegen

De volgende stap is het toevoegen van een knop aan onze widget. Wanneer de gebruiker in de widgethost op de knop klikt, doet de host een aanvraag bij de widgetprovider. In dit voorbeeld zal de widgetprovider de tellingswaarde verhogen en een bijgewerkte gegevenslading retourneren. Omdat voor deze bewerking een widgetprovider is vereist, kunt u dit gedrag niet weergeven in de Adaptieve kaarten Designer, maar u kunt de ontwerpfunctie nog steeds gebruiken om de indeling van de knop in uw gebruikersinterface aan te passen.

Met Adaptieve kaarten worden interactieve elementen gedefinieerd met actie elementen. Voeg het volgende JSON-blok direct na het body-element toe in de payload-editor van de card. Zorg ervoor dat u een komma toevoegt na de sluitende vierkante haak (]) van het hoofdtekstelement of de ontwerper een opmaakfout rapporteert.

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

In deze JSON-tekenreeks geeft typeeigenschap het type actie op dat wordt weergegeven. Widgets ondersteunen alleen het actietype Action.Execute. De titel bevat de tekst die wordt weergegeven op de knop voor de actie. De werkwoordeigenschap is een door de app gedefinieerde tekenreeks die de widgethost naar de widgetprovider verzendt om de intentie te communiceren die is gekoppeld aan de actie. Een widget kan meerdere acties hebben en de code van de widgetprovider controleert de waarde van het werkwoord in de aanvraag om te bepalen welke actie moet worden ondernomen.

De volledige widgetsjabloon

In de volgende codevermelding ziet u de uiteindelijke versie van de JSON-nettolading.

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

Voorbeeld van instellingen-payload

De volgende codevermelding toont een eenvoudig voorbeeld van een JSON-nettolading die gebruikmaakt van de eigenschap host.isSettingsPayload om verschillende inhoud weer te geven wanneer de gebruiker op de knop Widget aanpassen heeft geklikt.

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