Atualização dos Web Components: mais tempo para fazer upgrade para as APIs v1

Jonathan Bingham
X GitHub
Arthur Evans
X GitHub

As APIs Web Components v1 são um padrão de plataforma da Web lançado no Chrome, Safari, Firefox e, em breve, Edge. As APIs v1 são usadas por milhões de sites, alcançando bilhões de usuários diariamente. Os desenvolvedores que usaram as APIs de rascunho v0 forneceram um feedback valioso que influenciou as especificações. Mas as APIs v0 eram suportadas apenas pelo Chrome. Para garantir a interoperabilidade, no final do ano passado, anunciamos que essas APIs em rascunho foram descontinuadas e teriam sido removidas a partir do Chrome 73.

Como desenvolvedores suficientes pediram mais tempo para a migração, as APIs ainda não foram removidas do Chrome. As APIs de rascunho v0 serão removidas no Chrome 80 por volta de fevereiro de 2020.

Veja o que você precisa saber caso acredite estar usando as APIs v0:

De volta ao futuro: desativação das APIs v0

Para testar seu site com as APIs v0 desativadas, inicie o Chrome pela linha de comando com as seguintes sinalizações:

--disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports

É necessário sair do Chrome antes de iniciá-lo pela linha de comando. Se você tiver o Chrome Canary instalado, poderá executar o teste no Canary enquanto mantém essa página carregada no Chrome.

Para testar seu site com as APIs v0 desativadas:

  1. Se você estiver no Mac OS, navegue até chrome://version para encontrar o caminho executável do Chrome. Você precisará do caminho na etapa 3.
  2. Saia do Chrome.

  3. Reinicie o Chrome com as sinalizações de linha de comando:

    --disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports

    Para instruções sobre como iniciar o Chrome com sinalizações, consulte Executar o Chromium com sinalizações. Por exemplo, no Windows, você pode executar:

    chrome.exe --disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports

  4. Para verificar se você iniciou o navegador corretamente, abra uma nova guia, abra o console do DevTools e execute o seguinte comando:

    console.log(
"Native HTML Imports?", 'import' in document.createElement('link'),
"Native Custom Elements v0?", 'registerElement' in document,
"Native Shadow DOM v0?", 'createShadowRoot' in document.createElement('div'));

    Se tudo estiver funcionando conforme o esperado, você verá:

    Native HTML Imports? false Native Custom Elements v0? false Native Shadow DOM v0? false

    Se o navegador informar verdadeiro para um ou todos esses recursos, algo está errado. Saia totalmente do Chrome antes de reiniciar com as flags.

  5. Por fim, carregue o aplicativo e percorra os recursos. Se tudo funcionar conforme o esperado, está pronto.

Usar os polyfills v0

Os polyfills do Web Components v0 oferecem suporte às APIs v0 em navegadores que não oferecem suporte nativo. Caso seu site não funcione no Chrome com as APIs v0 desativadas, é provável que você não esteja carregando os polyfills. Existem várias possibilidades:

  • Você não está carregando os polyfills. Nesse caso, o site falhará em outros navegadores, como Firefox e Safari.
  • Você está carregando os polyfills condicionalmente com base na detecção do navegador. Nesse caso, seu site deve funcionar em outros navegadores. Pule para a seção Carregar os polyfills.

Antes, a equipe do Polymer Project e outros recomendavam carregar os polyfills condicionalmente com base na detecção de recursos. Essa abordagem funciona bem com as APIs v0 desativadas.

Instalar os polyfills v0

Os polyfills do Web Components v0 nunca foram publicados no registro npm. Você poderá instalar os polyfills usando o Bower, se seu projeto já estiver usando o Bower. Também é possível instalar usando um arquivo ZIP.

  • Para instalar com o Bower:

    bower install --save webcomponents/webcomponentsjs#^0.7.0

  • Para instalar usando um arquivo ZIP, faça o download da versão mais recente 0.7.x do GitHub:

    https://github.com/webcomponents/webcomponentsjs/releases/tag/v0.7.24

    Se você instalar usando um arquivo ZIP, vai precisar atualizar manualmente os polyfills se for lançada outra versão. Verifique os polyfills usando seu código.

