Specyfikacja modułu renderowania kart adaptacyjnych

Poniższa specyfikacja opisuje sposób implementowania modułu renderowania kart adaptacyjnych na dowolnej natywnej platformie interfejsu użytkownika.

Ważne

Ta zawartość jest w toku i może brakować pewnych szczegółów. Daj nam znać, jeśli masz jakiekolwiek pytania lub opinie.

Analizowanie kodu JSON

Warunki błędu

1. Analizator MUSI sprawdzić, czy zawartość JSON jest prawidłowa.
2. Analizator MUSI zweryfikować zgodność z schematem (wymagane właściwości itp.)
3. Powyższe błędy MUSZĄ być zgłaszane do aplikacji hosta (wyjątek lub odpowiednik)

Nieznane typy

1. Jeśli napotkane są nieznane "typy", MUSZĄ ZOSTAĆ usunięte z wyniku
2. Wszelkie zmiany ładunku (jak powyżej) powinny być zgłaszane jako ostrzeżenia do aplikacji hosta

Nieznane właściwości

1. Analizator MUSI zawieraćdodatkowe właściwości dla elementów

Uwagi dodatkowe

1. Właściwość speakMOŻE zawierać znacznik SSML i MUSI zostać zwrócona do aplikacji hosta zgodnie z określeniem.

Analizowanie konfiguracji hosta

1. TODO

Wersjonowanie

1. Renderer MUSI zaimplementować określoną wersję schematu.
2. Konstruktor AdaptiveCardMUSI nadać version właściwości wartość domyślną w oparciu o aktualną wersję schematu
3. Jeśli moduł renderujący napotka version właściwość w AdaptiveCard, której wersja jest wyższa niż obsługiwana, musi zamiast niej zwrócić fallbackText.

Renderowanie

AdaptiveCard składa się z body i actions. Kolekcja CardElement to zestaw danych, które moduł renderujący będzie wyliczać i renderować w kolejności.

1. Każdy element MUSI rozciągać się na szerokość elementu nadrzędnego (pomyśl display: block w kodzie HTML).
2. Moduł renderujący MUSI ignorować wszystkie napotkane nieznane typy elementów i kontynuować renderowanie reszty ładunku.

Text, TextBlock i RichTextBlock

1. TextBlock MUSI przyjąć jeden wiersz, chyba że właściwość wrap jest ustawiona na true.
2. Blok tekstu POWINIEN przycinać zbędny tekst, kończąc wielokropkiem (...)

Markdown

1. Karty adaptacyjne pozwalają na korzystanie z podzestawu języka Markdown i powinny być obsługiwane w TextBlock.
2. Funkcja RichTextBlock nie obsługuje języka Markdown i musi być stylizowany przy użyciu uwidocznionych właściwości.
3. Zobacz pełne wymagania dotyczące języka Markdown

Funkcje formatowania

1. TextBlock zezwala na funkcje formatowania DATE/TIME , które MUSZĄ być obsługiwane na każdym rendererze.
2. WSZYSTKIE BŁĘDY MUSZĄ wyświetlać nieprzetworzone ciągi na karcie. Nie podjęto próby wysłania przyjaznej wiadomości. (Celem jest natychmiastowe uświadomienie deweloperowi problemu)

Obrazy

1. Program renderowany POWINIEN zezwalać aplikacjom hosta na informacje o tym, kiedy wszystkie obrazy HTTP zostały pobrane, a karta jest "w pełni renderowana"
2. Program renderujący MUSI sprawdzić parametr konfiguracji maxImageSize hosta podczas pobierania obrazów HTTP
3. Renderator MUST obsługiwać .png oraz .jpeg
4. Renderer POWINIEN obsługiwać.gif obrazy

Zachowanie układu zaawansowanego

Program renderujący MUSI uwzględniać następujące zachowania podczas renderowania elementów karty w odniesieniu do atrybutów wymienionych w tym dokumencie.

Program renderujący powinien zarządzać ograniczeniami, uwzględniając różne czynniki, takie jak margines, wypełnienie, wysokość, szerokość itp., a także konfigurację elementów karty oraz ich elementów podrzędnych.

Szerokość

