Exibir um widget do PWA no Painel de Widgets do Windows

Vários sistemas operacionais têm widgets, painéis que permitem aos usuários ler conteúdo e realizar tarefas. Exemplos disso incluem widgets da tela inicial do Android, widgets do Painel do macOS e do Painel Hoje, Apple Touch Bar, Samsung Daily Cards, widgets do Mini App e complementos do aplicativo para smartwatch.

No Windows 11, os widgets aparecem no Quadro de Widgets, que você abre do lado esquerdo da barra de tarefas:

No Windows 11, os PWAs (Aplicativos Web Progressivos) podem definir widgets, atualizá-los e lidar com as interações do usuário neles.

Requer a criação de um widget personalizado para o PWA

Um PWA existente não pode simplesmente ser colocado no dashboard do widget como está, como você pode fazer com a Barra Lateral do Microsoft Edge. Em vez disso, você precisa criar uma experiência de widget personalizada que seja apropriada para o host do widget, que atualmente é o Painel de Widgets do Windows 11. (Pode haver outros hosts de widget no futuro.) O Painel de Widgets do Windows 11 requer que os widgets sejam criados usando modelos de Cartão Adaptável em vez de HTML e JavaScript, portanto, o widget deve ser projetado separadamente do restante da interface do usuário do aplicativo.

Veja também:

• Criar um PWA para a barra lateral no Microsoft Edge

Para criar um widget orientado por PWA e distribuí-lo por meio da Microsoft Store, não é necessário nenhum código C++/C#. Depois de produzir o widget e poder instalá-lo e executá-lo com êxito de um ponto de extremidade público, você poderá empacotar o aplicativo usando o PWABuilder.com e enviá-lo para a Microsoft Store sem a necessidade de nenhum código adicional. O PWA que dá suporte ao widget deve ser instalável de um ponto de extremidade público, pois o PWABuilder não dá suporte ao empacotamento de aplicativos do localhost.

Veja também:

• Publicar um PWA na Microsoft Store

Instale o WinAppSDK e habilite o Modo de Desenvolvedor

Para habilitar o desenvolvimento e o teste de widgets em sua máquina local:

• Instale o WinAppSDK 1.2.

• Habilite o modo de desenvolvedor no Windows 11:

  1. Abra Configurações.

  2. Na caixa de texto Localizar uma configuração , insira developere clique em Usar recursos de desenvolvedor.

  3. Habilitar Modo de Desenvolvedor:

     

Definir widgets

Os widgets são definidos no arquivo de manifesto do PWA, usando o membro manifesto widgets . Esse membro manifesto é uma matriz que pode conter várias definições de widget.

{
  "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 */
  ]
}

Cada entrada na widgets matriz contém vários campos, conforme mostrado abaixo:

{
  ...
  "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
    }
  ]
}

No exemplo acima, um aplicativo de player de música define um widget de mini player. Uma definição de widget no manifesto do aplicativo Web tem os seguintes campos obrigatórios e opcionais:

Definir um modelo de widget

Para facilitar a criação e adaptação de widgets a vários painéis de widgets do sistema operacional, eles são exibidos usando modelos. Existem dois tipos de modelos:

• Modelos genéricos, definidos por seus nomes usando o template campo.
• Modelos personalizados, definidos por suas URLs usando um campo de modelo personalizado.

Por enquanto, há suporte apenas para modelos de Cartões Adaptáveis personalizados. Os Cartões Adaptáveis são um formato de troca de card aberto que pode ser usado para trocar conteúdo da interface do usuário de maneira comum e consistente. Confira Visão geral dos Cartões Adaptáveis.

Para definir um modelo de Cartões Adaptáveis personalizado no Windows 11, use o campo na definição do widget que está no manifesto ms_ac_template do aplicativo Web. Embora template não esteja sendo usado no momento, é um campo obrigatório.

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

O ms_ac_template valor do campo deve ser uma URL válida de um arquivo de modelo.

Aqui está um exemplo de um modelo de Cartões Adaptáveis:

{
  "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"
}

Para saber mais, consulte Modelos de Cartões Adaptáveis.

Em seguida, você precisa vincular os dados ao seu modelo.

Associar dados ao seu modelo

O modelo declara a interface do usuário de um widget. Os dados então preenchem essa interface do usuário.

Para vincular dados ao seu modelo, use o campo na definição do data widget. Esse campo deve ser definido como uma URL que retorne dados JSON válidos.

