Habilitar ações de aplicativo no Windows para um PWA

Você pode criar e testar uma Ação de Aplicativo para a estrutura de Ações de Aplicativo no Windows, para um PWA (Aplicativo Web Progressivo) que você criou. Uma ação de aplicativo no Windows é uma unidade individual de comportamento que um aplicativo do Windows pode implementar e registrar. A Ação do Aplicativo pode então ser acessada de outros aplicativos e experiências, integrando-se perfeitamente aos fluxos de trabalho do usuário.

Um aplicativo cria e registra cada Ação do Aplicativo e, em seguida, os aplicativos e experiências do Windows podem recomendar Ações do Aplicativo registradas para o usuário em horários e locais contextualmente relevantes dentro do fluxo de trabalho do usuário.

Você pode criar Ações de Aplicativos do Windows App para aumentar a capacidade de descoberta e o envolvimento dos recursos do seu aplicativo.

Veja também:

Conteúdo detalhado:

A estrutura de Ações de Aplicativos do Windows App serve para expor e executar partes importantes da funcionalidade do aplicativo, não atividades genéricas do usuário, como abrir um menu de clique com o botão direito do mouse (menu de contexto). Consulte Cenários recomendados para ações de aplicativo em Visão geral de ações de aplicativo no Windows.

Definir ações do aplicativo no manifesto de definição de ação

Você define as ações do aplicativo que seu PWA dá suporte em um arquivo de manifesto de definição de ação (como ActionsManifest.json). Esse é um arquivo JSON de definição de ação para Ações de Aplicativo no Windows.

O presente artigo mostra como criar uma ação de aplicativo que usa o PWA de exemplo, wami, o aplicativo Web para manipular imagens. A demonstração wami suporta tarefas de manipulação de imagem, como redimensionar ou aplicar estilos de pós-processamento.

O arquivo de manifesto de definição de ação de exemplo a seguir (nomeado ActionsManifest.json), define uma ação do aplicativo Paint para o recurso Paint do aplicativo de exemplo wami. O recurso Paint, referenciado pela ação do aplicativo Paint , gera uma versão da imagem no estilo de pintura a óleo.

{
   "version": 1,
   "actions": [{
      "id": "Wami.Paint",
      "description": "Convert the image to oil paint style",
      "kind": "Search",
      "inputs": [{
         "name": "File",
         "kind": "Photo"
        }],
      "outputs": [],
      "invocation": {
         "type": "Uri",
         "uri": "web+wami://paint"
      },
      "inputCombinations": [{
         "inputs": [ "File" ],
         "description": "Photo to be converted to oil paint style."
      }]
   }]
}

Como entrada, a ação do aplicativo Paint aceita o arquivo de imagem que o usuário selecionou.

A ação do aplicativo Paint retorna a saída estilizada.

Propriedades com suporte em um manifesto de definição de ação

O arquivo de manifesto de definição de ação (como ActionsManifest.json) é um arquivo descritivo usado pelo Tempo de Execução de Ações de Aplicativos do Windows App para um aplicativo para declarar as ações de aplicativo compatíveis com o aplicativo.

Para obter a definição de cada propriedade JSON com suporte, consulte Propriedades JSON de definição de ação em Esquema JSON de definição de ação para ações de aplicativo no Windows.

Em Invocation, apenas o uri tipo é suportado. O com tipo não é aplicável para PWAs.

Tipos de entidade com suporte para ações de aplicativo para PWAs

No arquivo de manifesto de definição de ação (como ActionsManifest.json), a ActionEntityKind enumeração especifica os tipos de entidades compatíveis com Ações de Aplicativo no Windows.

No contexto de uma definição de ação do aplicativo JSON, os tipos de entidade são literais de cadeia de caracteres que diferenciam maiúsculas de minúsculas. As entidades com suporte são listadas na enumeração ActionEntityKind no esquema JSON de definição de ação para Ações de Aplicativo no Windows.

StreamingText e RemoteFile ainda não têm suporte para PWAs. Para File, Photo, Document e Text tipos de entidade, consulte Propriedades de entidade no esquema JSON de definição de ação para Ações de Aplicativo no Windows.

Como um PWA é iniciado por meio da ativação de URI

