XML-Format des Widgetanbieter-Paketmanifests
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.
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 |
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"
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>
Windows developer
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter: https://aka.ms/ContentUserFeedback.
Einreichen und Feedback anzeigen für