Создание шаблона мини-приложения с помощью конструктора Adaptive Cards

Для мини-приложения адаптивной карточки определите пользовательский интерфейс и взаимодействие с шаблоном JSON Adaptive Cards и, при необходимости, отдельной полезной нагрузкой JSON. В этой статье описывается шаблон виджета подсчета с привязкой данных и условным макетом. Виджеты Windows также могут отображать HTML из URL-адреса; для этого формата содержимого см. поставщики веб-виджетов.

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

Приложения должны реализовать поставщика виджетов для создания и обновления шаблона виджета и (или) данных и передачи их хосту виджета. В статье «Реализация поставщика виджетов в приложении Win32» приведены пошаговые инструкции по реализации поставщика виджетов для виджета подсчета, который мы создадим в следующих шагах.

Конструктор Adaptive Cards

Конструктор Adaptive Cards — это онлайн-средство для редактирования JSON карточки и предварительного просмотра его макета и привязки данных. Откройте Designer, чтобы работать с шаблоном.

Important

Конструктор использует собственные параметры отрисовщика и хоста. Не предполагайте, что функции, которые он предлагает, поддерживаются панелью "Виджеты" или что он предоставляет $hostзначения, специфичные для Windows. Эта пошаговая инструкция не зависит от пресета узла или редактора данных узла. Проверьте окончательный шаблон в провайдере виджетов Windows для каждого поддерживаемого размера и темы.

На рисунках ниже показан макет карты, а не текущий интерфейс Designer.

Начните с пустой карточки

Редактор полезной нагрузки карточки содержит JSON-определение карточки. Замените его содержимое содержимым этой пустой карточки:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": []
}

Редактор примеров данных содержит необязательный контекст данных JSON. Сведения о привязке этих данных к шаблону см. в разделе язык шаблонов Adaptive Cards.

Панель виджетов предоставляет свойства хоста во время выполнения. Ссылайтесь на них через $host в выражениях шаблона, например ${$host.widgetSize}. Эти свойства отделены от полезных данных поставщика; добавление widgetSize поля в пример данных не задает $host.widgetSize.

Недвижимость	Ценность	Описание
host.widgetSize	"малый", "средний" или "большой"	Размер закрепленного виджета.
host.hostTheme	"светлый" или "темный"	Текущая тема устройства, на котором отображается доска мини-приложений.
host.isSettingsPayload	истина или ложь	Если это значение равно true, пользователь щелкнул кнопку "Настроить мини-приложение " в контекстном меню мини-приложения. Это значение свойства можно использовать для отображения элементов пользовательского интерфейса параметров настройки. Это альтернативный способ использования IWidgetProvider2.OnCustomizationRequested для изменения JSON-полезной нагрузки в приложении провайдера виджетов. Дополнительные сведения см. в разделе "Реализация настройки мини-приложения".
host.isHeaderSupported	истина или ложь	Если это значение равно true, настройка заголовка поддерживается. Дополнительные сведения см. в функции isHeaderSupported.
host.isHeader	истина или ложь	Если это значение равно true, хост требует нагрузку специально для отрисовки заголовка мини-приложения.
host.isWebSupported	истина или ложь	Если это значение равно false, хост не поддерживает загрузку веб-содержимого мини-приложения. При этом веб-мини-приложения будут отображать резервные полезные данные JSON, предоставленные поставщиком мини-приложений, но это значение можно использовать для дальнейшей настройки содержимого. Дополнительные сведения см. в разделе "Поставщики веб-мини-приложений"
host.isUserContextAuthenticated	истина или ложь	Если это значение равно false, единственным поддерживаемым действием является Action.OpenUrl. Значение isUserContextAuthenticated можно использовать для правильной настройки содержимого мини-приложения, учитывая ограничения интерактивности.

Мини-приложение подсчета использует четыре элемента TextBlock и одно действие Action.Execute для своей кнопки.

Добавьте элементы TextBlock

Добавьте четыре элемента TextBlock из палитры элементов конструктора или добавьте их непосредственно в json карточки. Перед применением условного макета карточка имеет четыре строки текста, как показано ниже.

Адаптивная карточка в процессе создания. Он показывает виджет с четырьмя строками, содержащими текст New TextBlock. Четыре строки текста выходят за нижнюю границу виджета.

Реализация условного макета

В редакторе полезных данных карты замените массив body следующим фрагментом:

"body": [
    {
        "type": "TextBlock",
        "text": "You have clicked the button ${count} times"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if medium",
        "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if small",
        "$when": "${$host.widgetSize==\"small\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if large",
        "$when": "${$host.widgetSize==\"large\"}"
    }
]

На языке шаблона Adaptive Cards свойство $when указывает, что содержащий элемент отображается, когда связанное значение равно true. Если значение имеет значение false, содержащий элемент не отображается. В элементе body в нашем примере будет показан один из трех элементов TextBlock, а остальные два будут скрыты в зависимости от значения свойства $host.widgetSize. Дополнительные сведения об условных условиях, поддерживаемых в Adaptive Cards, см. в разделе Кондициональный макет с $when.

