Freigeben über

XML-Format des Widgetanbieter-Paketmanifests

  • Artikel

Um auf dem Widgethost angezeigt zu werden, müssen Apps, die Windows-Widgets unterstützen, ihren Widgetanbieter beim System registrieren. Für Win32-Apps werden derzeit nur gepackte Apps unterstützt, und Widgetanbieter geben ihre Registrierungsinformationen in der App-Paketmanifestdatei an. In diesem Artikel wird das XML-Format für die Widgetregistrierung dokumentiert. Im Abschnitt Beispiel finden Sie eine Codeliste eines Beispielpaketmanifests für einen Win32-Widgetanbieter.

App-Erweiterung

Die App-Paketmanifestdatei unterstützt viele verschiedene Erweiterungen und Features für Windows-Apps. Das Format des App-Paketmanifests wird durch eine Reihe von Schemas definiert, die in der Paketmanifestschemareferenz dokumentiert sind. Widgetanbieter deklarieren ihre Registrierungsinformationen in uap3:AppExtension. Das Name-Attribut der Erweiterung muss auf „com.microsoft.windows.widgets“ festgelegt werden.

Widgetanbieter sollten uap3:Properties als untergeordnetes Element von uap3:AppExtension einschließen. Das Paketmanifestschema erzwingt nicht die Struktur des uap3:Properties-Elements, außer dass wohlgeformte XML-Dateien erforderlich sind. Im weiteren Verlauf dieses Artikels wird das XML-Format beschrieben, das der Widgethost erwartet, um einen Widgetanbieter erfolgreich zu registrieren.

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

Elementhierarchie

WidgetProvider

  ProviderIcons

    Symbol

  Aktivierung

    CreateInstance

    ActivateApplication

  Definitionen

    Definition

      Funktionen

        Funktion

          Size

      ThemeResources

        Symbole

          Symbol

        Screenshots

          Screenshot

        DarkMode

          Symbole

            Symbol

          Screenshots

            Screenshot

        LightMode

          Symbole

            Symbol

          Screenshots

            Screenshot

WidgetProvider

Das Stammelement der Registrierungsinformationen des Widgetanbieters.

Screenshot des Dialogfelds

WidgetProviderIcons

Gibt Symbole an, die die Widgetanbieter-App darstellen.

Aktivierung

Gibt Aktivierungsinformationen für den Widgetanbieter an. Wenn sowohl CreateInstance als auch ActivateApplication im Manifest angegeben sind, hat CreateInstance Vorrang.

CreateInstance

CreateInstance sollte für Win32-basierte Widgetanbieter angegeben werden, die die IWidgetProvider-Schnittstelle implementieren. Das System aktiviert die Schnittstelle mit einem Aufruf von CoCreateInstance. Das ClassId-Attribut gibt die CLSID für den CreateInstance-Server an, der die IWidgetProvider-Schnittstelle implementiert.

attribute Typ Erforderlich Beschreibung Standardwert
ClassId GUID Ja Die CLSID für den CreateInstance-Server, der den Widgetanbieter implementiert. Nicht zutreffend

ActivateApplication

Wenn ActivateApplication angegeben ist, wird der Widgetanbieter über die Befehlszeile aktiviert, wobei die Argumente als base64url-codierte JSON-Zeichenfolgen bereitgestellt werden. Es wird empfohlen, dass Widgetanbieter den CreateInstance-Aktivierungstyp verwenden. Informationen zum Befehlszeilenformat ActivateApplication finden Sie unter ActivateApplication-Protokoll des Widgetanbieters.

Definitionen

Das Containerelement für mindestens eine Widgetregistrierung.

Definition

Stellt die Registrierung für ein einzelnes Widget dar.

attribute Typ Erforderlich Beschreibung Standardwert
Id Zeichenfolge Ja Eine eindeutige ID, die das Widget identifiziert. Dieser Wert wird auch in der Navigationsleiste der Widgetauswahl angezeigt. Widgetanbieterimplementierungen verwenden diese Zeichenfolge, um zu bestimmen oder anzugeben, auf welche der Widgets der App bei den einzelnen Vorgängen verwiesen wird. Diese Zeichenfolge muss für alle in der App-Manifestdatei definierten Widgets eindeutig sein. Nicht zutreffend
DisplayName Zeichenfolge Ja Der Name des Widgets, der auf dem Widgethost angezeigt wird. Nicht zutreffend
Beschreibung Zeichenfolge Ja Eine kurze Beschreibung des Widgets. Nicht zutreffend
AllowMultiple boolean Nein Legen Sie dies auf false fest, wenn nur eine Instanz dieses Widgets unterstützt wird. Dieses Attribut ist optional, und der Standardwert ist true. true
IsCustomizable boolean Nein Eingeführt in Windows App SDK 1.4. Auf true festgelegt, wenn Ihre App Widgetanpassungen unterstützt. Dies bewirkt, dass die Schaltfläche Widget anpassen im Menü mit den Auslassungspunkten des Widgets angezeigt wird. false
AdditionalInfoUri Zeichenfolge No Ein URI, der dem Widget zugeordnet werden kann, der verwendet werden kann, wenn der Benutzer auf die Titelleiste des Widgetframes klickt oder wenn er auf das Element "Powered by " des Kontextmenüs klickt. N/V
Ausgeschlossene Regionen Zeichenfolge No Eine Liste der Regionen, in denen das Widget nicht verfügbar sein sollte. Widgets können "ExcludedRegions" oder "ExclusiveRegions" angeben, dürfen jedoch nicht beide in einer einzelnen Widgetdefinition angeben. Der Wert des Attributs ist eine durch Trennzeichen getrennte Liste mit zwei Zeichenbereichscodes. N/V
ExclusiveRegions Zeichenfolge No Eine Liste der einzigen Regionen, in denen das Widget verfügbar sein soll. Widgets können "ExcludedRegions" oder "ExclusiveRegions" angeben, dürfen jedoch nicht beide in einer einzelnen Widgetdefinition angeben. Der Wert des Attributs ist eine durch Trennzeichen getrennte Liste mit zwei Zeichenbereichscodes. N/V

