Specifikace rendereru adaptivních karet

Následující specifikace popisuje, jak implementovat renderer adaptivní karty na libovolné nativní platformě uživatelského rozhraní.

Důležité

Tento obsah probíhá a může chybět několik podrobností. Pokud máte nějaké dotazy nebo zpětnou vazbu, dejte nám prosím vědět .

Analýza JSON

Stavy chyb

1. Analyzátor musí zkontrolovat, jestli je platný obsah JSON.
2. Analyzátor musí ověřit schéma (požadované vlastnosti atd.)
3. Výše uvedené chyby musí být hlášeny hostitelské aplikaci (výjimka nebo ekvivalent).

Neznámé typy

1. Pokud jsou zjištěny neznámé "typy", musí být vyřazeny z výsledku.
2. Jakékoli změny datové části (například výše) by měly být nahlášeny jako varování hostitelské aplikaci.

Neznámé vlastnosti

1. Analyzátor musí obsahovat další vlastnosti prvků.

Další důležité informace

1. Vlastnost speakMŮŽE obsahovat kód SSML a musí být vrácena do hostitelské aplikace tak, jak je uvedeno.

Analýza konfigurace hostitele

1. TODO

Verzování

1. Renderer MUSÍ implementovat konkrétní verzi schématu.
2. Konstruktor AdaptiveCardMUSÍ dát version vlastnosti výchozí hodnotu na základě aktuální verze schématu.
3. Pokud renderer objeví version vlastnost ve AdaptiveCard, která je vyšší než podporovaná verze, musí místo toho vrátit fallbackText.

Renderování

Skládá se z AdaptiveCard a bodyactions. Jedná se body o kolekci CardElementobjektů, které vykreslovací modul vypíše a vykresluje v daném pořadí.

1. Každý prvek se musí roztáhnout na šířku nadřazeného objektu (myslete si display: block v HTML).
2. Renderer musí ignorovat všechny neznámé typy prvků, na které narazí, a pokračovat v vykreslování zbývající části datové části.

Text, TextBlock a RichTextBlock

1. TextBlock MUSÍ zabírat jeden řádek, pokud není wrap vlastnost true.
2. Blok textu BY MĚL oříznout veškerý nadbytečný text třemi tečkami (...)

Markdown

1. Adaptivní karty umožňují podmnožinu Markdownu a měly by být podporovány v TextBlock.
2. RichTextBlock nepodporuje Markdown a musí být stylován pomocí vlastností, které jsou vystaveny.
3. Zobrazení úplných požadavků na Markdown

Funkce formátování

1. TextBlock umožňuje formátování funkcí data a času , které musí být podporovány v každém rendereru.
2. VŠECHNA SELHÁNÍ MUSÍ zobrazit na kartě nezpracovaný řetězec. Nebyla pokusena žádná přátelská zpráva. (Cílem, aby vývojář okamžitě věděl, že došlo k problému)

Obrázky

1. Vykreslovací modul BY měl umožnit hostitelským aplikacím zjistit, kdy byly staženy všechny image HTTP a karta je "plně vykreslená".
2. Renderer musí při stahování imagí HTTP zkontrolovat parametry konfigurace maxImageSize hostitele.
3. Vykreslovací modul MUSÍ podporovat.png a .jpeg
4. Vykreslovací modul BY MĚL podporovat .gif obrázky

Pokročilé chování rozložení

Renderer musí při vykreslování prvků karty s ohledem na atributy uvedené v tomto dokumentu dbát na následující chování.

Vykreslovací modul by měl spravovat omezení s ohledem na různé faktory, jako jsou okraje, odsazení, výška a šířka atd. prvky karty a jeho podřízené položky.

Šířka

1. Povolené hodnoty – autostretch a pevné hodnoty z hlediska pixels aweight
2. auto poskytuje dostatečný prostor pro rozšíření šířky (podporuje minimální rozšíření).
3. stretch zabírá zbývající šířku (podporuje maximální rozšíření)

Níže uvedené scénáře popisují, jak jsou omezení ovlivněna různými kombinacemi šířky sloupců.

auto vs. stretch

1. Sloupce s šířkou auto a stretch.

• První sloupec s auto šířkou zabírá dostatek místa k zobrazení obsahu a druhý sloupec s stretch šířkou zabírá celé místo.

2. Sloupce s pouze stretch šířkou

• Sloupce, které mají pouze natáhnutou šířku, zabírají zbylý prostor po rovnoměrném rozdělení.

3. auto, stretch a auto

Šířka prvního a třetího sloupce se upraví tak, aby vyhovovala prvkům dostatečně a druhý sloupec s roztaženou šířkou zabírá zbývající prostor.