1. Dozwolone wartości — autoi stretch stałe wartości w kategoriach pixels i weight
2. auto zapewnia wystarczającą ilość miejsca do poszerzania szerokości (obsługuje minimalne rozszerzenie)
3. stretch przyjmuje pozostałą szerokość (obsługuje maksymalne rozszerzenie)

W poniższych scenariuszach opisano, w jaki sposób ograniczenia mają wpływ na różne kombinacje szerokości kolumn

auto a stretch

1. Kolumny o szerokości auto i stretch.

• Pierwsza kolumna o auto szerokości zajmuje wystarczającą ilość miejsca, aby wyświetlić zawartość, a druga kolumna o stretch szerokości zajmuje całe miejsce.

2. Kolumny o tylko stretch szerokości

• Kolumny o szerokości rozciągniętej zajmują pozostałe spacje po podzieleniu ich w równym stopniu.

3. auto,stretch i auto

Szerokość pierwszej i trzeciej kolumny jest dostosowywana jako pierwsza, aby pomieścić elementy wystarczająco, a druga kolumna o szerokości rozciągniętej zajmuje pozostałe miejsce.

4. Kolejność wyświetlania elementów w kolumnach o szerokości auto

• Kolumny z auto ustawią się tak, aby zapewnić wystarczającą ilość miejsca do renderowania zawartości.
• W przypadku widoków obrazów obrazy zostaną pomniejszone, aby dopasować się do pozostałej szerokości.
• Uwaga: Obrazy będą zmniejszane tylko dla stretch i rozmiaru obrazu auto, ale nie dla stałej szerokości i wysokości w pikselach.

weights a pixels

1. Kolumny o kombinacji szerokości weight i pixel

• Na powyższej karcie istnieją trzy kolumny z następującą konfiguracją szerokości —
• Column1: Weight 50, Column2: 100px, Column3: Weight 50
• Szerokość kolumny 2 jest określana przez pixel value
• Szerokość kolumny 1 i 3 jest dostosowywana na podstawie weights i obliczonego weight ratio.

2. Kolumny z atrybutami weightpixel width i auto

• Na powyższej karcie istnieją cztery kolumny z następującą konfiguracją szerokości —
• Column1: Weight 50, Column2: 100px, Column3: Weight 50i Column4: auto
• Uwaga: Widok obrazu z kolumną o szerokości auto jest pomniejszana, aby dopasować się do pozostałej przestrzeni.

Kolejność pierwszeństwa wyświetlania elementów z atrybutem width

px > weight > auto > stretch

Wysokość

Dozwolone wartości — auto i stretch

W poniższych scenariuszach opisano wpływ ograniczeń na różne kombinacje wysokości dla elementów kart

1. Elementy rozszerzają się swobodnie w pionie, gdy karta nie ma stałej wysokości

• Obie kolumny mogą się rozszerzać w kierunku pionowym niezależnie od wartości auto i stretch.
• Właściwość wrap jest wyłączona dla bloku tekstu.

2. Poniższa karta ma włączoną wrap właściwość bloku tekstowego.

Odstępy i separatory

1. Właściwość spacing na każdym elemencie ma wpływ na ilość miejsca między elementem CURRENT a właściwością BEFORE .
2. Odstępy MUSZĄ mieć zastosowanie tylko wtedy, gdy istnieje element poprzedzający go. (Np. nie będzie dotyczyć pierwszego elementu w tablicy)
3. Moduł renderujący MUSI wyszukać ilość miejsca do użycia na podstawie odstępów hostConfig dla wartości wyliczenia zastosowanej do bieżącego elementu.
4. Jeśli element ma separator wartość true, widoczna linia MUSI zostać narysowana między bieżącym elementem a elementem przed nim.
5. Linia separatora MUSI być rysowana przy użyciu container.style.default.foregroundColor.
6. Separator MUSI być rysowany tylko wtedy, gdy element NIE JEST pierwszym w tablicy.
7. Odstępy — dozwolone wartościnone, , small, defaultmedium, largeextra large ipadding

• Atrybut odstępów dodaje odstępy między tym elementem a poprzednim elementem.