Quando a Ação do Aplicativo do PWA é chamada, a Ação do Aplicativo do PWA é iniciada pelo Windows por meio da ativação do URI do protocolo personalizado. Um PWA deve se registrar para tratamento de protocolo personalizado usando o campo no manifesto protocol_handlers do aplicativo Web do PWA, como Demos/wami/manifest.json.

O método do LaunchUriAsync(Uri, LauncherOptions, ValueSet) Windows é usado pelo Action Framework para ativação de URI. LaunchUriAsyncNão retorna um valor ou erro status.

uri No manifesto de definição de ação

Use um URI de protocolo personalizado, não um URI HTTPS.

Para um PWA que tenha várias Ações de Aplicativo, use a sintaxe:

"uri": "web+{app name}://{custom action name}"

Por exemplo:

"uri": "web+wami://paint"

A linha acima é mostrada no contexto em Definir ações do aplicativo no manifesto de definição de ação, acima.

Receber ValueSet dados e mapeá-los para um destino de compartilhamento

O URI do protocolo ativado será mapeado para o url campo dos dados de destino do compartilhamento.

A entrada ValueSet será convertida em uma cadeia de caracteres JSON válida e mapeada para o text campo dos dados de destino do compartilhamento. Isso permite que o Microsoft Edge determine se a inicialização do manipulador de protocolo representa uma ação do aplicativo.

O manifesto do aplicativo Web do aplicativo (como Demos/wami/manifest.json) deve configurar corretamente o share_target campo, para permitir a inicialização como um destino de compartilhamento para uma ação do aplicativo. Confira share_target no manifesto do aplicativo Web, abaixo.

Pré-requisitos para que seu PWA dê suporte a Ações de Aplicativo

Para integrar corretamente seu PWA à estrutura de Ações de Aplicativo no Windows, os seguintes membros do manifesto do aplicativo Web são necessários:

  • share_target
  • protocol_handlers
  • launch_handler

share_target No manifesto do aplicativo Web

Para que um PWA use Ações do Aplicativo, o campo deve estar presente no arquivo de manifesto share_target do aplicativo Web do PWA, como Demos/wami/manifest.json.

  • O método deve ser "POST".
  • O enctype deve ser multipart/form-data.
  • text e url em params são necessários para dar suporte a ações do aplicativo.
  • files é opcional. Você poderá omitir files se não quiser que seu PWA dê suporte ao recurso de destino de compartilhamento normal.

Exemplo share_target de declaração, de Demos/wami/manifest.json:

"share_target": {
   "action": "./share-target",
   "method": "POST",
   "enctype": "multipart/form-data",
   "params": {
      "title": "title",
      "text": "text",
      "url": "url"
   }
}

Veja também:

Manipular a entidade de uma ação do aplicativo

A entidade de uma ação de aplicativo é passada para o PWA por meio de dados de compartilhamento POST. Para lidar com dados de compartilhamento POST, você pode usar ou combinar as seguintes abordagens:

O código a seguir é do manipulador de trabalho de serviço de exemplo da demonstração do wami em Demos/wami/sw.js, para dar suporte à inicialização do App Action para o aplicativo:

// Extract data
const data = {
   text: formData.get('text') || '',
   url: formData.get('url') || ''
};
const files = formData.getAll('windowsActionFiles');

Explicação das formData chaves:

  • Texto: Uma cadeia de caracteres JSON que lista todas as entidades de entrada. O valor do parâmetro de entrada deve ser idêntico ao valor definido no manifesto share_target.params.textdo aplicativo Web do PWA. Os caminhos de arquivo contidos no texto são seguros de consumir. Para proteger a privacidade dos usuários, o Edge limpa todas as informações de caminho fornecidas pelo usuário antes que elas cheguem ao seu trabalho de serviço, deixando apenas o nome do arquivo.

  • URL: O URI do protocolo (por exemplo, no exemplo) web+wami://paint que identifica qual Ação de Aplicativo disparou a inicialização. O valor do parâmetro de entrada deve ser idêntico ao valor definido no manifesto share_target.params.urldo aplicativo Web do PWA.

  • Arquivos: Objetos de arquivo anexados à invocação de Ação do Aplicativo.

protocol_handlers No manifesto do aplicativo Web

