Vorlagensprache für adaptive Karten

Artikel
08/28/2023

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}".

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 dem AdaptiveCard-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 die data. 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.