Без оценки выражений шаблона карточка отображает все четыре текстовых блока:

Адаптивная карточка в процессе создания. На ней показан виджет с четырьмя строками, содержащими текст, указанный в полезной нагрузке JSON, показанной на предыдущем шаге. Вместо условного скрытия элементов все элементы видны и выходят за нижнюю границу изображения.

Когда панель мини-приложений оценивает шаблон при значении "small", заданном в $host.widgetSize, отображается только текстовый блок небольшого размера вместе со счетчиком:

Адаптивная карточка в разработке. Она показывает виджет с двумя строками, содержащими текст, указанный в JSON-нагрузке. Отображается только TextBlock для небольшого размера.

После интеграции шаблона с провайдером измените размер закрепленного виджета в доске Widgets Board и убедитесь, что соответствующий текстовый блок появится. Объявите каждый размер, который вы хотите протестировать в манифесте поставщика виджетов. Общий предварительный просмотр конструктора без данных узла Windows не может проверить эти условия.

Привязка к контексту данных

В примере используется свойство данных с именем count, на которое ссылается ${count} в первом TextBlock. Во время выполнения поставщик отправляет полезные данные хосту виджета. Во время разработки введите следующий код JSON в редакторе Sample data и включите предварительный просмотр конструктора для проверки привязки счетчика. Эти примерные данные не предоставляют отдельные свойства узла Windows.

{"count": "2"}

С {"count": "2"} в качестве примера данных расширение шаблона заменяет ${count} на 2 в первом TextBlock. Проверьте эту привязку в конструкторе после включения предварительного просмотра. Проверьте отдельные $host.widgetSize условия в Widgets Board, как описано выше.

Адаптивная карточка в процессе создания. Первая строка текста теперь содержит значение 2 из данных загружаемого пакета.

Добавление кнопки

Следующим шагом является добавление кнопки в наше мини-приложение. В хосте мини-приложения, когда пользователь нажимает кнопку, хост отправит запрос к провайдеру мини-приложений. В этом примере поставщик мини-приложений будет увеличивать значение счетчика и возвращать обновленные полезные данные. Так как для этой операции требуется поставщик мини-приложений, вы не сможете просматривать это поведение в конструкторе Adaptive Cards, но вы по-прежнему можете использовать конструктор для настройки макета кнопки в пользовательском интерфейсе.

С помощью Adaptive Cards интерактивные элементы определяются с помощью элементов action. Добавьте следующий блок JSON непосредственно после элемента body в редакторе содержимого карты. Не забудьте добавить запятую после закрывающей скобки (]) элемента тела или конструктор сообщит об ошибке форматирования.

,
"actions": [                                                      
    {                                                               
        "type": "Action.Execute",                               
        "title": "Increment",                                   
        "verb": "inc"                                           
    }                                                               
]

Свойство type выбирает Action.Execute, который узел мини-приложения перенаправляет обратному вызову OnActionInvoked вашего поставщика. Вместо этого используйте Action.OpenUrl для навигации по URL-адресу; он не вызывает этот обратный вызов поставщика. title предоставляет текст кнопки, а verb — это определяемая приложением операция, которая обрабатывается поставщиком. Если $host.isUserContextAuthenticated значение равно false, не предлагайте взаимодействия Action.Execute ; поддерживается только Action.OpenUrl .

Окончательная адаптивная карточка. Синяя кнопка с текстом

В следующем списке кода показан окончательный шаблон для взаимодействия counting-widget. Для кнопки Action.Execute требуется контекст аутентифицированного пользователя. Проверьте его в Widgets Board в вашем поставщике; Конструктор не запускает обработчик инкремента поставщика.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
    {
      "type": "TextBlock",
      "text": "You have clicked the button ${count} times"
    },
    {
      "type": "TextBlock",
       "text": "Rendering Only if Small",
      "$when": "${$host.widgetSize==\"small\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Medium",
      "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Large",
      "$when": "${$host.widgetSize==\"large\"}"
    }
    ],
   "actions": [
    {
      "type": "Action.Execute",
      "title": "Increment",
      "verb": "inc"
    }
  ]
}

Пример данных полезной нагрузки настроек

В следующем листинге кода приводится простой пример JSON нагрузки, использующей свойство host.isSettingsPayload для отображения другого содержимого, когда пользователь нажал на кнопку "Настройка мини-приложения".

{
    "type": "AdaptiveCard",
    "body": [
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Content payload",
                "$when": "${!$host.isSettingsPayload}"
            }
        ]
    },
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Settings payload",
                "$when": "${$host.isSettingsPayload}"
            }
        ]
    }
],
"actions": [
    {
        "type": "Action.Execute",
        "title": "Increment",
        "verb": "inc",
        "$when": "${!$host.isSettingsPayload}"
    },
    {
        "type": "Action.Execute",
        "title": "Update Setting",
        "verb": "setting",
        "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-10-27

Мини-приложение подсчета