Język szablonu kart adaptacyjnych

Szablonowanie umożliwia oddzielenie danych od układu w Twojej karcie adaptacyjnej. Język szablonu to składnia używana do tworzenia szablonu.

Przeczytaj to, aby zapoznać się z omówieniem tworzenia szablonów kart adaptacyjnych

Ważne

Istotne zmiany w programie Release Candidate z maja 2020 r.

Ciężko pracowaliśmy nad wydaniem szablonów i jesteśmy na ostatniej prostej! Musieliśmy wprowadzić drobne zmiany powodujące niezgodność, w miarę zbliżania się do wydania.

Zmiany wywołujące niezgodności od maja 2020 r.

Składnia powiązania została zmieniona z {...} na ${...}
- Na przykład: "text": "Hello {name}" staje się "text": "Hello ${name}"

Wiązanie z danymi

Pisanie szablonu jest tak proste, jak zastępowanie zawartości niestałej karty wyrażeniami wiążącymi.

Ładunek karty statycznej

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

Ładunek szablonu

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

Wyrażenia powiązań można umieszczać wszędzie tam, gdzie może być zawartość statyczna.
Składnia powiązania rozpoczyna się od ${ i kończy się na }. Na przykład ${myProperty}
Użyj notacji kropkowej , aby uzyskać dostęp do obiektów podrzędnych hierarchii obiektów. Na przykład ${myParent.myChild}
Elegancka obsługa wartości null gwarantuje, że nie uzyskasz wyjątków, jeśli uzyskasz dostęp do właściwości null w grafie obiektu.
Składnia indeksatora umożliwia pobieranie właściwości według klucza lub elementów w tablicy. Na przykład ${myArray[0]}

Podawanie danych

Teraz, gdy masz szablon, będziesz chciał dostarczyć dane, które go uzupełnią. Masz dwie opcje, aby to zrobić:

Opcja A: wbudowane w treść szablonu. Dane można podać bezpośrednio w ładunku szablonu AdaptiveCard. W tym celu wystarczy dodać $data atrybut do obiektu głównego AdaptiveCard .
Opcja B: jako oddzielny obiekt danych. Dzięki tej opcji udostępniasz dwa oddzielne obiekty zestawowi SDK tworzenia szablonów w czasie wykonywania: template i data. Będzie to bardziej typowe podejście, ponieważ zazwyczaj utworzysz szablon i chcesz później udostępnić dane dynamiczne.

Opcja A: dane wbudowane

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

Opcja B: oddzielenie szablonu od danych

Alternatywnie (i bardziej prawdopodobne) utworzysz szablon karty wielokrotnego użytku bez uwzględniania danych. Ten szablon może być przechowywany jako plik i dodawany do kontroli źródła.

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

Następnie załaduj je i dostarcz dane w czasie wykonywania przy użyciu Templating SDKs.

Przykład języka JavaScript

Korzystając z pakietu 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!

Obsługa projektanta

Projektant kart adaptacyjnych został zaktualizowany w celu obsługi tworzenia szablonów.

Wypróbuj go na stronie: https://adaptivecards.microsoft.com/designer

Przykładowy edytor danych — tutaj określ przykładowe dane, aby wyświetlić kartę powiązaną z danymi w trybie podglądu. W tym okienku znajduje się mały przycisk umożliwiający wypełnienie struktury danych z istniejących przykładowych danych.
Tryb podglądu — naciśnij przycisk paska narzędzi, aby przełączać się między trybem edycji a trybem podglądu danych przykładowych
Otwórz przykład — kliknij ten przycisk, aby otworzyć różne przykładowe ładunki

Powiązanie zaawansowane

Zakresy wiązań

Istnieje kilka zarezerwowanych słów kluczowych w celu uzyskania dostępu do różnych zakresów powiązań.

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

Przypisywanie kontekstu danych do elementów

Aby przypisać "kontekst danych" do dowolnego elementu, dodaj $data atrybut do elementu.

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

Powtarzanie elementów w tablicy

Jeśli właściwość elementu $data karty adaptacyjnej jest powiązana z tablicą, sam element będzie powtarzany dla każdego elementu w tablicy.
Wszystkie wyrażenia powiązania (${myProperty}) używane w wartościach właściwości będą ograniczone do pojedynczego elementu w tablicy.
Jeśli jest powiązanie z tablicą łańcuchów znaków, użyj polecenia ${$data}, aby uzyskać dostęp do pojedynczego elementu łańcucha. Na przykład "text": "${$data}"

Na przykład poniższy TextBlock będzie powtarzany 3 razy, ponieważ $data jest tablicą. Zwróć uwagę, że właściwość text jest powiązana z właściwością name pojedynczego obiektu w tablicy.

{
    "type": "Container",
    "items": [
        {
            "type": "TextBlock",
            "$data": [
                { "name": "Matt" }, 
                { "name": "David" }, 
                { "name": "Thomas" }
            ],
            "text": "${name}"
        }
    ]
}

Wynikowe:

{
    "type": "Container",
    "items": [ 
        {
            "type": "TextBlock",
            "text": "Matt"
        },
        {
            "type": "TextBlock",
            "text": "David"
        }
        {
            "type": "TextBlock",
            "text": "Thomas"
        }
    ]
}

Wbudowane funkcje

Język tworzenia szablonów nie jest kompletny bez rozbudowanego zestawu funkcji pomocnika. Tworzenie szablonów kart adaptacyjnych opiera się na języku AEL ( Adaptive Expression Language ), który jest otwartym standardem deklarowania wyrażeń, które można ocenić na wielu różnych platformach. Jest to odpowiedni nadzbiór "Logic Apps", dzięki czemu można użyć podobnej składni jak w usłudze Power Automate itp.

Jest to tylko małe próbkowanie wbudowanych funkcji.

Zapoznaj się z pełną listą wstępnie utworzonych funkcji języka wyrażeń adaptacyjnych.

Ocena warunkowa

if(expression, trueValue, falseValue)

if Przykład

{
    "type": "TextBlock",
    "color": "${if(priceChange >= 0, 'good', 'attention')}"
}

Analizowanie kodu JSON

json(jsonString) — analizowanie ciągu JSON

json Przykład

Jest to odpowiedź usługi Azure DevOps, w której message właściwość jest ciągiem serializowanym w formacie JSON. Aby uzyskać dostęp do wartości w ciągu, musimy użyć json funkcji w naszym szablonie.

Dane

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

Użycie

{
    "type": "TextBlock",
    "text": "${json(message).releaseName}"
}

Wynikowe

{
    "type": "TextBlock",
    "text": "Release-104"
}

Funkcje niestandardowe

Funkcje niestandardowe są obsługiwane za pośrednictwem interfejsów API w zestawach SDK tworzenia szablonów.

Układ warunkowy z `$when`

Aby usunąć cały element, jeśli warunek jest spełniony, użyj $when właściwości . Jeśli $when zostanie ocenione jako false, element nie pojawi się użytkownikowi.

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

Tworzenie szablonów

Obecnie nie ma obsługi składania elementów szablonu. Ale badamy opcje i mamy nadzieję, że wkrótce się podzielimy. Wszelkie myśli tutaj mile widziane!

Przykłady

Przejrzyj zaktualizowaną stronę z przykładami, aby zapoznać się ze wszystkimi rodzajami nowych kart szablonowych.

Last updated on 2025-12-18

Udostępnij przez