Para que um PWA use Ações do Aplicativo, o campo deve estar presente no arquivo de manifesto protocol_handlers do aplicativo Web do PWA (como Demos/wami/manifest.json). O protocol_handlers.protocol campo deve corresponder à primeira parte do arquivo de manifesto invocation.uri de definição de ação (como ActionsManifest.json).

Exemplo protocol_handlers de declaração, de Demos/wami/manifest.json:

"protocol_handlers": [{
   "protocol": "web+wami",
   "url": "./?url=%s"
}]

O campo de correspondência invocation.uri de ActionsManifest.json:

"invocation": {
   "type": "Uri",
   "uri": "web+wami://paint"
},

O snippet acima é mostrado no contexto em Definir ações do aplicativo no manifesto de definição de ação, acima.

Veja também:

launch_handler No manifesto do aplicativo Web

Se quiser manter uma única janela do PWA, você poderá definir launch_handler como navigate-existing no arquivo de manifesto do aplicativo Web do PWA (como Demos/wami/manifest.json).

Exemplo de declaração:

"launch_handler": {
   "client_mode": " navigate-existing"
}

O código acima não está em Demos/wami/manifest.json.

Empacotar um repositório PWA no Edge Estável

Em seguida, seu PWA precisa ser empacotado como um PWA da Microsoft Store, a ser chamado pela estrutura de Ações do Windows App.

Para empacotar seu PWA como um PWA da Microsoft Store:

  1. Empacote seu PWA para PWABuilder.com; consulte Empacotar seu PWA para a Store em Publicar um PWA na Microsoft Store.

  2. Em Todas as configurações, role para baixo até Ações – Ativar ações na parte inferior.

  3. Verifique se o arquivo de manifesto do aplicativo Web do PWA (como Demos/wami/manifest.json) tem protocol_handlers campos and share_target . PWABuilder.com executará um marcar e, se um dos campos estiver ausente do manifesto do aplicativo Web do aplicativo, a caixa de seleção Habilitar ações ficará esmaecida.

  4. Na seção Ações , clique em Escolher arquivo e carregue o arquivo de manifesto de definição de ação (como ActionsManifest.json) que você preparou para seu PWA.

  5. Clique no botão Download .

  6. Descompacte o arquivo de downloads. Instale-o executando o install.ps1.

  7. Inicie o PWA clicando no ícone do PWA.

  8. Teste suas ações do PWA localmente seguindo Ações de Teste do Aplicativo para um PWA, abaixo, para validar a funcionalidade.

  9. Abra o arquivo de manifesto de definição de ação (como ActionsManifest.json) que você usou ao empacotar no PWAbuilder.com.

  10. Defina a disponibilidade inicial de cada uma das ações do aplicativo como false, conforme descrito em Definir a disponibilidade inicial em Ativar/desativar disponibilidade de uma ação do aplicativo para Windows.

    Antes de publicar seu pacote, recomendamos a etapa acima. Se você não definir a disponibilidade inicial da ação do aplicativo como false, sua ação só funcionará se o usuário acessar edge://flags manualmente o Microsoft Edge e habilitar o sinalizador #edge-app-actions-on-windows-for-web-appsdo recurso.

    A definição da disponibilidade false inicial como é necessária porque o suporte do Microsoft Edge para Ações de Aplicativo no Windows em PWAs é controlado pelo sinalizador #edge-app-actions-on-windows-for-web-appsde recurso e está desabilitado por padrão, pois esse recurso está atualmente na Avaliação do Desenvolvedor.

    Quando o sinalizador #edge-app-actions-on-windows-for-web-apps de recurso for lançado oficialmente (mais tarde em 2025), o Microsoft Edge alternará automaticamente as ações definidas no arquivo de manifesto de definição de ação de DisabledEnabledpara , permitindo que os usuários finais utilizem as ações do seu aplicativo sem exigir alterações adicionais de sua parte.

  11. Publique seu PWA, conforme descrito em Publicar um PWA na Microsoft Store.

Empacotar um repositório PWA no Edge Canary

O Edge Canary fornece uma prévia das funcionalidades que ainda não estão disponíveis na versão estável.

