Vytvoření šablony widgetu pomocí návrháře Adaptivní karty

U widgetu Adaptive Card definujte uživatelské rozhraní a interakce pomocí šablony JSON Adaptivní karty a volitelně samostatného datového payloadu JSON. Tento článek vás provede šablonou counting-widget s datovými vazbami a podmíněným rozložením. Windows widgety můžou také zobrazovat kód HTML z adresy URL; pro tento formát obsahu viz poskytovatelé webových widgetů.

Widget pro počítání

Příklad v tomto článku je jednoduchý počítaný widget, který zobrazuje celočíselnou hodnotu a umožňuje uživateli zvýšit hodnotu kliknutím na tlačítko v uživatelském rozhraní widgetu. Tato ukázková šablona používá datovou vazbu k automatické aktualizaci uživatelského rozhraní na základě kontextu dat.

Aplikace musí implementovat poskytovatele widgetů, aby vygenerovaly a aktualizovaly šablonu widgetu nebo data a předaly je hostiteli widgetu. Článek Implementace zprostředkovatele widgetu v aplikaci win32 obsahuje podrobné pokyny k implementaci zprostředkovatele pro počítací widget, který vygenerujeme v níže uvedených krocích.

Návrhář Adaptivní karty

Návrhář Adaptivní karty je online nástroj pro úpravy formátu JSON karty a zobrazení náhledu rozložení a datové vazby. Otevřete Návrhář pro práci se šablonou.

Important

Návrhář používá vlastní renderer a možnosti hostitele. Nepředpokládejte, že funkce, které nabízí, jsou podporovány službou Widgets Board nebo že poskytuje hodnoty $host specifické pro Windows. Tento průvodce nezávisí na předvolbě hostitele ani na editoru dat hostitele. Otestujte konečnou šablonu v poskytovateli widgetů Windows pro každou podporovanou velikost a motiv.

Následující obrázky znázorňují rozložení karty, nikoli aktuální rozhraní Designer.

Začněte s prázdnou kartou

Editor datové části karty obsahuje definici JSON karty. Nahraďte její obsah touto prázdnou kartou:

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

Editor ukázkových dat obsahuje volitelný kontext dat JSON. Informace o vazbě dat k šabloně najdete v tématu Adaptivní karty Template Language.

vlastnosti hostitele widgetu Windows

Widgets Board poskytuje vlastnosti hostitele za běhu. Odkazujte na ně ve $host výrazech šablony, například ${$host.widgetSize}. Tyto vlastnosti jsou oddělené od datové části vašeho poskytovatele; přidání pole widgetSize do ukázkových dat nenastaví $host.widgetSize.

Vlastnictví	Hodnota	Description
host.widgetSize	„malý“, „střední“ nebo „velký“	Velikost připnutého widgetu
host.hostTheme	"světlé" nebo "tmavé"	Aktuální motiv zařízení, na kterém se zobrazuje panel widgetů.
host.isSettingsPayload	pravda nebo lež	Pokud je tato hodnota pravdivá, uživatel v místní nabídce widgetu kliknul na tlačítko Přizpůsobit widget. Tuto hodnotu vlastnosti můžete použít k zobrazení prvků uživatelského rozhraní nastavení přizpůsobení. Toto je alternativní metoda použití IWidgetProvider2.OnCustomizationRequested ke změně datové části JSON v aplikaci zprostředkovatele widgetu. Další informace naleznete v tématu Implementace přizpůsobení widgetu.
host.isHeaderSupported	pravda nebo lež	Pokud je tato hodnota pravdivá, je podporováno přizpůsobení hlavičky. Další informace najdete v tématu isHeaderSupported.
host.isHeader	pravda nebo lež	Pokud je tato hodnota pravdivá, hostitel požaduje datovou část určenou speciálně pro vykreslení hlavičky widgetu.
host.isWebSupported	pravda nebo lež	Pokud je tato hodnota false, hostitel v současné době nepodporuje načítání webového obsahu widgetu. Když k tomu dojde, webové widgety zobrazí záložní datovou část JSON zadanou poskytovatelem widgetu, ale tuto hodnotu můžete použít k dalšímu přizpůsobení obsahu. Další informace najdete v tématu Poskytovatelé webových widgetů.
host.isUserContextAuthenticated	pravda nebo lež	Pokud je tato hodnota false, jedinou podporovanou akcí je Action.OpenUrl. Hodnotu isUserContextAuthenticated lze použít k úpravě obsahu widgetu odpovídajícím způsobem vzhledem k omezením interaktivity.

