Compartilhar via

Formato XML do manifesto do pacote do provedor de widget

  • Artigo

Para serem exibidos no host de widgets, os aplicativos que dão suporte aos widgets do Windows precisam registrar o provedor de widget no sistema. Nos aplicativos Win32, atualmente, só há suporte para aplicativos empacotados, e os provedores de widget especificam as informações de registro no arquivo de manifesto do pacote do aplicativo. Este artigo documenta o formato XML para o registro de widget. Confira a seção Exemplo para ver uma listagem de código de um exemplo de manifesto do pacote para um provedor de widgets do Win32.

Extensão de aplicativo

O arquivo de manifesto do pacote do aplicativo dá suporte a várias extensões e recursos diferentes para aplicativos do Windows. O formato do manifesto do pacote do aplicativo é definido por um conjunto de esquemas documentados na Referência de esquemas de manifesto do pacote. Os provedores de widgets declaram as informações de registro no uap3:AppExtension. O atributo Name da extensão precisa ser definido como “com.microsoft.windows.widgets”.

Os provedores de widgets devem incluir uap3:Properties como o filho de uap3:AppExtension. O esquema de manifesto do pacote não impõe a estrutura do elemento uap3:Properties, a não ser a exigência de um XML bem formado. O restante deste artigo descreve o formato XML esperado pelo host Widget para registrar um provedor de widgets com sucesso.

<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>

Hierarquia de elementos

WidgetProvider

  ProviderIcons

    Ícone

  Ativação

    CreateInstance

    ActivateApplication

  Definições

    Definição

      Funcionalidades

        Recurso

          Tamanho

      ThemeResources

        Ícones

          Ícone

        Capturas de tela

          Captura de tela

        DarkMode

          Ícones

            Ícone

          Capturas de tela

            Captura de tela

        LightMode

          Ícones

            Ícone

          Capturas de tela

            Captura de tela

WidgetProvider

O elemento raiz das informações de registro do provedor de widgets.

Uma captura de tela da caixa de diálogo Adicionar widget no quadro Widgets. Ele mostra duas colunas de entradas, cada uma com um ícone e um nome de aplicativo, com um sinal de mais indicando que um widget pode ser adicionado

WidgetProviderIcons

Especifica ícones que representam o aplicativo do provedor de widgets.

Ativação

Especifica informações de ativação do provedor de widgets. Se CreateInstance e ActivateApplication forem especificados no manifesto, CreateInstance terá precedência.

CreateInstance

CreateInstance deve ser especificado para provedores de widgets baseados no Win32 que implementam a interface IWidgetProvider. O sistema ativará a interface com uma chamada a CoCreateInstance. O atributo ClassId especifica o CLSID para o servidor CreateInstance que implementa a interface IWidgetProvider.

Atributo Tipo Obrigatória Descrição Valor padrão
ClassId GUID Sim O CLSID do servidor CreateInstance que implementa o provedor de widgets. N/D

ActivateApplication

Quando ActivateApplication é especificado, o provedor de widgets é ativado por meio da linha de comando, com os argumentos fornecidos como cadeias de caracteres JSON codificadas em base64url. É recomendável que os provedores de widget usem o tipo de ativação CreateInstance . Para obter informações sobre o formato de linha de comando ActivateApplication, confira o Protocolo ActivateApplication do provedor de widgets.

Definições

O elemento de contêiner de um ou mais registros de widget.

Definição

Representa o registro de um só widget.

