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

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

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

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

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

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

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

Создание пустого шаблона из предустановки

В верхней части страницы в раскрывающемся списке Select host app выберите "Панель виджетов". Это задаст размер контейнера для Adaptive Card так, чтобы он соответствовал поддерживаемому размеру для виджетов. Обратите внимание, что мини-приложения поддерживают небольшие, средние и большие размеры. Размер предустановки шаблона по умолчанию является правильным размером для небольшого мини-приложения. Не беспокойтесь, если содержимое выходит за границы, потому что мы заменим его на контент, предназначенный для размещения внутри виджета.

В нижней части страницы есть три текстовых редактора. Редактор Card Payload с меткой содержит определение JSON пользовательского интерфейса виджета. Редактор с меткой "Пример данных" содержит JSON, определяющий необязательный контекст данных для мини-приложения. Контекст данных динамически привязан к адаптивной карточке при отображении мини-приложения. Дополнительные сведения о привязке данных в Adaptive Cards см. в языке шаблонов Adaptive Cards.

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

Размер контейнера и раскрывающийся список темы рядом с раскрывающимся списком "Выбор ведущего приложения " в верхней части страницы позволяет задать эти свойства без ручного редактирования примера json узла в редакторе.

Создание новой карточки

В левом верхнем углу страницы нажмите кнопку "Создать карточку". В диалоговом окне "Создать" выберите "Пустая карточка". Теперь вы увидите пустую адаптивную карточку. Вы также заметите, что документ JSON в примере редактора данных пуст.

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

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

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

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

Редактор полезных данных карты обновлен, чтобы отразить элементы TextBlock, которые мы добавили. Замените строку JSON для объекта 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.

Теперь предварительный просмотр должен выглядеть следующим образом:

Обратите внимание, что условные инструкции не отражаются в предварительной версии. Это связано с тем, что дизайнер не моделирует поведение контейнера виджета. Нажмите кнопку режима предварительного просмотра в верхней части страницы, чтобы запустить имитацию. Теперь предварительный просмотр мини-приложения выглядит следующим образом:

Во всплывающем списке Размер контейнера выберите "Средний" и обратите внимание, что предварительный просмотр переключается только на TextBlock среднего размера. Контейнер в предварительной версии также изменяет размер, демонстрируя, как использовать предварительную версию, чтобы убедиться, что пользовательский интерфейс соответствует контейнеру мини-приложения для каждого поддерживаемого размера.

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

В нашем примере мини-приложение будет использовать пользовательское свойство состояния с именем count. В текущем шаблоне можно увидеть, что значение для первого TextBlock содержит ссылку $countна переменную. При запуске мини-приложения на Панели мини-приложений поставщик мини-приложений отвечает за сборку полезных данных и передачу их в узел мини-приложения. Во время проектирования можно использовать Редактор примерных данных для создания прототипа данных и просмотреть, как различные значения влияют на отображение вашего виджета. Замените пустые полезные данные следующим JSON.

{"count": "2"}

Обратите внимание, что предварительная версия теперь вставляет значение, указанное для свойства count , в текст для первого TextBlock.

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

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

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

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

В этой строке JSON свойство типа указывает тип действия, которое представлено. Виджеты поддерживают только тип действия «Action.Execute». Заголовок содержит текст, отображаемый на кнопке для действия. Свойство глагол — это определяемая приложением строка, которую хост виджета отправит поставщику виджетов для передачи намерения, связанного с действием. Мини-приложение может иметь несколько действий, и код поставщика мини-приложений проверяет значение команды в запросе, чтобы определить, какие действия следует предпринять.

Полный шаблон мини-приложения

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

{
    "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.Submit",
    "title": "Increment",
    "verb": "inc",
    "$when": "${!$host.isSettingsPayload}"
    },
    {
    "type": "Action.Submit",
    "title": "Update Setting",
    "verb": "setting",
    "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}