4. Pořadí zobrazení prvků se sloupci o šířce auto

• Sloupce s auto se umístí tak, aby zajistily dostatečný prostor pro vykreslení obsahu.
• V případě náhledů obrázků se obrázky zmenší, aby se vešly do zbývající šířky.
• Poznámka: Obrázky se zmenší pouze pro stretch a auto velikost obrázku, ale ne pro pevně danou šířku a výšku v pixelech.

weights vs. pixels

1. Sloupce s kombinací šířky weight a pixel

• Výše uvedená karta má tři sloupce s následující konfigurací šířky :
• Column1: Weight 50, Column2: 100px, Column3: Weight 50
• Šířka sloupce 2 je určena prvkem pixel value
• Šířka sloupce 1 a 3 se upraví na základě weights a vypočítaného weight ratio.

2. Sloupce s atributy weight, pixel width a auto

• Výše uvedená karta má čtyři sloupce s následující konfigurací šířky :
• Column1: Weight 50, Column2: 100px, Column3: Weight 50 a Column4: auto
• Poznámka: Zobrazení obrázku se snížením auto šířky sloupců, aby se přizpůsobilo zbývajícímu prostoru.

Pořadí priorit zobrazení prvků s atributem width

px > weight > auto > stretch

Výška

Povolené hodnoty – auto a stretch

Následující scénáře popisují, jak jsou omezení ovlivněna různými kombinacemi výšky pro prvky karty.

1. Prvky se volně zvětšují svisle, pokud karta nemá pevné výšky

• Oba sloupce mohou být dostatečně svisle rozbalené bez ohledu na hodnotách auto a stretch.
• V tomto je vlastnost wrap u blok textu deaktivována.

2. Karta níže má pro blok textu povolenou wrap vlastnost.

Mezery a oddělovače

1. Vlastnost spacing u každého prvku ovlivňuje velikost mezery mezi prvkem CURRENT a jednou PŘED ním.
2. Mezery se mohou aplikovat pouze tehdy, když před nimi skutečně existuje prvek. (Např. nebude platit pro první položku v poli)
3. Vykreslovací modul musí vyhledat množství prostoru, které se má použít z hostConfig odsazení pro hodnotu výčtu přiřazenou aktuálnímu prvku.
4. Pokud má prvek separator hodnotu true, musí být viditelná čára nakreslena mezi aktuálním prvkem a čárou před ním.
5. Oddělovač musí být nakreslen pomocí container.style.default.foregroundColor.
6. Oddělovač musí být nakreslen pouze v případě, že položka NENÍ první v matici.
7. Mezery - Povolené hodnoty none, small, default, medium, , large, extra large a padding

• Atribut Mezery přidává mezery mezi tímto elementem a předchozím prvkem.

• Atribut mezer nemá žádný vliv, pokud se jedná o první prvek v kontejneru view.

• Prvky označené šipkou jsou první mezi svými sourozenci, takže na jejich rozvržení nemají mezery žádný vliv.

2. Oddělovač – možné hodnoty (přepínač zapnuto/vypnuto)

• Nakreslí oddělovací čáru v horní části prvku.

3. Kombinace mezer a seperátoru

• Omezení mezer a kombinace seperátoru jsou znázorněna níže.

• Celková vzdálenost mezer je zachována s ohledem na zadané hodnoty.
• Separátor se přidá v polovině uprostřed vymezené vzdálenosti.

[Poznámka: Je potřeba potvrdit vzdálenost, na které je umístěn separátor v prostoru mezer. Připadá jako by to byl střed.]

Styly kontejnerů

• Poskytuje tipy pro styly pro kontejnery, jako jsou sloupce a sada sloupců.
• Povolené hodnoty none, default, emphasis, good, attention, warning a accent
• Tyto předdefinované možnosti stylu poskytují odsazení pro prvky v kontejneru a barvu pozadí.

1. Karta A znázorňuje sloupce a sadu sloupců bez možností stylu.
2. Karta B znázorňuje soubor sloupců se stylem Pozornost. Všimněte si odsazení v kontejneru sloupců a změny barvy pozadí.
3. Karta C znázorňuje sloupce s pouhým stylováním. Podobně jako v předchozím sloupci se změní odsazení a pozadí.
4. Karta D znázorňuje sloupce i sadu sloupců s možnostmi stylu.

[Poznámka: Je potřeba zkontrolovat, jak se určuje velikost odsazení. Určuje hostitel? ]

Krvácet

