Spezifikation eines Renderers für adaptive Karten

Die folgende Spezifikation beschreibt die Implementierung eines Renderers für adaptive Karten auf einer beliebigen nativen Benutzeroberflächenplattform.

Wichtig

Dieser Inhalt ist noch in Bearbeitung, und möglicherweise fehlen noch einige Details. Mit Fragen oder Feedback können Sie sich gerne an uns wenden.

Analysieren von JSON

Fehlerbedingungen

1. Ein Parser MUSS prüfen, ob es sich um gültigen JSON-Inhalt handelt.
2. Ein Parser MUSS eine Überprüfung anhand des Schemas (erforderliche Eigenschaften usw.) ausführen.
3. Die oben genannten Fehler MÜSSEN der Host-App gemeldet werden (als Ausnahme oder eine entsprechende Angabe).

Unbekannte Typen

1. Wenn unbekannte „Typen“ ermittelt werden, MÜSSEN DIESE AUS DEM ERGEBNIS GELÖSCHT werden.
2. Alle Änderungen der Nutzlast (wie oben) SOLLTEN der Host-App als Warnungen gemeldet werden.

Unbekannte Eigenschaften

1. Ein Parser MUSSzusätzliche Eigenschaften in Elementen einschließen.

Weitere Überlegungen

1. Die Eigenschaft speakKANN SSML-Markup enthalten und MUSS wie angegeben an die Host-App zurückgegeben werden.

Analyse der Hostkonfiguration

1. TODO

Versionsverwaltung

1. Ein Renderer MUSS eine bestimmte Version des Schemas implementieren.
2. Der AdaptiveCard-Konstruktor MUSS der Eigenschaft version einen Standardwert basierend auf der aktuellen Schemaversion zuweisen.
3. Wenn ein Renderer eine version-Eigenschaft in einer AdaptiveCard findet, die höher ist als die unterstützte Version, MUSS er stattdessen den fallbackText zurückgeben.

Darstellung

Eine AdaptiveCard besteht aus einem body- und einem actions-Element. Der body ist eine Sammlung von CardElement-Elementen, die von einem Renderer enumeriert und in der entsprechenden Reihenfolge gerendert werden.

1. Jedes Element MUSS auf die Breite des übergeordneten Elements gestreckt werden (ähnlich wie bei display: block in HTML).
2. Ein Renderer MUSS alle unbekannten Elementtypen, auf die er trifft, ignorieren und mit dem Rest der Nutzlast fortfahren.

Text, TextBlock und RichTextBlock

1. Ein TextBlock MUSS eine einzelne Zeile aufnehmen, sofern die wrap-Eigenschaft nicht true lautet.
2. Der Textblock SOLLTE überschüssigen Text abschneiden und Auslassungspunkte (...) anzeigen.

Markdown

1. Adaptive Karten lassen eine Teilmenge von Markdown zu und SOLLTEN in TextBlock unterstützt werden.
2. RichTextBlock unterstützt Markdown NICHT und muss mithilfe der verfügbar gemachten Eigenschaften formatiert werden.
3. Weitere Informationen findest du unter Markdownanforderungen.

Formatierungsfunktionen

1. TextBlock ermöglicht Formatierungsfunktionen für DATUM und UHRZEIT, die in jedem Renderer unterstützt werden MÜSSEN.
2. BEI ALLEN FEHLERN MUSS die unformatierte Zeichenfolge auf der Karte angezeigt werden. Es wird keine benutzerfreundliche Meldung angezeigt. (Ziel hierbei ist es, den Entwickler sofort darauf aufmerksam zu machen, dass ein Problem vorliegt).

Bilder

1. Ein Renderer SOLLTE Host-Apps informieren, wenn alle HTTP-Bilder heruntergeladen wurden und die Karte „vollständig gerendert“ ist.
2. Ein Renderer MUSS beim Herunterladen von HTTP-Bildern den Hostkonfigurationsparameter maxImageSize überprüfen.
3. Ein Renderer MUSS.png und .jpeg unterstützen.
4. Ein Renderer SOLLTE.gif-Bilder unterstützen.

Erweitertes Layoutverhalten

Der Renderer MUSS beim Rendern von Kartenelementen hinsichtlich der in diesem Dokument erwähnten Attribute die folgenden Verhaltensweisen berücksichtigen.

Der Renderer sollte Einschränkungen verwalten und dabei die verschiedenen Faktoren berücksichtigen wie Rand, Abstand, Höhe und Breite usw. sowie die Konfiguration der Kartenelemente und ihrer untergeordneten Elemente.

