Karty adaptacyjne w Teams: jak korzystać z projektanta, z przykładami
By Mirko Peters ·
Jak zaprojektować kartę adaptacyjną dla Microsoft Teams za pomocą projektanta kart adaptacyjnych, jakie wersje schematu i akcje obsługuje Teams, zasady układu dla urządzeń mobilnych oraz minimalny przykład w JSON.
Automatically translated with AI from the original post. Read the English original
Karta adaptacyjna w Teams to opis w formacie JSON niewielkiego fragmentu interfejsu, który Teams wyświetla jako kartę wiadomości. Najszybszym sposobem jej utworzenia jest projektant kart adaptacyjnych działający w przeglądarce: dodajesz elementy, kopiujesz JSON i wysyłasz go z poziomu bota lub aplikacji. Ten przewodnik omawia przebieg pracy z projektantem, obsługiwane przez Teams funkcje, zasady układu, które zapobiegają ucinaniu kart, oraz minimalny przykład.
Najważniejsze wnioski
- Projektant kart adaptacyjnych działający w przeglądarce znajduje się pod adresem adaptivecards.microsoft.com/designer.html. Dodawaj elementy wizualnie, skopiuj ładunek JSON i użyj go w swojej aplikacji.
- Boty Teams i rozszerzenia wiadomości obsługują schemat kart adaptacyjnych w wersji 1.6 lub wcześniejszej, a aplikacja mobilna Teams obsługuje wersje do 1.6 włącznie.
- Przychodzące webhooki obsługują wszystkie natywne elementy kart oprócz Action.Submit. Obsługiwane tam akcje to Action.OpenURL, Action.ShowCard, Action.ToggleVisibility i Action.Execute.
- Projektuj najpierw z myślą o wąskich ekranach, ustaw wrap na true w tekstach i zestawach wyboru, a stosuj od jednej do trzech głównych akcji, maksymalnie sześć.
- Karty w Teams nie obsługują przesyłania plików ani obrazów, a właściwość isEnabled akcji Action.Submit nie jest obsługiwana.
Uwaga dotycząca źródeł: strony Microsoft Learn, na których oparto ten artykuł, nie opisują selektora aplikacji hosta w projektancie ani edytora danych przykładowych dla Teams. Poniższe kroki trzymają się tego, co podają te strony.
Otwórz projektanta
Dokumentacja kart adaptacyjnych wskazuje projektanta działającego w przeglądarce pod adresem adaptivecards.microsoft.com/designer.html. Może on być także osadzony we własnej aplikacji webowej za pomocą pakietu npm adaptivecards-designer. Przewodnik Microsoft po Teams SDK opisuje trzyetapowy przebieg pracy:
- Dodawaj elementy wizualnie, aż karta będzie wyglądać poprawnie.
- Skopiuj ładunek JSON z panelu edytora.
- Wklej JSON do swojego projektu lub przekonwertuj go na wywołania konstruktora.
Jeśli wolisz edytor, strona narzędzi dla kart adaptacyjnych wymienia rozszerzenie Visual Studio Code o nazwie Adaptive Card Viewer, które podgląda kartę podczas edycji pliku .json z właściwością $schema. Wymienia również AdaptiveCards Studio, które pozwala edytować szablony kart i dane przykładowe w VS Code.
Co obsługuje Teams
Dokumentacja kart Teams podaje następujące ograniczenia:
| Obszar | Udokumentowane wsparcie |
|---|---|
| Wersja schematu | Wersja 1.6 lub wcześniejsza dla kart botów, rozszerzeń wiadomości, rozwijania linków i okien dialogowych |
| Aplikacja mobilna Teams | Do wersji 1.6; nowsze wersje mogą wyświetlać się niespójnie |
| Webhooki przychodzące | Wszystkie natywne elementy oprócz Action.Submit |
| Action.Submit | Właściwość isEnabled nie jest obsługiwana |
| Style akcji | Stylizacja pozytywna lub destrukcyjna nie jest obsługiwana |
| Przesyłanie | Przesyłanie plików lub obrazów nie jest obsługiwane |
| Powierzchnie | Boty, rozszerzenia wiadomości i Bot Framework są oznaczone jako obsługiwane. Karty i łączniki są oznaczone jako nieobsługiwane. Webhooki przychodzące obsługują karty adaptacyjne tylko dla typu łącznika grup Microsoft 365. |
Dokumentacja SDK dodaje, że jego pakiety kart zawierają schemat Adaptive Card v1.5 jako typy ścisłe. Mieści się to w limicie wersji 1.6.
Minimalny przykład
To jest struktura, którą bot wysyła jako załącznik. Została dostosowana na podstawie formatu ze strony referencyjnej kart Teams. Karta trafia do content, a contentType to application/vnd.microsoft.card.adaptive.
``json { "contentType": "application/vnd.microsoft.card.adaptive", "content": { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.0", "body": [ { "type": "TextBlock", "text": "Publish Adaptive Card schema", "weight": "bolder", "size": "medium", "wrap": true } ], "actions": [ { "type": "Action.Submit", "title": "OK" } ] } } ``
Właściwość wrap jest dodatkiem wynikającym z poniższych wskazówek projektowych. Strona pokazuje też wartości dynamiczne z użyciem szablonów, na przykład blok tekstu, którego text to ${titleText}.
Wysyłanie karty
Strona referencyjna kart nie zawiera pełnego przewodnika po wysyłaniu. Odsyła do przykładów Bot Framework dla .NET i Node.js. Przewodnik po SDK Teams pokazuje wzorzec builder z pakietami dla C# (Microsoft.Teams.Cards), Pythona (microsoft-teams-cards) i TypeScript (@microsoft/teams.cards). Krótki przykład w Pythonie z przewodnika buduje kartę z blokiem tekstu i wysyła ją za pomocą MessageActivityInput(text="Hello text!").add_card(card). Buildery sprawdzają każdą właściwość względem schematu, dzięki czemu błędy są wychwytywane już na etapie budowania.
Zasady układu w Teams
Wskazówki projektowe Microsoftu zawierają następujące zasady:
- Najpierw wąsko. Projektuj najpierw dla wąskich ekranów. Karty dobrze się skalują w górę, ale nie w dół.
- Zawijaj tekst. Ustaw
"wrap": truewTextBlock,ColumnSetiInput.ChoiceSet. - Kolumny. Używaj mniejszej liczby kolumn, aby lepiej wyglądało to na urządzeniach mobilnych. Wskazówki nie podają liczbowego limitu kolumn.
- Wartości szerokości kolumn.
autodopasowuje szerokość do zawartości i sprawdza się w kolumnach z przyciskami, które muszą pozostać w pełni widoczne;stretchdzieli dostępną szerokość równo; zwykła liczba oznacza proporcję, a<number>pxto stała szerokość, która nie powinna przekraczać szerokości urządzenia. Nie ustawiajautodla każdej kolumny. - Obrazy. Używaj przezroczystych teł, aby obrazy dopasowywały się do dowolnego motywu Teams. Obraz 100 na 100 pikseli wyświetlany w rozmiarze 50 na 50 pozostaje ostry, ale odwrotnie powoduje pikselizację. Użyj
widthiheight, aby kontrolować dokładny rozmiar. - Karty na pełną szerokość. Testuj je w wąskich układach, takich jak urządzenia mobilne i boczne panele spotkań, aby treść nie została ucięta.
- Akcje. Używaj od jednej do trzech akcji podstawowych, najwyżej sześciu.
- Kontenery. Używaj
styledo wyróżniania,selectActiondo przypisania akcji iAction.ToggleVisibilitydla grup, które można zwijać. Nie używaj kontenerów do innych celów.
Microsoft wymienia też typy kart według zastosowania, takie jak Hero do artykułów, Thumbnail do prostej wiadomości z akcją, List do wyboru z elementów i ChoiceSet do zbierania kilku danych wejściowych. Strona projektowa zaznacza, że jej wskazówki pochodzą z dawnego przewodnika po Teams, i jako aktualne źródło najlepszych praktyk projektowych wskazuje centrum dokumentacji Adaptive Cards.
Częste błędy
- Projektowanie szerokiej karty i odkrycie na urządzeniu mobilnym, że tekst jest ucinany.
- Używanie wersji schematu wyższej niż 1.6.
- Używanie elementu Action.Submit w karcie przychodzącego webhooka.
- Dodawanie zbyt wielu przycisków.
- Używanie stałych szerokości w pikselach w kilku kolumnach.
Materiały startowe
Strona projektowania zawiera odnośniki do repozytorium gotowych szablonów Microsoft-Teams-Adaptive-Card-Samples w serwisie GitHub oraz do zestawu Teams UI Kit w programie Figma, który obejmuje motywy, dostępność i responsywne rozmiary.
Powiązane
Źródła
- Microsoft Learn: Narzędzia Adaptive Cards
- Microsoft Learn: Tworzenie i poznawanie typów kart w usłudze Teams
- Microsoft Learn: Projektowanie kart Adaptive Cards dla aplikacji
- Microsoft Learn: Tworzenie kart Adaptive Cards (zestaw Teams SDK)
FAQ
Gdzie znajduje się projektant kart adaptacyjnych?
Microsoft Learn wskazuje projektanta działającego w przeglądarce pod adresem adaptivecards.microsoft.com/designer.html. Dokumentacja Teams SDK opisuje przebieg pracy: dodaj elementy wizualnie, aż karta będzie wyglądać poprawnie, skopiuj ładunek JSON z panelu edytora, a następnie wklej go do projektu lub przekonwertuj na wywołania konstruktora.
Jaką wersję karty adaptacyjnej obsługuje Teams?
Zgodnie z dokumentacją platformy Teams na Microsoft Learn karty wysyłane przez boty, rozszerzenia wiadomości oparte na akcjach, rozszerzenia wiadomości oparte na wyszukiwaniu, rozwijanie linków oraz okna dialogowe obsługują schemat w wersji 1.6 lub wcześniejszej. Aplikacja mobilna Teams obsługuje wersje do 1.6 włącznie, a nowsze mogą nie wyświetlać się tam poprawnie.
Dlaczego tekst mojej karty jest ucinany na urządzeniach mobilnych?
Microsoft Learn zaleca ustawienie wrap na true w elementach TextBlock, ColumnSet i Input.ChoiceSet. Bez tego tekst na urządzeniach mobilnych zostanie obcięty. Zaleca także projektowanie najpierw z myślą o wąskich ekranach i stosowanie mniejszej liczby kolumn, które lepiej wyglądają na urządzeniach mobilnych.
Czy mogę użyć Action.Submit w karcie z przychodzącego webhooka?
Nie. Dokumentacja kart na Microsoft Learn podaje, że przychodzące webhooki obsługują wszystkie natywne elementy kart adaptacyjnych oprócz Action.Submit. Zamiast tego użyj Action.OpenURL, Action.ShowCard, Action.ToggleVisibility lub Action.Execute.
Ile przycisków powinna mieć karta?
Microsoft Learn zaleca od jednej do trzech głównych akcji i dopuszcza maksymalnie sześć, podkreślając, że mniej znaczy więcej. Zaznacza także, że karty powinny być zwięzłe, ponieważ tracą na użyteczności, gdy wypadają z widoku podczas przewijania, szczególnie w kanałach.