Формат XML манифеста пакета поставщика мини-приложений

Чтобы отобразиться в узле мини-приложений, приложения, поддерживающие мини-приложения Windows, должны зарегистрировать своего поставщика мини-приложений в системе. Для приложений Win32 в настоящее время поддерживаются только упакованные приложения, а поставщики мини-приложений указывают сведения о регистрации в файле манифеста пакета приложения. В этой статье описан формат XML для регистрации мини-приложений. См. раздел "Пример" для описания кода примера манифеста пакета для поставщика мини-приложений Win32.

Расширение приложения

Файл манифеста пакета приложения поддерживает множество различных расширений и функций для приложений Windows. Формат манифеста пакета приложения определяется набором схем, которые описаны в Справочнике по схеме манифеста пакета. Поставщики мини-приложений объявляют свои сведения о регистрации в uap3:AppExtension. Атрибут Name расширения должен иметь значение com.microsoft.windows.widgets.

Поставщики мини-приложений должны включать uap3:Properties в качестве дочернего элемента uap3:AppExtension. Схема манифеста пакета не накладывает требований к структуре элемента uap3:Properties, кроме требования, чтобы XML был правильно сформирован. Далее в этой статье описывается формат XML, который ожидает хост мини-приложения и который необходим для успешной регистрации поставщика мини-приложений.

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.widgets" DisplayName="WidgetTestApp" Id="ContosoWidgetApp" PublicFolder="Public">
    <uap3:Properties>
    <!-- Widget provider registration content goes here -->
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>

Иерархия элементов

WidgetProvider

  ProviderIcons

    Значок

  Активация

    CreateInstance

    Активировать приложение

  Определения

    Определение

      Возможности

        Возможность

          Размер

      ThemeResources

        Значки

          Значок

        Снимки экрана

          Снимок экрана

        Тёмный режим

          Значки

            Значок

          Снимки экрана

            Снимок экрана

        LightMode

          Значки

            Значок

          Снимки экрана

            Снимок экрана

WidgetProvider

Корневой элемент регистрационных данных поставщика виджета.

Снимок экрана: диалоговое окно

WidgetProviderIcons

Задает значки, представляющие приложение поставщика мини-приложений.

Активация

Указывает сведения об активации для поставщика виджетов. Если в манифесте указаны как CreateInstance, так и ActivateApplication, CreateInstance имеет приоритет.

CreateInstance

CreateInstance следует указать для поставщиков мини-приложений на основе Win32, реализующих интерфейс IWidgetProvider . Система активирует интерфейс с вызовом CoCreateInstance. Атрибут ClassId указывает CLSID для сервера CreateInstance, реализующего интерфейс IWidgetProvider.

Атрибут Тип Обязательно Описание Значение по умолчанию
ClassId GUID Да CLSID для сервера CreateInstance, реализующего поставщика мини-приложений. Н/П

Активировать приложение

Если указано ActivateApplication, поставщик виджета активируется через командную строку, а аргументы передаются в виде закодированных в base64url строк JSON. Рекомендуется, чтобы поставщики мини-приложений использовали тип активации CreateInstance . Сведения о формате командной строки ActivateApplication см. в разделе «Протокол ActivateApplication поставщика мини-приложений».

Определения

Контейнерный элемент для одной или нескольких регистраций виджетов.

Определение

Представляет собой регистрацию для одного виджета.

Атрибут Тип Обязательно Описание Значение по умолчанию
Id строка Да Идентификатор, определяющий мини-приложение. Это значение также отображается на панели навигации средства выбора мини-приложений. Реализации поставщика виджетов используют эту строку, чтобы определить или указать, какой из виджетов приложения имеется в виду в каждой операции. Эта строка должна быть уникальной для всех мини-приложений, определенных в файле манифеста приложения. Н/П
Отображаемое имя строка Да Имя мини-приложения, отображаемого на узле мини-приложений. Н/П
Description строка Да Краткое описание мини-приложения. Н/П
AllowMultiple boolean Нет Установите значение false, если поддерживается только один экземпляр этого мини-приложения. Этот атрибут является необязательным, а значение по умолчанию — true. true
IsCustomizable boolean Нет Представлено в пакете SDK для приложений Windows 1.4. Установите значение true, если ваше приложение поддерживает настройку виджетов. Это приводит к отображению кнопки "Настройка мини-приложения" в меню с многоточием мини-приложения. false
ДополнительныйInfoUri строка Нет URI, который можно связать с мини-приложением и использовать, когда пользователь щёлкает по строке заголовка фрейма мини-приложения или по элементу Powered by в его контекстном меню. Н/П
Исключенные регионы строка Нет Список регионов, где мини-приложение не должно быть доступно. Мини-приложения могут указывать ExcludedRegions или ExclusiveRegions, но не должны указывать оба свойства в определении одного мини-приложения. Значение атрибута — это разделенный запятыми список двух кодов областей символов. Н/П
ExclusiveRegions строка Нет Список только тех регионов, в которых должен быть доступен виджет. Мини-приложения могут указывать ExcludedRegions или ExclusiveRegions, но не должны указывать оба свойства в одном определении мини-приложения. Значение атрибута — это разделенный запятыми список двух кодов областей символов. Н/П
WebRequestFilter строка Нет Указывает фильтр, который определяет URL-адреса запросов ресурсов, для которых запрос будет перехвачен и перенаправлен на реализацию поставщика виджетов IWidgetResourceProvider.OnResourceRequested. Шаблон фильтра задаётся в формате, который описан в шаблонах сопоставления. При необходимости строка фильтра в регистрации должна использовать Punycode. Строка фильтра должна соответствовать источнику, откуда осуществляется регистрация мини-приложения, указанного в поле webUrl в содержимом адаптивной карточки. Н/П