Breite

1. Zulässige Werte: auto, stretch und feste Werte in Bezug auf pixels und weight
2. auto bietet ausreichend Platz für die Ausdehnung der Breite (unterstützt minimale Ausdehnung )
3. stretch nimmt die verbleibende Breite in Anspruch (unterstützt die maximale Ausdehnung )

In den folgenden Szenarien wird beschrieben, wie sich unterschiedliche Breitenkombinationen für Spalten auf die Einschränkungen auswirken.

auto vs stretch

1. Spalten mit einer auto- und stretch-Breite.

• Die erste Spalte mit auto-Breite verwendet ausreichend Platz, um den Inhalt anzuzeigen, und die zweite Spalte mit stretch-Breite nimmt den gesamte Platz ein.

2. Spalten mit nur stretch-Breite

• Spalten mit nur „stretch“-Breite nehmen den verbleibenden Platz ein, nachdem sie den Platz gleichmäßig untereinander aufgeteilt haben.

3. auto, stretch und auto

Die Breite der ersten und dritten Spalte wird zuerst so angepasst, dass die Elemente ausreichend aufgenommen werden, und die zweite Spalte mit „stretch“-Breite beansprucht den verbleibenden Platz.

4. Reihenfolge der Anzeige von Elementen mit Spalten mit auto-Breite

• Spalten mit auto-Breite positionieren sich selbst so, dass ausreichend Platz vorhanden ist, um den zu rendernden Inhalt aufzunehmen.
• Im Falle von Bildansichten werden Bilder so herunterskaliert, dass sie in die verbleibende Breite passen.
• Hinweis: Bilder werden nur für die Bildgrößen stretch und auto herunterskaliert, aber nicht für feste Breiten und Höhen in Pixel.

weights vs pixels

1. Spalten mit Kombination aus weight- und pixel-Breite

• Die obige Karte enthält drei Spalten mit der folgenden Breitenkonfiguration:
• Column1: Weight 50, Column2: 100px, Column3: Weight 50
• Die Breite von Spalte 2 wird vom pixel value bestimmt.
• Die Breite von Spalte 1 und 3 wird auf Grundlage von weights und der berechneten weight ratio angepasst.

2. Spalten mit den Attributen weight, pixel width und auto

• Die obige Karte enthält vier Spalten mit der folgenden Breitenkonfiguration:
• Column1: Weight 50, Column2: 100px, Column3: Weight 50 und Column4: auto
• Hinweis: Eine Bildansicht mit einer Spalte mit auto-Breite wird so herunterskaliert, dass sie in den verbleibenden Platz passt.

Die Rangfolge der Anzeige von Elementen mit „width“-Attribut

px > weight > auto > stretch

Höhe

Zulässige Werte: auto und stretch

In den folgenden Szenarien wird beschrieben, wie sich unterschiedliche Breitenkombinationen für Spalten auf die Einschränkungen auswirken.

1. Elemente dehnen sich vertikal frei aus, wenn die Karte keine feste Höhe hat.

• Beide Spalten können sich unabhängig von auto- und stretch-Werten ausreichend vertikal ausdehnen.
• Dies ist der Fall bei für den Textblock deaktivierter Eigenschaft wrap.

2. Bei der folgenden Karte ist für den Textblock die Eigenschaft wrap aktiviert.

Abstände und Trennzeichen

1. Die spacing-Eigenschaft jedes Elements wirkt sich darauf aus, wie viel Abstand zwischen dem AKTUELLEN Element und dem Element DAVOR vorhanden ist.
2. Ein Abstand DARF NUR DANN angewendet werden, wenn vor dem Element tatsächlich ein anderes Element vorhanden ist. (Diese Eigenschaft gilt also nicht für das erste Element in einem Array).
3. Ein Renderer MUSS den zu verwendenden Abstand aus hostConfig für den Enumerationswert ablesen, der auf das aktuelle Element angewendet wird.
4. Wenn das Element den separator-Wert true aufweist, MUSS eine sichtbare Linie zwischen dem aktuellen Element und dem Element davor gezeichnet werden.
5. Die Trennlinie MUSS mithilfe der Eigenschaft container.style.default.foregroundColor gezeichnet werden.
6. Eine Trennlinie DARF NUR gezeichnet werden, wenn das Element NICHT das erste Element im Array ist.
7. Spacing (Abstände): Zulässige Werte: none, small, default, medium, large, extra large und padding

