Compartilhar via

Ativar as Ações da Aplicação no Windows para um PWA

Pode criar e testar uma Ação de Aplicação para as Ações de Aplicação na arquitetura do Windows, para uma Aplicação Web Progressiva (PWA) que criou. Uma Ação de Aplicação no Windows é uma unidade individual de comportamento que uma aplicação do Windows pode implementar e registar. Em seguida, a Ação da Aplicação pode ser acedida a partir de outras aplicações e experiências, integrando-se perfeitamente nos fluxos de trabalho do utilizador.

Uma aplicação cria e regista cada Ação de Aplicação e, em seguida, as aplicações e experiências do Windows podem recomendar ações de aplicação registadas ao utilizador em horas e localizações contextualmente relevantes no fluxo de trabalho do utilizador.

Pode criar Windows App Ações para aumentar a deteção e o envolvimento das funcionalidades da sua aplicação.

Veja também:

Conteúdo detalhado:

A arquitetura Windows App Actions destina-se a expor e executar peças-chave da funcionalidade da aplicação, não atividades genéricas do utilizador, como abrir um menu de contexto (menu de contexto). Veja Cenários recomendados para Ações da Aplicação em Ações da Aplicação na Descrição Geral do Windows.

Definir Ações da Aplicação no manifesto de definição de ação

Define as Ações da Aplicação suportadas pelo PWA num ficheiro de manifesto de definição de ação (como ActionsManifest.json). Este é um ficheiro JSON de definição de ação para ações de aplicação no Windows.

O artigo atual mostra como criar uma Ação de Aplicação que utiliza o PWA de exemplo, wami, a Aplicação Web para Manipular Imagens. A demonstração wami suporta tarefas de manipulação de imagens, como redimensionar ou aplicar estilos de pós-processamento.

O seguinte ficheiro de manifesto de definição de ação de exemplo (denominado ActionsManifest.json), define uma Ação do Paint App para a funcionalidade Paint da aplicação de exemplo wami. A funcionalidade Paint, referenciada pela Paint App Action, gera uma versão em estilo pintura a óleo da imagem.