Capabilities

Optional. Gibt die Funktionen für ein einzelnes Widget an. Wenn keine Funktionen deklariert sind, wird standardmäßig eine Funktion hinzugefügt, die eine „große“ Größe angibt.

Funktion

Gibt eine Funktion für ein Widget an.

Size

Gibt unterstützte Größen für das zugeordnete Widget an.

attribute Typ Erforderlich Beschreibung Standardwert
Name Zeichenfolge Ja Gibt eine unterstützte Größe für ein Widget an. Der Wert muss einer der folgenden sein: „small“ (klein), „medium“ (mittel), „large“ (groß) Nicht zutreffend

ThemeResources

Gibt Designressourcen für ein Widget an.

Symbole

Ein Containerelement für mindestens ein Icon-Element.

Symbol

Erforderlich. Gibt ein Symbol an, das im Zuordnungsbereich des Widgets angezeigt wird.

attribute Typ Erforderlich Beschreibung Standardwert
Path Zeichenfolge Ja Der paketrelative Pfad zu einer Symbolbilddatei. Nicht zutreffend

Screenshots

Erforderlich. Gibt mindestens einen Screenshot des Widgets an.

Screenshot

Erforderlich. Gibt einen Screenshot für ein Widget an. Dieser Screenshot wird im Widgets-Host im Dialogfeld Widgets hinzufügen angezeigt, wenn der Benutzer Widgets zum Hinzufügen zum Host für Widgets auswählt. Wenn Sie einen Screenshot für die unten aufgeführten optionalen Elemente DarkMode oder LightMode bereitstellen, verwendet der Widgets-Host den Screenshot, der dem aktuellen Gerätedesign entspricht. Wenn Sie keinen Screenshot für das aktuelle Gerätedesign bereitstellen, wird das in diesem Screenshot-Element bereitgestellte Bild verwendet. Informationen zu den Entwurfsanforderungen für Screenshots und den Benennungskonventionen für lokalisierte Screenshots finden Sie unter Integrieren in die Widgetauswahl.

Hinweis

Die Widget-Screenshots werden in der aktuellen Vorschauversion nicht im Dialogfeld „Widgets hinzufügen“ des Widgetboards angezeigt.

attribute Typ Erforderlich Beschreibung Standardwert
Path Zeichenfolge Ja Der paketrelative Pfad zu einer Screenshotbilddatei. Nicht zutreffend
DisplayAltText Zeichenfolge Nein Der Alt-Text für das Bild, um Barrierefreiheit zu gewährleisten. Nicht zutreffend

DarkMode

Optional. Gibt Designressourcen an, wenn der dunkle Modus auf dem Gerät aktiv ist. Wenn Sie ein oder mehrere Screenshotbilder im optionalen DarkMode-Element angeben, wählt der Widgets-Host diese Screenshots aus, wenn sich das Gerät im dunklen Modus befindet. Wenn Sie kein Bild für den dunklen Modus bereitstellen, verwendet der Widgethost das oben beschriebene erforderliche Screenshot-Element der obersten Ebene. Informationen zu den Entwurfsanforderungen für Screenshots und den Benennungskonventionen für lokalisierte Screenshots finden Sie unter Integrieren in die Widgetauswahl.

LightMode

Optional. Gibt Designressourcen an, wenn der helle Modus auf dem Gerät aktiv ist. Wenn Sie ein oder mehrere Screenshotbilder im optionalen LightMode-Element angeben, wählt der Widgets-Host diese Screenshots aus, wenn sich das Gerät im hellen Modus befindet. Wenn Sie kein Bild für den hellen Modus bereitstellen, verwendet der Widgethost das oben beschriebene erforderliche Screenshot-Element der obersten Ebene. Informationen zu den Entwurfsanforderungen für Screenshots und den Benennungskonventionen für lokalisierte Screenshots finden Sie unter Integrieren in die Widgetauswahl.

Beispiel

Im folgenden Codebeispiel wird die Verwendung des XML-Formats des Widgetpaketmanifests veranschaulicht.

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