Atributo Tipo Obrigatória Descrição Valor padrão
Id cadeia de caracteres Sim Uma ID que identifica o widget. Esse valor também é exibido na barra de navegação do seletor de widgets. As implementações do provedor de widgets usam essa cadeia de caracteres para determinar ou especificar os widgets do aplicativo que estão sendo referenciados para cada operação. Essa cadeia de caracteres precisa ser exclusiva para todos os widgets definidos no arquivo de manifesto do aplicativo. N/D
DisplayName string Sim O nome do widget exibido no host de widgets. N/D
Descrição string Sim Descrição curta do widget. N/D
AllowMultiple boolean Não Defina-o como false se houver suporte apenas para uma instância desse widget. Esse atributo é opcional, e o valor padrão é true. true
IsCustomizable boolean Não Introduzido no SDK 1.4 do Aplicativo Windows. Defina-o como true se o aplicativo der suporte à personalização de widgets. Isso faz com que o botão Personalizar widget seja exibido no menu de reticências do widget. false
AdditionalInfoUri string Não Um URI que pode ser associado ao widget a ser usado quando o usuário clica na barra de título do quadro do widget ou ao clicar no elemento Powered by de seu menu de contexto. N/D
Regiões Excluídas string Não Uma lista de regiões onde o widget não deve estar disponível. Os widgets podem especificar ExcludedRegions ou ExclusiveRegions, mas não devem especificar ambos em uma única definição de widget. O valor do atributo é uma lista separada por vírgulas de dois códigos de região de caracteres. N/D
Regiões Exclusivas string Não Uma lista das únicas regiões onde o widget deve estar disponível. Os widgets podem especificar ExcludedRegions ou ExclusiveRegions, mas não devem especificar ambos na definição de widget único. O valor do atributo é uma lista separada por vírgulas de dois códigos de região de caracteres. N/D

Funcionalidades

Opcional. Especifica as funcionalidades de um só widget. Se nenhuma funcionalidade for declarada, uma funcionalidade que especifica um tamanho “grande” será adicionada por padrão.

Recurso

Especifica uma funcionalidade para um widget.

Tamanho

Especifica os tamanhos com suporte para o widget associado.

Atributo Tipo Obrigatória Descrição Valor padrão
Nome string Sim Especifica um tamanho com suporte para um widget. O valor precisa ser um dos seguintes: “pequeno”, “médio” ou “grande” N/D

ThemeResources

Especifica recursos de tema para um widget.

Ícones

Um elemento de contêiner de um ou mais elementos Icon.

Ícone

Obrigatório. Especifica um ícone que é exibido na área de atribuição do widget.

Atributo Tipo Obrigatória Descrição Valor padrão
Caminho string Sim O caminho relativo ao pacote para um arquivo de imagem de ícone. N/D

Capturas de tela

Obrigatório. Especifica uma ou mais capturas de tela do widget.

Captura de tela

Obrigatório. Especifica uma captura de tela para um widget. Essa captura de tela é mostrada no host de widgets na caixa de diálogo Adicionar Widgets quando o usuário seleciona widgets para adicionar ao host de widgets. Se você fornecer uma captura de tela para os elementos opcionais DarkMode ou LightMode listados abaixo, o host de widgets usará a captura de tela que corresponde ao tema atual do dispositivo. Se você não fornecer uma captura de tela para o tema atual do dispositivo, a imagem fornecida neste elemento Screenshot será usada. Para obter informações sobre os requisitos de design de imagens de captura de tela e as convenções de nomenclatura de capturas de tela localizadas, confira Integrar com o seletor de widget.

Observação

As capturas de tela do widget não são exibidas na caixa de diálogo Adicionar Widgets do quadro de widgets na versão prévia atual.

Atributo Tipo Obrigatória Descrição Valor padrão
Caminho string Sim O caminho relativo ao pacote para um arquivo de imagem de captura de tela. N/D
DisplayAltText string Não O texto Alt da imagem, para fins de acessibilidade. N/D

DarkMode

Opcional. Especifica recursos de tema para quando o modo escuro está ativo no dispositivo. Se você especificar uma ou mais imagens de captura de tela no elemento opcional DarkMode, o host de widgets selecionará essas capturas de tela quando o dispositivo estiver no modo escuro. Se você não fornecer uma imagem de modo escuro, o host de widgets usará o elemento Screenshot de nível superior obrigatório descrito acima. Para obter informações sobre os requisitos de design de imagens de captura de tela e as convenções de nomenclatura de capturas de tela localizadas, confira Integrar com o seletor de widget.

LightMode

Opcional. Especifica recursos de tema para quando o modo claro está ativo no dispositivo. Se você fornecer uma ou mais imagens de captura de tela no elemento opcional LightMode, o host de widgets selecionará essas capturas de tela quando o dispositivo estiver no modo claro. Se você não fornecer uma imagem de modo claro, o host de widgets usará o elemento Screenshot de nível superior obrigatório descrito acima. Para obter informações sobre os requisitos de design de imagens de captura de tela e as convenções de nomenclatura de capturas de tela localizadas, confira Integrar com o seletor de widget.

Exemplo

O exemplo de código a seguir ilustra o uso do formato XML do manifesto do pacote de widgets.

<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>