Compartir a través de

Formato XML del manifiesto de paquete del proveedor de widgets

  • Artículo

Para mostrarse en el host de widgets, las aplicaciones que admiten widgets de Windows deben registrar su proveedor de widgets en el sistema. En el caso de las aplicaciones Win32, actualmente solo se admiten aplicaciones empaquetadas y los proveedores de widgets especifican su información de registro en el archivo de manifiesto del paquete de la aplicación. En este artículo se documenta el formato XML para el registro de widgets. Consulte la sección Ejemplo para obtener una lista de código de un manifiesto de paquete de ejemplo para un proveedor de widgets win32.

Extensión de la aplicación

El archivo de manifiesto del paquete de aplicación admite muchas extensiones y características diferentes para las aplicaciones de Windows. El formato del manifiesto de paquete de la aplicación se define mediante un conjunto de esquemas que se documentan en la referencia del esquema del manifiesto del paquete. Los proveedores de widgets declaran su información de registro en uap3:AppExtension. El atributo Name de la extensión debe establecerse en "com.microsoft.windows.widgets".

Los proveedores de widgets deberían incluir uap3:Properties como elemento secundario de uap3:AppExtension. El esquema del manifiesto de paquete no aplica la estructura del elemento uap3:Properties que no requiera XML con formato correcto. En el resto de este artículo se describe el formato XML que el host de widget espera para registrar correctamente un proveedor de widgets.

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

Jerarquía de elementos

WidgetProvider

  ProviderIcons

    Iconos

  Activación

    CreateInstance

    ActivateApplication

  Definiciones

    Definición

      Funcionalidades

        Funcionalidad

          Size

      ThemeResources

        Iconos

          Iconos

        Capturas de pantalla

          Captura de pantalla

        DarkMode

          Iconos

            Iconos

          Capturas de pantalla

            Captura de pantalla

        LightMode

          Iconos

            Iconos

          Capturas de pantalla

            Captura de pantalla

WidgetProvider

Elemento raíz de la información de registro del proveedor del widget.

Captura de pantalla del cuadro de diálogo Agregar widget en el panel Widgets. Muestra dos columnas de entradas, cada una con un icono y un nombre de aplicación, con un signo más que indica que se puede agregar un widget.

WidgetProviderIcons

Especifica iconos que representan la aplicación del proveedor de widgets.

Activación

Especifica información de activación para el proveedor de widgets. Si se especifican CreateInstance y ActivateApplication en el manifiesto, CreateInstance tiene prioridad.

CreateInstance

Se debe especificar CreateInstance para los proveedores de widgets basados en Win32 que implementan la interfaz IWidgetProvider. El sistema activará la interfaz con una llamada a CoCreateInstance. El atributo ClassId especifica el CLSID para el servidor CreateInstance que implementa la interfaz IWidgetProvider.

Atributo Tipo Obligatorio Descripción Valor predeterminado
ClassId GUID Sí CLSID del servidor CreateInstance que implementa el proveedor de widgets. N/D

ActivateApplication

Cuando se especifica ActivateApplication, el proveedor de widgets se activa a través de la línea de comandos con los argumentos proporcionados como cadenas JSON codificadas en base64url. Se recomienda que los proveedores de widgets usen el tipo de activación CreateInstance . Para obtener información sobre el formato de línea de comandos ActivateApplication, consulte Protocolo ActivateApplication del proveedor de widgets.

Definiciones

Elemento contenedor para uno o varios registros de widgets.

Definición

Representa el registro de un único widget.

Atributo Tipo Obligatorio Descripción Valor predeterminado
Id string Sí Identificador que identifica el widget. Este valor también se muestra en la barra de navegación del selector de widgets. Las implementaciones del proveedor de widgets usan esta cadena para determinar o especificar a qué widgets de la aplicación se hace referencia para cada operación. Esta cadena debe ser única para todos los widgets definidos en el archivo de manifiesto de la aplicación. N/D
DisplayName cadena Sí Nombre del widget que se muestra en el host de widgets. N/D
Descripción string Sí Descripción breve del widget. N/D
AllowMultiple boolean No Se establece en false si solo se admite una instancia de este widget. Este atributo es opcional y el valor predeterminado es verdadero. true
IsCustomizable boolean No Introducido en el SDK 1.4 de aplicaciones para Windows. Establézcalo en verdadero si la aplicación admite la personalización de widgets. Esto hace que el botón Personalizar widget se muestre en el menú de puntos suspensivos del widget. false
AdditionalInfoUri string No URI que se puede asociar al widget que se va a usar cuando el usuario hace clic en la barra de título del marco del widget o al hacer clic en el elemento Powered by de su menú contextual. N/D
ExcludedRegions string No Lista de regiones en las que el widget no debe estar disponible. Los widgets pueden especificar ExcludedRegions o ExclusiveRegions, pero no deben especificar ambos en una sola definición de widget. El valor del atributo es una lista separada por comas de dos códigos de región de caracteres. N/D
ExclusiveRegions string No Lista de las únicas regiones en las que el widget debe estar disponible. Los widgets pueden especificar ExcludedRegions o ExclusiveRegions, pero no deben especificar ambos en la definición de widget único. El valor del atributo es una lista separada por comas de dos códigos de región de caracteres. N/D

Funcionalidades

Opcional. Especifica las funcionalidades de un único widget. Si no se declara ninguna funcionalidad, se agregará de forma predeterminada una funcionalidad que especifica un tamaño "grande".

Funcionalidad

Especifica una funcionalidad para un widget.

Size

Especifica los tamaños admitidos para el widget asociado.

Atributo Tipo Obligatorio Descripción Valor predeterminado
Nombre string Sí Especifica un tamaño admitido para un widget. El valor debe ser uno de los siguientes: "pequeño", "medio" o "grande" N/D

ThemeResources

Especifica los recursos de tema de un widget.

Iconos

Elemento contenedor para uno o varios elementos Icono.

Iconos

Necesario. Especifica un icono que se muestra en el área de atribución del widget.

Atributo Tipo Obligatorio Descripción Valor predeterminado
Path cadena Sí Ruta de acceso relativa al paquete a un archivo de imagen de icono. N/D

Capturas de pantalla

Necesario. Especifica una o varias capturas de pantalla del widget.

Captura de pantalla

Necesario. Especifica una captura de pantalla de un widget. Esta captura de pantalla se muestra en el host de widgets en el cuadro de diálogo Agregar widgets cuando el usuario selecciona widgets para agregar al host de widgets. Si proporciona una captura de pantalla para los elementos opcionales DarkMode o LightMode que se enumeran a continuación, el host de widgets usará la captura de pantalla que coincida con el tema del dispositivo actual. Si no proporciona una captura de pantalla para el tema del dispositivo actual, se usará la imagen proporcionada en este elemento Captura de pantalla. Para obtener información sobre los requisitos de diseño de las imágenes de las capturas de pantalla y las convenciones de nomenclatura para las capturas de pantalla localizadas, consulte Integración con el selector de widgets.

Nota:

Las capturas de pantalla del widget no se muestran en el cuadro de diálogo Agregar widgets del panel de widgets en la versión preliminar actual.

Atributo Tipo Obligatorio Descripción Valor predeterminado
Path cadena Sí Ruta de acceso relativa al paquete a un archivo de imagen de captura de pantalla. N/D
DisplayAltText cadena No Texto alternativo de la imagen, para accesibilidad. N/D

DarkMode

Opcional. Especifica los recursos del tema para cuando el modo oscuro está activo en el dispositivo. Si se especifica una o varias imágenes de captura de pantalla en el elemento DarkMode opcional, el host de widgets seleccionará estas capturas de pantalla cuando el dispositivo esté en modo oscuro. Si no se proporciona una imagen en modo oscuro, el host de widgets usará el elemento Captura de pantalla de nivel superior necesario descrito anteriormente. Para obtener información sobre los requisitos de diseño de las imágenes de las capturas de pantalla y las convenciones de nomenclatura para las capturas de pantalla localizadas, consulte Integración con el selector de widgets.

LightMode

Opcional. Especifica los recursos del tema para cuando el modo claro está activo en el dispositivo. Si se proporciona una o varias imágenes de captura de pantalla en el elemento LightMode opcional, el host de widgets seleccionará estas capturas de pantalla cuando el dispositivo esté en modo claro. Si no se proporciona una imagen en modo claro, el host de widgets usará el elemento Captura de pantalla de nivel superior necesario descrito anteriormente. Para obtener información sobre los requisitos de diseño de las imágenes de las capturas de pantalla y las convenciones de nomenclatura para las capturas de pantalla localizadas, consulte Integración con el selector de widgets.

Ejemplo

En el ejemplo de código siguiente, se muestra el uso del formato XML del manifiesto de paquete 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>