• Das Attribut „spacing“ fügt Abstand zwischen diesem Element und dem vorangehenden Element hinzu.

• Das Attribut „spacing“ hat keine Auswirkung, wenn es das erste Element im Ansichtscontainer ist.

• Die mit einem Pfeil markierten Elemente sind die ersten Elemente unter ihren nebengeordneten Elementen, sodass „spacing“ keine Auswirkung hat.

2. Separator (Trennzeichen): Mögliche Werte: Ein-/Aus-Umschalter

• Zeichnet eine Trennlinie am oberen Rand des Elements.

3. Kombination aus „spacing“ und „separator“

• Die Einschränkungen der Kombination aus „spacing“ und „separator“ sind unten dargestellt.

• Der Gesamtabstand wird in Bezug auf die angegebenen Werte beibehalten.
• Das Trennzeichen wird in der Mitte der Abstandsentfernung hinzugefügt.

[Hinweis: Der Abstand, bei dem das Trennzeichen in den Abstandsbereich eingefügt wird, muss bestätigt werden. Scheint die Mitte zu sein.]

Containerstile

• Stellt Formatierungshinweise für Container wie Spalten und Spaltensätze (ColumnSet) bereit.
• Zulässige Werte: none, default, emphasis, good, attention, warning und accent
• Diese vordefinierten Stiloptionen bieten Abstand für die Elemente innerhalb des Containers und die Hintergrundfarbe.

1. Karte A veranschaulicht „columns“ und „columnset“ ohne Stiloptionen
2. Karte B veranschaulicht „columnset“ mit dem Attention-Stil (Achtung). Beachten Sie den Abstand innerhalb des „columnset“-Containers und die Änderung der Hintergrundfarbe.
3. Karte C veranschaulicht nur „columns“ mit Formatierung. Ähnlich wie im vorherigen Beispiel beinhaltet „columns“ Abstand und Änderung des Hintergrunds.
4. Karte D veranschaulicht „columns“ und „columnset“, beide mit Stiloptionen.

[Hinweis: Die Methode zur Bestimmung des Abstands muss überprüft werden. Wird er vom Host bestimmt? ]

Bleed (Anschnitt)

• Diese Eigenschaft ermöglicht es einem Container wie „columns“ und „columnset“, in sein übergeordnetes Element überzugehen.
• Mögliche Werte: on und off.

1. Karte A veranschaulicht „columns“ und „columnset“ mit normaler Formatierung.
2. Karte B veranschaulicht die erste Spalte mit Option „bleed“. Der Inhalt schneidet so gerade die Ränder zu seinem übergeordneten Element an.

Abbildgröße

Size-Attribut

• Zulässige Werte: auto, stretch, small, medium, large
• auto: Bilder werden nach Bedarf passend herunterskaliert, aber nicht hochskaliert, um den Bereich auszufüllen.
• stretch: Bild, das nach Bedarf passend sowohl herunter- als auch hochskaliert wird.
• small, medium und large: Das Bild wird mit fester Breite angezeigt, wobei die Breite vom Host bestimmt wird.

1. auto vs stretch

2. Kombination aus Spaltenbreite und Bildgröße

• Im Allgemeinen ermöglichen Spalten mit stretch-Breite Bildern das freie Skalieren gemäß der stretch-Größe.
• Spalten mit auto-Breite gestatten es dem Bild, einen exakten Raum einzunehmen, unabhängig von der auto- und stretch-Größe des Bilds.
• Die Spaltenbreite hat Vorrang bei der Bestimmung der Bildgröße in dieser Anordnung.

Bildattribut Width (in pixels)

• Dieses bietet die gewünschte Breite des Bilds auf dem Bildschirm.
• Die size-Eigenschaft wird außer Kraft gesetzt, wenn ein Wert angegeben wird.

• Die Spalte mit auto-Breite hat Vorrang vor stretch bei der Bereitstellung von Raum für Bildinhalte in dieser Anordnung.

Kombination aus Spaltenbreite („weight“ und „pixel“) und Bildgröße („auto“ und „stretch“)

• Bilder mit auto-Größe nehmen ausreichend Platz zum Ausdehnen (oder für eine Herunterskalierung) ein, innerhalb der Spalteneinschränkungen durch die Breiten weight und pixel.
• Bilder mit der stretch-Größe können so ausgedehnt werden, dass sie den verbleibenden Platz einnehmen, innerhalb der Einschränkungen durch die Spaltenbreiten weight und pixel.

