Vorlagensprache für adaptive Karten

Vorlagen ermöglichen die Trennung von Daten vom Layout in Ihrer adaptiven Karte. Die Vorlagensprache ist die Syntax, die zum Erstellen einer Vorlage verwendet wird.

Bitte lesen Sie dies für eine Übersicht über die Vorlagen für adaptive Karten

Änderungen mit disruptiven Auswirkungen ab Mai 2020

1. Die Bindungssyntax wurde von {...} zu ${...}
   • Beispiel: "text": "Hello {name}" wird zu "text": "Hello ${name}"

Datenbindung

Das Schreiben einer Vorlage ist so einfach wie das Ersetzen des "nicht statischen" Inhalts Ihrer Karte durch "Bindungsausdrücke".

Statische Kartennutzlast

{
   "type": "TextBlock",
   "text": "Matt"
}

Vorlagennutzlast

{
   "type": "TextBlock",
   "text": "${firstName}"
}

• Bindungsausdrücke können an einer beliebigen Stelle platziert werden, an der statische Inhalte vorhanden sein können
• Die Bindungssyntax beginnt mit ${ und endet mit }. Beispiel: ${myProperty}
• Verwenden Sie Punktnotation , um auf Unterobjekte einer Objekthierarchie zuzugreifen. Beispiel: ${myParent.myChild}
• Die ordnungsgemäße Nullbehandlung stellt sicher, dass Sie keine Ausnahmen erhalten, wenn Sie auf eine NULL-Eigenschaft in einem Objektdiagramm zugreifen.
• Verwenden Sie die Indexersyntax , um Eigenschaften nach Schlüsseln oder Elementen in einem Array abzurufen. Beispiel: ${myArray[0]}

Bereitstellen der Daten

Nachdem Sie nun über eine Vorlage verfügen, möchten Sie möglicherweise die Daten bereitstellen, die sie vervollständigen. Hierfür stehen ihnen zwei Möglichkeiten zur Auswahl:

1. Option A: Eingebettet in die Vorlagendaten. Sie können die Daten inline innerhalb der AdaptiveCard Vorlagennutzlast bereitstellen. Fügen Sie dazu einfach dem Stammobjekt $data ein AdaptiveCard Attribut hinzu.
2. Option B: Als separates Datenobjekt. Mit dieser Option stellen Sie zwei separate Objekte für das Templating SDK zur Laufzeit bereit: die template und die data. Dies ist der häufigere Ansatz, da Sie in der Regel eine Vorlage erstellen und 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 der Vorlage von den Daten

Alternativ (und wahrscheinlicher) erstellen Sie eine wiederverwendbare Kartenvorlage, ohne die Daten einzuverwenden. Diese Vorlage kann als Datei gespeichert und der Quellcodeverwaltung 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 sie dann und stellen Sie die Daten zur Laufzeit mithilfe der Vorlagen-SDKs bereit.

JavaScript-Beispiel

Verwendung 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 Adaptive Card Designer wurde aktualisiert, um die Vorlagen-Erstellung zu unterstützen.

Probieren Sie es aus: https://adaptivecards.microsoft.com/designer

• Beispieldaten-Editor – Geben Sie hier Beispieldaten an, um die datengebundene Karte im "Vorschaumodus" anzuzeigen. In diesem Bereich gibt es eine kleine Schaltfläche, um die Datenstruktur aus den vorhandenen Beispieldaten aufzufüllen.
• Vorschaumodus – Drücken Sie die Symbolleistenschaltfläche, um zwischen der Bearbeitungsoberfläche und der Beispieldatenvorschau zu wechseln.
• Beispiel öffnen – Klicken Sie auf diese Schaltfläche, um verschiedene Beispielnutzlasten zu öffnen.

Erweiterte Bindung

Bindungsbereiche

Es gibt einige reservierte Schlüsselwörter für den Zugriff auf verschiedene Bindungsbereiche.

{
    "${<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

Um jedem Element einen "Datenkontext" zuzuweisen, 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 Eigenschaft eines adaptiven Kartenelements $data an ein Array gebunden ist, 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 eine Bindung an ein Array von Zeichenfolgen erfolgt, verwenden Sie ${$data}, um auf das einzelne Zeichenfolgelement zuzugreifen. Beispiel: "text": "${$data}"

Beispielsweise wird die TextBlock 3 Mal wiederholt, da sie $data ein Array ist. Beachten Sie, wie 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

Ohne eine umfangreiche Suite von Hilfsfunktionen ist keine Template-Sprache vollständig. Die Vorlagen für adaptive Karten basieren auf der Adaptiven Ausdruckssprache (Adaptive Expression Language , AEL), einem offenen Standard zum Deklarieren von Ausdrücken, die auf vielen verschiedenen Plattformen ausgewertet werden können. Außerdem ist es eine vollständige Obermenge von "Logic Apps", sodass Sie eine ähnliche Syntax wie bei Power Automate usw. nutzen können.

Dies ist nur ein kleines Sampling der integrierten Funktionen.

Sehen Sie sich die vollständige Liste der vordefinierten Funktionen für adaptive Ausdruckssprache 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 es sich bei der message Eigenschaft um eine JSON-serialisierte Zeichenfolge handelt. Um auf Werte innerhalb der Zeichenfolge zuzugreifen, müssen wir die json Funktion in unserer Vorlage verwenden.

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

Verwendung

{
    "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

Verwenden Sie die $when Eigenschaft, um ein gesamtes Element abzulegen, wenn eine Bedingung erfüllt ist. Falls $when zu false ausgewertet wird, 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"
        }
    ]
}

Erstellen von Vorlagen

Derzeit gibt es keine Unterstützung für die Zusammensetzung von Vorlagen "Teilen". Aber wir untersuchen Optionen und hoffen, dass wir bald mehr teilen können. Alle Gedanken hier willkommen!

Examples

Durchsuchen Sie die aktualisierte Beispielseite , um alle Arten neuer Vorlagenkarten zu erkunden.