• Tato vlastnost umožňuje kontejneru, jako jsou sloupce a sada sloupců, přesahovat přes nadřazený objekt.
• Možné hodnoty on a off.

1. Karta A znázorňuje sloupce a sadu sloupců se standardní úpravou.
2. Karta B znázorňuje první sloupec s možností přesahu. Obsah právě přesahuje jeho hranice do nadřazeného objektu.

Velikost obrázku

atribut Size

• Povolené hodnoty - auto, stretch, small, medium, large
• auto : Obrázky se v případě potřeby zmenší tak, aby se vešly, ale nezvětší se tak, aby vyplnily oblast.
• stretch : Obrázek s možností zmenšit i zvětšit velikost podle potřeby.
• small medium a large: Obrázek se zobrazí s pevnou šířkou, kde je šířka určena hostitelem.

1. auto vs. stretch

2. Kombinace šířky sloupce a velikosti obrázku

• Obecně platí, že sloupce s stretch šířkou umožňují volně škálovat obrázky s velikostí stretch .
• Sloupce o šířce auto umožňují, aby obrázek zabíral přesný prostor bez ohledu na auto a stretch velikost obrázku.
• Šířka sloupce má větší prioritu při určování velikosti obrázku v tomto uspořádání.

Atribut Image Width (in pixels)

• To poskytuje požadovanou šířku obrázku na obrazovce.
• size vlastnost je přepsána po zadání hodnoty

• Sloupec s auto šířkou bude mít větší prioritu než stretch při poskytování místa pro obsah obrázků v tomto uspořádání.

Šířka sloupce (váha a pixel) a velikost obrázku (automatická a roztažená) Kombinace

• Obrázky s auto velikostí mají dostatek místa pro rozšíření (nebo zmenšení) v rámci omezení šířky sloupců weight a pixel.
• Obrázky s stretch velikostí se můžou rozšířit a vyplnit zbývající místo v rámci omezení sloupce weight a pixel šířky.

Souhrn rozšířeného rozložení

• Šířka sloupce má větší přednost při určování velikosti obrázku než jeho velikost (automaticky, roztažení, minimální šířka atd.).
• Priorita šířky sloupce pořízená k dostatečnému zobrazení jeho obsahu - px>weight>auto>stretch
• Při zadání obrázku width a height v px je obrázek size (automaticky, roztažení) ignorován.
• Atribut velikostí obrázku stretch zvýší měřítko obrázku pouze v případech, kdy zbývá místo a sloupec automaticky neníauto.
• Obrázek se roztáhne na limit, kde udržuje poměr stran v prostoru dostupném ve sloupci. Výška se postupně volně rozšiřuje.
• Spacing atribut nebude mít žádný vliv, pokud je prvním nebo jediným prvkem mezi prvky na stejné úrovni.

Akce

1. Pokud je supportsInteractivityHostConfigfalse, vykreslovací modul NESMÍ vykreslit žádné akce.
2. Vlastnost actionsmusí být vykreslena jako tlačítka v nějakém druhu panelu akcí, obvykle v dolní části karty.
3. Když na tlačítko klepnete , musí hostitelská aplikace povolit zpracování události.
4. Událost musí předat všechny přidružené vlastnosti k akci.
5. Událost musí projít AdaptiveCard , která byla provedena.

Činnost	Chování
Action.OpenUrl	Otevření externí adresy URL pro zobrazení
Action.ShowCard	Požádá o zobrazení dílčí karty uživateli.
`Action.Odeslat`	Požádejte, aby se všechny vstupní prvky shromáždily do objektu, který se pak odešle prostřednictvím některé metody definované hostitelskou aplikací.
Action.Execute	(Představeno ve verzi 1.4) Vyžádejte si shromáždění všech vstupních prvků do objektu, který je pak odeslán prostřednictvím univerzální akční pipeline.

Action.OpenUrl

1. Action.OpenUrl MĚLA by otevřít adresu URL pomocí mechanismu nativní platformy.
2. Pokud to není možné, musí v hostitelské aplikaci vyvolat událost pro zpracování otevření adresy URL. Tato událost musí umožnit hostitelské aplikaci přepsat výchozí chování. Například jim umožníte otevřít adresu URL v rámci své vlastní aplikace.

Action.ShowCard

1. Action.ShowCard Na základě nastavení hostConfig musí být podporována nějakým způsobem. Existují dva režimy: inline a popup. Vložené karty BY MĚLY automaticky přepínat viditelnost karty. V režimu automatického otevírání by se měla událost spustit v hostitelské aplikaci, aby se karta nějakým způsobem zobrazila.

Akce.Odeslat

