[GUIA PWA 03] Adapte seu PWA para Windows

Os PWAs instalados no Windows 10 desfrutam de todos os benefícios da execução como aplicativos da Plataforma Universal do Windows (UWP), incluindo proteção através da segurança do sandbox de aplicativos do Windows e acesso total a APIs do Windows Runtime (WinRT), incluindo:

• Controlando recursos do dispositivo (como câmera, microfone, GPS)
• Acessando recursos do usuário (como calendário, contatos, documentos, música)
• Lançando / navegando no seu aplicativo através dos comandos de voz da Cortana
• Integração com o sistema operacional Windows (por meio da Central de Açõesdo Windows, da barra de tarefas da área de trabalho e dos menus de contexto)

… e estas são apenas algumas das possibilidades adicionais para o seu PWA no Windows!

Este guia mostrará como instalar, executar e aprimorar seu PWA como um aplicativo do Windows 10, garantindo a compatibilidade entre navegadores e plataformas cruzadas.

Pré-requisitos

• Um PWA existente (ou aplicativo da web hospedado), seja um site ao vivo ou localhost. Este guia usará o PWA de amostra em Introdução aos Aplicativos da Web Progressivos.
• Baixe o (gratuito) Visual Studio Community 2017. Você também pode usar as edições Professional, Enterprise ou Preview ). No Visual Studio Installer, escolha as seguintes cargas de trabalho:
  • Desenvolvimento da Plataforma Universal do Windows

Configurar e executar seu aplicativo universal do Windows

Um PWA instalado como um aplicativo do Windows 10 é executado independentemente do navegador, em uma janela independente ( processo WWAHost.exe ). Habilitar isso simplesmente exige um “wrapper de aplicativo” leve que contenha seu aplicativo da Web hospedado, que você pode configurar rapidamente usando o modelo de projeto do Visual Studio Progressivo Web App (Universal Windows) . (Toda a lógica do seu aplicativo, incluindo as chamadas nativas da API do Tempo de Execução do Windows, ainda acontece no código original do aplicativo da Web.)

Vamos configurar nosso ambiente de desenvolvimento de aplicativos do Windows no Visual Studio.

1. Nas configurações doWindows, ative o modo de desenvolvedor . (Digite “modo de desenvolvedor” na barra de busca do Windows para encontrá-lo.)
2. Inicie o Visual Studioe crie um novo projeto…
3. Na categoria JavaScript> Windows Universal , selecione:
   • Aplicativo da Web hospedado (Universal Windows)se você estiver usando uma versão de lançamento do Visual Studio ou
   • Aplicativo Web progressivo (Windows universal)se você estiver usando uma compilação do Visual Studio Preview

• (O modelo de projeto subjacente é o mesmo.)
• Selecione a versãopadrão do Windows 10 Target( versão mais recente) e a versão mínima(compilação 10586 ou superior) e clique em OK .

Seu novo projeto será carregado com o designer package.appxmanifest aberto. Aqui você configura os detalhes do seu aplicativo, incluindo identidade de pacote, dependências de pacote, recursos necessários, elementos visuais e pontos de extensibilidade. Essa é uma versão temporária e facilmente configurável do manifesto do pacote de aplicativos usado durante o desenvolvimento do aplicativo.

Quando você cria seu projeto de aplicativo, o Visual Studio gera um arquivo AppxManifest.xml a partir desses metadados, que serão usados para instalar e executar o aplicativo. Sempre que você atualizar seu arquivo package.appxmanifest , certifique-se de reconstruir o projeto para que eles sejam refletidos em seu AppxManifest.xml em tempo de execução.

No painel Aplicativo do designer de manifesto, insira a URL do seu PWA como a página inicial.

1. Você também pode modificar o nome de exibiçãoe a descrição como desejar.
2. Salve esse arquivo(ou outra imagem de 512×512 de sua escolha) localmente.

Em seguida, no painel Ativos visuais do designer de manifesto, clique no botão Campo de origem…, selecione-o como seu arquivo de origem e clique em Gerar. (Em seguida, clique em OK para substituir as imagens de espaço reservado padrão).

