Adaptív kártya renderelő specifikációja

Az alábbi specifikáció bemutatja, hogyan implementálhat adaptív kártya renderelőt bármely natív felhasználói felületi platformon.

Fontos

Ez a tartalom egy folyamatban lévő munka, és előfordulhat, hogy hiányzik néhány részlet. Kérjük, tudassa velünk, ha kérdése vagy visszajelzése van.

JSON elemzése

Hibafeltételek

1. Az elemzőnek ellenőriznie kell , hogy az érvényes JSON-tartalom-e
2. Az elemzőnek ellenőriznie kell a sémát (a szükséges tulajdonságokat stb.)
3. A fenti hibákat jelenteni kell a gazdaalkalmazásnak (kivétel vagy azzal egyenértékű)

Ismeretlen típusok

1. Ismeretlen "típusok" észlelése esetén azokat EL KELL HAGYNI az eredményből.
2. A hasznos adatok módosításait (a fentiekhez hasonlóan) figyelmeztetésként kell jelenteni a gazdaalkalmazásnak

Ismeretlen tulajdonságok

1. Az elemzőnek további tulajdonságokat kell tartalmaznia az elemeken

További szempontok

1. A speakMAY tulajdonság SSML-korrektúrát tartalmaz, és a megadott módon kell visszaadni a gazdaalkalmazásnak

Gazdagép konfigurációjának elemzése

1. TEENDŐ

Verziókezelés

1. A renderelőnek implementálnia kell a séma egy adott verzióját.
2. A AdaptiveCard konstruktornak alapértelmezett értéket kell adnia a version tulajdonságnak az aktuális sémaverzió alapján
3. Ha egy renderelő a AdaptiveCard-ben talál egy version tulajdonságot, amely magasabb, mint a támogatott verzió, akkor köteles a fallbackText-t visszaadni.

Renderelés

Egy AdaptiveCard egy body-ből és egy actions-ből áll. A body egy CardElement gyűjtemény, amelyet a renderer sorrendben számba vesz és renderel.

1. Minden elemnek a szülőszélességig kell nyúlnia (gondoljon display: block HTML-ben).
2. A megjelenítőnek figyelmen kívül kell hagynia az ismeretlen elemtípusokat, és folytatnia kell az adatcsomag renderelését.

Text, TextBlock és RichTextBlock

1. A TextBlock-nak egyetlen sort kell felvennie, kivéve, ha a wrap tulajdonság true.
2. A szövegblokknak három ponttal kell levágnia a felesleges szövegeket (...)

Markdown

1. Az adaptív kártyák lehetővé teszik a Markdown egy részhalmazát, és támogatni kell a TextBlock.
2. A RichTextBlock NEM támogatja a Markdownt, és a közzétett tulajdonságok használatával kell stílust használnia.
3. Teljes markdown-követelmények megtekintése

Formázási függvények

1. TextBlock lehetővé teszi a DÁTUM/IDŐ formázási függvényeket , amelyeket minden renderelőn támogatni kell .
2. Minden hiba esetén meg kell jeleníteni a nyers sztringet a kártyán. Nem próbálkozott barátságos üzenettel. (A cél az, hogy a fejlesztő azonnal értesüljön arról, hogy probléma van)

Képek

1. A renderelőnek ajánlott lehetővé tenni, hogy a gazdaalkalmazások tudják, mikor töltötték le az összes HTTP-képet, és a kártya "teljesen megjelenített".
2. A renderelő köteles megvizsgálni a gazdagép konfiguráció maxImageSize paraméterét HTTP-képek letöltésekor
3. A renderelőnek támogatnia .png kell és .jpeg
4. A renderelőNEK támogatnia.gif kell a képeket

Speciális elrendezési viselkedés

A renderelőnek a következő viselkedésre kell ügyelnie a kártyaelemek renderelésekor a jelen dokumentumban említett attribútumok tekintetében.

A Korlátozásokat a megjelenítőnek kezelnie kell, figyelembe véve a kártyaelemek és azok alárendeltjei konfigurációját, mint például a margók, a párnázás, a magasság és a szélesség stb.

