Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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
Anbietersymbole
Symbol
Aktivierung
CreateInstance
Anwendung aktivieren
Definitionen
Definition
Funktionen
Fähigkeit
Größe
ThemeResources
Symbole
Symbol
Bildschirmfotos
Screenshot
Dunkelmodus
Symbole
Symbol
Bildschirmfotos
Screenshot
LightMode
Symbole
Symbol
Bildschirmfotos
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.
| Attribut | Typ | Erforderlich | Beschreibung | Standardwert |
|---|---|---|---|---|
| ClassId | GUID | Ja | Die CLSID für den CreateInstance-Server, der den Widgetanbieter implementiert. | Nicht zutreffend |
Anwendung aktivieren
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 Container-Element für eine oder mehrere Widget-Registrierungen.
Definition
Stellt die Registrierung für ein einzelnes Widget dar.
| Attribut | 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 | Nein | 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. | Nicht zutreffend |
| Ausgeschlossene Regionen | Zeichenfolge | Nein | 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. | Nicht zutreffend |
| ExclusiveRegions | Zeichenfolge | Nein | 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. | Nicht zutreffend |
| WebRequestFilter | Zeichenfolge | Nein | Gibt den Filter an, der die URLs der Ressourcenanforderungen festlegt, für die die Anforderung abgefangen und an die Implementierung von IWidgetResourceProvider.OnResourceRequested des Widgetanbieters umgeleitet wird. Das Filtermuster wird mit dem in Übereinstimmungsmustern beschriebenen Format ausgedrückt. Die Filterzeichenfolge in der Registrierung muss bei Bedarf Punycode verwenden. Die Filterzeichenfolge muss mit dem Ursprung der Widgetregistrierung übereinstimmen, die im WebUrl-Feld des adaptiven Karteninhalts angegeben ist. | Nicht zutreffend |
Funktionen
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.
Fähigkeit
Gibt eine Funktion für ein Widget an.
Größe
Gibt unterstützte Größen für das zugeordnete Widget an.
| Attribut | 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.
| Attribut | Typ | Erforderlich | Beschreibung | Standardwert |
|---|---|---|---|---|
| Path | Zeichenfolge | Ja | Der paketrelative Pfad zu einer Symbolbilddatei. | Nicht zutreffend |
Bildschirmfotos
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.
| Attribut | 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 |
Dunkelmodus
Optional. Legt Theme-Ressourcen für den Fall fest, dass auf dem Gerät der Dark Mode aktiviert 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 Themenressourcen an, wenn auf dem Gerät der helle Modus 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>
Zusammenarbeit auf GitHub
Die Quelle für diesen Inhalt finden Sie auf GitHub, wo Sie auch Issues und Pull Requests erstellen und überprüfen können. Weitere Informationen finden Sie in unserem Leitfaden für Mitwirkende.
Windows developer