• Action.Submit Element shromažďuje vstupní pole, slučuje s volitelným datovým polem a odesílá událost klientovi.
• Významný rozdíl v chování prvku je patrný mezi verzemi 1.x a 2.x rendereru ACL.

Akce odeslání se chová jako odeslání formuláře HTML s tím rozdílem, že zatímco HTML obvykle spouští HTTP post, Adaptive Cards ponechává na každé hostitelské aplikaci, aby určila, co pro ně "odeslat" znamená.

1. Když to musí vyvolat událost, uživatel klepne na vyvolánou akci.
2. Vlastnost datamusí být obsažena v datové části zpětného volání.
3. V případě Action.Submitvykreslovacího modulu musí shromáždit všechny vstupy na kartě a načíst jejich hodnoty.

• 1.x Renderer – Vstupy se shromažďují ze všech polí bez ohledu na to, kde je vstupní pole v hierarchii přítomno.
• 2.x Renderer – Vstupy se shromažďují z polí, která jsou přítomna v nadřazeném kontejneru, nebo jako sousední prvek Action.Submit.

Action.Execute (podrobnosti přicházejí později)

Action.Execute byl zaveden ve verzi 1.4. Pokyny k implementaci sad SDK poskytneme později. Pokud máte dotazy k tomuto tématu, prosím obraťte se na nás.

vybratAkce

1. Pokud je supportedInteractivity konfigurace hostitele false, potom selectActionnesmí být vykreslena jako dotykový cíl.
2. Image, ColumnSet, a Column nabízejí vlastnost selectAction, která by měla být spuštěna, když ji uživatel vyvolá, například klepnutím na prvek.

Vstupy

1. Pokud je HostConfig supportsInteractivity, false Renderer NESMÍ vykreslit žádné vstupy.
2. Vstupy BY MĚLY vykreslit s nejvyšší možnou věrností. Například Input.Date by v ideálním případě nabízel uživateli výběr data, ale pokud to v rámci vaší platformy uživatelského rozhraní není možné, pak se musí vykreslovací modul vrátit k vykreslení standardního textového pole.
3. Vykreslovací modul BY měl zobrazit placeholderText , pokud je to možné
4. Vstupní vazba hodnoty musí být správně escapeovaná.
5. Před verzí 1.3 nemusí renderer implementovat ověření vstupu. Uživatelé adaptivních karet musí naplánovat ověření všech přijatých dat na jejich konci.
6. Vstupní popisky a ověřování byly zavedeny ve schématu adaptivních karet verze 1.3. Je třeba věnovat zvláštní pozornost tomu, jak jsou vykresleny přidružený popisek, nápovědy k ověření a chybové zprávy.

Rozhraní API pro styling, přizpůsobení a rozšiřitelnost

Každá sada SDK by měla poskytovat určitou úroveň flexibilty pro hostování aplikací, aby mohla řídit celkový styl a rozšířit schéma podle potřeby.

Konfigurace hostitele

• ÚKOL: Jaká by měla být výchozí nastavení? Měli by to všichni sdílet? Měli bychom do binárních souborů vložit společný hostConfig.json soubor?

HostConfig je sdílený objekt konfigurace, který určuje, jak renderer adaptivní karty generuje uživatelské rozhraní.

To umožňuje sdílení vlastností, které jsou nezávislé na platformě mezi renderery na různých platformách a zařízeních. Umožňuje také vytvářet nástroje, které vám dávají představu o vzhledu a chování karty pro dané prostředí.

1. Renderery musí vystavit parametr Konfigurace hostitele pro hostitelské aplikace.
2. Všechny prvky musí být stylovány podle příslušných nastavení konfigurace hostitele.

Styly nativní platformy

1. Každý typ elementu BY měl připojit nativní styl platformy s vygenerovaným prvkem uživatelského rozhraní. Například v HTML jsme přidali třídu CSS k typům elementů a v XAML přiřadíme určitý styl.

Rozšiřitelnost

1. Vykreslovač musí povolit hostitelským aplikacím přepsat výchozí vykreslovače prvků. Například při nahrazování vykreslování TextBlock použijte vlastní logiku.
2. Vykreslovací modul musí povolit hostitelským aplikacím registrovat vlastní typy elementů. Například přidání podpory vlastního Rating elementu
3. Vykreslovací modul musí povolit, aby hostitelské aplikace odebraly podporu výchozího prvku. Například pokud si nepřejí, aby to bylo podporováno, odeberte Action.Submit.

Události

1. Renderer BY měl aktivovat událost, když se změnila viditelnost prvku, což hostitelské aplikaci umožňuje posunout kartu na pozici.