• Atrybut odstępów nie ma żadnego wpływu, gdy jest to pierwszy element w kontenerze widoków.

• Elementy oznaczone strzałką są pierwszymi elementami wśród swoich równorzędnych, więc odstępy nie mają wpływu.

2. Separator — możliwe wartości (przełącznik włączony/wyłączony)

• Rysuje linię rozdzielającą u góry elementu.

3. Kombinacja spacji i separatora

• Poniżej przedstawiono ograniczenia odstępów i kombinacji seperatora.

• Ogólna odległość odstępu jest utrzymywana w odniesieniu do podanych wartości.
• Separator jest dodawany w połowie rozstawionej odległości.

[Uwaga. Należy potwierdzić odległość, gdzie wstawiono separator w obszarze odstępów. Wydaje się, że środek]

Style kontenerów

• Zawiera wskazówki dotyczące stylów dla kontenerów, takich jak kolumny i zestaw kolumn
• pl-PL: Dozwolone wartości none, default, emphasis, good, attention, warning i accent
• Te wstępnie zdefiniowane opcje stylu zapewniają wypełnienie elementów w kontenerze i kolorze tła

1. Karta A ilustruje kolumny i zestaw kolumn bez opcji stylu
2. Karta B ilustruje zestaw kolumn ze stylem Ostrzeżenie. Zwróć uwagę na wypełnienie w kontenerze zestawu kolumn i zmianę koloru tła.
3. Karta C ilustruje kolumny tylko ze stylizacją. Podobnie jak w poprzedniej kolumnie, ta kolumna zawiera dopełnienie i zmianę tła.
4. Karta D ilustruje kolumny i zestaw kolumn z opcjami stylu.

[Uwaga. Należy sprawdzić, jak określana jest ilość wypełnienia. Czy jest on określany przez hosta? ]

Krwawić

• Ta właściwość umożliwia kontenerom, takim jak kolumny i zestawy kolumn, przenikanie przez element nadrzędny.
• Możliwe wartości on i off.

1. Kafel A ilustruje kolumny i zestaw kolumn ze standardowym stylem.
2. Karta B ilustruje pierwszą kolumnę z opcją spadu. Zawartość po prostu przenika przez granice do elementu nadrzędnego.

Rozmiar obrazu

Atrybut Size

• Dozwolone wartości — auto, , smallstretch, , mediumlarge
• auto : Obrazy będą skalowane w dół, aby zmieścić się w razie potrzeby, ale nie będą skalowane w górę w celu wypełnienia obszaru.
• stretch : Obraz skalowany w dół i w górę, aby dopasować się do potrzeb.
• small, medium i large: Obraz jest wyświetlany ze stałą szerokością, gdzie szerokość jest określana przez hosta.

1. auto a stretch

2. Szerokość kolumny i kombinacja rozmiaru obrazu

• Ogólnie rzecz biorąc, kolumny o stretch szerokości umożliwiają swobodne skalowanie w górę obrazów wraz z rozmiarem stretch.
• Kolumny o auto szerokości umożliwiają obrazowi zajmowanie dokładnego miejsca niezależnie od auto rozmiaru obrazu i stretch jego rozmiaru.
• Szerokość kolumny ma większy priorytet podczas określania rozmiaru obrazu w tym układzie.

Atrybut obrazu Width (in pixels)

• Zapewnia to żądaną szerokość obrazu na ekranie.
• size właściwość jest zastępowana po określeniu wartości

• Kolumna o auto szerokości będzie miała większy priorytet niż stretch w przypadku zapewnienia miejsca na zawartość obrazu w tym układzie.

Kombinacja szerokości kolumny (ciężar i piksele) oraz rozmiaru obrazu (automatyczny i rozciągnięty)

• Obrazy o rozmiarze auto zajmują wystarczającą ilość miejsca na rozszerzanie (lub zmniejszanie) w obrębie ograniczeń szerokości weight i pixel kolumn.
• Obrazy o rozmiarze stretch mogą się rozszerzać, aby wypełnić pozostałe miejsce w granicach szerokości kolumn weight i pixel.

Podsumowanie układu zaawansowanego

