Vytvoření šablony widgetu pomocí Návrháře adaptivních karet

Poznámka:

Některé informace se týkají předem vydaného produktu, který může být podstatně změněn před komerčním vydáním. Společnost Microsoft neposkytuje žádné záruky, výslovné ani implicitní, ohledně zde poskytnutých informací.

Důležité

Funkce popsaná v tomto tématu je dostupná v buildech Dev Channel Preview systému Windows počínaje buildem 25217. Informace o buildech Windows ve verzi Preview najdete v tématu Windows 10 Insider Preview.

Uživatelské rozhraní a interakce widgetů Windows jsou implementovány pomocí Adaptivních karet. Každý widget poskytuje vizuální šablonu a volitelně datovou šablonu definovanou pomocí dokumentů JSON, které odpovídají schématu adaptivních karet. 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 poskytovatele widgetu v aplikaci win32 poskytuje podrobné pokyny k implementaci poskytovatele widgetu pro widget na počítání, který vytvoříme v následujících krocích.

Návrhář adaptivních karet

Návrhář adaptivních karet 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 průvodci.

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

V horní části stránky v rozevíracím seznamu vyberte hostitelskou aplikaci a 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. Ten označený jako Editor datové části karty obsahuje definici JSON uživatelského rozhraní widgetu. Editor označený ukázkový datový 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é vazbě v adaptivních kartách naleznete v tématu Jazyk šablony adaptivních karet.

Třetí textový editor je označen Ukázkový editor pro data hostitele. Všimněte si, že tento editor se může sbalit pod úroveň dvou dalších editorů 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.

Vlastnictví	Hodnota	Popis
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.

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ázdná karta. 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čítací widget, který vytvoříme, je velmi jednoduchý, který se skládá pouze ze 4 TextBlock prvků a jedna 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 prvků karty nalevo od 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 opět přesahuje hranice widgetu, ale toto bude opraveno v následujících krocích procesu.

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

Editor obsahu karty byl aktualizován, aby zobrazoval prvky TextBlock, které jsme přidali. Nahraďte řetězec JSON pro objekt tělo následujícím:

"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ích karet 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 elementu v našem příkladu bude jeden ze tří elementů TextBlock zobrazen a ostatní dva skryty, v závislosti na hodnotě vlastnosti $host.widgetSize. Další informace o podmíněných možnostech podporovaných v adaptivních kartách najdete v tématu Podmíněné rozložení s $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 nyní zobrazuje 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 TextBlock obsahuje odkaz na proměnnou $count. 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ý objekt následujícím kódem JSON.

{"count": "2"}

Všimněte si, že náhled nyní vloží hodnotu určenou pro vlastnost počtu do textu prvního bloku textu .

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čítadla 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ích karet, ale stále můžete použít návrháře k úpravě rozložení tlačítka v uživatelském rozhraní.

Pomocí adaptivních karet jsou interaktivní prvky definovány pomocí akcí elementy. Přidejte následující blok JSON přímo za element body v editoru datové části 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 typu druh akce, která je reprezentována. Widgety podporují pouze typ akce Action.Execute. Název obsahuje text zobrazený na tlačítku pro akci. Vlastnost sloveso 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 datové části 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.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"
}