Примечание
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Замечание
Некоторые сведения относятся к предварительной версии продукта, в которую перед коммерческим выпуском могут быть внесены существенные изменения. Корпорация Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых в отношении информации, предоставленной здесь.
Это важно
Функция, описанная в этом разделе, доступна в предварительных сборках канала разработчиков 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 слева от страницы на пустую адаптивную карточку в области предварительного просмотра. На этом этапе предварительный просмотр мини-приложения должен выглядеть следующим образом. Содержимое снова переполняется за пределами границ мини-приложения, но это будет исправлено в следующих шагах.
Реализация условного макета
Редактор данных полезной нагрузки карточки был обновлён для отображения элементов текстового блока, которые мы добавили. Замените строку 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.
Теперь предварительный просмотр должен выглядеть следующим образом:
Обратите внимание, что условные инструкции не отражаются в предварительной версии. Это связано с тем, что дизайнер не моделирует поведение хоста виджета. Нажмите кнопку Режим предпросмотра в верхней части страницы, чтобы запустить симуляцию. Теперь предварительный просмотр мини-приложения выглядит следующим образом:
Во всплывающем списке размер контейнера выберите "Средний" и обратите внимание, что предварительный просмотр переключается на показ только TextBlock среднего размера. Контейнер в предварительной версии также изменяет размер, демонстрируя, как использовать предварительную версию, чтобы убедиться, что пользовательский интерфейс соответствует контейнеру мини-приложения для каждого поддерживаемого размера.
Привязка к контексту данных
В нашем примере мини-приложение будет использовать пользовательское свойство состояния с именем count. В текущем шаблоне можно увидеть, что значение для первого TextBlock содержит ссылку $count
на переменную. При запуске мини-приложения в Доске мини-приложений поставщик мини-приложений отвечает за сборку полезных данных и передачу его в узел мини-приложения. Во время разработки можно использовать редактор данных для создания прототипа структуры данных и определения того, как различные значения влияют на отображение виджета. Замените пустые данные следующим JSON.
{"count": "2"}
Обратите внимание, что предварительная версия теперь вставляет значение, указанное для свойства счетчика, в текст для первого TextBlock.
Добавление кнопки
Следующим шагом является добавление кнопки в наше мини-приложение. В хосте виджета, когда пользователь нажимает кнопку, хост выполнит запрос к поставщику виджета. В этом примере виджет увеличит значение счетчика и вернет обновленные данные. Так как для этой операции требуется поставщик мини-приложений, вы не сможете просматривать это поведение в конструкторе адаптивных карточек, но вы по-прежнему можете использовать конструктор для настройки макета кнопки в пользовательском интерфейсе.
С помощью Адаптивных карточек интерактивные элементы определяются с помощью действий элементов. Добавьте следующий блок JSON непосредственно после элемента тела в редакторе контента карты. Не забудьте добавить запятую после закрывающей скобки (]) элемента тела или конструктор сообщит об ошибке форматирования.
,
"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"
}
Windows developer