1. Isso gerará os recursos visuais básicos para instalar, executar, lançar e distribuir seu aplicativo na loja.

Se você vir algum erro vermelho (‘X’) indicando imagens ausentes, poderá clicar nos botões … para selecionar manualmente um arquivo a partir das imagens geradas.

2. No painel URIs de Conteúdo dodesigner de manifesto, substitua http://example.com pelo local do seu PWA (de forma que Regra = incluir e WinRT Acessar = Tudo).

Isso concede a permissão do PWA para chamar APIs nativas do Tempo de Execução do Windows (WinRT) durante a execução como um aplicativo do Windows 10, o que faremos um pouco mais tarde. Se o seu PWA real não exigir acesso ao WinRT, você poderá alternar o valor do WinRT Access para Nenhum. De qualquer maneira, certifique-se de sub- inserir a string padrão http://example.com com o URI do seu PWA, ou seu aplicativo não carregará adequadamente em tempo de execução.

Você está pronto para executar e depurar seu PWA como um aplicativo do Windows 10. Se você estiver usando um site localhost para percorrer este guia, verifique se ele está sendo executado. Então,

3. Construa(Ctrl + Shift + F5) e execute (F5) seu projeto PWA. Seu site agora deve ser lançado em uma janela de aplicativo independente. Não é apenas um aplicativo da web hospedado; ele está sendo executado como um aplicativo da Web progressivo instalado no Windows 10!

Depure seu PWA como um aplicativo do Windows

Como um PWA é simplesmente um aplicativo da Web hospedado aprimorado progressivamente, você pode depurar seu código do lado do servidor da mesma maneira que faria com qualquer aplicativo da Web, usando seu IDE e fluxo de trabalho habituais. As alterações implantadas ao vivo serão refletidas no seu PWA instalado na próxima vez que forem executadas (não é necessário reimplantar o pacote do aplicativo Universal do Windows ).

Para a depuração do lado do cliente em seu aplicativo do Windows 10, você precisará do aplicativo Microsoft Edge DevTools Preview. Este aplicativo independente inclui todas as funcionalidades do Microsoft Edge DevTools (incluindo ferramentas PWA ) no navegador, além de suporte básico de depuração remota e um seletor de Destino de Depuração para anexar a qualquer instância em execução do mecanismo EdgeHTML, incluindo suplementos para o Office , Cortana , webviews de aplicativos e, claro, PWAs em execução no Windows .

Veja como configurar a depuração do seu PWA.

1. Instale o aplicativo Microsoft Edge DevTools Previewda Microsoft Store, se você ainda não o tiver.
2. Com o site do PWA ativo e em execução, inicie o aplicativo DevTools.
3. No Visual Studio, inicie o aplicativo do Windows 10 com o comando Iniciar sem depuração(Ctrl + F5). (O aplicativo DevTools não será anexado corretamente se o depurador do Visual Studio estiver ativo.)
4. No aplicativo DevTools, clique no botão Atualizarno seletor de destino de depuração loca . Seu site do PWA agora deve estar listado. (Se também estiver sendo executado em uma janela do navegador da etapa 2, será a última instância desse site na lista.)
5. Clique na listagem de sites do PWA para abrir uma nova guia da instância do DevTools e iniciar a depuração.

1. Você pode verificar se o DevTools está conectado ao aplicativo do PWA que executa o Windows. No DevTools Console, digite:

window.Windows

Isso retornará o objeto global do Tempo de Execução do Windows contendo todos os namespaces do WinRT de nível superior. Esse é o ponto de entrada do seu PWA para a Plataforma Universal do Windows e está exposto apenas a aplicativos da Web executados como aplicativos do Windows 10 (em execução fora do navegador, em um processo WWAHost.exe ).

Encontre APIs do Windows Runtime (WinRT)

Como um aplicativo do Windows instalado, seu PWA tem acesso total às APIs nativas do Windows Runtime; é apenas uma questão de identificar o que você precisa usar, obter as permissões necessárias e empregar a detecção de recursos para chamar essa API em ambientes suportados.

