Een widgetsjabloon maken met adaptieve kaartenontwerper

Opmerking

Sommige informatie heeft betrekking op vooraf uitgebrachte producten, die aanzienlijk kunnen worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Belangrijk

De functie die in dit onderwerp wordt beschreven, is beschikbaar in Preview-versies van Dev Channel van Windows vanaf build 25217. Zie Windows 10 Insider Preview-voor meer informatie over preview-versies van Windows.

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 schema adaptieve kaarten. In dit artikel wordt u begeleid bij de stappen voor het maken van een eenvoudige widgetsjabloon.

Een tellende widget

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 Implementeer een widgetprovider in een win32-app biedt stapsgewijze richtlijnen voor het implementeren van de widgetprovider voor de telwidget die we in de onderstaande stappen genereren.

De ontwerper voor adaptieve kaarten

De Adaptive Cards Designer is een online interactief hulpprogramma waarmee u eenvoudig JSON-sjablonen voor adaptieve kaarten kunt genereren. 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 boven aan de pagina in de Selecteer host-app vervolgkeuzelijst de optie Widgets Board. 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. Het label Card Payload Editor bevat de JSON-definitie van de gebruikersinterface van uw widget. De editor met het label Voorbeeldgegevenseditor 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 Adaptive Cards Template Languagevoor meer informatie over gegevensbinding in adaptieve kaarten.

De derde teksteditor heeft de aanduiding Voorbeeldeditor voor hostgegevens. Houd er rekening mee dat deze editor kan samenvouwen onder de twee andere 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 widgetbord ondersteunt de volgende hosteigenschappen.

Vastgoed	Waarde	Beschrijving
host.widgetSize	"klein", "gemiddeld" of "groot"	De grootte van de gepinde widget.
host.hostTheme	licht of donker	Het huidige thema van het apparaat waarop het widgetsbord wordt weergegeven.
host.isSettingsPayload	waar of onwaar	Wanneer deze waarde waar is, heeft de gebruiker op de knop Widget aanpassen geklikt in het contextmenu van de widget. U kunt deze eigenschapswaarde gebruiken om ui-elementen voor aanpassingsinstellingen weer te geven. Dit is een alternatieve methode voor het gebruik van IWidgetProvider2.OnCustomizationRequested om de JSON-nettolading in de widgetprovider-app te wijzigen. Zie Widgetaanpassing implementeren voor meer informatie.
host.isHeaderSupported	waar of onwaar	Als deze waarde waar is, wordt aanpassing van headers ondersteund. Zie isHeaderSupported voor meer informatie.
host.isHeader	waar of onwaar	Wanneer deze waarde waar is, vraagt de host specifiek om een gegevenspakket voor het weergeven van de widgetkop.
host.isWebSupported	waar of onwaar	Als deze waarde onwaar is, biedt de host momenteel geen ondersteuning voor het laden van de webinhoud van een widget. Wanneer dit gebeurt, worden in webwidgets de terugval-JSON-lading weergegeven die door de widgetprovider wordt geleverd, maar je kunt deze waarde gebruiken om de inhoud verder aan te passen. Zie Webwidgetproviders voor meer informatie
host.isUserContextAuthenticated	waar of onwaar	Als deze waarde onwaar is, is de enige actie die wordt ondersteund Action.OpenUrl. De waarde van isUserContextAuthenticated kan worden gebruikt om widgetinhoud op de juiste wijze aan te passen, gezien de beperkingen van interactiviteit.

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 in het dialoogvenster maken lege kaart. U ziet nu een lege adaptieve kaart. U ziet ook dat het JSON-document in de voorbeeldgegevenseditor leeg is.

De widget tellen 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 kaartelementen deelvenster 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 met de TextBlock elementen die we hebben toegevoegd. Vervang de JSON-tekenreeks voor de hoofdtekst object 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 taal van de sjabloon voor adaptieve kaarten geeft de eigenschap $when aan dat het betreffende element wordt weergegeven wanneer de bijbehorende waarde waar oplevert. Als de waarde onwaar oplevert, wordt het bijbehorende element niet weergegeven. In het body-element in ons voorbeeld wordt een van de drie TextBlock-elementen weergegeven, en de andere twee verborgen, afhankelijk van de waarde van eigenschap $host.widgetSize. Zie Voorwaardelijke indeling met $whenvoor 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 weerspiegeld worden in de preview. Dit komt doordat de ontwerper het gedrag van de widgethost niet simuleert. Klik op de preview-modus knop boven aan de pagina om de simulatie te starten. Het voorbeeld van de widget ziet er nu als volgt uit:

Selecteer in de vervolgkeuzelijst Containergrootte de optie Medium en houd er rekening mee dat in het voorbeeld alleen de TextBlock voor de medium grootte wordt weergegeven. 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 de eerste TextBlock de verwijzing naar de variabele $countbevat. Wanneer de widget draait op het Widgets-bord, is de widgetprovider verantwoordelijk voor het samenstellen van het gegevenspakket en het doorgeven ervan aan de widget-host. Tijdens het ontwerpen kunt u de Voorbeeldgegevenseditor gebruiken om uw nettolading van 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 het voorbeeld wordt nu de opgegeven waarde voor de eigenschap aantal ingevoegd in de tekst voor de 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, zal de host een aanvraag indienen 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 kaartenontwerper, 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 als -acties en-elementen. Voeg het volgende JSON-blok rechtstreeks toe na het body-element in de payload-editor van de kaart. Zorg ervoor dat u een komma toevoegt na de sluitende vierkante haak (]) van het hoofdtekstelement, anders rapporteert de ontwerper een opmaakfout.

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

In deze JSON-tekenreeks geeft type eigenschap het type actie op dat wordt weergegeven. Widgets ondersteunen alleen het actietype Action.Execute. De titel bevat de tekst die op de actieknop wordt weergegeven. De werkwoord eigenschap is een door de app bepaalde tekenreeks die de widgethost naar de widgetprovider verzendt om de intentie die met de actie is verbonden te communiceren. 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"
}