Widget pro počítání používá čtyři elementy TextBlock a jednu akci Action.Execute pro své tlačítko.

Přidání elementů TextBlock

Přidejte čtyři prvky TextBlock z palety elementů Návrháře nebo je přidejte přímo do formátu JSON karty. Před použitím podmíněného rozložení má karta čtyři řádky textu, jak je znázorněno níže.

Implementace podmíněného rozložení

V editoru datové části karty nahraďte pole body následujícím fragmentem:

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

V jazyce šablony Adaptivní karty vlastnost $when určuje, že obsahující prvek se zobrazí, když se přidružená hodnota vyhodnotí jako true. Pokud se hodnota vyhodnotí jako nepravda, prvek obsahující se nezobrazí. V základním prvku v našem příkladu se zobrazí jeden ze tří elementů TextBlock a ostatní dva skryté v závislosti na hodnotě $host.widgetSize vlastnosti. Další informace o podmíněných nastaveních podporovaných v Adaptivní karty najdete v tématu Conditional layout with $when.

Bez vyhodnocení výrazů šablony se na kartě zobrazí všechny čtyři textové bloky:

Když panel widgetů vyhodnotí šablonu s nastavenou $host.widgetSize hodnotou "small", zobrazí se vedle počtu pouze malý textový blok:

Po integraci šablony s vaším poskytovatelem změňte velikost připnutého widgetu na panelu widgetů a zkontrolujte, že se zobrazí odpovídající blok textu. Deklarujte každou velikost, kterou chcete otestovat v manifestu zprostředkovatele widgetu. Obecný náhled Návrháře bez dat hostitele Windows nemůže tyto podmínky ověřit.

Vytvoření vazby k kontextu dat

Příklad používá datovou vlastnost s názvem count, na kterou v prvním TextBlock odkazuje ${count}. Za běhu poskytovatel odešle datovou část hostiteli widgetu. V době návrhu zadejte v editoru Ukázková data následující kód JSON a povolte náhled v Návrháři, abyste zkontrolovali vazbu count. Tato ukázková data neposkytují samostatné vlastnosti hostitele Windows.

{"count": "2"}

S {"count": "2"} jako ukázkovými daty rozšíření šablony nahradí ${count} za 2 v prvním TextBlock. Po povolení náhledu zkontrolujte tuto vazbu v Návrháři. Zkontrolujte samostatné $host.widgetSize podmínky na panelu widgetů, jak je popsáno výše.

Přidání tlačítka

Dalším krokem je přidání tlačítka do našeho widgetu. Když uživatel v hostiteli widgetu klikne na tlačítko, hostitel odešle žádost poskytovateli widgetu. V tomto příkladu poskytovatel widgetu zvýší hodnotu počtu a vrátí aktualizovanou datovou část. Vzhledem k tomu, že tato operace vyžaduje poskytovatele widgetů, nebudete moct toto chování zobrazit v návrháři Adaptivní karty, ale stále můžete použít návrháře k úpravě rozložení tlačítka v uživatelském rozhraní.

U Adaptivní karty se interaktivní prvky definují pomocí prvků action. Přidejte následující blok JSON přímo za body prvek v editoru obsahu karty. Nezapomeňte přidat čárku za pravou závorku (]) základního prvku nebo návrhář oznámí chybu formátování.

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

Vlastnost type určuje Action.Execute, kterou hostitel widgetu přepošle zpětnému volání OnActionInvoked poskytovatele. Místo toho použijte Action.OpenUrl pro navigaci na adresu URL; nevyvolá zpětné volání poskytovatele. Název dodává text tlačítka a příkaz je operace definovaná aplikací, kterou zprostředkovatel zpracovává. Pokud je $host.isUserContextAuthenticated false, nenabízejte interakce Action.Execute; podporuje se pouze Action.OpenUrl.

Kompletní šablona widgetu

Následující výpis kódu ukazuje konečnou šablonu pro interakci s counting-widget. Jeho tlačítko Action.Execute vyžaduje kontext autentizovaného uživatele. Ověřte ho ve Widgets Board u svého poskytovatele; Designer nespustí obslužnou rutinu inkrementace vašeho poskytovatele.

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

Příklad zátěžového balíčku Nastavení

Následující výpis kódu ukazuje jednoduchý příklad datové části JSON, která používá vlastnost host.isSettingsPayload k zobrazení jiného obsahu, když uživatel kliknul na tlačítko Přizpůsobit 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.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"
}