O modelo definido na seção anterior contém duas variáveis: song e , que estão incluídas na sintaxe artistda expressão de associação: ${}. Os dados retornados pela data URL em sua definição de widget devem conter valores para essas variáveis.

Aqui está um exemplo do que a data URL pode retornar:

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

Definir ações do widget

Se você deseja que seu widget permita que os usuários executem tarefas, defina um modelo que suporte ações.

Aqui está um exemplo de uma ação definida em um modelo personalizado de Cartões Adaptáveis:

{
  "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"
}

Observe o verb campo no modelo JSON acima. Ele será usado ao lidar com ações de widget em seu código de trabalho de serviço. Consulte Manipular ações do widget.

Acessar instâncias de widget em tempo de execução

Você pode acessar widgets e atualizá-los a partir do código de trabalho do serviço PWA. O acesso a widgets em tempo de execução é útil em casos como:

• Renderizando widgets na instalação.
• Atualização de widgets em atualizações de trabalho de serviço.
• Manipulação de ações do usuário em widgets.
• Atualizando widgets quando o aplicativo é alterado.

Um service worker tem acesso ao objeto e a self.widgets vários eventos de widget que, juntos, constituem uma API que você usa para reagir a alterações e acessar widgets em tempo de execução.

As seções a seguir fornecem exemplos de código. Para obter uma referência da API, consulte a referência da API do trabalho de serviço.

Renderizar widgets na instalação

Quando um PWA é instalado, os widgets que o aplicativo define em seu manifesto são adicionados ao dashboard de widgets, mas ainda não estão instalados. Um widget só é instalado quando o usuário escolhe adicionar o widget a partir do dashboard.

Quando um widget é instalado, ele não é renderizado automaticamente usando os ms_ac_template campos and data da definição do widget.

Para renderizar o widget, ouça o widgetinstall evento em seu trabalho de serviço e atualize o widget usando a widgets.updateByTag função:

// 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});
}

Atualizar widgets em atualizações de trabalho de serviço

Quando o código do service worker é alterado em um PWA, o navegador detecta essa alteração, instala o novo service worker e, em seguida, ativa o service worker.

Quando isso acontece, é importante atualizar todas as instâncias de widget que já podem estar em execução. Os widgets podem ter sido instalados antes que o evento de trabalho activate de serviço seja emitido. Para evitar exibir widgets vazios, atualize seus widgets quando o activate evento ocorrer

// 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});
}

Lidar com ações do widget

Se o modelo de widget contiver ações, os usuários poderão executar essas ações clicando nos botões no widget renderizado. Para obter informações sobre como definir ações em um modelo, consulte Definir ações de widget.

Quando um usuário executa uma ação de widget, um widgetclick evento é disparado no trabalho de serviço do PWA. Para manipular a ação do usuário, ouça o evento:

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;
  }
});

Para resumir, o código real do aplicativo não é mostrado no snippet de código acima. Quando as previous-song ações ou next-song forem recebidas, uma mensagem provavelmente precisará ser enviada ao aplicativo usando Client.postMessage para que o aplicativo saiba que ele deve começar a reproduzir as músicas anteriores ou seguintes.

Observe que a actionwidgetEvent propriedade do objeto passado para o ouvinte de eventos acima corresponde à string definida no action.verb campo do modelo de widget.

Para obter mais informações sobre o evento e quais informações você pode acessar a partir dele, consulte Referência widgetclick da API de trabalho de serviço, abaixo.

Atualizar widgets em alterações de aplicativos

Nas seções anteriores, você aprendeu como atualizar widgets quando eventos específicos de widget, ações de widget e atualizações de service worker ocorreram. Também pode ser útil atualizar widgets quando algo acontece no aplicativo, ou quando ocorre uma notificação por push, ou periodicamente.

Nesta seção, você aprenderá a usar a API de Sincronização em Segundo Plano Periódica para atualizar widgets periodicamente. Para obter mais informações sobre a API de Sincronização em Segundo Plano Periódica, consulte Usar a API de Sincronização em Segundo Plano Periódica para obter conteúdo atualizado regularmente.

No snippet de código a seguir, um ouvinte de eventos é usado para reagir a vários eventos do ciclo de vida do widget do aplicativo. Quando uma instalação de widget é detectada, uma sincronização periódica é registrada e quando uma remoção de widget é detectada, a sincronização periódica é cancelada.

Quando ocorrem eventos de sincronização periódicos, as instâncias do widget são atualizadas usando a widgets.updateByTag função.

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});
}

