Partager via

Format XML du manifeste du package du fournisseur de widgets

  • Article

Pour être affichées dans l’hôte de widgets, les applications qui prennent en charge les widgets Windows doivent inscrire leur fournisseur de widgets auprès du système. Pour les applications Win32, seules les applications empaquetées sont actuellement prises en charge, et les fournisseurs de widgets spécifient leurs informations d’inscription dans le fichier manifeste du package d’application. Cet article documente le format XML pour l’inscription des widgets. Consultez la section Exemple pour obtenir le code d’un exemple de manifeste de package pour un fournisseur de widgets Win32.

Extension d’application

Le fichier manifeste du package d’application prend en charge de nombreuses extensions et fonctionnalités différentes pour les applications Windows. Le format du manifeste du package d’application est défini par un ensemble de schémas documentés dans les Informations de référence sur le schéma du manifeste de package. Les fournisseurs de widgets déclarent leurs informations d’inscription dans uap3:AppExtension. L’attribut Name de l’extension doit être défini sur « com.microsoft.windows.widgets ».

Les fournisseurs de widgets doivent inclure uap3:Properties en tant qu’enfant de uap3:AppExtension. Le schéma de manifeste du package n’applique pas la structure de l’élément uap3:Properties, hormis l’exigence relative au code XML correctement formé. Le reste de cet article décrit le format XML attendu par l’hôte de widget pour inscrire correctement un fournisseur 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>

Hiérarchie d’éléments

WidgetProvider

  ProviderIcons

    Icon

  Activation

    CreateInstance

    ActivateApplication

  Définitions

    Définition

      Fonctions

        Fonctionnalité

          Taille

      ThemeResources

        Icônes

          Icon

        Captures d’écran

          Screenshot

        DarkMode

          Icônes

            Icon

          Captures d’écran

            Screenshot

        LightMode

          Icônes

            Icon

          Captures d’écran

            Screenshot

WidgetProvider

Élément racine des informations d’inscription du fournisseur de widgets.

Capture d’écran de la boîte de dialogue Ajouter un widget dans le tableau Widgets. Il affiche deux colonnes d’entrées, chacune avec une icône et un nom d’application, avec un signe plus indiquant qu’un widget peut être ajouté

WidgetProviderIcons

Spécifie les icônes représentant l’application fournisseur de widgets.

Activation

Spécifie les informations d’activation pour le fournisseur de widgets. Si CreateInstance et ActivateApplication sont tous deux spécifiés dans le manifeste, CreateInstance est prioritaire.

CreateInstance

CreateInstance doit être spécifié pour les fournisseurs de widgets win32 qui implémentent l’interface IWidgetProvider. Le système active l’interface avec un appel à CoCreateInstance. L’attribut ClassId spécifie le CLSID du serveur CreateInstance qui implémente l’interface IWidgetProvider.

Attribut Type Requise Description Valeur par défaut
ClassId GUID Oui CLSID du serveur CreateInstance qui implémente le fournisseur de widgets. S.O.

ActivateApplication

Lorsque ActivateApplication est spécifié, le fournisseur de widgets est activé via la ligne de commande, avec les arguments fournis sous forme de chaînes JSON encodées en base64url. Il est recommandé que les fournisseurs de widgets utilisent le type d’activation CreateInstance . Pour plus d’informations sur le format de ligne de commande ActivateApplication, consultez Protocole ActivateApplication du fournisseur de widgets.

Définitions

Élément conteneur pour une ou plusieurs inscriptions de widgets.

Définition

Représente l’inscription d’un widget unique.

Attribut Type Requise Description Valeur par défaut
Id string Oui ID qui identifie le widget. Cette valeur est également affichée dans la barre de navigation du sélecteur de widgets. Les implémentations de fournisseur de widgets utilisent cette chaîne pour déterminer ou spécifier les widgets de l’application qui sont référencés pour chaque opération. Cette chaîne doit être unique pour tous les widgets définis dans le fichier manifeste de l’application. S.O.
DisplayName string Oui Nom du widget affiché sur l’hôte de widgets. S.O.
Description string Oui Brève description du widget. S.O.
Allowmultiple booléen Non Affectez la valeur false si une seule instance de ce widget est prise en charge. Cet attribut est facultatif, et la valeur par défaut est true. true
IsCustomizable booléen Non Introduit dans le SDK d’application Windows 1.4. Affectez la valeur true si votre application prend en charge la personnalisation du widget. Cela entraîne l’affichage du bouton Personnaliser le widget dans le menu de points de suspension du widget. false
AdditionalInfoUri string Non URI qui peut être associé au widget à utiliser lorsque l’utilisateur clique sur la barre de titre du cadre du widget ou lorsque vous cliquez sur l’élément Optimisé par l’élément de son menu contextuel. N/A
ExcludedRegions string Non Liste des régions où le widget ne doit pas être disponible. Les widgets peuvent spécifier ExcludedRegions ou ExclusiveRegions , mais ne doivent pas spécifier les deux dans une définition de widget unique. La valeur de l’attribut est une liste séparée par des virgules de deux codes de région de caractères. N/A
ExclusiveRegions string Non Liste des seules régions où le widget doit être disponible. Les widgets peuvent spécifier ExcludedRegions ou ExclusiveRegions , mais ne doivent pas spécifier les deux dans une définition de widget unique. La valeur de l’attribut est une liste séparée par des virgules de deux codes de région de caractères. N/A

