Tworzenie szablonu widżetu za pomocą projektanta Adaptive Cards

W przypadku widżetu karty adaptacyjnej zdefiniuj interfejs użytkownika i interakcje za pomocą szablonu JSON Adaptive Cards oraz opcjonalnie osobnego obiektu danych JSON. W tym artykule przedstawiono szablon widżetu licznika z powiązaniem danych i układem warunkowym. Widżety systemu Windows mogą również wyświetlać kod HTML z adresu URL; informacje o tym formacie zawartości znajdziesz w Dostawcy widżetów sieci Web.

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

Adaptive Cards Designer to narzędzie online do edytowania kodu JSON karty i wyświetlania podglądu układu i powiązania danych. Otwórz Designer, aby pracować nad szablonem.

Important

Designer używa własnego renderera i opcji hosta. Nie zakładaj, że funkcje, które oferuje, są obsługiwane przez tablicę widżetów lub że dostarcza wartości specyficzne dla systemu Windows $host. Ten przewodnik nie wymaga ustawień wstępnych hosta ani edytora danych hosta. Przetestuj ostateczny szablon w dostawcy widżetów systemu Windows dla każdego obsługiwanego rozmiaru i motywu.

Poniższe obrazy ilustrują układ karty, a nie bieżący interfejs Projektanta.

Zacznij od pustej karty

Edytor payloadu karty zawiera definicję JSON karty. Zastąp jego zawartość tą pustą kartą:

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

Edytor przykładowych danych zawiera opcjonalny kontekst danych JSON. Aby uzyskać informacje o powiązaniu tych danych z szablonem, zobacz Adaptive Cards Template Language Język szablonu Adaptive Cards.

Właściwości hosta widżetów systemu Windows

Widgets Board dostarcza właściwości hosta w czasie działania. Odwołuj się do nich przez $host w wyrażeniach szablonu, takich jak ${$host.widgetSize}. Te właściwości są oddzielne od payloadu danych dostawcy; dodanie pola widgetSize do przykładowych danych nie powoduje ustawienia $host.widgetSize.

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.

Widżet zliczania używa czterech elementów TextBlock i jednej akcji Action.Execute na potrzeby swojego przycisku.

Dodawanie elementów TextBlock

Dodaj cztery elementy TextBlock z palety elementów projektanta lub dodaj je bezpośrednio w kodzie JSON karty. Przed zastosowaniem układu warunkowego karta ma cztery wiersze tekstu, jak pokazano poniżej.

Implementowanie układu warunkowego

W edytorze Card payload zastąp tablicę body następującym 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\"}"
    }
]

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.

Bez oceniania wyrażeń szablonu karta zawiera wszystkie cztery bloki tekstowe:

Gdy panel Widgets ocenia szablon, gdy $host.widgetSize ustawiono na "small", obok liczby pojawia się tylko mały blok tekstowy:

Po zintegrowaniu szablonu z dostawcą zmień rozmiar przypiętego widżetu na tablicy widżetów i sprawdź, czy zostanie wyświetlony pasujący blok tekstowy. Zadeklaruj każdy rozmiar, który chcesz przetestować w manifeście dostawcy widżetu. Ogólny podgląd Designera bez danych hosta systemu Windows nie może zweryfikować tych warunków.

Wiązanie z kontekstem danych

W przykładzie użyto właściwości danych o nazwie count, do której odwołuje się element ${count} w pierwszym elemencie TextBlock. W czasie wykonywania dostawca wysyła pakiet danych do hosta widżetu. W czasie projektowania wprowadź następujący kod JSON w edytorze przykładowych danych i włącz podgląd projektanta, aby sprawdzić powiązanie wartości count. Te przykładowe dane nie dostarczają oddzielnych właściwości hosta Windows.

{"count": "2"}

Przy użyciu {"count": "2"} jako przykładowych danych rozszerzenie szablonu zastępuje ${count} elementem 2 w pierwszym elemencie TextBlock. Sprawdź to powiązanie w Designer po włączeniu podglądu. Sprawdź oddzielne $host.widgetSize warunki w panelu Widgets Board, jak opisano powyżej.

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łaściwość type wybiera wartość Action.Execute, którą host widżetu przekazuje do wywołania zwrotnego dostawcy OnActionInvoked. Zamiast tego użyj elementu Action.OpenUrl do otwierania adresów URL; nie wywołuje funkcji zwrotnej tego dostawcy. Tytuł dostarcza tekst przycisku, a verb jest operacją zdefiniowaną przez aplikację obsługiwaną przez dostawcę. Jeśli $host.isUserContextAuthenticated ma wartość false, nie udostępniaj interakcji Action.Execute; obsługiwana jest tylko wartość Action.OpenUrl.

Kompletny szablon widżetu

Na poniższej liście kodu przedstawiono ostateczny szablon interakcji z widżetem zliczania. Jego przycisk Action.Execute wymaga uwierzytelnionego kontekstu użytkownika. Zweryfikuj go w Widgets Board w swoim providerze; Projektant nie uruchamia procedury obsługi inkrementacji dostawcy.

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