Erweitertes Layout – Zusammenfassung

• Die Spaltenbreite hat Vorrang bei der Bestimmung der Größe des Bilds als seine Bildgröße („auto“, „stretch“, „min width“ usw).
• Die Rangfolge der Spaltenbreite, die zur ausreichenden Anzeige des Inhalts verwendet wird: px>weight>auto>stretch
• Bild-size („auto“, „stretch“) wird ignoriert, wenn Bild-width und -height in Pixel (px) bereitgestellt werden.
• Das Größenattribut stretch des Bilds führt nur dann zu einer Hochskalierung des Bilds, wenn noch Platz übrig ist und „auto“ der Spalte nicht den Wert auto hat.
• Ein Bild dehnt sich selbständig bis zu der Grenze aus, bei der es sein Seitenverhältnis in dem in der Spalte verfügbaren Raum beibehält. Die Höhe wiederum wird frei ausgedehnt.
• Das Attribut Spacing hat keine Auswirkung, wenn es das erste oder einzige Element unter seinen nebengeordneten Elementen ist.

Aktionen

1. Ein Renderer DARF KEINE Aktionen rendern, wenn das supportsInteractivity-Element in der HostConfig false ist.
2. Die actions-Eigenschaft MUSS als Schaltflächen auf einer Form von Aktionsleiste gerendert werden, üblicherweise am unteren Rand der Karte.
3. Wenn eine Schaltfläche aktiviert wird, MUSS die Host-App das Ereignis verarbeiten können.
4. Das Ereignis MUSS alle zugeordneten Eigenschaften mit der Aktion übergeben.
5. Das Ereignis MUSS die ausgeführte AdaptiveCard übergeben.

Aktion	Verhalten
Action.OpenUrl	Öffnet eine externe URL zur Anzeige.
Action.ShowCard	Fordert eine untergeordnete Karte an, die dem Benutzer angezeigt werden soll.
Action.Submit	Fordert an, dass alle Eingabeelemente in einem Objekt zusammengefasst werden, das dir anschließend über eine von der Hostanwendung definierte Methode gesendet wird.
Action.Execute	(In v1.4 eingeführt) Fordert an, dass alle Eingabeelemente in einem Objekt zusammengefasst werden, das anschließend über die „universelle Aktionspipeline“ an Sie gesendet wird.

Action.OpenUrl

1. Action.OpenUrlSOLLTE eine URL mithilfe des nativen Plattformmechanismus öffnen.
2. Wenn dies nicht möglich ist, MUSS die Aktion ein Ereignis auslösen, damit die Host-App das Öffnen der URL verarbeitet. Dieses Ereignis MUSS es der Host-App ermöglichen, das Standardverhalten zu überschreiben, beispielsweise durch Öffnen der URL innerhalb der eigenen App.

Action.ShowCard

1. Action.ShowCardMUSS auf irgendeine Weise unterstützt werden, basierend auf der HostConfig-Einstellung. Es gibt zwei Modi: Inline und Popup. Inlinekarten SOLLTEN die Sichtbarkeit der Karte automatisch umschalten. Im Popupmodus SOLLTE ein Ereignis ausgelöst werden, damit die Host-App die Karte auf irgendeine Weise anzeigt.

Action.Submit

• Das Action.Submit-Element sammelt Eingabefelder, führt diese mit einem optionalen Datenfeld zusammen und sendet ein Ereignis an den Client.
• Ein signifikanter Unterschied beim Verhalten des Elements zeigt sich zwischen Version 1.x und 2.x des ACL-Renderers.

Die Submit-Aktion verhält sich wie eine Übermittlungsaktion in einem HTML-Formular, mit einer Ausnahme: In HTML wird typischerweise eine HTTP-POST-Aktion ausgelöst, bei adaptiven Karten dagegen bleibt der Host-App die Entscheidung überlassen, wie „submit“ zu interpretieren ist.

1. Wenn ein Ereignis ausgelöst werden MUSS, tippt der Benutzer auf die aufgerufene Aktion.
2. Die data-Eigenschaft MUSS in der Rückrufnutzlast enthalten sein.
3. Bei Action.SubmitMUSS ein Renderer alle Eingaben auf der Karte erfassen und die zugehörigen Werte abrufen.

• 1.x Renderer: Die Eingaben werden aus allen Feldern gesammelt, unabhängig davon, wo in der Hierarchie sich das Eingabefeld befindet.
• 2.x Renderer: Die Eingaben werden aus Feldern gesammelt, die im übergeordneten Container oder als nebengeordnetes Element des Action.Submit-Elements vorhanden sind.