Fonctionnalités

facultatif. Spécifie les capacités d’un widget unique. Si aucune capacité n’est déclarée, une capacité spécifiant une taille « large » est ajoutée par défaut.

Fonctionnalité

Spécifie une capacité pour un widget.

Taille

Spécifie les tailles prises en charge pour le widget associé.

Attribut Type Requise Description Valeur par défaut
Nom string Oui Spécifie une taille prise en charge pour un widget. La valeur doit être l’une des suivantes : « small », « medium », « large » S.O.

ThemeResources

Spécifie des ressources de thème pour un widget.

Icônes

Élément conteneur pour un ou plusieurs éléments Icon.

Icon

Obligatoire. Spécifie une icône affichée dans la zone d’attribution du widget.

Attribut Type Requise Description Valeur par défaut
Chemin d’accès string Oui Chemin relatif au package d’un fichier image d’icône. S.O.

Captures d’écran

Obligatoire. Spécifie une ou plusieurs captures d’écran du widget.

Screenshot

Obligatoire. Spécifie une capture d’écran pour un widget. Cette capture d’écran s’affiche dans l’hôte de widgets dans la boîte de dialogue Ajouter des widgets lorsque l’utilisateur sélectionne des widgets à ajouter à l’hôte de widgets. Si vous fournissez une capture d’écran pour les éléments facultatifs DarkMode ou LightMode listés ci-dessous, l’hôte de widgets utilise la capture d’écran correspondant au thème de l’appareil actuel. Si vous ne fournissez pas de capture d’écran pour le thème de l’appareil actuel, l’image fournie dans cet élément Screenshot sera utilisée. Pour plus d’informations sur les exigences de conception pour les images de capture d’écran et les conventions de nommage des captures d’écran localisées, consultez Intégrer au sélecteur de widgets.

Remarque

Les captures d’écran du widget ne sont pas affichées dans la boîte de dialogue Ajouter des widgets du tableau de widgets dans la préversion actuelle.

Attribut Type Requise Description Valeur par défaut
Chemin d’accès string Oui Chemin relatif au package d’un fichier image de capture d’écran. S.O.
DisplayAltText string Non Texte de remplacement de l’image, à des fins d’accessibilité. S.O.

DarkMode

facultatif. Spécifie les ressources de thème applicables lorsque le mode sombre est actif sur l’appareil. Si vous spécifiez une ou plusieurs images de capture d’écran dans l’élément facultatif DarkMode, l’hôte de widgets sélectionne ces captures d’écran lorsque l’appareil est en mode sombre. Si vous ne fournissez pas d’image en mode sombre, l’hôte de widgets utilise l’élément Screenshot obligatoire de niveau supérieur décrit ci-dessus. Pour plus d’informations sur les exigences de conception pour les images de capture d’écran et les conventions de nommage des captures d’écran localisées, consultez Intégrer au sélecteur de widgets.

LightMode

facultatif. Spécifie les ressources de thème applicables lorsque le mode clair est actif sur l’appareil. Si vous fournissez une ou plusieurs images de capture d’écran dans l’élément facultatif LightMode, l’hôte de widgets sélectionne ces captures d’écran lorsque l’appareil est en mode clair. Si vous ne fournissez pas d’image en mode clair, l’hôte de widgets utilise l’élément Screenshot obligatoire de niveau supérieur décrit ci-dessus. Pour plus d’informations sur les exigences de conception pour les images de capture d’écran et les conventions de nommage des captures d’écran localisées, consultez Intégrer au sélecteur de widgets.

Exemple

L’exemple de code suivant illustre l’utilisation du format XML de manifeste du package de widget.

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