Vamos percorrer este processo para adicionar um aprimoramento progressivo para usuários de área de trabalho do Windows do seu PWA.

As APIs do WinRT podem fornecer funcionalidades adicionais para aplicativos da web em todas as áreas a seguir:

Há várias maneiras de identificar as APIs da Plataforma Universal do Windows necessárias para o seu Windows PWA, incluindo a pesquisa de documentos UWP abrangentes no Windows Dev Center, o download e a execução de amostras de código UWP com o Visual Studio e a navegação de trechos de código para tarefas comuns para PWAs. no Windows .

Windows Dev Center

No geral, as APIs do WinRT funcionam em JavaScript da mesma forma que em C#, portanto, você pode seguir a documentação geral da Plataforma Universal do Windows para uso. No entanto, observe as seguintes diferenças:

• Recursos do WinRT em JavaScript usam diferentes convenções de maiúsculas e minúsculas
• Eventos são representados como identificadores de string passados para a classe addEventListener/removeEventListenermétodos
• Métodos assíncronos usam o modelo Promise de JavaScript
• As APIs no Windows.UI.Xamlnamespace não são suportadas para aplicativos JavaScript, que usam a pilha de renderização da Web do mecanismo EdgeHTML (HTML, CSS)

Para mais detalhes, consulte Usando o Windows Runtime em JavaScript .

Amostras de código UWP

Confira o repositório de amostras de código da Plataforma Universal do Windows (UWP) para procurar exemplos de JavaScript para cenários comuns de aplicativos do Windows 10. Embora as versões JS dessas amostras usem a biblioteca WinJS para estruturar o modelo de amostra, o WinJS não é necessário para chamar as APIs do WinRT demonstradas por essas amostras. Observe que, se você precisar ouvir o activatedevento do aplicativo , poderá fazer isso usando a seguinte API nativa do WinRT:

USE ISTO

JavaScript

Windows.UI.WebUI.WebUIApplication.addEventListener(“activated”, function (activatedEventArgs) {
// Check activatedEventArgs.kind and respond as needed
});

… ao contrário deste tipo de chamada do WinJS usada nas amostras:

ISSO NÃO

JavaScript

var page = WinJS.UI.Pages.define(“/html/scenario1-launched.html”, {
ready: function (element, options) {
// Check options.activationKind and respond as needed
}
});

Chame as APIs do WinRT do seu PWA

Neste ponto, vamos fingir que queremos adicionar um menu de contexto personalizado para usuários do Windows do nosso PWA e identificamos as APIs que precisamos no namespace Windows.UI.Popups.

Para chamar qualquer API do WinRT do nosso PWA, primeiro precisamos estabelecer as permissões necessárias(ou, Regras de URI do Conteúdo do Aplicativo ) no arquivo do manifesto do pacote de aplicativos do Windows ( .appxmanifest ).

Se qualquer uma dessas chamadas de API envolver acesso a recursos do usuário, como imagens ou músicas, ou a recursos do dispositivo como a câmera ou o microfone, também precisaremos adicionar declarações de recursos do aplicativo ao manifesto do pacote de aplicativos para que o Windows solicite ao usuário permissão. Se você publicar mais tarde o seu PWA na Microsoft Store, essas permissões necessárias do App também serão registradas na listagem do seu armazenamento.

Definir regras de URI de conteúdo do aplicativo (ACURs)

Por meio de ACURs, também conhecido como lista de permissão de URL, você pode fornecer às URLs do seu PWA acesso direto às APIs de Tempo de Execução do Windows. No nível do sistema operacional Windows, os limites de política corretos serão definidos para permitir que o código hospedado em seu servidor da Web chame diretamente as APIs da plataforma. Você define esses limites no arquivo de manifesto do pacote de aplicativos quando especifica os URLs do PWA como ApplicationContentUriRules.

Suas regras devem incluir a página inicial do seu aplicativo e qualquer outra página que você queira incluir como páginas do aplicativo. Se o usuário navegar para uma URL que não esteja incluída nas regras, o Windows abrirá a URL de destino no navegador Microsoft Edge, e não na janela independente do PWA ( processo WWAHost.exe ). Você também pode excluir URLs específicos.