Action.Execute (Details folgen später)

Action.Execute wurde in Version 1.4 eingeführt. Wir werden Anweisungen zur Implementierung von SDKs zu einem späteren Zeitpunkt zur Verfügung stellen. Bitte setzen Sie sich mit uns in Verbindung, wenn Sie Fragen zu diesem Thema haben.

selectAction

1. Eine selectActionDARF NICHT als Berührungsziel gerendert werden, wenn das supportedInteractivity-Element der Hostkonfiguration false ist.
2. Image, ColumnSet und Column bieten eine selectAction-Eigenschaft, die ausgeführt werden SOLLTE, wenn sie von einem Benutzer z. B. durch Tippen auf das Element aufgerufen wird.

Eingaben

1. Ein Renderer DARF KEINE Eingaben rendern, wenn das supportsInteractivity-Element der HostConfig false ist.
2. Eingaben SOLLTEN mit der höchstmöglichen Genauigkeit gerendert werden. Ein Input.Date-Element beispielsweise sollte dem Benutzer idealerweise eine Datumsauswahl bieten. Wenn dies jedoch in deinem UI-Stapel nicht möglich ist, MUSS der Renderer ein Standardtextfeld rendern.
3. Ein Renderer SOLLTE nach Möglichkeit placeholderText anzeigen.
4. Die Bindung von Eingabewerten MUSS ordnungsgemäß mit Escapezeichen versehen werden.
5. Vor v1.3 muss ein Renderer KEINE Überprüfung der Eingabe implementieren. Benutzer von adaptiven Karten müssen die Überprüfung empfangener Daten auf ihrer Seite selbst planen.
6. Eingabebezeichnungen und Überprüfung wurden in v1.3 des Schemas für adaptive Karten eingeführt. Beim Rendern der zugeordneten Bezeichnung, der Überprüfungshinweise und der Fehlermeldungen muss besonders sorgfältig vorgegangen werden.

Formatierungs-, Anpassungs- und Erweiterungs-APIs

Jedes SDK sollte ein gewisses Maß an Flexibilität zum Hosten von Apps bieten, um die Formatierung im Allgemeinen zu steuern und das Schema nach Bedarf zu erweitern.

Hostkonfiguration

• TODO: Wie sollten die Standardwerte lauten? Sollten diese überall freigegeben werden? Sollten wir eine gemeinsame hostConfig.json-Datei in den Binärdateien einbetten?

HostConfig ist ein gemeinsam genutztes Konfigurationsobjekt, das angibt, wie ein Renderer für adaptive Karten eine Benutzeroberfläche generiert.

So können plattformunabhängige Eigenschaften für Renderer auf verschiedenen Plattformen und Geräten freigegeben werden. Zudem können Tools erstellt werden, die dir eine Vorstellung vom Aussehen und Verhalten einer Karte in einer bestimmten Umgebung vermitteln.

1. Renderer MÜSSEN einen HostConfig-Parameter für Host-Apps verfügbar machen.
2. Alle Elemente MÜSSEN entsprechend ihren jeweiligen HostConfig-Einstellungen formatiert werden.

Native Plattformformatierung

1. Jeder Elementtyp SOLLTE eine native Plattformformatierung mit dem generierten Benutzeroberflächenelement anfügen. In HTML haben wir beispielsweise eine CSS-Klasse zu den Elementtypen hinzugefügt, und in XAML weisen wir einen bestimmten Stil zu.

Erweiterungen

1. Ein Renderer MUSS es Host-Apps ermöglichen, standardmäßige Elementrenderer zu überschreiben. Beispiel: Ersetzen des Renderns von TextBlock durch eigene Logik.
2. Ein Renderer MUSS es Host-Apps ermöglichen, benutzerdefinierte Elementtypen zu registrieren. Beispiel: Hinzufügen von Unterstützung für ein benutzerdefiniertes Rating-Element.
3. Ein Renderer MUSS es Host-Apps ermöglichen, Unterstützung für ein Standardelement zu entfernen. Beispiel: Entfernen von Action.Submit, wenn die Unterstützung nicht gewünscht ist.

Events

1. Ein Renderer SOLLTE ein Ereignis auslösen, wenn sich die Sichtbarkeit eines Elements geändert hat, sodass die Host-App die Karte an die richtige Position verschieben kann.