Widgetsablon létrehozása a Adaptív kártyák Tervezővel

A Windows widgetek felhasználói felülete és interakciója a Adaptív kártyák használatával valósul meg. Minden widget egy vizuális sablont és opcionálisan egy adatsablont biztosít, amely a Adaptív kártyák sémának megfelelő JSON-dokumentumokkal van definiálva. Ez a cikk végigvezeti egy egyszerű widgetsablon létrehozásának lépésein.

Számláló widget

A cikkben szereplő példa egy egyszerű számláló widget, amely egy egész számot jelenít meg, és lehetővé teszi a felhasználó számára az érték növelését a widget felhasználói felületén található gombra kattintva. Ez a példasablon adatkötéssel automatikusan frissíti a felhasználói felületet az adatkörnyezet alapján.

Az alkalmazásoknak implementálniuk kell egy widget-szolgáltatót a widgetsablon és/vagy adatok létrehozásához és frissítéséhez, és át kell adniuk őket a widget-gazdagépnek. A widget-szolgáltató implementálása win32-alkalmazásokban című cikk részletes útmutatást nyújt a widget-szolgáltató implementálásához az alábbi lépésekben létrehozott számláló widgethez.

Az Adaptív kártyák Tervező

A Adaptív kártyák Designer egy online interaktív eszköz, amellyel egyszerűen hozhat létre JSON-sablonokat Adaptív kártyák. A tervező használatával valós időben láthatja a renderelt vizualizációkat és az adatkötési viselkedést a widgetsablon létrehozásakor. A hivatkozást követve nyissa meg a tervezőt, amely az útmutató összes lépéséhez használható.

Üres sablon létrehozása egy előre beállított sablonból

A lap tetején található Host alkalmazás kiválasztása legördülő menüből válassza a Widgets Boardot. Ezzel az adaptív kártya tárolóméretét úgy állítja be, hogy a widgetek számára támogatott méretű legyen. Vegye figyelembe, hogy a widgetek támogatják a kis, közepes és nagy méretű elemeket. Az alapértelmezett sablonkészlet mérete egy kis widget megfelelő mérete. Ne aggódjon, ha a tartalom túlcsordul a szegélyeken, mert lecseréljük a vezérlőbe illeszkedő tartalomra.

A lap alján három szövegszerkesztő található. A card payload editor a widget felhasználói felületének JSON-definícióját tartalmazza. A Mintaadat-szerkesztő címkével ellátott szerkesztő JSON-t tartalmaz, amely a widget opcionális adatkörnyezetét határozza meg. Az adatkörnyezet dinamikusan kötődik az adaptív kártyához a widget megjelenítésekor. A Adaptív kártyák adatkötéséről további információt a Adaptív kártyák Sablonnyelv című témakörben talál.

A harmadik szövegszerkesztő a mintagazdaadat-szerkesztő címkével van ellátva. Vegye figyelembe, hogy ez a szerkesztő a lap többi szerkesztője alá csukódhat össze. Ha igen, kattintson a + gombra a szerkesztő kibontásához. A widgetgazda alkalmazások olyan gazda tulajdonságokat adhatnak meg, amelyek a widgetsablonban felhasználhatók a különböző tartalmak dinamikus megjelenítésére az aktuális tulajdonságértékek alapján. A Widgets Board a következő gazdagéptulajdonságokat támogatja.

Ingatlan	Érték	Leírás
host.widgetSize	"kicsi", "közepes" vagy "nagy"	A rögzített widget mérete.
host.hostTheme	"világos" vagy "sötét"	Az eszköz aktuális témája, amelyen a Widgets Board megjelenik.
host.isSettingsPayload	igaz vagy hamis	Ha ez az érték igaz, a felhasználó a widget helyi menüjében a Widget testreszabása gombra kattintott. Ezzel a tulajdonságértékel megjelenítheti a testreszabási beállítások felhasználói felületének elemeit. Ez egy alternatív módszer az IWidgetProvider2.OnCustomizationRequested helyett, a JSON hasznos adatainak módosítására a widgetszolgáltató alkalmazásban. További információ: Widget testreszabásának implementálása.
host.isHeaderSupported	igaz vagy hamis	Ha ez az érték igaz, a fejléc testreszabása támogatott. További információ: isHeaderSupported.
host.isHeader	igaz vagy hamis	Ha ez az érték igaz, a gazdagép kifejezetten a widget fejlécének megjelenítéséhez kér terhelést.
host.isWebSupported	igaz vagy hamis	Ha ez az érték hamis, a gazdagép jelenleg nem támogatja a widget webes tartalmának betöltését. Ha ez történik, a webes widgetek megjelenítik a widget-szolgáltató által biztosított tartalék JSON hasznos adatokat, de ez az érték a tartalom további testreszabására használható. További információ: Web widget-szolgáltatók
host.isUserContextAuthenticated # Ellenőrzi a felhasználói kontextus hitelesítését	igaz vagy hamis	Ha ez az érték hamis, az egyetlen támogatott művelet az Action.OpenUrl. Az isUserContextAuthenticated értéke használható a widget tartalmának megfelelő módosítására az interaktivitási korlátozások miatt.

A lap tetején található Gazdaalkalmazás kiválasztása legördülő lista mellett található Tárolóméret és Téma legördülő lista lehetővé teszi, hogy ezeket a tulajdonságokat anélkül állítsa be, hogy manuálisan nem szerkeszti a JSON-mintagazdafájlt a szerkesztőben.

Új kártya létrehozása

