Tworzenie szablonu widżetu za pomocą projektanta kart adaptacyjnych

Interfejs użytkownika i interakcja z widżetami systemu Windows są implementowane przy użyciu kart adaptacyjnych . Każdy widżet udostępnia szablon wizualizacji i, opcjonalnie, szablon danych zdefiniowany przy użyciu dokumentów JSON zgodnych ze schematem kart adaptacyjnych. W tym artykule opisano kroki tworzenia prostego szablonu widżetu.

Widżet zliczania

Przykład w tym artykule to prosty widżet zliczania, który wyświetla wartość całkowitą i umożliwia użytkownikowi zwiększanie wartości przez kliknięcie przycisku w interfejsie użytkownika widżetu. Ten przykładowy szablon używa powiązania danych do automatycznego aktualizowania interfejsu użytkownika na podstawie kontekstu danych.

Aplikacje muszą zaimplementować dostawcę widżetu w celu wygenerowania i zaktualizowania szablonu widżetu i/lub danych i przekazania ich do hosta widżetu. Artykuł Implementowanie dostawcy widżetu w aplikacji win32 zawiera szczegółowe wskazówki dotyczące implementowania dostawcy widżetu dla widżetu zliczania, który zostanie wygenerowany w poniższych krokach.

Projektant kart adaptacyjnych

Projektant kart adaptacyjnych to interaktywne narzędzie online, które ułatwia generowanie szablonów JSON dla kart adaptacyjnych. Za pomocą kreatora możesz zobaczyć renderowane elementy wizualne i zachowanie powiązania danych w czasie rzeczywistym, gdy tworzysz szablon widżetu. Kliknij link, aby otworzyć projektanta, który będzie używany dla wszystkich kroków opisanych w tym przewodniku.

Tworzenie pustego szablonu na podstawie ustawień wstępnych

W górnej części strony, z listy rozwijanej Wybierz aplikację hosta, wybierz Tablicę widżetów. Spowoduje to ustawienie rozmiaru kontenera dla karty adaptacyjnej na rozmiar obsługiwany dla widżetów. Należy pamiętać, że widżety obsługują małe, średnie i duże rozmiary. Rozmiar domyślnego ustawienia wstępnego szablonu jest prawidłowym rozmiarem małego widżetu. Nie martw się, jeśli zawartość wychodzi poza granice, ponieważ zastąpimy ją zawartością dopasowaną do wnętrza widżetu.

W dolnej części strony znajdują się trzy edytory tekstów. Ten element oznaczony jako Card Payload Editor zawiera definicję JSON interfejsu użytkownika twojego widżetu. Edytor z etykietą Sample Data Editor zawiera kod JSON, który definiuje opcjonalny kontekst danych dla widżetu. Kontekst danych jest powiązany dynamicznie z kartą adaptacyjną po renderowaniu widżetu. Aby uzyskać więcej informacji na temat powiązania danych w kartach adaptacyjnych, zobacz język szablonu kart adaptacyjnych.

Trzeci edytor tekstów ma etykietę Przykładowy edytor danych hosta. Należy pamiętać, że ten edytor może zwinąć poniżej pozostałych dwóch edytorów strony. Jeśli tak, kliknij przycisk +, aby rozwinąć edytor. Aplikacje hosta widżetu mogą określać właściwości hosta, których można użyć w szablonie widżetu, aby dynamicznie wyświetlać inną zawartość na podstawie bieżących wartości właściwości. Panel widżetów obsługuje następujące właściwości hosta.

Listy rozwijane Rozmiar kontenera i Motyw obok listy rozwijanej Wybierz aplikację hosta w górnej części strony umożliwiają ustawianie tych właściwości bez ręcznego edytowania przykładowego pliku JSON hosta w edytorze.

Tworzenie nowej karty

W lewym górnym rogu strony kliknij pozycję Nowa karta. W oknie dialogowym Tworzenie wybierz pozycję Pusta karta. Teraz powinna wyświetlać się pusta karta adaptacyjna. Zauważysz również, że dokument JSON w przykładowym edytorze danych jest pusty.

Widżet zliczania, który utworzymy, jest bardzo prosty, składa się tylko z 4 TextBlock elementów i jednej akcji typu Action.Execute, która definiuje przycisk widżetu.

Dodawanie elementów TextBlock

Dodaj cztery elementy TextBlock, przeciągając je z okienka elementów karty po lewej stronie strony na pustą kartę adaptacyjną w okienku podglądu. Na tym etapie podgląd widżetu powinien wyglądać jak na poniższej ilustracji. Zawartość ponownie przepełnia się poza obramowaniem widżetu, ale zostanie to naprawione w poniższych krokach.

