Язык шаблонов адаптивных карточек

Шаблоны позволяют отделить данные от макета в вашей адаптивной карточке. Язык шаблона — это синтаксис, используемый для создания шаблона.

Ознакомьтесь с этим обзором шаблонов адаптивных карточек

Это важно

Критические изменения в кандидате на выпуск за май 2020 г.

Мы усердно работали над выпуском шаблонов, и, наконец, мы на финишной прямой! Мы должны были внести некоторые незначительные критические изменения, поскольку мы приближаемся к выпуску.

Серьезные изменения по состоянию на май 2020 г.

Синтаксис привязки изменился с {...} на ${...}
- Например: "text": "Hello {name}" становится "text": "Hello ${name}"

Привязка к данным

Написание шаблона так же просто, как замена содержимого карточки нестатичным на "выражения привязки".

Полезная нагрузка статической карты

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

Нагрузка шаблона

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

Выражения привязки можно размещать примерно в любом месте, где может быть статическое содержимое.
Синтаксис привязки начинается с ${ и заканчивается }. Пример: ${myProperty}.
Используйте Dot-notation для доступа к подобъектам в иерархии объектов. Пример: ${myParent.myChild}.
Грациозная обработка null гарантирует, что вы не получите исключения, если получить доступ к свойству NULL в графе объектов
Используйте синтаксис индексатора для получения свойств по ключу или элементам в массиве. Пример: ${myArray[0]}.

Предоставление данных

Теперь, когда у вас есть шаблон, необходимо предоставить данные, которые делают его завершенным. Это можно сделать двумя способами:

Вариант А: Встроенный в полезную нагрузку шаблона. Вы можете предоставить данные встроенно в полезную нагрузку шаблона AdaptiveCard. Для этого просто добавьте $data атрибут в корневой AdaptiveCard объект.
Вариант B. В качестве отдельного объекта данных. С помощью этого параметра вы предоставляете два отдельных объекта пакету SDK для шаблонов во время выполнения: template и data. Это будет более распространенный подход, так как обычно вы создадите шаблон и хотите предоставить динамические данные позже.

Вариант A. Встроенные данные

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

Вариант B. Разделение шаблона из данных

Кроме того, (и скорее всего), вы создадите шаблон карточки для повторного использования без включения данных. Этот шаблон может храниться в виде файла и добавляться в систему управления версиями.

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

Затем загрузите его и предоставьте данные во время выполнения с помощью пакетов SDK для шаблонов.

Пример JavaScript

Использование пакета адаптивных карточек-шаблонов .

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!

Поддержка конструктора

Конструктор адаптивных карточек обновлен для поддержки шаблонов.

Попробуйте: https://adaptivecards.microsoft.com/designer

Пример редактора данных . Укажите примеры данных здесь, чтобы просмотреть привязанную к данным карточку в режиме предварительного просмотра. В этой области есть небольшая кнопка, чтобы заполнить структуру данных из существующих примеров данных.
Режим предварительного просмотра . Нажмите кнопку панели инструментов, чтобы переключиться между интерфейсом редактирования и интерфейсом предварительного просмотра примеров данных
Открыть пример - нажмите эту кнопку, чтобы открыть различные примеры полезных нагрузок.

Расширенная привязка

Области привязки

Существует несколько зарезервированных ключевых слов для доступа к различным областям привязки.

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

Назначение контекста данных элементам

Чтобы назначить элементу контекст данных, добавьте $data атрибут в элемент.

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

Повторяющиеся элементы в массиве

Если свойство элемента $data Адаптивной карточки привязано к массиву, сам элемент будет повторяться для каждого элемента в массиве.
Все выражения привязки (${myProperty}), используемые в значениях свойств, будут ограничены отдельным элементом в массиве.
Если привязка к массиву строк используется ${$data} для доступа к отдельному элементу строки. Пример: "text": "${$data}".

Например, ниже TextBlock будет повторяться 3 раза, так как $data является массивом. Обратите внимание, что text свойство привязано к name свойству отдельного объекта в массиве.

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

В результате:

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

Встроенные функции

Язык шаблонов не завершен без расширенного набора вспомогательных функций. Шаблон адаптивной карточки основан на языке адаптивных выражений (AEL), который является открытым стандартом для объявления выражений, которые можно оценить на многих разных платформах. И это строгое супермножество "Logic Apps", поэтому вы можете использовать такой же синтаксис, как в Power Automate и т. д.

Это лишь небольшая выборка встроенных функций.

Полный список предварительно созданных функций языка адаптивного выражения.

Условная оценка

if(expression, trueValue, falseValue)

if Пример

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

Анализ JSON

json(jsonString) — анализ строки JSON

json пример

Это ответ Azure DevOps, где message свойство является сериализованной строкой JSON. Чтобы получить доступ к значениям в строке, необходимо использовать json функцию в нашем шаблоне.

Данные

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

Использование

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

В результате

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

Пользовательские функции

Пользовательские функции поддерживаются через API-интерфейсы в пакетах SDK для шаблонов.

Условный макет с `$when`

Чтобы удалить весь элемент, если условие выполнено, используйте $when свойство. Если $when оценивается как false, элемент не будет виден пользователю.

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

Создание шаблонов

В настоящее время нет поддержки составления шаблонных "частей" вместе. Но мы изучаем варианты и надеемся поделиться более скоро. Все мысли здесь приветствуются!

Примеры

Перейдите на обновленную страницу примеров , чтобы просмотреть все виды новых шаблонных карточек.

Last updated on 2025-12-18