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

Uživatelské rozhraní a interakce widgetů Windows se implementují pomocí Adaptivní karty. Každý widget poskytuje vizuální šablonu a volitelně datovou šablonu definovanou pomocí dokumentů JSON, které odpovídají schématu Adaptivní karty. Tento článek vás provede postupem vytvoření jednoduché šablony widgetu.

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 interaktivní nástroj, který usnadňuje generování šablon JSON pro Adaptivní karty. Pomocí návrháře můžete při vytváření šablony widgetu zobrazit vykreslené vizuály a chování datových vazeb v reálném čase. Pomocí odkazu otevřete návrháře, který bude použit pro všechny kroky v tomto návodu.

Vytvoření prázdné šablony z přednastavení

V horní části stránky v rozevíracím seznamu Vybrat hostitelskou aplikaci zvolte Panel widgetů. Tím nastavíte velikost kontejneru pro adaptivní kartu tak, aby měla velikost podporovanou pro widgety. Všimněte si, že widgety podporují malé, střední a velké velikosti. Velikost výchozí předvolby šablony je správná velikost malého widgetu. Nemějte obavy, pokud obsah přeteče ohraničení, protože ho nahradíme obsahem navrženým tak, aby se vešel do widgetu.

V dolní části stránky jsou tři textové editory. Payload Editor karty obsahuje definici JSON uživatelského rozhraní widgetu. Editor s popiskem Sample Data Editor obsahuje JSON, který definuje volitelný kontext dat pro widget. Kontext dat je při vykreslení widgetu dynamicky svázán s adaptivní kartou. Další informace o datových vazbách v Adaptivní karty najdete v tématu Adaptivní karty Template Language.

Třetí textový editor je označený editor ukázkových dat hostitele. Všimněte si, že tento editor se může zobrazit pod dalšími dvěma editory na stránce. Pokud ano, kliknutím na + rozbalte editor. Hostitelské aplikace widgetů můžou určovat vlastnosti hostitele, které můžete použít v šabloně widgetu k dynamickému zobrazení jiného obsahu na základě aktuálních hodnot vlastností. Panel widgetů podporuje následující vlastnosti hostitele.

Rozevírací seznamy Velikost kontejneru a Motiv vedle rozevíracího seznamu Vybrat hostitelskou aplikaci v horní části stránky umožňují nastavit tyto vlastnosti bez ruční úpravy kódu JSON ukázkového hostitele v editoru.

Vytvoření nové karty

V levém horním rohu stránky klikněte na Nová karta. V dialogovém okně Vytvořit vyberte Prázdnou kartu. Teď byste měli vidět prázdnou adaptivní kartu. Všimněte si také, že dokument JSON v ukázkovém editoru dat je prázdný.

Počítaný widget, který vytvoříme, je velmi jednoduchý, který se skládá pouze ze 4 elementů TextBlock a jedné akce typu Action.Execute, která definuje tlačítko widgetu.

Přidání elementů TextBlock

Přidejte čtyři prvky TextBlock přetažením z podokna Prvky karty na levé straně stránky na prázdnou adaptivní kartu v podokně náhledu. V tomto okamžiku by náhled widgetu měl vypadat jako na následujícím obrázku. Obsah znovu přeteká mimo ohraničení widgetu, ale to bude napraveno v dalších krocích.

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

Editor datové části karty byl aktualizován tak, aby zohledňoval prvky TextBlock, které jsme přidali. Nahraďte řetězec JSON pro základní objekt následujícím kódem:

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

Náhled by teď měl vypadat jako na následujícím obrázku:

Všimněte si, že se podmíněné příkazy neprojevují ve verzi Preview. Důvodem je to, že návrhář nes simuluje chování hostitele widgetu. Kliknutím na tlačítko Režim náhledu v horní části stránky spusťte simulaci. Náhled widgetu teď vypadá jako na následujícím obrázku:

V rozevíracím seznamu Velikost kontejneru vyberte "Střední" a všimněte si, že náhled se přepne tak, aby zobrazoval pouze TextBlock pro střední velikost. Kontejner ve verzi Preview také změní velikost a předvádí, jak můžete použít náhled, abyste měli jistotu, že uživatelské rozhraní zapadá do kontejneru widgetů pro každou podporovanou velikost.

Vytvoření vazby k kontextu dat

Náš ukázkový widget použije vlastní vlastnost stavu s názvem count. V aktuální šabloně vidíte, že hodnota prvního Objektu TextBlock obsahuje odkaz na $countproměnnou . Když je widget spuštěný na panelu widgetů, je poskytovatel widgetu zodpovědný za sestavení datové části dat a jeho předání hostiteli widgetu. V době návrhu můžete pomocí ukázkového datového editoru vytvořit prototyp datové části a zjistit, jak různé hodnoty ovlivňují zobrazení widgetu. Nahraďte prázdný datový payload následujícím JSON.

{"count": "2"}

Všimněte si, že náhled nyní vloží hodnotu zadanou pro vlastnost count do textu pro první TextBlock.

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

V tomto řetězci JSON určuje vlastnost typu akce, která je reprezentována. Widgety podporují pouze typ akce Action.Execute. Nadpis obsahuje text zobrazený na tlačítku akce. Vlastnost slovesa je řetězec definovaný aplikací, který hostitel widgetu odešle poskytovateli widgetu, aby komunikoval záměr spojený s akcí. Widget může mít více akcí a kód zprostředkovatele widgetu zkontroluje hodnotu příkazu v požadavku a určí, jaká akce se má provést.

Kompletní šablona widgetu

Následující výpis kódu ukazuje konečnou verzi datové části JSON.

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