{
   "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 Paint App aceita o ficheiro de imagem que o utilizador selecionou.

A Ação do Paint App devolve a saída estilizada.

Propriedades suportadas num manifesto de definição de ação

O ficheiro de manifesto de definição de ação (como ActionsManifest.json) é um ficheiro descritivo que é utilizado pelo Windows App Actions Runtime para uma aplicação, para declarar as Ações da Aplicação suportadas pela aplicação.

Para obter a definição de cada propriedade JSON suportada, veja Propriedades JSON de definição de ação em Esquema JSON de definição de ação para Ações de Aplicação no Windows.

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

Tipos de Entidade suportados para Ações da Aplicação para PWAs

No ficheiro de manifesto de definição de ação (como ActionsManifest.json), a ActionEntityKind enumeração especifica os tipos de entidades suportados pelas Ações da Aplicação no Windows.

No contexto de uma definição de Ação de Aplicação JSON, os tipos de entidade são literais de cadeia que são sensíveis a maiúsculas e minúsculas. As entidades suportadas estão listadas na enumeração ActionEntityKind em Esquema JSON de definição de ação para Ações da Aplicação no Windows.

StreamingText e RemoteFile ainda não são suportados para PWAs. Para File, PhotoDocument e Text tipos de entidade, veja Propriedades da entidade no esquema JSON de definição de ação para Ações de Aplicação no Windows.

Como um PWA é iniciado através da ativação do URI

Quando uma Ação de Aplicação do PWA é chamada, a Ação da Aplicação PWA é iniciada pelo Windows através da ativação do URI de protocolo personalizado. Um PWA tem de se registar para processamento de protocolos personalizados através do protocol_handlers campo no manifesto da aplicação Web do PWA, como Demos/wami/manifest.json.

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

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

Utilize um URI de protocolo personalizado e não um URI HTTPS.

Para um PWA que tenha várias Ações de Aplicação, utilize a sintaxe:

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

Por exemplo:

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

A linha acima é apresentada no contexto em Definir Ações da Aplicação no manifesto de definição de ação, acima.

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

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

A entrada ValueSet será convertida numa cadeia JSON válida e mapeada para o text campo dos dados de destino da partilha. Isto permite ao Microsoft Edge determinar que a iniciação do processador de protocolos representa uma Ação de Aplicação.

O manifesto da aplicação Web da aplicação (como Demos/wami/manifest.json) tem de configurar corretamente o share_target campo, para permitir que seja iniciado como um destino de partilha para uma Ação de Aplicação. Veja share_target abaixo no manifesto da aplicação Web.

Pré-requisitos para o seu PWA suportar Ações de Aplicação

Para integrar corretamente o seu PWA com a arquitetura Ações de Aplicação no Windows, são necessários os seguintes membros do manifesto da aplicação Web:

  • share_target
  • protocol_handlers
  • launch_handler

share_target no manifesto da aplicação Web

Para um PWA utilizar ações de aplicação, o share_target campo tem de estar presente no ficheiro de manifesto da aplicação Web do PWA, como Demos/wami/manifest.json.

  • O método tem de ser "POST".
  • Tem enctype de ser multipart/form-data.
  • text e url no params são necessários para suportar as Ações da Aplicação.
  • files é opcional. Pode omitir files se não quiser que o seu PWA suporte a funcionalidade de destino de partilha normal.

Declaração de exemplo share_target , 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:

Processar a entidade de uma Ação de Aplicação

A entidade de uma Ação de Aplicação é transmitida para o PWA através de dados de partilha POST. Para processar dados de partilha POST, pode utilizar ou combinar as seguintes abordagens:

O código seguinte é do processador de trabalho de serviço de exemplo da demonstração wami em Demos/wami/sw.js, para suportar o lançamento da Ação de Aplicação para a aplicação:

// 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 JSON que lista todas as entidades de entrada. O valor do parâmetro de entrada tem de ser idêntico ao valor que definiu no manifesto share_target.params.textda aplicação Web do PWA. Os caminhos de ficheiro contidos no texto são seguros de consumir. Para proteger a privacidade dos utilizadores, o Edge limpa todas as informações de caminho fornecidas pelo utilizador antes de chegar à sua função de trabalho de serviço, deixando apenas o nome do ficheiro.

  • URL: O URI do protocolo (por exemplo, web+wami://paint no exemplo) que identifica que Ação da Aplicação acionou o lançamento. O valor do parâmetro de entrada tem de ser idêntico ao valor que definiu no manifesto share_target.params.urlda aplicação Web do PWA.

  • ficheiros: Objetos de ficheiro anexados à invocação da Ação da Aplicação.

protocol_handlers no manifesto da aplicação Web

Para um PWA utilizar as Ações da Aplicação, o protocol_handlers campo tem de estar presente no ficheiro de manifesto da aplicação Web do PWA (como Demos/wami/manifest.json). O protocol_handlers.protocol campo tem de corresponder à primeira parte do no ficheiro de invocation.uri manifesto de definição de ação (como ActionsManifest.json).

Declaração de exemplo protocol_handlers , de Demos/wami/manifest.json:

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

O campo correspondente invocation.uri de ActionsManifest.json:

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

O fragmento acima é apresentado no contexto em Definir Ações da Aplicação no manifesto de definição de ação acima.

Veja também:

launch_handler no manifesto da aplicação Web

Se quiser manter uma única janela do PWA, pode definir launch_handler como navigate-existing no ficheiro de manifesto da aplicação Web do PWA (como Demos/wami/manifest.json).

Declaração de exemplo:

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

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

Empacotar um PWA de loja no Microsoft Edge Stable

Em seguida, o seu PWA tem de ser empacotado como um PWA da Microsoft Store, para ser chamado pela arquitetura Windows App Actions.

Para empacotar o seu PWA como um PWA da Microsoft Store:

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

  2. Em Todas as definições, desloque-se para baixo até Ações – Ativar Ações na parte inferior.

  3. Certifique-se de que o ficheiro de manifesto da aplicação Web do PWA (como Demos/wami/manifest.json) tem protocol_handlers campos e share_target . PWABuilder.com executará uma marcar e, se um dos campos estiver em falta no manifesto da aplicação Web da aplicação, a caixa de verificação Ativar Ações estará desativada.

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

  5. Clique no botão Transferir .

  6. Deszipe o arquivo de transferência. Instale-o ao executar install.ps1.

  7. Inicie o PWA ao clicar no ícone do PWA.

  8. Teste as suas ações do PWA localmente ao seguir as Ações da Aplicação de Teste para um PWA, abaixo, para validar a funcionalidade.

  9. Abra o ficheiro de manifesto de definição de ação (como ActionsManifest.json) que utilizou ao empacotar no PWAbuilder.com.

  10. Defina a disponibilidade inicial de cada uma das ações da aplicação como false, conforme descrito em Definir disponibilidade inicial em Alternar disponibilidade de uma Ação de Aplicação para Windows.

    Antes de publicar o pacote, recomendamos o passo acima. Se não definir a disponibilidade inicial da ação da aplicação como false, a ação só funcionará se o utilizador aceder manualmente ao edge://flags Microsoft Edge e, em seguida, ativar o sinalizador #edge-app-actions-on-windows-for-web-appsde funcionalidade .

    A definição da disponibilidade inicial para false é necessária porque o suporte do Microsoft Edge para Ações de Aplicação no Windows em PWAs é controlado pelo sinalizador #edge-app-actions-on-windows-for-web-appsde funcionalidade e está desativado por predefinição, porque esta funcionalidade está atualmente na Versão de Avaliação do Programador.

    Quando o sinalizador #edge-app-actions-on-windows-for-web-apps de funcionalidade for lançado oficialmente (mais tarde, em 2025), o Microsoft Edge mudará automaticamente as ações que definiu no ficheiro de manifesto de definição de ação de Disabled para Enabled, permitindo que os utilizadores finais utilizem as ações da sua aplicação sem precisar de mais alterações da sua parte.

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

Empacotar um PWA de loja no Edge Canary

O Edge Canary fornece uma pré-visualização das funcionalidades que ainda não estão disponíveis num estado estável.

Se quiser experimentar as funcionalidades mais recentes das Ações da Aplicação no Edge Canary, pode empacotar o seu PWA no Edge Canary da seguinte forma:

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

  2. Obtenha o ID do Pacote, o ID do Publicador e o nome a apresentar do Publisher do seu PWA; consulte Publicar um PWA na Microsoft Store.

  3. Aceda a PWABuilder.Windows.Chromium tester.

  4. Introduza as configurações do PWA na caixa de entrada para os seguintes campos:

    • name: o nome do seu PWA.
    • packageId: não é necessário se não publicar a versão do Edge Canary da sua aplicação na loja; pode ser uma cadeia vazia.
    • url: o URL do seu PWA.
    • publisher.displayName: o nome do editor. Não é necessário se não publicar a versão do Edge Canary da sua aplicação na loja; pode ser uma cadeia vazia.
    • publisher.commonName: O ID do Publicador. Não é necessário se não publicar a versão do Edge Canary da sua aplicação na loja; pode ser uma cadeia vazia.
    • startUrl: o seu PWA.startUrl

    Exemplo de listagem JSON que pode copiar e colar no campo de texto do teste 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 da sua aplicação.

  5. Carregue o ficheiro de manifesto de definição de ação (como ActionsManifest.json) e, em seguida, clique no botão Transferir .

  6. A sua transferência é um .zip arquivo que contém ficheiros como .msix e .msixbundle ficheiros. Deszipe-o e execute-o install.ps1 para instalar o seu PWA diretamente.

  7. Clique no ícone do seu PWA.

    O seu PWA é iniciado.

  8. Inicie o Edge Canary e, em seguida, aceda a edge://apps.

    O seu PWA está listado.

  9. Clique no botão Detalhes .

    O seu PWA é indicado como instalado a partir da Microsoft Store.

O seu PWA foi agora instalado como um PWA de loja no Edge Canary.

Testar Ações da Aplicação para um PWA

Para testar as Ações da Aplicação para o seu PWA:

  1. Certifique-se de que o PWA foi configurado e empacotado com êxito, conforme abordado nas secções acima.

  2. Certifique-se de que o Windows está atualizado para suportar as Ações da Aplicação; consulte Windows 11 Insider Preview Build 26120.4151 (Canal Beta).

  3. Certifique-se de que o Microsoft Edge está atualizado para a versão mais recente e instale o seu PWA com êxito; consulte Compactar um PWA de arquivo no Edge Stable ou Empacotar um PWA de loja no Edge Canary, acima.

  4. Inicie o Edge Canary ou o Edge Stable (seja qual for o canal em que instalou o PWA).

  5. Aceda a edge://flags, procure Ações da Aplicação e localize a entrada Ativar Ações de Aplicação no Windows para aplicações Web. (O nome do sinalizador é #edge-app-actions-on-windows-for-web-apps.)

  6. Altere o status para Ativado e, em seguida, clique no botão Reiniciar no canto inferior direito.

  7. Inicie o seu PWA.

    O seu PWA tem de ser iniciado pelo menos uma vez para inicializar o PWA para a Ação da Aplicação, antes de ser chamado pelo runtime das Ações da Aplicação.

  8. Utilize a aplicação Ambiente de teste de ações de aplicativos para testar as Ações da Aplicação para o seu PWA.

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

    O PWA é iniciado e executa a Ação da Aplicação.

Confira também

Artigos do Windows:

Sites:

MDN:

Repositório de demonstrações:

  • Last updated on