Szélesség

1. Engedélyezett értékek – auto, stretch és rögzített értékek a pixels és weight szempontjából.
2. auto elegendő helyet biztosít a szélesség bővítéséhez (támogatja a minimális bővítést)
3. stretch a fennmaradó szélességet veszi fel (támogatja a maximális bővítést)

Az alábbi forgatókönyvek azt ismertetik, hogyan érintik a kényszereket az oszlopok különböző szélességi kombinációi

auto és stretch

1. auto és stretch szélességű oszlopok.

• Az első szélességű auto oszlop elegendő helyet foglal a tartalom megjelenítéséhez, a második szélességű stretch oszlop pedig a teljes területet elfoglalja.

2. Csak stretch szélességű oszlopok

• Az csak stretch szélességű oszlopok egyenlő elosztás után foglalják el a fennmaradó területet.

3. auto,stretch és auto

Az első és a harmadik oszlopszélesség először az elemek megfelelő elhelyezésére van beállítva, a második pedig a feszített szélességű oszlop elfoglalja a fennmaradó helyet.

4. Az elemek szélességi oszlopokkal való megjelenítésének auto sorrendje

• Az olyan oszlopok, amelyek auto-vel rendelkeznek, automatikusan elegendő helyet biztosítanak a tartalom rendereléséhez.
• Képnézetek esetén a képek leskálázása a fennmaradó szélességhez igazodik.
• Jegyzet: A képek csak a stretch és auto képméreteknél lesznek leskálázva, de a képpontokban megadott rögzített szélesség és magasság esetén nem.

weights és pixels

1. weight és pixel szélességgel rendelkező oszlopok kombinációja.

• A fenti kártya három oszlopot tartalmaz a következő szélességű konfigurációval :
• \, \, \
• A 2. oszlop szélességét a pixel value
• Az 1. és a 3. oszlop szélessége a weights és a számított weight ratio alapján van beállítva.

2. Oszlopok weight, pixel width és auto attribútumokkal

• A fenti kártya négy oszlopot tartalmaz a következő szélességi konfigurációval :
• Column1: Weight 50, Column2: 100px, Column3: Weight 50és Column4: auto
• Megjegyzés: A képek nézete úgy csökkenti az oszlop szélességét, hogy az igazodjon a fennmaradó helyhez.

A szélességi attribútummal rendelkező elemek megjelenítési sorrendje

px > weight > auto > stretch

Magasság

Engedélyezett értékek – auto és stretch

Az alábbi forgatókönyvek azt írják le, hogy a kártyaelemek különböző magassági kombinációi hogyan befolyásolják a korlátozásokat

1. Az elemek függőlegesen szabadon tágulnak, ha a kártya nem rögzített magasságú.

• Mindkét oszlop elegendően függőlegesen terjeszthető, függetlenül a auto és stretch értékektől.
• Ez azzal történik, hogy a wrap szövegblokk tulajdonsága le van tiltva.

2. Az alábbi kártyán engedélyezve van a wrap tulajdonság a szövegblokkhoz.

Térköz és elválasztó

1. Minden spacing elem tulajdonsága befolyásolja az AKTUÁLIS elem és az ELŐTTE lévő elem közötti térközt.
2. A térközt CSAK akkor kell alkalmazni, ha valójában egy elem van előtte. (Például nem vonatkozik a tömb első elemére)
3. A renderelőnek meg kell keresnie az aktuális elemhez alkalmazott enum érték térközéből hostConfig használandó térközt.
4. Ha az elem separator értéke true, akkor látható vonalat kell rajzolni az aktuális elem és az előtte lévő elem között.
5. Az elválasztó vonalatcontainer.style.default.foregroundColor kell húzni.
6. Az elválasztó csak akkor rajzolható meg, ha az elem NEM az első a tömbben.
7. Térköz – Engedélyezett értékek none, small, default, largemediumés extra largepadding

• A térköz attribútum térközt ad az elem és az előző elem közé.

• A Térköz attribútumnak nincs hatása, ha ez a nézettároló első eleme.

