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

Adaptív kártya widget esetén adja meg a felhasználói felületet és az interakciókat egy Adaptív kártyák JSON-sablonnal, és opcionálisan egy külön JSON-adatcsomaggal. Ez a cikk bemutat egy számlálówidget-sablont adatkötéssel és feltételes elrendezéssel. A Windows-vezérlők URL-címről is megjeleníthetnek HTML-t; ehhez a tartalomformátumhoz tekintse meg a webes widget-szolgáltatókat.

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ő

Az Adaptív kártyák Designer egy online eszköz a kártya JSON-jának szerkesztéséhez, valamint az elrendezés és az adatkötés előnézetéhez. Nyissa meg a Tervezőt a sablon szerkesztéséhez.

Important

A Tervező saját renderelőt és hosztbeállításokat használ. Ne feltételezze, hogy az általa kínált funkciókat a Widgets Board támogatja, vagy hogy Windows-specifikus $host értékeket biztosít. Ez az útmutató nem függ a gazdagép előbeállításától vagy a gazdagép-adatszerkesztőtől. Tesztelje a végleges sablont egy Windows widget-szolgáltatóban minden támogatott mérethez és témához.

Az alábbi képek a kártya elrendezését szemléltetik, nem az aktuális Tervező felületet.

Kezdés üres kártyáról

A Kártya payload-szerkesztője tartalmazza a kártya JSON-definícióját. Cserélje ki a tartalmát erre az üres kártyára:

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

A mintaadat-szerkesztő opcionális JSON-adatkontextust tartalmaz. További információ az adatok sablonhoz való kötéséről: Adaptív kártyák Template Language.

A Widgets Board futásidőben biztosítja a gazdagép tulajdonságait. Hivatkozzon rájuk a(z) $host segítségével sablonkifejezésekben, például ${$host.widgetSize}. Ezek a tulajdonságok elkülönülnek a szolgáltató adatcsomagjától; a widgetSize mező hozzáadása a mintaadatokhoz nem állítja be a $host.widgetSize értéket.

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 számláló widget négy TextBlock-elemet és egy Action.Execute műveletet használ a gombhoz.

TextBlock-elemek hozzáadása

Vegyen fel négy TextBlock-elemet a Tervező elempalettájából, vagy vegye fel őket közvetlenül a kártya JSON-jában. A feltételes elrendezés alkalmazása előtt a kártya négy sornyi szövegből áll, ahogyan az alább látható.

Egy adaptív kártya folyamatban. Egy widgetet jelenít meg, amely négy sort tartalmaz a New TextBlock szöveget tartalmazó szöveggel. A négy sornyi szöveg túlcsordul a widget alsó szegélyén.

Feltételes elrendezés implementálása

A Card payload szerkesztőjében cserélje le a body tömböt a következő töredékre:

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

A sablonkifejezések kiértékelése nélkül a kártya mind a négy szövegblokkot megjeleníti:

Egy adaptív kártya folyamatban. Az előző lépésben látható JSON hasznos adatban megadott szöveget tartalmazó négysoros vezérlőt jelenít meg. Az elemek feltételes elrejtése helyett az összes elem látható és túlcsordul a kép alsó szegélyén.

Amikor a Widgets Board a(z) $host.widgetSize sablont "small" értékre állítva értékeli ki, csak a kis méretű szövegblokk jelenik meg a szám mellett:

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.

Miután integrálta a sablont a szolgáltatójával, méretezze át a rögzített widgetet a Widgets Boardban, és ellenőrizze, hogy megjelenik-e a megfelelő szövegblokk. Deklarálja a tesztelni kívánt méreteket a widget-szolgáltató manifesztumában. A gazdagép-adatok nélküli általános tervezői előzetes verzió nem tudja ellenőrizni ezeket a feltételeket.

Kötés az adatkörnyezethez

A példa egy nevű adattulajdonságot használ, amelyre az első count elemben a ${count} hivatkozik. Futásidőben a szolgáltató elküldi az adatcsomagot a widget-gazdagépnek. Tervezéskor adja meg a következő JSON-t a Mintaadat-szerkesztőben, és engedélyezze a Tervező előnézetét a darabszám kötésének ellenőrzéséhez. Ezek a mintaadatok nem tartalmazzák a külön Windows-gazdagép tulajdonságait.

{"count": "2"}

A(z) {"count": "2"} mintaadatokkal a sablonkibontás az első 2 elemben a(z) helyére ${count}-t tesz. Az előnézet engedélyezése után ellenőrizze ezt a kötést a Tervezőben. Ellenőrizze a Widgets Boardban található külön $host.widgetSize feltételeket a fent leírtak szerint.

Egy adaptív kártya készítés alatt. Az első szövegsor mostantól tartalmazza az adatcsomagból a 2-es értéket.

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

A type tulajdonság az Action.Execute lehetőséget választja, amelyet a widget-gazdagép továbbít a szolgáltató OnActionInvoked visszahívásának. Használja helyette az Action.OpenUrl parancsot URL-navigációhoz; az nem hívja meg az adott szolgáltató visszahívási függvényét. A cím tartalmazza a gomb szövegét, a műveletet pedig az alkalmazás által meghatározott, a szolgáltató által kezelt művelet jelöli. Ha $host.isUserContextAuthenticated hamis, ne kínáljon Action.Execute interakciókat; csak az Action.OpenUrl támogatott.

Az utolsó adaptív kártya. A két szövegsor után megjelenik a

Az alábbi kódlista a számláló-widget interakció végső sablonját mutatja be. A Action.Execute gombhoz hitelesített felhasználói környezet szükséges. Érvényesítse a Widgets Boardban a szolgáltatójával; a Tervező nem futtatja a szolgáltató inkrementálási kezelőjét.

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

Visszajelzés

Hasznosnak találta ezt az oldalt?

Utolsó frissítés időpontja: 2026-10-27

Számláló widget