• Szerokość kolumny ma większy priorytet podczas określania rozmiaru obrazu niż rozmiar obrazu (auto, rozciągnięcie, minimalna szerokość itp.).
• Priorytet szerokości kolumny w celu odpowiedniego wyświetlenia jej zawartości — px>weight>auto>stretch
• Obraz size (auto, rozciągnięcie) jest ignorowany, gdy dostarczany jest obraz width i height w px.
• Atrybut rozmiaru dotyczący obrazu stretch będzie powiększany tylko wtedy, gdy pozostanie wolne miejsce i auto kolumny nieauto jest.
• Obraz rozciąga się do maksimum, gdzie zachowuje proporcje obrazu w przestrzeni dostępnej w kolumnie. Wysokość zwiększa się swobodnie.
• Spacing atrybut nie będzie miał żadnego wpływu, gdy jest to pierwszy lub jedyny element wśród elementów równorzędnych.

Czynności

1. Jeśli parametr HostConfig supportsInteractivity to false, program renderowany NIE MOŻE renderować żadnych akcji.
2. Właściwość actionsMUSI być renderowana jako przyciski w jakimś pasku akcji, zwykle w dolnej części karty.
3. Po naciśnięciu przycisku MUSI zezwolić aplikacji hosta na obsługę zdarzenia.
4. Zdarzenie MUSI przekazać wszystkie skojarzone właściwości z akcją
5. Zdarzenie MUSI przekazać dalej element AdaptiveCard, który został wykonany.

Akcja	Zachowanie
Action.OpenUrl	Otwieranie zewnętrznego adresu URL do wyświetlania
Action.ShowCard	Żąda wyświetlania użytkownikowi karty podrzędnej.
Akcja.Wyślij	Poproś o zebranie wszystkich elementów wejściowych do obiektu, który następnie jest wysyłany do Ciebie za pośrednictwem jakiejś metody zdefiniowanej przez aplikację hosta.
Action.Execute	(Wprowadzone w wersji 1.4) Poproś o zebranie wszystkich elementów wejściowych do obiektu, który jest następnie wysyłany do użytkownika za pośrednictwem "uniwersalnego kanału akcji"

Action.OpenUrl

1. Action.OpenUrl POWINNO otworzyć adres URL przy użyciu mechanizmu platformy natywnej
2. Jeśli nie jest to możliwe, należy zgłosić zdarzenie do aplikacji hosta w celu obsługi otwierania adresu URL. To zdarzenie MUSI zezwalać aplikacji hosta na zastąpienie domyślnego zachowania. Na przykład pozwól im otworzyć adres URL w ramach własnej aplikacji.

Akcja.PokażKartę

1. Action.ShowCard Musi być obsługiwany w jakiś sposób na podstawie ustawienia hostConfig. Istnieją dwa tryby: wbudowany i wyskakujące okienka. Karty wbudowane POWINNY automatycznie przełączać widoczność karty. W trybie wyskakującym zdarzenie POWINNO zostać wyzwolone w aplikacji hosta w celu wyświetlenia karty w pewien sposób.

Akcja.Wyślij

• Action.Submit Element zbiera pola wejściowe, scala z opcjonalnym polem danych i wysyła zdarzenie do klienta.
• Znacząca różnica w zachowaniu elementu występuje między wersją 1.x i 2.x modułu renderowania listy ACL.

Akcja przesyłania działa jak przesyłanie formularza HTML, z tą różnicą, że kod HTML zwykle wyzwala wpis HTTP, karty adaptacyjne pozostawiają ją do każdej aplikacji hosta, aby określić, co oznacza "przesyłanie".

1. Gdy to ustawienie MUSI zgłosić zdarzenie, użytkownik naciągnie wywołaną akcję.
2. Właściwość dataMUSI być uwzględniona w odpowiedzi zwrotnej.
3. W przypadku Action.Submit, renderer MUSI zebrać wszystkie dane wejściowe na karcie i pobrać ich wartości.

• 1.x Renderer — Dane wejściowe są zbierane ze wszystkich pól niezależnie od tego, gdzie w hierarchii znajduje się pole wejściowe.
• 2.x Renderer — Dane wejściowe są zbierane z pól znajdujących się w kontenerze nadrzędnym lub jako element równorzędny z elementem Action.Submit.