Existem várias maneiras de especificar um URL Matchnas suas regras:

• Um nome de host exato
• Um nome de host para o qual um URI com qualquer subdomínio desse nome de host é incluído ou excluído
• Um URI exato
• Um URI exato contendo uma propriedade de consulta
• Um caminho parcial e um curinga para indicar uma extensão de arquivo específica para uma regra de inclusão
• Caminhos relativos para regras de exclusão

Aqui estão alguns exemplos de ACURs em um arquivo .appxmanifest :

XML

<Application
Id=”App”
StartPage=”https://contoso.com/home”>
<uap:ApplicationContentUriRules>
<uap:Rule Type=”include” Match=”https://contoso.com/” WindowsRuntimeAccess=”all” />
<uap:Rule Type=”include” Match=”https://*.contoso.com/” WindowsRuntimeAccess=”all” />
<uap:Rule Type=”exclude” Match=”https://contoso.com/excludethispage.aspx” />
</uap:ApplicationContentUriRules>

As URLs definidas nos ACURs do aplicativo podem receber permissão para o Tempo de Execução do Windows por meio do WindowsRuntimeAccessatributo, que aceita os seguintes valores:

• all: o código JavaScript remoto tem acesso a todas as APIs do WinRT e a qualquer componente local empacotado. O namespace Windows (WinRT) será injetado e presente no mecanismo de script
• allowForWeb: O acesso ao código JavaScript remoto é limitado a componentes locais empacotados, incluindo componentes C ++ / C # personalizados.
• nenhum: padrão. O URL especificado não tem acesso à plataforma.

Neste tutorial, já definimos o único ACUR necessário ( Etapa 6 da seção Configurar e executar seu aplicativo anterior ) para nosso “aplicativo de página única”. Você pode confirmar isso no painel URIs de conteúdo do designer package.appxmanifest do Visual Studio.

Você também pode exibir o XML bruto do seu manifesto clicando com o botão direito do mouse no arquivo package.appxmanifest no Visual Studio Solution Explorer e selecionando View Code (F7). Para alternar de volta para a visualização Designer , selecione View Designer (Shift + F7).

Declarações de capacidade de aplicativos

Se o seu aplicativo precisar de acesso programático a recursos do usuário, como imagens ou músicas, ou a dispositivos como uma câmera ou um microfone, você precisará incluir as declarações de recursos do aplicativo correspondentes no arquivo de manifesto do seu pacote de aplicativos. Existem três categorias de declaração de capacidade de aplicativo:

• Recursos de uso geralque se aplicam aos cenários de aplicativos mais comuns.
• Recursos do dispositivoque permitem que seu aplicativo acesse dispositivos periféricos e internos.
• Recursos de uso especialque suportam cenários corporativos e exigem uma conta corporativa da Microsoft Store . Para mais informações sobre contas de empresas, consulte Tipos de contas, locais e taxas .

A página da Microsoft Store do seu aplicativo listará todos os recursos que você declarar no manifesto do seu pacote de aplicativos, portanto, certifique-se de especificar apenas os recursos que o seu aplicativo realmente usa.

Alguns recursos fornecem acesso a aplicativos para recursos confidenciais. Esses recursos são considerados sensíveis porque podem acessar os dados pessoais do usuário ou custar dinheiro ao usuário. As configurações de privacidade, gerenciadas pelo aplicativo Configurações do Windows 10, permitem que o usuário controle dinamicamente o acesso a recursos confidenciais. Assim, é importante que seu aplicativo não assuma que um recurso confidencial esteja sempre disponível. Para obter mais informações sobre como acessar recursos confidenciais, consulte Diretrizes para aplicativos com reconhecimento de privacidade.

Você solicita acesso declarando recursos no manifesto do pacote do seu aplicativo. No Visual Studio, você pode fazer isso no painel Capacidades do designer package.appxmanifest.

Neste tutorial, exigimos apenas o recurso padrão da Internet (Cliente), portanto, nenhuma outra ação é necessária.

Use a detecção de recursos para chamar o WinRT