Carregar os polyfills v0

Os polyfills do Web Components v0 são fornecidos como dois pacotes separados:

webcomponents-min.js Inclui todos os polyfills. Esse pacote inclui o polyfill shadow DOM, muito maior do que os outros e com maior impacto no desempenho. Use este pacote somente se precisar de suporte ao shadow DOM.
webcomponents-lite-min.js Inclui todos os polyfills, exceto o shadow DOM. Observação: os usuários do Polymer 1.x precisam escolher esse pacote, já que a emulação do Shadow DOM foi incluída diretamente na biblioteca do Polymer. Os usuários do Polymer 2.x precisam de uma versão diferente dos polyfills. Veja a postagem do blog sobre o Polymer Project (em inglês) para mais detalhes.

Há também polyfills individuais disponíveis como parte do pacote polyfill de Web Components. O uso de polyfills individuais separadamente é um tópico avançado não abordado aqui.

Para carregar os polyfills incondicionalmente:

<script src="/bower_components/webcomponents/webcomponentsjs/webcomponents-lite-min.js">
</script>

ou:

<script src="/bower_components/webcomponents/webcomponentsjs/webcomponents-min.js">
</script>

Se você instalou os polyfills diretamente do GitHub, informe o caminho em que eles foram instalados.

Se você carregar condicionalmente os polyfills com base na detecção de recursos, o site continuará funcionando quando a compatibilidade com a v0 for removida.

Se você carregar os polyfills condicionalmente usando a detecção do navegador (ou seja, carregando os polyfills em navegadores que não sejam o Chrome), o site falhará quando a compatibilidade com a v0 for removida do Chrome.

Preciso de ajuda! Não sei quais APIs estou usando.

Se você não sabe se está usando uma das APIs v0 ou quais APIs estão usando, verifique a saída do console no Chrome.

  1. Se você iniciou o Chrome anteriormente com as sinalizações para desativar as APIs v0, feche o Chrome e reinicie-o normalmente.
  2. Abra uma nova guia do Chrome e carregue o site.
  3. Pressione Control + Shift + J (Windows, Linux, ChromeOS) ou Command + Option + J (Mac) para abrir o Console do DevTools.
  4. Verifique se há mensagens de descontinuação na saída do console. Se houver muita saída do console, insira "Descontinuação" na caixa Filtro.
Janela do console mostrando avisos de descontinuação

Você verá mensagens de descontinuação para cada API v0 que estiver usando. A saída acima mostra mensagens para importações HTML, elementos personalizados v0 e shadow DOM v0.

Se você usa uma ou mais dessas APIs, consulte Usar os polyfills v0.

Próximas etapas: saída da v0

Verifique se os polyfills v0 estão sendo carregados para garantir que o site continue funcionando quando as APIs v0 forem removidas. Recomendamos migrar para as APIs Web Components v1, que têm ampla compatibilidade.

Se você estiver usando uma biblioteca do Web Components, como a biblioteca Polymer, a X-Tag ou a SkateJS, a primeira etapa será verificar se há versões mais recentes da biblioteca que dão suporte às APIs v1.

Se você tiver sua própria biblioteca ou tiver escrito elementos personalizados sem uma biblioteca, atualize para as novas APIs. Estes recursos podem ajudar:

Resumo

As APIs de rascunho do Web Components v0 serão desativadas. Se você perceber mais algum detalhe desta postagem, teste seu app com as APIs v0 desativadas e carregue os polyfills conforme necessário.

A longo prazo, recomendamos que você faça upgrade para as APIs mais recentes e continue usando o Web Components.