Tworzenie szablonu widżetu za pomocą projektanta Adaptive Cards

Uwaga / Notatka

Niektóre informacje odnoszą się do wstępnie wydanego produktu, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Microsoft nie udziela żadnych gwarancji, wyraźnych ani domniemanych, w odniesieniu do podanych tutaj informacji.

Ważna

Funkcja opisana w tym temacie jest dostępna w kompilacjach programu Dev Channel w wersji zapoznawczej Windows począwszy od kompilacji 25217. Aby uzyskać informacje na temat kompilacji Windows w wersji zapoznawczej, zobacz Windows 10 Insider Preview.

Interfejs użytkownika i interakcja dla widżetów Windows są implementowane przy użyciu Adaptive Cards. Każdy widżet udostępnia szablon wizualizacji i, opcjonalnie, szablon danych zdefiniowany przy użyciu dokumentów JSON zgodnych ze schematem Adaptive Cards. 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 Adaptive Cards

Projektant Adaptive Cards to interaktywne narzędzie online, które ułatwia generowanie szablonów JSON dla Adaptive Cards. Korzystając z projektanta, możesz w czasie rzeczywistym zobaczyć renderowane wizualizacje i zachowanie wiązania danych, gdy tworzysz szablon widżetu. Kliknij link, aby otworzyć projektanta, który będzie używany we wszystkich krokach tego przewodnika.

Tworzenie pustego szablonu na podstawie ustawień wstępnych

W górnej części strony z listy rozwijanej Wybierz aplikację hosta wybierz pozycję Tablica 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ść przekracza granice, ponieważ zastąpimy ją zawartością zaprojektowaną tak, aby pasowała do wnętrza widżetu.

W dolnej części strony znajdują się trzy edytory tekstów. Element z etykietą Card Payload Editor zawiera definicję JSON interfejsu użytkownika (UI) widżetu. Edytor z etykietą Przykładowy edytor danych 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 Adaptive Cards, zobacz Adaptive Cards Template Language.

Trzeci edytor tekstu ma etykietę Przykładowy edytor danych hosta. Należy pamiętać, że ten edytor może znajdować się 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.

Majątek	Wartość	Opis
host.widgetSize	"mały", "średni" lub "duży"	Rozmiar przypiętego widżetu.
host.hostTheme	"jasny" lub "ciemny"	Bieżący motyw urządzenia, na którym jest wyświetlana tablica widżetów.
host.isSettingsPayload	prawda lub fałsz	Gdy ta wartość ma wartość true, użytkownik kliknął przycisk Dostosuj widżet w menu kontekstowym widżetu. Możesz użyć tej wartości właściwości, aby wyświetlić elementy interfejsu użytkownika ustawień dostosowywania. Jest to alternatywna metoda używania elementu IWidgetProvider2.OnCustomizationRequested w celu zmiany ładunku JSON w aplikacji dostawcy widżetów. Aby uzyskać więcej informacji, zobacz Implementowanie dostosowywania widżetu.
host.isHeaderSupported	prawda lub fałsz	Jeśli ta wartość ma wartość true, dostosowywanie nagłówka jest obsługiwane. Aby uzyskać więcej informacji, zobacz isHeaderSupported.
host.isHeader	prawda lub fałsz	Gdy ta wartość ma wartość true, host żąda ładunku specjalnie do renderowania nagłówka widżetu.
host.isWebSupported	prawda lub fałsz	Jeśli ta wartość jest fałsz, host nie obsługuje obecnie ładowania zawartości internetowej widżetu. W takim przypadku widżety internetowe będą wyświetlać rezerwowy ładunek JSON dostarczony przez dostawcę widżetu, ale ta wartość może służyć do dalszego dostosowywania zawartości. Aby uzyskać więcej informacji, zobacz Dostawcy widżetów sieci Web
host.isUserContextAuthenticated	prawda lub fałsz	Jeśli ta wartość ma wartość false, jedyną obsługiwaną akcją jest Action.OpenUrl. Wartość parametru isUserContextAuthenticated może służyć do odpowiedniego dostosowywania zawartości widżetu, biorąc pod uwagę ograniczenia interakcyjności.

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. Powinna zostać wyświetlona 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 elementów TextBlock 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 Elementy karty po lewej stronie 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 karty został zaktualizowany, aby odzwierciedlić dodane elementy TextBlock. Zastąp ciąg JSON dla obiektu body następującym kodem:

"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 Adaptive Cards Template Language 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 elemecie body w naszym przykładzie zostanie wyświetlony jeden z trzech elementów TextBlock , a pozostałe dwa ukryte, w zależności od wartości $host.widgetSize właściwości. Aby uzyskać więcej informacji na temat warunków obsługiwanych w Adaptive Cards, zobacz 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 w górnej części strony, aby rozpocząć symulację. Podgląd widżetu wygląda teraz jak na poniższej ilustracji:

Z listy rozwijanej Rozmiar kontenera wybierz pozycję "Średni" i zwróć uwagę, że wersja zapoznawcza powoduje przełączenie do wyświetlania tylko elementu 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 elementu TextBlock zawiera odwołanie do $countzmiennej . 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ć edytora przykładowych 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"}

Zwróć uwagę, że podgląd wstawia teraz wartość określoną dla właściwości count do tekstu pierwszego elementu TextBlock.

Dodawanie przycisku

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 pakiet danych. Ponieważ ta operacja wymaga dostawcy widżetów, nie będzie można wyświetlić tego zachowania w projektancie Adaptive Cards, ale nadal możesz użyć projektanta do dostosowania układu przycisku w interfejsie użytkownika.

Adaptacyjne karty umożliwiają definiowanie elementów interaktywnych za pomocą elementów action. Dodaj następujący blok JSON bezpośrednio po elemencie treści 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ść type określa typ reprezentowanej akcji. Widżety obsługują tylko typ akcji "Akcja.Wykonaj". Tytuł zawiera tekst wyświetlany na przycisku akcji. Właściwość verb jest ciągiem zdefiniowanym przez aplikację, który host widżetu wyśle do dostawcy widżetu, aby przekazać zamiar związany z daną akcją. Widżet może zawierać wiele działań, a kod dostawcy widżetu sprawdzi wartość czasownika w żądaniu, aby określić, jakie działanie 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 pakietu 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"
}