Anzeigen eines PWA-Widgets im Windows Widgets Board

Verschiedene Betriebssysteme verfügen über Widgets und Dashboards, mit denen Benutzer Inhalte lesen und Aufgaben ausführen können. Beispiele hierfür sind Android-Startbildschirm-Widgets, macOS-Dashboard- und Heute-Panel-Widgets, die Apple Touch Bar, Samsung Daily Cards, Mini-App-Widgets und Smartwatch-App-Begleiter.

Unter Windows 11 erscheinen Widgets im Widgetboard , das Sie von der linken Seite der Taskleiste aus öffnen:

In Windows 11 können progressive Web-Apps (PWAs) Widgets definieren, aktualisieren und Benutzerinteraktionen darin verarbeiten.

Erfordert die Erstellung eines benutzerdefinierten Widgets für PWA

Eine vorhandene PWA kann nicht einfach unverändert in das Widget-Dashboard eingefügt werden, wie dies bei der Microsoft Edge-Randleiste möglich ist. Stattdessen müssen Sie eine benutzerdefinierte Widgeterfahrung erstellen, die für den Widgethost geeignet ist, bei dem es sich derzeit um das Windows 11 Widgets Board handelt. (Möglicherweise gibt es in Zukunft weitere Widgethosts.) Das Windows 11 Widgets Board erfordert, dass Widgets mithilfe von adaptiven Kartenvorlagen anstelle von HTML und JavaScript erstellt werden, sodass das Widget separat vom Rest der App-Benutzeroberfläche entworfen werden muss.

Siehe auch:

• Erstellen einer PWA für die Randleiste in Microsoft Edge

Um ein PWA-gesteuertes Widget zu erstellen und über den Microsoft Store bereitzustellen, ist kein C++/C#-Code erforderlich. Sobald Sie das Widget erstellt haben und das Widget erfolgreich von einem öffentlichen Endpunkt aus installieren und ausführen können, können Sie die App unter Verwendung von PWABuilder.com verpacken und an den Microsoft Store senden, ohne dass zusätzlicher Code erforderlich ist. Die PWA, die das Widget unterstützt, muss von einem öffentlichen Endpunkt aus installiert werden können, da PWABuilder das Packen von Apps aus localhostnicht unterstützt.

Siehe auch:

• Veröffentlichen einer PWA im Microsoft Store

Installieren des WinAppSDK und Aktivieren des Entwicklermodus

So aktivieren Sie das Entwickeln und Testen von Widgets auf Ihrem lokalen Computer:

• Installieren Sie WinAppSDK 1.2.

• Aktivieren Sie den Entwicklermodus in Windows 11:

  1. Öffnen Sie die Einstellungen.

  2. Geben Sie im Textfeld Einstellung suchen den Text developerein, und klicken Sie dann auf Entwicklerfeatures verwenden.

  3. Entwicklermodus aktivieren:

     

Definieren von Widgets

Widgets werden in Ihrer PWA-Manifestdatei mithilfe des widgets Manifestmitglieds definiert. Dieses Manifestelement ist ein Array, das mehrere Widgetdefinitionen enthalten kann.

{
  "name": "PWAmp",
  "description": "A music player app",
  "icons": [
    { "src": "img/icon-96.png", "sizes": "96x96" },
    { "src": "img/icon-128.png", "sizes": "128x128" },
    { "src": "img/icon-256.png", "sizes": "256x256" },
    { "src": "img/icon-512.png", "sizes": "512x512" }
  ],
  "widgets": [
    /* widget definitions go here */
  ]
}

Jeder Eintrag im widgets Array enthält mehrere Felder, wie unten dargestellt:

{
  ...
  "widgets": [
    {
      "name": "PWAmp mini player",
      "description": "widget to control the PWAmp music player",
      "tag": "pwamp",
      "template": "pwamp-template",
      "ms_ac_template": "widgets/mini-player-template.json",
      "data": "widgets/mini-player-data.json",
      "type": "application/json",
      "screenshots": [
        {
          "src": "./screenshot-widget.png",
          "sizes": "600x400",
          "label": "The PWAmp mini-player widget"
        }
      ],
      "icons": [
        {
          "src": "./favicon-16.png",
          "sizes": "16x16"
        }
      ],
      "auth": false,
      "update": 86400
    }
  ]
}

Im obigen Beispiel definiert eine Musikplayeranwendung ein Miniplayer-Widget. Eine Widgetdefinition im Web-App-Manifest verfügt über die folgenden erforderlichen und optionalen Felder:

Definieren einer Widgetvorlage

Um Widgets einfach zu erstellen und an verschiedene Betriebssystem-Widget-Dashboards anzupassen, werden sie mithilfe von Vorlagen angezeigt. Es gibt zwei Arten von Vorlagen:

• Generische Vorlagen, definiert durch ihre Namen mithilfe des template Felds.
• Benutzerdefinierte Vorlagen, die durch ihre URLs mithilfe eines benutzerdefinierten Vorlagenfelds definiert werden.

Derzeit werden nur benutzerdefinierte Vorlagen für adaptive Karten unterstützt. Adaptive Karten sind ein offenes Format für den Austausch von Karten, das verwendet werden kann, um Benutzeroberflächeninhalte auf gemeinsame und konsistente Weise auszutauschen. Siehe Übersicht über adaptive Karten.

Um eine benutzerdefinierte Vorlage für adaptive Karten unter Windows 11 zu definieren, verwenden Sie das ms_ac_template Feld in der Widgetdefinition in Ihrem Web-App-Manifest. Obwohl template es derzeit nicht verwendet wird, ist es ein Pflichtfeld.

{
  ...
  "template": "pwamp-template",
  "ms_ac_template": "widgets/mini-player.json",
  ...
}

Der ms_ac_template Feldwert sollte eine gültige URL einer Vorlagendatei sein.

Hier ist ein Beispiel für eine Vorlage für adaptive Karten:

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "text": "Now playing...",
      "horizontalAlignment": "Center"
    },
    {
      "type": "TextBlock",
      "spacing": "Large",
      "weight": "Bolder",
      "horizontalAlignment": "Center",
      "text": "${song}, by ${artist}",
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5"
}

Weitere Informationen finden Sie unter Vorlagen für adaptive Karten.

Als Nächstes müssen Sie Daten an Ihre Vorlage binden.

Binden von Daten an Ihre Vorlage

Die Vorlage deklariert die Benutzeroberfläche eines Widgets. Diese Benutzeroberfläche wird dann von Daten ausgefüllt.

Um Daten an Ihre Vorlage zu binden, verwenden Sie das data Feld in Ihrer Widgetdefinition. Dieses Feld sollte auf eine URL festgelegt sein, die gültige JSON-Daten zurückgibt.

Die im vorherigen Abschnitt definierte Vorlage enthält zwei Variablen: song und artist, die in der Syntax des Bindungsausdrucks enthalten sind: ${}. Die Daten, die von der data URL in Ihrer Widgetdefinition zurückgegeben werden, sollten Werte für diese Variablen enthalten.

Hier ist ein Beispiel für die data URL:

{
  "song": "I Will Always Love You",
  "artist": "Whitney Houston"
}

Definieren von Widgetaktionen

Wenn Sie möchten, dass Ihr Widget Benutzern das Ausführen von Aufgaben ermöglicht, definieren Sie eine Vorlage, die Aktionen unterstützt.

Hier sehen Sie ein Beispiel für eine Aktion, die in einer benutzerdefinierten Vorlage für adaptive Karten definiert ist:

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "text": "Now playing...",
      "horizontalAlignment": "Center"
    },
    {
      "type": "TextBlock",
      "spacing": "Large",
      "weight": "Bolder",
      "horizontalAlignment": "Center",
      "text": "${song}, by ${artist}",
    }
  ],
  "actions": [
    {
      "type": "Action.Execute",
      "title": "Previous",
      "verb": "previous-song"
    },
    {
      "type": "Action.Execute",
      "title": "Next",
      "verb": "next-song"
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5"
}

Beachten Sie das verb Feld in der obigen JSON-Vorlage. Er wird bei der Behandlung von Widgetaktionen in Ihrem Service Worker-Code verwendet. Weitere Informationen finden Sie unter Behandeln von Widgetaktionen.

Zugriff auf Widgetinstanzen zur Laufzeit

Sie können über den PWA Service Worker-Code auf Widgets zugreifen und diese aktualisieren. Der Zugriff auf Widgets zur Laufzeit ist in Fällen wie den folgenden nützlich:

• Rendern von Widgets bei der Installation.
• Aktualisieren von Widgets bei Service Worker-Updates.
• Behandeln von Benutzeraktionen auf Widgets.
• Aktualisieren von Widgets, wenn sich die Anwendung ändert.

Ein Service Worker hat Zugriff auf das self.widgets Objekt und mehrere Widgetereignisse, die zusammen eine API bilden, die Sie verwenden, um auf Änderungen zu reagieren und zur Laufzeit auf Widgets zuzugreifen.

Die folgenden Abschnitte enthalten Codebeispiele. Eine Referenz der API finden Sie in der Service Worker-API-Referenz.

Rendern von Widgets bei der Installation

Wenn eine PWA installiert ist, werden die Widgets, die die App in ihrem Manifest definiert, dem Widgets-Dashboard hinzugefügt, aber noch nicht installiert. Ein Widget wird nur installiert, wenn der Benutzer das Widget aus dem Dashboard hinzufügt.

Wenn ein Widget installiert wird, wird es nicht automatisch mit den Feldern und data der ms_ac_template Widgetdefinition gerendert.

Um das Widget zu rendern, hören Sie auf das widgetinstall Ereignis in Ihrem Service Worker, und aktualisieren Sie das Widget mithilfe der widgets.updateByTag folgenden Funktion:

// Listen to the widgetinstall event.
self.addEventListener("widgetinstall", event => {
  // The widget just got installed, render it using renderWidget.
  // Pass the event.widget object to the function.
  event.waitUntil(renderWidget(event.widget));
});

async function renderWidget(widget) {
  // Get the template and data URLs from the widget definition.
  const templateUrl = widget.definition.msAcTemplate;
  const dataUrl = widget.definition.data;

  // Fetch the template text and data.
  const template = await (await fetch(templateUrl)).text();
  const data = await (await fetch(dataUrl)).text();

  // Render the widget with the template and data.
  await self.widgets.updateByTag(widget.definition.tag, {template, data});
}

Widgets für Service Worker-Updates aktualisieren

Wenn sich der Service Worker-Code in einer PWA ändert, erkennt der Browser diese Änderung, installiert den neuen Service Worker und aktiviert ihn später.

In diesem Fall ist es wichtig, alle Widgetinstanzen zu aktualisieren, die möglicherweise bereits ausgeführt werden. Widgets wurden möglicherweise installiert, bevor das Service Worker-Ereignis activate ausgegeben wird. Um die Anzeige leerer Widgets zu vermeiden, aktualisieren Sie Ihre Widgets, wenn das activate Ereignis eintritt

// Update the widgets to their initial states
// when the service worker is activated.
self.addEventListener("activate", event => {
  event.waitUntil(updateWidgets());
});

async function updateWidgets() {
  // Get the widget that match the tag defined in the web app manifest.
  const widget = await self.widgets.getByTag("pwamp");
  if (!widget) {
    return;
  }

  // Using the widget definition, get the template and data.
  const template = await (await fetch(widget.definition.msAcTemplate)).text();
  const data = await (await fetch(widget.definition.data)).text();

  // Render the widget with the template and data.
  await self.widgets.updateByTag(widget.definition.tag, {template, data});
}

Behandeln von Widgetaktionen

Wenn die Widgetvorlage Aktionen enthält, können Benutzer diese Aktionen ausführen, indem sie auf Schaltflächen im gerenderten Widget klicken. Informationen zum Definieren von Aktionen in einer Vorlage finden Sie unter Definieren von Widgetaktionen.

Wenn ein Benutzer eine Widgetaktion ausführt, wird ein widgetclick Ereignis im PWA Service Worker ausgelöst. Um die Benutzeraktion zu verarbeiten, hören Sie auf das Ereignis:

self.addEventListener('widgetclick', (event) => {
  switch (event.action) {
    case 'previous-song':
      // Application logic to play the previous song...
      break;
    case 'next-song':
      // Application logic to play the next song...
      break;
  }
});

Aus Gründen der Kürze wird der tatsächliche Anwendungscode im obigen Codeausschnitt nicht angezeigt. Wenn die oder-Aktionen empfangen werden, muss wahrscheinlich eine Nachricht mithilfe von previous-songnext-songClient.postMessage an die App gesendet werden, um die App zu informieren, dass sie mit der Wiedergabe der vorherigen oder nächsten Songs beginnen soll.

Beachten Sie, dass die action Eigenschaft des Objekts, das widgetEvent an den obigen Ereignis-Listener übergeben wird, mit der Zeichenfolge übereinstimmt, die im action.verb Feld der Widgetvorlage definiert ist.

Weitere Informationen zum widgetclick Ereignis und zu den Informationen, auf die Sie zugreifen können, finden Sie weiter unten in der Service Worker-API-Referenz.

Aktualisieren von Widgets bei Anwendungsänderungen

In den vorherigen Abschnitten haben Sie erfahren, wie Widgets aktualisiert werden, wenn bestimmte Widgetereignisse, Widgetaktionen und Service Worker-Updates aufgetreten sind. Es kann auch nützlich sein, Widgets zu aktualisieren, wenn etwas in der Anwendung geschieht oder wenn eine Push-Benachrichtigung auftritt oder in regelmäßigen Abständen.

In diesem Abschnitt erfahren Sie, wie Sie die API für die regelmäßige Hintergrundsynchronisierung verwenden, um Widgets regelmäßig zu aktualisieren. Weitere Informationen zur API für die regelmäßige Hintergrundsynchronisierung finden Sie unter Verwenden der API für regelmäßige Hintergrundsynchronisierung, um regelmäßig neue Inhalte zu erhalten.

Im folgenden Codeausschnitt wird ein Ereignis-Listener verwendet, um auf verschiedene Lebenszyklusereignisse des Anwendungswidgets zu reagieren. Wenn eine Widgetinstallation erkannt wird, wird eine regelmäßige Synchronisierung registriert, und wenn eine Widgetentfernung erkannt wird, wird die Registrierung der regelmäßigen Synchronisierung aufgehoben.

Wenn regelmäßige Synchronisierungsereignisse auftreten, werden Widgetinstanzen mithilfe der widgets.updateByTag Funktion aktualisiert.

self.addEventListener("widgetinstall", event => {
  event.waitUntil(onWidgetInstall(event.widget));
});

self.addEventListener("widgetuninstall", event => {
  event.waitUntil(onWidgetUninstall(event.widget));
});

async function onWidgetInstall(widget) {
  // Register a periodic sync, if this wasn't done already.
  // We use the same tag for the sync registration and the widget to
  // avoid registering several periodic syncs for the same widget.
  const tags = await self.registration.periodicSync.getTags();
  if (!tags.includes(widget.definition.tag)) {
    await self.registration.periodicSync.register(widget.definition.tag, {
      minInterval: widget.definition.update
    });
  }

  // And also update the instance.
  await updateWidget(widget);
}

async function onWidgetUninstall(widget) {
  // On uninstall, unregister the periodic sync.
  // If this was the last widget instance, then unregister the periodic sync.
  if (widget.instances.length === 1 && "update" in widget.definition) {
    await self.registration.periodicSync.unregister(widget.definition.tag);
  }
}

// Listen to periodicsync events to update all widget instances
// periodically.
self.addEventListener("periodicsync", async event => {
  const widget = await self.widgets.getByTag(event.tag);

  if (widget && "update" in widget.definition) {
    event.waitUntil(updateWidget(widget));
  }
});

async function updateWidget(widget) {
  // Get the template and data URLs from the widget definition.
  const templateUrl = widget.definition.msAcTemplate;
  const dataUrl = widget.definition.data;

  // Fetch the template text and data.
  const template = await (await fetch(templateUrl)).text();
  const data = await (await fetch(dataUrl)).text();

  // Render the widget with the template and data.
  await self.widgets.updateByTag(widget.definition.tag, {template, data});
}

Demo-App

PWAmp ist eine Musikplayer-PWA-Demoanwendung, die ein Widget definiert. Mit dem PWAmp-Widget können Benutzer den aktuellen Song visualisieren und den vorherigen oder nächsten Song abspielen.

1. Wenn noch nicht geschehen, installieren Sie WinAppSDK 1.2 und aktivieren Sie den Entwicklermodus in Windows 11.

2. Wechseln Sie zu PWAmp und installieren Sie die App unter Windows 11.

3. Öffnen Sie das Windows 11 Widgets Board, indem Sie Windows-Logo-Taste+W drücken.

4. Klicken Sie auf Widgets hinzufügen , um den Bildschirm mit den Widgeteinstellungen zu öffnen, scrollen Sie zum PWAmp-Miniplayer-Widget , und fügen Sie es hinzu.

5. Schließe den Bildschirm mit den Widgeteinstellungen. Der PWAmp-Miniplayer wird jetzt im Widgetboard angezeigt.

Das PWAmp-Widget zeigt den aktuellen Song und Schaltflächen zum Abspielen des vorherigen oder nächsten Songs an.

Service Worker-API-Referenz

Das globale Objekt Service Worker (oder ServiceWorkerGlobalScope) enthält ein widgets Attribut, das die folgenden Promise-basierten Methoden verfügbar macht:

Das globale Objekt "Service Worker" definiert außerdem die folgenden Ereignisse:

• widgetinstall: Wird ausgelöst, wenn der Widgethost ein Widget installiert.
• widgetuninstall: Wird ausgelöst, wenn der Widgethost ein Widget deinstalliert.
• widgetresume: Wird ausgelöst, wenn der Widgethost das Rendern installierter Widgets fortsetzt, was passieren kann, nachdem der Host das Rendern von Widgets angehalten hat, um Ressourcen zu sparen.
• widgetclick: Wird ausgelöst, wenn der Benutzer eine der Widgetaktionen ausführt.

Weitere Informationen zu den Objekten, die mit diesen Ereignissen bereitgestellt werden, finden Sie unten unter widgetEvent-Objekt und widgetClickEvent-Objekt.

Widget-Objekt

Jedes Widget wird als widget Objekt dargestellt, welches die folgenden Eigenschaften aufweist:

• installable: Ein boolescher Wert, der angibt, ob das Widget installiert werden kann.
• definition: Ein widgetDefinition-Objekt.
• instances: Ein Array von widgetInstance-Objekten, die den aktuellen Status jeder Instance des Widgets darstellen.

widgetOptions-Objekt

Wenn Sie mehrere Widgets abrufen möchten matchAll(options) , ist ein widgetOptions Objekt erforderlich, um zu filtern, welche Widgets zurückgegeben werden sollen. Das widgetOptions Objekt enthält die folgenden Eigenschaften, die alle optional sind:

• installable: Ein boolescher Wert, der angibt, ob die zurückgegebenen Widgets installierbar sein sollen.
• installed: Ein boolescher Wert, der angibt, ob die zurückgegebenen Widgets im Widgethost installiert sind.
• tag: Eine Zeichenfolge, die zum Filtern der zurückgegebenen Widgets nach Tag verwendet wird.
• instanceId: Eine Zeichenfolge, die zum Filtern der zurückgegebenen Widgets nach instance-ID verwendet wird.
• hostId: Eine Zeichenfolge, die zum Filtern der zurückgegebenen Widgets nach Widget-Host-ID verwendet wird.

widgetPayload-Objekt

Beim Erstellen oder Aktualisieren einer Widget-Instance muss der Service Worker die Vorlage und die Daten senden, die zum Auffüllen des Widgets erforderlich sind. Die Vorlage und die Daten werden als Nutzlast bezeichnet. Das widgetPayload Objekt enthält die folgenden Eigenschaften:

• template: Die Vorlage, als Zeichenfolge, die zum Rendern des Widgets verwendet werden soll. Dies ist der in Zeichenfolgen unterteilte JSON-Code einer adaptiven Kartenvorlage.
• data: Die Daten als Zeichenfolge, die mit der Widgetvorlage verwendet werden sollen. Diese Daten können in Zeichenfolgen konvertierte JSON-Daten sein.

widgetInstance-Objekt

Dieses Objekt stellt eine bestimmte Instance eines Widgets in einem Widgethost dar und enthält die folgenden Eigenschaften:

• id: Die interne GUID-Zeichenfolge, die zum Verweisen auf die Instance verwendet wird.
• host: Ein interner Zeiger auf den Widgethost, der diese Instance installiert hat.
• updated: Ein Date Objekt, das das letzte Mal angibt, zu dem Daten an die instance gesendet wurden.
• payload: Ein widgetPayload-Objekt, das die letzte Nutzlast darstellt, die an diese instance gesendet wurde.

widgetDefinition-Objekt

Dieses Objekt stellt die ursprüngliche Definition des Widgets dar, die in der PWA-Manifestdatei enthalten ist. Die Eigenschaften dieses Objekts stimmen mit den Eigenschaften überein, die oben unter Definieren von Widgets aufgeführt sind.

widgetEvent-Objekt

Dieses Objekt wird als Argument an Listener von Service Worker-Widgetereignissen vom Typ widgetinstall, widgetuninstallund widgetresumeübergeben.

Für die widgetinstallEreignistypen , widgetuninstallund widgetresume hat das widgetEvent Objekt die folgenden Eigenschaften:

widgetClickEvent-Objekt

Dieses Objekt wird als Argument an Listener von Service Worker-Widgetereignissen vom Typ .widgetclick Sie können das Fenster Ihrer App als Reaktion auf das widgetclick Ereignis öffnen, indem clients.openWindow()Sie verwenden.

Das widgetClickEvent Objekt hat die folgenden Eigenschaften: