Aggiornamento dei componenti web: più tempo per eseguire l'upgrade alle API v1

Jonathan Bingham
X GitHub
Arthur Evans
X GitHub

Le API Web Componenti v1 sono uno standard della piattaforma web disponibile in Chrome, Safari, Firefox e (a breve) Edge. Le API v1 vengono utilizzate letteralmente da milioni di siti e raggiungono miliardi di utenti ogni giorno. Gli sviluppatori che utilizzavano le API v0 in versione bozza hanno fornito un feedback prezioso che ha influenzato le specifiche. Tuttavia, le API v0 erano supportate solo da Chrome. Per garantire l'interoperabilità, alla fine dell'anno scorso, abbiamo annunciato che queste API in versione bozza erano deprecate e ne è stata programmata la rimozione a partire da Chrome 73.

Poiché un numero sufficiente di sviluppatori ha richiesto più tempo per la migrazione, le API non sono ancora state rimosse da Chrome. Le API bozza v0 verranno ora rimosse in Chrome 80, intorno a febbraio 2020.

Ecco cosa devi sapere se ritieni di utilizzare le API v0:

Ritorno al futuro: disattivazione delle API v0

Per testare il tuo sito con le API v0 disattivate, devi avviare Chrome dalla riga di comando con i seguenti flag:

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

Devi uscire da Chrome prima di avviarlo dalla riga di comando. Se hai installato Chrome Canary, puoi eseguire il test in Canary mantenendo la pagina caricata in Chrome.

Per testare il tuo sito con le API v0 disattivate:

  1. Se usi Mac OS, vai a chrome://version per trovare il percorso eseguibile di Chrome. Avrai bisogno del percorso indicato nel passaggio 3.
  2. Esci da Chrome.

  3. Riavvia Chrome con i flag della riga di comando:

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

    Per istruzioni su come avviare Chrome con i flag, consulta l'articolo Eseguire Chromium con i flag. Ad esempio, su Windows potresti eseguire:

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

  4. Per verificare di aver avviato correttamente il browser, apri una nuova scheda, apri la console DevTools ed esegui questo 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 tutto funziona come previsto, dovresti vedere:

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

    Se il browser segnala una o tutte le funzionalità vere, si è verificato un problema. Assicurati di aver chiuso completamente Chrome prima di riavviare con i flag.

  5. Infine, carica l'app ed esamina le funzionalità. Se tutto funziona come previsto, è tutto.

Utilizza i polyfill v0

I polyfill v0 dei componenti web forniscono supporto per le API v0 sui browser che non offrono supporto nativo. Se il tuo sito non funziona su Chrome con le API v0 disattivate, probabilmente non stai caricando i polyfill. Esistono diverse possibilità:

  • Non stai caricando affatto i polyfill. In questo caso, il tuo sito non dovrebbe funzionare su altri browser, come Firefox e Safari.
  • Stai caricando i polyfill in modo condizionale in base allo sniffing del browser. In questo caso, il tuo sito dovrebbe funzionare su altri browser. Vai direttamente a Caricare i polyfill.

In passato, il team di Polymer Project e altri consigliavano di caricare i polyfill in modo condizionale in base al rilevamento delle funzionalità. Questo approccio dovrebbe funzionare correttamente con le API v0 disabilitate.

Installa i polyfill v0

I polyfill della versione v0 di Web Componenti non sono mai stati pubblicati nel registro npm. Puoi installare i polyfill utilizzando Bower, se il tuo progetto utilizza già Bower. In alternativa, puoi eseguire l'installazione da un file ZIP.

  • Per l'installazione con Bower:

    bower install --save webcomponents/webcomponentsjs#^0.7.0

  • Per eseguire l'installazione da un file ZIP, scarica l'ultima release 0.7.x da GitHub:

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

    Se esegui l'installazione da un file ZIP, dovrai aggiornare manualmente i polyfill se esce un'altra versione. Probabilmente vorrai controllare i polyfill con il tuo codice.

Carica i polyfill v0

I polyfill della versione v0 di Web Componenti vengono forniti come due bundle separati:

webcomponents-min.js Include tutti i polyfill. Questo bundle include il polyfill shadow DOM, che è molto più grande degli altri polyfill e ha un impatto maggiore sulle prestazioni. Utilizza questo bundle solo se hai bisogno del supporto dello shadow DOM.
webcomponents-lite-min.js Include tutti i polyfill tranne shadow DOM. Nota: gli utenti di Polymer 1.x devono scegliere questo bundle, poiché l'emulazione DOM Shadow è stata inclusa direttamente nella libreria Polymer. Gli utenti di Polymer 2.x devono avere una versione diversa dei polyfill. Per informazioni dettagliate, consulta il post del blog di Polymer Project.

Nel pacchetto di polyfill di Web Componenti sono disponibili anche singoli polyfill. L'utilizzo di singoli polyfill separatamente è un argomento avanzato, non trattato qui.

Per caricare i polyfill incondizionatamente:

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

Oppure:

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

Se hai installato i polyfill direttamente da GitHub, dovrai fornire il percorso in cui hai installato i polyfill.

Se carichi in modo condizionale i polyfill in base al rilevamento delle funzionalità, il tuo sito continuerà a funzionare anche dopo la rimozione del supporto della versione v0.

Se carichi i polyfill in modo condizionale utilizzando lo sniffing del browser (ovvero caricando i polyfill su browser diversi da Chrome), il sito non riuscirà quando verrà rimosso il supporto v0 da Chrome.

Aiuto! Non so quali API sto utilizzando.

Se non sai se stai utilizzando una delle API v0 o quali API stai utilizzando, puoi controllare l'output della console in Chrome.

  1. Se in precedenza hai avviato Chrome con i flag per disabilitare le API v0, chiudi Chrome e riavvialo normalmente.
  2. Apri una nuova scheda di Chrome e carica il tuo sito.
  3. Premi Ctrl + Maiusc + J (Windows, Linux, ChromeOS) o Comando + Opzione + J (Mac) per aprire la console DevTools.
  4. Verifica la presenza di messaggi relativi al ritiro nell'output della console. Se sono disponibili molti output della console, inserisci "Deprecazione" nella casella Filtro.
Finestra della console che mostra avvisi relativi al ritiro

Dovresti vedere i messaggi relativi al ritiro per ogni API v0 che utilizzi. L'output riportato sopra mostra i messaggi per le importazioni HTML, gli elementi personalizzati v0 e shadow DOM v0.

Se utilizzi una o più di queste API, consulta Utilizzare i polyfill v0.

Passaggi successivi: rimozione dalla versione 0

Assicurati che i polyfill v0 vengano caricati per garantire che il tuo sito continui a funzionare anche dopo la rimozione delle API v0. Ti consigliamo di passare alle API Web Componenti v1, che sono ampiamente supportate.

Se utilizzi una libreria di componenti web, ad esempio la libreria Polymer, X-Tag o SkateJS, il primo passaggio consiste nel verificare se sono disponibili versioni più recenti della libreria che supportano le API v1.

Se hai la tua libreria o hai scritto elementi personalizzati senza una libreria, dovrai eseguire l'aggiornamento alle nuove API. Queste risorse potrebbero esserti utili:

Riepilogo

Le API bozza Web Componenti v0 non saranno più disponibili. Se traspari qualcosa da questo post, assicurati di testare la tua app con le API v0 disabilitate e di caricare i polyfill secondo necessità.

A lungo termine, ti invitiamo a eseguire l'upgrade alle API più recenti e a continuare a utilizzare i componenti web.