Возможности

Необязательно. Задает возможности для одного мини-приложения. Если возможности не объявлены, по умолчанию добавляется одна возможность, указывающая размер "большой".

Возможность

Задает возможность виджета.

Размер

Указывает поддерживаемые размеры связанного мини-приложения.

Атрибут Тип Обязательно Описание Значение по умолчанию
Имя строка Да Указывает поддерживаемый размер мини-приложения. Значение должно быть одним из следующих значений: "small", "средний", "большой" Н/П

ThemeResources

Задает ресурсы темы для мини-приложения.

Значки

Элемент контейнера для одного или нескольких элементов Icon .

Значок

Обязательный. Указывает значок, отображаемый в области атрибуции мини-приложения.

Атрибут Тип Обязательно Описание Значение по умолчанию
Путь строка Да Относительный путь пакета к файлу изображения значка. Н/П

Снимки экрана

Обязательный. Указывает один или несколько снимков экрана мини-приложения.

Снимок экрана

Обязательный. Указывает снимок экрана для мини-приложения. На этом снимке экрана показано окно контейнера мини-приложений в диалоговом окне «Добавить мини-приложения», когда пользователь выбирает мини-приложения для добавления в контейнер мини-приложений. Если вы предоставите снимок экрана для необязательных элементов DarkMode или LightMode, перечисленных ниже, хост виджетов будет использовать снимок экрана, соответствующий текущей теме устройства. Если вы не предоставляете снимок экрана для текущей темы устройства, будет использоваться изображение, предоставленное в этом элементе снимка экрана . Сведения о требованиях к оформлению снимков экрана и правилах именования локализованных снимков экрана см. в разделе Интеграция со средством выбора мини-приложений.

Атрибут Тип Обязательно Описание Значение по умолчанию
Путь строка Да Относительный относительно пакета путь к файлу изображения снимка экрана. Н/П
DisplayAltText строка Нет Альтернативный текст для изображения, для обеспечения доступности. Н/П

Тёмный режим

Необязательно. Указывает ресурсы темы для того, когда на устройстве активен темный режим. Если в необязательном элементе DarkMode указать одно или несколько изображений снимков экрана, хост мини-приложений будет выбирать эти снимки экрана, если на устройстве включен темный режим. Если вы не предоставите изображение для тёмного режима, хост виджетов будет использовать обязательный элемент верхнего уровня Снимок экрана, описанный выше. Сведения о требованиях к оформлению снимков экрана и правилах именования локализованных снимков экрана приведены в разделе Интеграция со средством выбора мини-приложений.

LightMode

Необязательно. Указывает ресурсы темы для того, когда на устройстве активен световый режим. Если вы укажете одно или несколько изображений снимков экрана в необязательном элементе LightMode, хост виджетов будет выбирать эти снимки экрана, когда устройство находится в светлом режиме. Если вы не предоставите изображение для светлой темы, хост виджетов будет использовать обязательный корневой элемент Снимок экрана, описанный выше. Сведения о требованиях к оформлению снимков экрана и правилах именования локализованных снимков экрана см. в разделе Интеграция со средством выбора мини-приложений.

Пример

В следующем примере кода показан формат XML манифеста пакета мини-приложения.

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.widgets" DisplayName="Widget Test App" Id="ContosoWidgetApp" PublicFolder="Public">
    <uap3:Properties>
      <WidgetProvider>
        <ProviderIcons>
            <Icon Path="Images\StoreIcon.png" />
        </ProviderIcons>
        <Activation>
          <!-- App exports COM interface which implements IWidgetProvider -->
          <CreateInstance ClassId="XXXXXXXX-XXXX-XXXX-XXXX-D3397A3FF15C" />
        </Activation>
        <Definitions>
          <Definition
            Id="Weather_Widget"
            DisplayName="Microsoft Weather Widget"
            Description="Weather Widget Description"
            AdditionalInfoUri="https://contoso.com/widgets/Weather"
            ExclusiveRegions="US,UK"
            AllowMultiple="true">
            <Capabilities>
              <Capability>
                 <Size Name="small" />
              </Capability>
              <Capability>
                 <Size Name="medium" />
              </Capability>
              <Capability>
                 <Size Name="large" />
              </Capability>
            </Capabilities>

            <ThemeResources>
              <Icons>
                <Icon Path="Assets\icon.png" />
                <Icon Path="Assets\icon.gif" />
              </Icons>
              <Screenshots>
                <Screenshot Path="Assets\background.png" DisplayAltText ="For accessibility"/>
              </Screenshots>

              <!-- DarkMode and LightMode are optional -->
              <DarkMode>
                <Icons>
                  <Icon Path="Assets\dark.png" />
                </Icons>
                <Screenshots>
                  <Screenshot Path="Assets\darkBackground.png" DisplayAltText ="For accessibility"/>
                </Screenshots>
              </DarkMode>

              <LightMode>
                <Icons>
                  <Icon Path="Assets\light.png" />
                </Icons>
                <Screenshots>
                  <Screenshot Path="Assets\lightBackground.png"/>
                </Screenshots>
              </LightMode>
            </ThemeResources>
          </Definition>
        </Definitions>
      </WidgetProvider>
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>
  • Last updated on