Implementowanie układu warunkowego

edytor ładunku kart został zaktualizowany w celu odzwierciedlenia elementów TextBlock , które dodaliśmy. Zastąp ciąg JSON dla obiektu ciągiem dla obiektu następującym：

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

W języku szablonów kart adaptacyjnych właściwość $when określa, że element zawierający jest wyświetlany, gdy skojarzona wartość ma wartość true. Jeśli wartość ma wartość false, element zawierający nie jest wyświetlany. W elemencie ciała w naszym przykładzie, zależnie od wartości właściwości , zostanie wyświetlony jeden z trzech elementów $host.widgetSize, a pozostałe dwa będą ukryte. Aby uzyskać więcej informacji na temat obsługiwanych warunków w kartach adaptacyjnych, zobacz sekcję Układ warunkowy z $when.

Teraz podgląd powinien wyglądać podobnie do poniższego obrazu:

Należy pamiętać, że instrukcje warunkowe nie są odzwierciedlane w wersji zapoznawczej. Dzieje się tak, ponieważ projektant nie symuluje zachowania hosta widżetu. Kliknij przycisk Tryb podglądu na górze strony, aby rozpocząć symulację. Podgląd widżetu wygląda teraz jak na poniższej ilustracji:

Z listy rozwijanej rozmiaru kontenera wybierz pozycję "Średni" i zwróć uwagę, że podgląd zmienia się, aby wyświetlać tylko TextBlock dla średniego rozmiaru. Kontener w wersji zapoznawczej zmienia również rozmiar, pokazując, jak można użyć podglądu, aby upewnić się, że interfejs użytkownika mieści się w kontenerze widżetu dla każdego obsługiwanego rozmiaru.

Wiązanie z kontekstem danych

Nasz przykładowy widżet będzie używać niestandardowej właściwości stanu o nazwie "count". W bieżącym szablonie widać, że wartość pierwszego TextBlock zawiera odwołanie do zmiennej $count. Gdy widżet jest uruchomiony na tablicy widżetów, dostawca widżetu jest odpowiedzialny za zebranie ładunku danych i przekazanie go do hosta widżetu. W czasie projektowania możesz użyć Przykładowego edytora danych, aby utworzyć prototyp ładunku danych i zobaczyć, jak różne wartości wpływają na wyświetlanie widżetu. Zastąp pusty ładunek danych następującym kodem JSON.

{"count": "2"}

Należy pamiętać, że podgląd wstawia teraz wartość określoną dla właściwości count do tekstu dla pierwszego TextBlock.

Dodaj przycisk

Następnym krokiem jest dodanie przycisku do widżetu. Na hoście widżetu, gdy użytkownik kliknie przycisk, host wyśle żądanie do dostawcy widżetu. W tym przykładzie dostawca widżetu zwiększy wartość licznika i zwróci zaktualizowany ładunek danych. Ponieważ ta operacja wymaga dostawcy widżetów, nie będzie można wyświetlić tego zachowania w Projektancie kart adaptacyjnych, ale nadal możesz użyć projektanta, aby dostosować układ przycisku w interfejsie użytkownika.

W kartach adaptacyjnych elementy interaktywne są definiowane za pomocą elementów akcji i. Dodaj następujący blok JSON bezpośrednio po elemencie body w edytorze zawartości karty. Pamiętaj, aby dodać przecinek po nawiasie zamykającym (]) elementu treści lub projektant zgłosi błąd formatowania.

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

W tym ciągu JSON, właściwość typu określa typ reprezentowanego działania. Widżety obsługują tylko typ akcji "Akcja.Wykonaj". Tytuł zawiera tekst wyświetlany na przycisku akcji. Właściwość czasownika jest ciągiem zdefiniowanym przez aplikację, który host widżetu wyśle do dostawcy widżetu w celu przekazania intencji skojarzonej z akcją. Widżet może mieć wiele akcji, a kod dostawcy widżetu sprawdzi wartość czasownika w żądaniu, aby określić, jaką akcję podjąć.

Kompletny szablon widżetu

Poniższa lista kodu przedstawia ostateczną wersję ładunku 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"
    }
  ]
}

Przykład ładunku ustawień

Na poniższej liście kodu przedstawiono prosty przykład ładunku JSON, który używa właściwości host.isSettingsPayload do wyświetlania innej zawartości, gdy użytkownik kliknął przycisk Dostosuj widżet .

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