• A nyíllal jelölt elemek a testvérek első elemei, így a térközöknek nincs hatása.

2. Elválasztó – Lehetséges értékek (be- és kikapcsolt kapcsoló)

• Egy elválasztó vonalat rajzol az elem tetején.

3. Térköz és elválasztó kombináció

• Az alábbiakban a térköz és a szeperátor kombináció korlátait szemléltetjük.

• A teljes térköz távolsága a megadott értékekhez képest megmarad.
• A szeparátor a távolság közepén, félúton kerül hozzáadásra.

[Megjegyzés. Meg kell erősíteni a távolságot, ahol a szeparátort a térköz területére beillesztik. Úgy tűnik, mintha a középső lenne.

Konténertípusok

• Stílustippeket biztosít tárolókhoz, például oszlopokhoz és oszlophalmazokhoz.
• Engedélyezett értékeknone, default, emphasis, good, attentionés warningaccent
• Ezek az előre definiált stílusbeállítások kitöltést biztosítanak a tárolóban lévő elemekhez és a háttérszínhez

1. Az A kártya stílusbeállítások nélkül szemlélteti az oszlopokat és oszlopkészleteket
2. A B kártya illusztrál egy oszlopkészletet a figyelem stílussal. Vegye észre az oszlopkészlet tartályának párnázását és a háttérszín változását.
3. A C kártya csak stílust tartalmazó oszlopokat ábrázol. Az előzőhöz hasonlóan az oszlop tartalmaz párnázást és háttérmódosítást is.
4. A D kártya stílusbeállításokkal szemlélteti az oszlopokat és az oszlopkészleteket.

[Megjegyzés. Meg kell vizsgálni, hogy a kitöltési érték hogyan van meghatározva. A gazdagép határozza ezt meg? ]

Vérzik

• Ez a tulajdonság lehetővé teszi, hogy a tároló, például az oszlopok és az oszlopkészlet kifutódjon a szülőn keresztül.
• Lehetséges értékek on és off.

1. Az A kártya normál stílussal szemlélteti az oszlopokat és az oszlopkészleteket.
2. A B kártya az első oszlopot kifutó beállítással szemlélteti. A tartalom átlépi a saját határait, és eléri a szülőjét.

Képméret

Size attribútum

• Engedélyezett értékek – auto, stretch, small, mediumlarge
• auto : A képek szükség esetén le lesznek kicsinyítve, de nem lesznek felnagyítva a terület kitöltéséhez.
• stretch : A képet szükség szerint kicsinyítheti vagy nagyíthatja, hogy illeszkedjen.
• small, medium és large: A kép fix szélességű, ahol a szélességet a gazdagép határozza meg.

1. auto és stretch

2. Oszlopszélesség és képméret kombinációja

• A stretch szélességű oszlopok általában lehetővé teszik, hogy a képek szabadon skálázhatók legyenek stretch mérettel.
• A auto szélességű oszlopok lehetővé teszik, hogy a kép pontos helyet foglaljon el függetlenül a méretétől auto és stretch.
• Az oszlopszélesség nagyobb elsőbbséget élvez a képméret meghatározásában ebben a elrendezésben.

Kép attribútum Width (in pixels)

• Ez biztosítja a kép kívánt képernyőszélességet.
• size tulajdonság felülírásra kerül, amikor értéket adnak meg

• Az auto szélességű oszlop előnyt élvez stretch-vel szemben a képtartalom elrendezésekor.

Oszlopszélesség (súly és képpont) és képméret (automatikus és nyújtás) kombináció

• Megfelelő méretű auto képek elegendő helyet foglalnak el a bővítéshez (vagy lekicsinyítéséhez) az oszlopkorlátokon belül weight és pixel szélesség esetén.
• A stretch méretű képek kibővülhetnek, hogy kitöltsék a fennmaradó területet az oszlop weight és pixel szélesség korlátain belül.

Fejlett elrendezés összefoglalása

• Az oszlopszélesség nagyobb elsőbbséget élvez a kép méretének meghatározásában, mint a kép mérete (automatikus, nyújtás, minimális szélesség stb.).
• A tartalom megfelelő megjelenítéséhez használt oszlopszélesség elsőbbsége - px>weight>auto>stretch
• size kép (automatikus, nyújtás) figyelmen kívül hagyásra kerül, ha width és height px-ben van megadva.
• A képméret stretch attribútum csak akkor skálázja fel a képet, ha van még hely, és az automatikus oszlop nemauto.
• A kép az oszlopban rendelkezésre álló térbeli méretarányt megtartó korlátig nyúlik. A magasság viszont szabadon bővül.
• Spacing az attribútumnak nincs hatása, ha ez az első vagy az egyetlen elem a testvére között.

Műveletek

1. Ha a HostConfig supportsInteractivity az false, a renderelő nem jeleníthet meg semmilyen műveletet.
2. A actions tulajdonságot gombként kell megjeleníteni valamilyen műveletsávban, általában a kártya alján.
3. Ha egy gombot megérintenek, KÖTELEZŐEN engedélyeznie kell, hogy a gazdaalkalmazás kezelje az eseményt.
4. Az eseménynek a művelettel együtt kell átadnia az összes társított tulajdonságot.
5. Az eseménynek végig kell haladnia a AdaptiveCard végrehajtott eseményen

Tevékenység	Magatartás
Action.OpenUrl	Külső URL-cím megnyitása megtekintésre
Action.ShowCard	A rendszer kéri, hogy egy alkártya jelenjen meg a felhasználó számára.
Művelet.Beküldés	Kérje meg, hogy az összes bemeneti elemet összegyűjtse egy objektumba, amelyet aztán a gazdaalkalmazás által meghatározott metódussal küld el Önnek.
Action.Execute	(Az 1.4-ben bevezetett) Kérje meg, hogy az összes bemeneti elemet összegyűjtse egy objektumba, amelyet aztán az "univerzális műveleti folyamaton" keresztül küld el Önnek.

Action.OpenUrl

1. Action.OpenUrl URL-címet kell megnyitnia a natív platform mechanizmusával
2. Ha ez nem lehetséges, eseményt kell létrehoznia a gazdagépalkalmazásnak az URL-cím megnyitásának kezeléséhez. Ennek az eseménynek engedélyeznie kell , hogy a gazdaalkalmazás felülbírálja az alapértelmezett viselkedést. Például nyissák meg az URL-címet a saját alkalmazásukon belül.

Action.ShowCard

1. Action.ShowCardA hostConfig beállítástól függően valamilyen módon támogatni kell. Két mód van: beágyazott és előugró. A beágyazott kártyák automatikusan váltják a kártya láthatóságát. Előugró módban egy eseményt kell aktiválni a gazdaalkalmazásba, hogy valamilyen módon megjelenítse a kártyát.

Művelet.Beküldés

• Action.Submit az elem összegyűjti a bemeneti mezőket, egyesül az opcionális adatmezővel, és eseményt küld az ügyfélnek.
• Az elem viselkedésében jelentős különbség van az ACL-megjelenítő 1.x és 2.x verziója között.

A Küldési művelet úgy működik, mint egy HTML-űrlap elküldése, azzal a különbséggel, hogy míg a HTML általában egy HTTP POST kérést indít el, az Adaptive Cards esetében a gazdagép alkalmazás határozza meg, mit jelent számukra a "küldés".

1. Ha ennek KÖTELEZŐ eseményt kiváltania, a felhasználó koppint a meghívott műveletre.
2. A data tulajdonságnak szerepelnie kell a visszahívás terhelésében.
3. Ehhez Action.Submita megjelenítőnek össze kell gyűjtenie a kártyán lévő összes bemenetet, és le kell kérnie az értékeit.

• 1.x Renderer - A bemenetek minden mezőből összegyűjthetők, függetlenül attól, hogy a hierarchiában hol található a bemeneti mező.
• 2.x Renderer - A bemenetek a szülőtárolóban található mezőkből vagy az Action.Submit elem testvéreként lesznek összegyűjtve.

Action.Execute (Részletek később)

Az Action.Execute az 1.4-es verzióban lett bevezetve. Az SDK-khoz egy későbbi időpontban nyújtunk megvalósítási útmutatót. Ha kérdése van ezzel a témával kapcsolatban, forduljon.

selectAction

1. Amennyiben a gazdagép konfiguráció supportedInteractivityfalse, akkor selectActionnem szabad megjelenítenie mint érinthető elemet.
2. Image, ColumnSetés Column felajánl egy tulajdonságot selectAction , amelyet a felhasználó meghívásakor végre kell hajtani, például az elemre koppintva.

Bemenetek

1. Ha a false HostConfig supportsInteractivity egy renderelő, nem jeleníthet meg semmilyen bemenetet.
2. A bemeneteknek a lehető legmagasabb hűséggel kell megjelennie. Egy felhasználónak például Input.Date ideális esetben dátumválasztót ajánlana, de ha ez nem lehetséges a felhasználói felületen, akkor a renderelőnek vissza kell esnie egy szabványos szövegdoboz megjelenítéséhez.
3. A renderelőnek lehetőség szerint meg kell jelenítenie a placeholderText
4. A bemeneti érték kötését megfelelően kell megszűkíteni
5. Az 1.3-s verzió előtt a renderelőnek NEM kell implementálnia a bemenet érvényesítését. Az adaptív kártyák felhasználóinak a végén érvényesíteniük kell a kapott adatokat.
6. A bemeneti címkék és az ellenőrzés az Adaptív Kártyák séma 1.3-ás verziójában lett bevezetve. A kapcsolódó címke, érvényesítési tippek és hibaüzenetek megjelenítéséhez különös figyelmet kell fordítani.

Stílus- és testreszabási és bővíthetőségi API-k

Minden SDK-nak bizonyos fokú rugalmasságot kell biztosítania a Gazdagépalkalmazások számára az általános stílus szabályozása és a séma megfelelőnek látszó kiterjesztése érdekében.

Gazdagép konfigurációja

• TEENDŐ: Mi legyen az alapértelmezett érték? Mindannyian megosszák? Be kell ágyaznunk egy közös hostConfig.json fájlt a bináris fájlokba?

HostConfig egy megosztott konfigurációs objektum, amely meghatározza, hogy az Adaptív Kártya renderelő hogyan hozza létre a felhasználói felületet.

Ez lehetővé teszi a platformfüggetlen tulajdonságok megosztását a különböző platformokon és eszközökön lévő renderelők között. Emellett lehetővé teszi az eszközök létrehozását is, amely képet ad arról, hogy a kártya milyen megjelenésű lenne egy adott környezetben.

1. A renderelőknek közzé kell tenniük egy gazdagép konfigurációs paramétert a gazdaalkalmazások számukra.
2. Minden elemet a megfelelő host konfigurációs beállításainak megfelelően MUST formázni.

Natív platformformázás

1. Minden elemtípusnak natív platformstílust kell csatolnia a létrehozott felhasználói felületi elemhez. A HTML-ben például hozzáadtunk egy CSS-osztályt az elemtípusokhoz, az XAML-ben pedig egy adott stílust rendelünk hozzá.

Bővíthetőség

1. A renderelőnek engedélyeznie kell, hogy a gazdagép-alkalmazások felülbírálhassák az alapértelmezett elemmegjelenítőket. Például saját logikájuk szerint cseréljék le a TextBlock renderelését.
2. A renderelőnek engedélyeznie kell, hogy a gazda alkalmazások egyéni elemtípusokat regisztráljanak. Például egy egyéni Rating elem támogatásának hozzáadása
3. A megjelenítőnek engedélyeznie kell , hogy a gazdagépalkalmazások eltávolítsák az alapértelmezett elem támogatását. Például távolítsa el Action.Submit , ha nem szeretné, hogy támogatott legyen.

Események

1. A megjelenítőnek eseményt kell aktiválnia, amikor egy elem láthatósága megváltozott, így a gazdaalkalmazás görgetheti a kártyát a pozícióba.