Vorlagensprache für adaptive Karten
Durch Vorlagen wird die Trennung von Daten und Layout auf Ihrer adaptiven Karte ermöglicht. Die Vorlagensprache ist die Syntax, die zum Erstellen einer Vorlage verwendet wird.
Hier finden Sie einen Überblick über Vorlagen für adaptive Karten.
Wichtig
Breaking Changes im Release Candidate von Mai 2020
Wir haben hart an der Veröffentlichung der Vorlagen gearbeitet, und endlich sind wir auf der Zielgeraden. Wir mussten kurz vor der Veröffentlichung einige geringfügige, nicht abwärtskompatible Änderungen vornehmen.
Breaking Changes Stand Mai 2020
- Die Bindungssyntax wurde von
{...}
in${...}
geändert.- Beispiel: Aus
"text": "Hello {name}"
wird"text": "Hello ${name}"
.
- Beispiel: Aus
Binden an Daten
Das Schreiben einer Vorlage beschränkt sich einfach darauf, den "nicht statischen" Inhalt Ihrer Karte durch "Bindungsausdrücke" zu ersetzen.
Statische Kartennutzlast
{
"type": "TextBlock",
"text": "Matt"
}
Vorlagennutzlast
{
"type": "TextBlock",
"text": "${firstName}"
}
- Bindungsausdrücke können praktisch überall dort platziert werden, so sich statische Inhalte befinden können
- Die Bindungssyntax beginnt mit
${
und endet mit}
. Beispiel:${myProperty}
- Verwenden Sie Punkt-Notation, um auf untergeordnete Objekte einer Objekthierarchie zuzugreifen. Beispiel:
${myParent.myChild}
- Eine ordnungsgemäße Behandlung von Nullwerten stellt sicher, dass Sie keine Ausnahmen empfangen, wenn Sie auf eine NULL-Eigenschaft in einem Objektgraphen zugreifen
- Verwenden Sie Indexersyntax zum Abrufen von Eigenschaften nach Schlüsseln oder Elementen in einem Array. Beispiel:
${myArray[0]}
Bereitstellung der Daten
Nachdem Sie nun über eine Vorlage verfügen, sollten Sie die Daten bereitstellen, um ein fertiges Ergebnis zu erzielen. Hierzu haben Sie zwei Möglichkeiten:
- Option A: Inline innerhalb der Nutzlast der Vorlage. Sie können die Daten inline in der Nutzlast der
AdaptiveCard
-Vorlage bereitstellen. Fügen Sie zu diesem Zweck einfach demAdaptiveCard
-Stammobjekt ein$data
-Attribut hinzu. - Option B: Als separates Datenobjekt. Bei dieser Option stellen Sie dem Vorlagen-SDK- zur Laufzeit zwei separate Objekte zur Verfügung: die
template
und diedata
. Dies ist der gängigere Ansatz, da Sie normalerweise eine Vorlage erstellen, für die Sie später dynamische Daten bereitstellen möchten.
Option A: Inlinedaten
{
"type": "AdaptiveCard",
"$data": {
"employee": {
"name": "Matt",
"manager": { "name": "Thomas" },
"peers": [{
"name": "Andrew"
}, {
"name": "Lei"
}, {
"name": "Mary Anne"
}, {
"name": "Adam"
}]
}
},
"body": [
{
"type": "TextBlock",
"text": "Hi ${employee.name}! Here's a bit about your org..."
},
{
"type": "TextBlock",
"text": "Your manager is: ${employee.manager.name}"
},
{
"type": "TextBlock",
"text": "3 of your peers are: ${employee.peers[0].name}, ${employee.peers[1].name}, ${employee.peers[2].name}"
}
]
}
Option B: Trennen von Vorlage und Daten
Alternativ (und wahrscheinlicher) erstellen Sie eine wiederverwendbare Kartenvorlage ohne Daten. Diese Vorlage kann als Datei gespeichert und dem Quellsteuerelement hinzugefügt werden.
EmployeeCardTemplate.json
{
"type": "AdaptiveCard",
"body": [
{
"type": "TextBlock",
"text": "Hi ${employee.name}! Here's a bit about your org..."
},
{
"type": "TextBlock",
"text": "Your manager is: ${employee.manager.name}"
},
{
"type": "TextBlock",
"text": "3 of your peers are: ${employee.peers[0].name}, ${employee.peers[1].name}, ${employee.peers[2].name}"
}
]
}
Laden Sie die Daten dann zur Laufzeit, und stellen Sie sie mithilfe des Vorlagen-SDKs bereit.
JavaScript-Beispiel
Verwenden des Pakets adaptivecards-templating.
var template = new ACData.Template({
// EmployeeCardTemplate goes here
});
// Specify data at runtime
var card = template.expand({
$root: {
"employee": {
"name": "Matt",
"manager": { "name": "Thomas" },
"peers": [{
"name": "Andrew"
}, {
"name": "Lei"
}, {
"name": "Mary Anne"
}, {
"name": "Adam"
}]
}
}
});
// Now you have an AdaptiveCard ready to render!
Designerunterstützung
Der Designer für adaptive Karten wurde aktualisiert, um Vorlagen zu unterstützen.
Jetzt testen unter: https://adaptivecards.io/designer
- Beispieldaten-Editor: Geben Sie hier Beispieldaten an, um die datengebundene Karte im Vorschaumodus anzuzeigen. Es gibt eine kleine Schaltfläche in diesem Bereich, um die Datenstruktur aus den vorhandenen Beispieldaten zu füllen.
- Vorschaumodus – Klicken Sie auf die Symbolleistenschaltfläche, um zwischen der „edit-experience“ und der „sample-data-preview“ zu wechseln.
- Beispiel öffnen – Klicken Sie auf diese Schaltfläche, um verschiedene Beispielnutzlasten zu öffnen.
Erweiterte Bindung
Bindungsbereiche
Für den Zugriff auf verschiedene Bindungsbereiche sind einige reservierte Schlüsselwörter verfügbar.
{
"${<property>}": "Implicitly binds to `$data.<property>`",
"$data": "The current data object",
"$root": "The root data object. Useful when iterating to escape to parent object",
"$index": "The current index when iterating"
}
Zuweisen eines Datenkontexts zu Elementen
Wenn Sie einem Element einen „Datenkontext“ zuweisen möchten, fügen Sie dem-Element ein $data
-Attribut hinzu.
{
"type": "Container",
"$data": "${mySubObject}",
"items": [
{
"type": "TextBlock",
"text": "This TextBlock is now scoped directly to 'mySubObject': ${mySubObjectProperty}"
},
{
"type": "TextBlock",
"text": "To break-out and access the root data, use: ${$root}"
}
]
}
Wiederholen von Elementen in einem Array
- Wenn die
$data
-Eigenschaft eines „Adaptive Karte“-Elements an ein -Array gebunden ist, dann wird das -Element selbst für jedes Element im Array wiederholt. - Alle in Eigenschaftswerten verwendeten Bindungsausdrücke (
${myProperty}
) werden auf das einzelne Element innerhalb des Arrays festgelegt. - Wenn Sie eine Bindung an ein Array von Zeichenfolgen herstellen, verwenden Sie
${$data}
, um auf das einzelne Zeichenfolgenelement zuzugreifen. Beispiel:"text": "${$data}"
Der TextBlock
unten wird beispielsweise dreimal wiederholt, da sein $data
-Objekt ein Array ist. Beachten Sie, dass die text
-Eigenschaft an die name
-Eigenschaft eines einzelnen Objekts innerhalb des Arrays gebunden ist.
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"$data": [
{ "name": "Matt" },
{ "name": "David" },
{ "name": "Thomas" }
],
"text": "${name}"
}
]
}
Ergebnis:
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Matt"
},
{
"type": "TextBlock",
"text": "David"
}
{
"type": "TextBlock",
"text": "Thomas"
}
]
}
Integrierte Funktionen
Keine Vorlagensprache kommt ohne eine umfassende Sammlung an Hilfsfunktionen aus. Die Vorlagen für adaptive Karten bauen auf der Adaptive Expression Language (AEL) auf, einem offenen Standard zum Deklarieren von Ausdrücken, die auf vielen verschiedenen Plattformen ausgewertet werden können. Sie bildet eine echte Obermenge von "Azure Logic Apps", sodass Sie eine ähnliche Syntax wie in Power Automate usw. verwenden können.
Die ist nur eine kleine Stichprobe der integrierten Funktionen.
Sehen Sie sich die vollständige Liste der Vordefinierten Funktionen in der Adaptive Expression Language an.
Bedingte Auswertung
- if(expression, trueValue, falseValue)
if
-Beispiel
{
"type": "TextBlock",
"color": "${if(priceChange >= 0, 'good', 'attention')}"
}
Analysieren von JSON
- json(jsonString): Analysieren einer JSON-Zeichenfolge
json
-Beispiel
Dies ist eine Azure DevOps-Antwort, bei der die message
-Eigenschaft eine serialisierte JSON-Zeichenfolge ist. Um auf Werte innerhalb der Zeichenfolge zuzugreifen, muss die Funktion json
in der Vorlage verwendet werden.
Daten
{
"id": "1291525457129548",
"status": 4,
"author": "Matt Hidinger",
"message": "{\"type\":\"Deployment\",\"buildId\":\"9542982\",\"releaseId\":\"129\",\"buildNumber\":\"20180504.3\",\"releaseName\":\"Release-104\",\"repoProvider\":\"GitHub\"}",
"start_time": "2018-05-04T18:05:33.3087147Z",
"end_time": "2018-05-04T18:05:33.3087147Z"
}
Nutzung
{
"type": "TextBlock",
"text": "${json(message).releaseName}"
}
Ergebnis
{
"type": "TextBlock",
"text": "Release-104"
}
Benutzerdefinierte Funktionen
Benutzerdefinierte Funktionen werden über APIs in den Vorlagen-SDKs unterstützt.
Bedingtes Layout mit $when
Um ein komplettes Element zu entfernen, wenn eine Bedingung erfüllt ist, verwenden Sie die $when
-Eigenschaft. Wird $when
zu false
ausgewertet, wird das Element dem Benutzer nicht angezeigt.
{
"type": "AdaptiveCard",
"$data": {
"price": "35"
},
"body": [
{
"type": "TextBlock",
"$when": "${price > 30}",
"text": "This thing is pricy!",
"color": "attention",
},
{
"type": "TextBlock",
"$when": "${price <= 30}",
"text": "Dang, this thing is cheap!",
"color": "good"
}
]
}
Zusammensetzen von Vorlagen
Derzeit wird das Zusammenstellen von Vorlagenteilen nicht unterstützt. Wir untersuchen jedoch Optionen und hoffen, bald mehr berichten zu können. Alle Ideen sind willkommen!
Beispiele
Durchsuchen Sie die aktualisierte Beispielseite, um alle möglichen neuen Kartenvorlagen zu erkunden.