Para garantir uma experiência de linha de base de qualidade para o nosso público do PWA em todas as plataformas, aprimoraremos progressivamente nossa experiência do PWA no Windows usando a detecção de recursos do WinRT. Dessa forma, podemos ter certeza de que nosso código específico do Windows é executado apenas em um contexto em que as APIs do WinRT estão disponíveis e são aplicáveis.

A detecção de recursos pode ser tão simples quanto procurar o Windowsobjeto (o ponto de entrada para o namespace do WinRT ) como abaixo:

JavaScript

if(window.Windows){
/*Execute code that calls Windows APIs */
}

No entanto, como nem todas as APIs do Windows estão disponíveis em todos os tipos de dispositivos do Windows 10, geralmente é útil usar uma detecção de recurso mais específica para qualificar ainda mais o namespace da API que você estará chamando:

JavaScript

if(window.Windows && Windows.Media.SpeechRecognition){
/*Execute code that calls Windows APIs */
}

Com esse pano de fundo, estamos prontos para adicionar um código WinRT para implementar um menu de contexto personalizado. Se você estiver usando o exemplo do PWA em Introdução ao Progressive Web Apps :

1. Abra o Visual Studio para seu projeto de site do PWA.
2. No Solution Explorer, abra o arquivo views \ layout.puge adicione a seguinte linha, logo abaixo da scriptreferência para o seu service worker:

Copiar

script(src=’/javascripts/site.js’)

3. Em Solution Explorer, clique com botão direito sobre a javascriptspasta e Adicionar > Novo arquivo … .
4. Nomeie seu arquivo: jse copie no código a seguir:

JavaScript

if (window.Windows && Windows.UI.Popups) {
document.addEventListener(‘contextmenu’, function (e) {

// Build the context menu
var menu = new Windows.UI.Popups.PopupMenu();
menu.commands.append(new Windows.UI.Popups.UICommand(“Option 1”, null, 1));
menu.commands.append(new Windows.UI.Popups.UICommandSeparator);
menu.commands.append(new Windows.UI.Popups.UICommand(“Option 2”, null, 2));

// Convert from webpage to WinRT coordinates
function pageToWinRT(pageX, pageY) {
var zoomFactor = document.documentElement.msContentZoomFactor;
return {
x: (pageX – window.pageXOffset) * zoomFactor,
y: (pageY – window.pageYOffset) * zoomFactor
};
}

// When the menu is invoked, execute the requested command
menu.showAsync(pageToWinRT(e.pageX, e.pageY)).done(function (invokedCommand) {
if (invokedCommand !== null) {
switch (invokedCommand.id) {
case 1:
console.log(‘Option 1 selected’);
// Invoke code for option 1
break;
case 2:
console.log(‘Option 2 selected’);
// Invoke code for option 2
break;
default:
break;
}
} else {
// The command is null if no command was invoked.
console.log(“Context menu dismissed”);
}
});
}, false);
}

5. Compare o comportamento do menu de contexto quando você executa seu PWA no navegador ( F5do projeto de site do PWA) versus de dentro de sua janela de aplicativo do Windows ( F5 do projeto de aplicativo Universal do Windows ). No navegador, clicar com o botão direito do mouse fornece o menu de contexto padrão do Edge, enquanto no processo exe , o menu personalizado aparece agora.

Microsoft Edge                                                                 Aplicativo do Windows 10

Espero que agora você tenha uma base sólida para aprimorar progressivamente seus PWAs no Windows. Se você tiver dúvidas ou algo não estiver claro, por favor, envie um comentário!

O Windows Dev Center é sua referência completa para todos os estágios da criação de aplicativos do Windows, desde o início, até o design, o desenvolvimento e a publicação na Microsoft Store.

Para obter uma visão geral sobre a Plataforma Universal do Windows (UWP) e como segmentar diferentes famílias de dispositivos do Windows 10, consulte Introdução à Plataforma Universal do Windows.

E quando você estiver pronto, veja como (e por quê) enviar seu PWA à Microsoft Store.

No próximo post: PWAs na Microsoft Store

Fonte: Microsoft