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

2025-06-10

Замечание

Некоторые сведения относятся к предварительной версии продукта, в которую перед коммерческим выпуском могут быть внесены существенные изменения. Корпорация Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых в отношении информации, предоставленной здесь.

Это важно

Функция, описанная в этом разделе, доступна в предварительных сборках канала разработчиков Windows, начиная с версии 25217. Сведения о предварительных сборках Windows см. в Windows 10 Insider Preview.

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

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

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

Конструктор адаптивных карточек

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Редактор данных полезной нагрузки карточки был обновлён для отображения элементов текстового блока, которые мы добавили. Замените строку JSON для объекта тела на следующий:

"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 указывает, что содержащий элемент отображается, когда связанное значение оценивается как истина. Если значение имеет значение false, содержащий элемент не отображается. В элементе body в нашем примере будет отображен один из трех элементов TextBlock , а остальные два будут скрыты в зависимости от значения свойства $host.widgetSize. Дополнительные сведения об условных выражениях, поддерживаемых в адаптивных карточках, см. в разделе о условной компоновке с использованием $when.

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

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

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

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

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

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

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

{"count": "2"}

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

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

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

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

С помощью Адаптивных карточек интерактивные элементы определяются с помощью действий элементов. Добавьте следующий блок JSON непосредственно после элемента тела в редакторе контента карты. Не забудьте добавить запятую после закрывающей скобки (]) элемента тела или конструктор сообщит об ошибке форматирования.

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

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

финальная адаптивная карточка. Синяя кнопка с текстом 'Increment' отображается после двух текстовых строк.

В следующем фрагменте кода показана окончательная версия полезной нагрузки 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"
}

Поделиться через

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