Action.Execute (Szczegóły zostaną podane później)

Action.Execute został wprowadzony w wersji 1.4. W późniejszym terminie udostępnimy wskazówki dotyczące implementacji zestawów SDK. Skontaktuj się, jeśli masz pytania dotyczące tego tematu.

wybierzAkcję

1. Jeśli konfiguracja supportedInteractivity hosta jest false, wtedy selectActionNIE MOŻE być renderowany jako cel dotykowy.
2. Image, ColumnSeti Column oferują selectAction właściwość , która powinna być wykonywana, gdy użytkownik go wywołuje, np. przez naciśnięcie elementu.

Dane wejściowe

1. Jeśli HostConfig supportsInteractivity jest false rendererem NIE MOŻE renderować żadnych wejść.
2. Dane wejściowe POWINNY być renderowane z największą możliwą wiernością. Na przykład najlepszym rozwiązaniem Input.Date jest oferowanie użytkownikowi selektora dat, ale jeśli nie jest to możliwe w stosie interfejsu użytkownika, moduł renderujący MUSI wrócić do renderowania standardowego pola tekstowego.
3. Renderer POWINIEN wyświetlaćplaceholderText, jeśli to możliwe
4. Powiązanie wartości wejściowej MUSI zostać prawidłowo uniknięte
5. Przed wersją 1.3 program renderowany nie musi implementować walidacji danych wejściowych. Użytkownicy kart adaptacyjnych muszą zaplanować weryfikację wszystkich odebranych danych na ich końcu.
6. Etykiety wejściowe i walidacja zostały wprowadzone w wersji 1.3 schematu kart adaptacyjnych. Należy zachować szczególną ostrożność podczas renderowania skojarzonej etykiety, wskazówek dotyczących walidacji i komunikatów o błędach.

API do stylizacji, dostosowania i rozszerzalności

Każdy zestaw SDK powinien zapewnić pewien poziom elastyczności do hostowania aplikacji w celu kontrolowania ogólnego stylu i rozszerzania schematu zgodnie z ich potrzebami.

Konfiguracja hosta

• TODO: Jakie powinny być wartości domyślne? Czy wszyscy powinni się tym podzielić? Czy należy osadzić wspólny plik hostConfig.json w plikach binarnych?

HostConfig jest obiektem konfiguracji udostępnionej, który określa sposób generowania interfejsu użytkownika przez moduł renderowania kart adaptacyjnych.

Dzięki temu właściwości, które są niezależne od platformy, mogą być współużytkowane przez programy renderujące na różnych platformach i urządzeniach. Umożliwia również tworzenie narzędzi, co daje pojęcie wyglądu i działania karty dla danego środowiska.

1. Programy renderowane MUSZĄ uwidaczniać parametr konfiguracji hosta w celu hostowania aplikacji
2. Wszystkie elementy MUSZĄ być stylowane zgodnie z ich odpowiednimi ustawieniami konfiguracji hosta

Natywna stylizacja platformy

1. Każdy typ elementu POWINIEN dołączyć natywny styl platformy z wygenerowanym elementem interfejsu użytkownika. Na przykład w kodzie HTML dodaliśmy klasę CSS do typów elementów, a w języku XAML przypisujemy określony styl.

Rozszerzalność

1. Program renderujący MUSI zezwalać aplikacjom hosta na zastępowanie domyślnych rendererów elementów. Na przykład zastąp TextBlock renderowanie własną logiką.
2. Silnik renderujący MUSI zezwalać aplikacjom hosta na rejestrowanie niestandardowych typów elementów. Na przykład dodaj obsługę elementu niestandardowego Rating
3. Renderer MUSI umożliwiać aplikacjom hosta usunięcie wsparcia dla elementu domyślnego. Na przykład usuń Action.Submit, jeśli nie chcą, aby była wspierana.

Zdarzenia

1. Renderer POWINIEN uruchamiać zdarzenie, gdy widoczność elementu uległa zmianie, umożliwiając aplikacji gospodarza przesunięcie karty na odpowiednią pozycję.