Se você quiser experimentar os recursos mais recentes de Ações de Aplicativo no Edge Canary, poderá empacotar seu PWA no Edge Canary, da seguinte maneira:

  1. Instale o Edge Canary e atualize para a versão mais recente.

  2. Obtenha o ID do pacote, o ID do editor e o nome de exibição do editor do seu PWA; consulte Publicar um PWA na Microsoft Store.

  3. Vá para PWABuilder.Windows.Chromium tester.

  4. Insira suas configurações do PWA na caixa de entrada, para os seguintes campos:

    • name: o nome do seu PWA.
    • packageId: não será necessário se você não publicar a versão do Edge Canary do seu aplicativo na loja; pode ser uma cadeia de caracteres vazia.
    • url: a URL do seu PWA.
    • publisher.displayName: o nome do editor. Não será necessário se você não publicar a versão do Edge Canary do seu aplicativo na loja; pode ser uma cadeia de caracteres vazia.
    • publisher.commonName: sua ID de Publicador. Não será necessário se você não publicar a versão do Edge Canary do seu aplicativo na loja; pode ser uma cadeia de caracteres vazia.
    • startUrl: Seu PWA's startUrl.

    Exemplo de listagem JSON que você pode copiar e colar no campo de texto do testador PWABuilder.Windows.Chromium:

    {
   "name": "Wami for Canary",
   "packageId": "",
   "url": "https://microsoftedge.github.io/Demos/wami",
   "version": "1.0.2",
   "allowSigning": true,
   "classicPackage": {
      "generate": true,
      "version": "1.0.0"
   },
   "publisher": {
      "displayName": "",
      "commonName": ""
   },
   "edgeChannel": "canary",
   "appUserModelId": "Microsoft.Canary_8wekyb3d8bbwe!MSEDGE",
   "generateModernPackage": true,
   "resourceLanguage": "EN-US",
   "startUrl": "https://microsoftedge.github.io/Demos/wami"
}

    Substitua os atributos acima pelos atributos reais do seu aplicativo.

  5. Carregue o arquivo de manifesto de definição de ação (como ActionsManifest.json) e clique no botão Baixar .

  6. Seu download é um .zip arquivo morto que contém arquivos como .msix e .msixbundle arquivos. Descompacte-o e execute install.ps1 para instalar seu PWA diretamente.

  7. Clique no ícone do PWA.

    Seu PWA é iniciado.

  8. Inicie o Edge Canary e vá para edge://apps.

    Seu PWA está listado.

  9. Clique no botão Detalhes .

    Seu PWA é indicado como instalado da Microsoft Store.

Seu PWA agora foi instalado como um PWA de armazenamento no Edge Canary.

Ações de aplicativo de teste para um PWA

Para testar ações do aplicativo para seu PWA:

  1. Certifique-se de que seu PWA tenha sido configurado e empacotado com êxito, conforme discutido nas seções acima.

  2. Certifique-se de que o Windows esteja atualizado para oferecer suporte a ações do aplicativo; consulte o Build de Visualização 26120.4151 do Participante do Programa Windows Insider do Windows 11 (Canal beta).

  3. Certifique-se de que o Microsoft Edge esteja atualizado para a versão mais recente e instale seu PWA com êxito; consulte Empacotar um repositório PWA no Edge Estável ou Empacotar um repositório PWA no Edge Canary, acima.

  4. Inicie o Edge Canary ou o Edge Stable (em qualquer canal em que você instalou o PWA).

  5. Vá para edge://flags, pesquise Ações do Aplicativo e localize a entrada Habilitar Ações do Aplicativo no Windows para aplicativos da Web. (O nome do sinalizador é #edge-app-actions-on-windows-for-web-apps.)

  6. Altere o status para Habilitado e clique no botão Reiniciar no canto inferior direito.

  7. Inicie seu PWA.

    Seu PWA deve ser iniciado pelo menos uma vez, para inicializar seu PWA para a Ação do Aplicativo, antes de ser chamado pelo runtime de Ações do Aplicativo.

  8. Use o aplicativo Playground de Teste de Ambiente de teste de ações de aplicativo para testar as ações de aplicativo para seu PWA.

  9. Adicione uma entidade de que essa Ação de Aplicativo precisa. Por exemplo, se a Ação do Aplicativo processar imagens, adicione uma imagem. Em seguida, execute a ação do aplicativo.

    O PWA é iniciado e executa a ação do aplicativo.

Confira também

Artigos do Windows:

Sites:

MDN:

Demos repo:

  • Last updated on