Aplicativo de demonstração

PWAmp é um aplicativo de demonstração PWA de reprodutor de música que define um widget. O widget PWAmp permite que os usuários visualizem a música atual e reproduzam as músicas anteriores ou seguintes.

1. Se ainda não tiver feito isso, instale o WinAppSDK 1.2 e habilite o modo de desenvolvedor no Windows 11.

2. Vá para PWAmp e instale o aplicativo no Windows 11.

3. Abra o Quadro de Widgets do Windows 11 pressionando a tecla do logotipo do Windows + W.

4. Clique em Adicionar widgets para abrir a tela de configurações de widgets , role até o widget mini player PWAmp e adicione-o.

5. Feche a tela de configurações de widgets . O mini player do PWAmp agora é exibido no Painel de Widgets.

O widget PWAmp exibe a música atual e os botões para reproduzir a música anterior ou a próxima.

Referência da API do trabalho de serviço

O objeto global de trabalho de serviço (ou ServiceWorkerGlobalScope) contém um widgets atributo que expõe os seguintes métodos baseados em promessa:

O objeto global de trabalho de serviço também define os seguintes eventos:

• widgetinstall: acionado quando o host do widget está instalando um widget.
• widgetuninstall: acionado quando o host do widget está desinstalando um widget.
• widgetresume: acionado quando o host do widget retoma a renderização de widgets instalados, o que pode acontecer depois que o host suspendeu a renderização de widgets para preservar recursos.
• widgetclick: acionado quando o usuário executa uma das ações do widget.

Para obter mais informações sobre os objetos fornecidos com esses eventos, consulte o objeto widgetEvent e o objeto widgetClickEvent, abaixo.

objeto widget

Cada widget é representado como um widget objeto, que contém as seguintes propriedades:

• installable: Um booliano que indica se o widget é instalável.
• definition: Um objeto widgetDefinition.
• instances: Uma matriz de objetos widgetInstance que representam o estado atual de cada instância do widget.

objeto widgetOptions

Ao usar matchAll(options) para obter vários widgets, um widgetOptions objeto é necessário para filtrar quais widgets retornar. O widgetOptions objeto contém as seguintes propriedades, todas elas opcionais:

• installable: Um booliano que indica se os widgets retornados devem ser instaláveis.
• installed: Um booliano que indica se os widgets retornados estão instalados no host do widget.
• tag: Uma cadeia de caracteres usada para filtrar os widgets retornados por marca.
• instanceId: Uma cadeia de caracteres usada para filtrar os widgets retornados por ID de instância.
• hostId: Uma cadeia de caracteres usada para filtrar os widgets retornados por ID do host do widget.

objeto widgetPayload

Ao criar ou atualizar uma instância de widget, o trabalho de serviço deve enviar o modelo e os dados necessários para preencher o widget. O modelo e os dados são chamados de conteúdo. O widgetPayload objeto contém as seguintes propriedades:

• template: O modelo, como uma cadeia de caracteres, a ser usado para renderizar o widget. Esse será o JSON stringificado de um modelo de Cartão Adaptável.
• data: Os dados, como uma cadeia de caracteres, a serem usados com o modelo de widget. Esses dados podem ser dados JSON estringidos.

objeto widgetInstance

Este objeto representa uma determinada instância de um widget em um host de widget e contém as seguintes propriedades:

• id: a cadeia de caracteres GUID interna usada para fazer referência à instância.
• host: Um ponteiro interno para o host do widget que instalou essa instância.
• updated: Um Date objeto que representa a última vez em que os dados foram enviados para a instância.
• payload: Um objeto widgetPayload que representa a última carga útil que foi enviada para essa instância.

objeto widgetDefinition

Esse objeto representa a definição original do widget, encontrada no arquivo de manifesto do PWA. As propriedades desse objeto correspondem às propriedades listadas em Definir widgets, acima.

objeto widgetEvent

Esse objeto é passado como um argumento para ouvintes de eventos de widget de trabalho de serviço do tipo widgetinstall, widgetuninstalle widgetresume.

Para os widgetinstalltipos widgetEvent de evento , widgetuninstall, o widgetresume objeto tem as seguintes propriedades:

objeto widgetClickEvent

Esse objeto é passado como um argumento para ouvintes de eventos de widget de trabalho de serviço do tipo widgetclick. Você pode abrir a janela do aplicativo em resposta ao widgetclick evento, usando clients.openWindow().

O widgetClickEvent objeto tem as seguintes propriedades: