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

Статья
07/05/2024

Примечание.

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

Внимание

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

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

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

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

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

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

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

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

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

Третий текстовый редактор помечен редактором данных узла. Обратите внимание, что этот редактор может свернуться под двумя другими редакторами страницы. Если да, щелкните +, чтобы развернуть редактор. Приложения узла мини-приложений, такие как Панель мини-приложений, имеют два свойства, указывающие размер и тему мини-приложения. Эти свойства называются host.widgetSize и host.hostTheme. Поддерживаемые размеры : "малый", "средний" и "большой". Поддерживаемые темы : "светлый" и "темный". Шаблон мини-приложения может динамически отображать разное содержимое в зависимости от текущего значения этих свойств. Чтобы узнать, как мини-приложение реагирует на изменения размера и темы, можно настроить значения этих свойств в редакторе или задать эти значения в раскрывающемся списке "Размер контейнера" и "Тема " рядом с раскрывающимся списком "Выбор ведущего приложения " в верхней части страницы.

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

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

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

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

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

Выполняется адаптивная карточка. В нем показан мини-приложение с четырьмя строками, содержащими текст New 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\"}"
    }
]

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

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

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

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

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

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

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

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

{"count": "2"}

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

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

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

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

С помощью адаптивных карточек интерактивные элементы определяются с элементами действия . Добавьте следующий блок 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"
    }
  ]
}

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

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