A lap bal felső sarkában kattintson az Új kártya gombra. A Létrehozás párbeszédpanelen válassza az Üres kártya lehetőséget. Most egy üres adaptív kártyát kell látnia. Azt is láthatja, hogy a mintaadat-szerkesztő JSON-dokumentuma üres.

A létrehozható számláló widget nagyon egyszerű, csak 4 TextBlock-elemből és egy Action.Execute típusú műveletből áll, amely meghatározza a widget gombját.

TextBlock-elemek hozzáadása

Négy TextBlock elemet adjon hozzá úgy, hogy áthúzza őket a lap bal szélén lévő Kártyaelemek panelről az előnézeti panel üres adaptív kártyájára. Ezen a ponton a widget előnézetének az alábbi képhez hasonlóan kell kinéznie. A tartalom ismét túlcsordul a widget szegélyén kívül, de ezt a következő lépésekben kijavítjuk.

Feltételes elrendezés implementálása

A Card Payload Editor frissült, hogy tükrözze a hozzáadott TextBlock elemeket. Cserélje le a törzsobjektum JSON-sztringét a következőre:

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

A Adaptív kártyák sablonnyelvben a $when tulajdonság azt határozza meg, hogy a tartalomelem akkor jelenik meg, ha a társított érték értéke igaz. Ha az érték értéke hamis, akkor a benne lévő elem nem jelenik meg. A példánk törzselemében megjelenik a három TextBlock-elem egyike, a másik kettő pedig rejtett, a $host.widgetSize tulajdonság értékétől függően. A Adaptív kártyák által támogatott feltételes feltételekről további információt a Kondíciós elrendezés $when című témakörben talál.

Most az előnézetnek a következő képhez hasonlóan kell kinéznie:

Vegye figyelembe, hogy a feltételes állítások nem jelennek meg az előnézetben. Ennek az az oka, hogy a tervező nem szimulálja a widget-gazdagép viselkedését. A szimuláció elindításához kattintson a lap tetején található Előnézet mód gombra. A widget előnézete a következő képhez hasonlóan néz ki:

Fejlesztés alatt álló adaptív kártya. Egy két soros widgetet jelenít meg, amely az JSON adatbázisban megadott szöveget tartalmazza. Csak a kis méretű TextBlock kerül megjelenítésre.

A Tárolóméret legördülő listában válassza a "Közepes" lehetőséget, és vegye figyelembe, hogy az előnézet csak a közepes méretű TextBlock megjelenítésére vált. Az előzetes verzióban lévő tároló is módosítja a méretet, bemutatva, hogyan használhatja az előnézetet annak biztosításához, hogy a felhasználói felület minden támogatott mérethez illeszkedjen a widgettárolóban.

Kötés az adatkörnyezethez

A példa widget egy "count" nevű egyéni állapottulajdonságot fog használni. Az aktuális sablonban látható, hogy az első TextBlock értéke tartalmazza a változóhivatkozást $count. Amikor a widget a Widgets Board felületén fut, a widget-szolgáltató feladata az adatcsomag összeállítása és továbbítása a widget-gazdagépnek. Tervezéskor a Mintaadat-szerkesztővel prototípust készíthet az adatcsomagról, és megtekintheti, hogy a különböző értékek milyen hatással vannak a widget megjelenésére. Cserélje le az üres adatcsomagot a következő JSON-ra.

{"count": "2"}

Vegye figyelembe, hogy az előnézet most beszúrja a darabszám tulajdonsághoz megadott értéket az első TextBlock szövegébe.

Gomb hozzáadása

A következő lépés egy gomb hozzáadása a widgethez. A widget-gazdagépen, amikor a felhasználó a gombra kattint, a gazdagép kérést küld a widget-szolgáltatónak. Ebben a példában a widget-szolgáltató növeli a számláló értékét, és egy frissített adatcsomagot ad vissza. Mivel ehhez a művelethez widget-szolgáltatóra van szükség, nem fogja tudni megtekinteni ezt a viselkedést a Adaptív kártyák Tervezőben, de a tervezővel módosíthatja a gomb elrendezését a felhasználói felületen belül.

Az Adaptív kártyák interaktív elemek action elemekkel vannak definiálva. Adja hozzá a következő JSON-blokkot közvetlenül a body elem után a kártya terhelésszerkesztőben. Ügyeljen arra, hogy a törzselem záró zárójele (]) után adjon hozzá vesszőt, vagy a tervező formázási hibát jelez.

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

Ebben a JSON-sztringben a típustulajdonság adja meg a megjelenítendő művelet típusát. A widgetek csak a "Action.Execute" művelettípust támogatják. A cím tartalmazza a művelet gombján megjelenő szöveget. Az igetulajdonság egy alkalmazás által definiált sztring, amelyet a widget-gazdagép elküld a widget-szolgáltatónak a művelethez társított szándék közléséhez. A widgetek több művelettel is rendelkezhetnek, és a widget-szolgáltató kódja ellenőrzi a kérésben szereplő igék értékét, hogy megállapítsa, milyen műveletet kell végrehajtani.

A teljes widgetsablon

Az alábbi kódrészlet a JSON adat végleges verzióját mutatja.

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

Beállítási payload példa

Az alábbi kódlista egy egyszerű példát mutat be egy olyan JSON-hasznos adatra, amely a host.isSettingsPayload tulajdonságot használja a különböző tartalmak megjelenítéséhez, amikor a felhasználó a Widget testreszabása gombra kattint.

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