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

Jonathan Bingham
X GitHub
Arthur Evans
X GitHub

Le API Web Components v1 sono uno standard della piattaforma web che è stato implementato in Chrome, Safari, Firefox e (a breve) Edge. Le API v1 vengono utilizzate da milioni di siti e raggiungono miliardi di utenti ogni giorno. Gli sviluppatori che utilizzano le API di bozza v0 hanno fornito feedback preziosi che hanno influito sulle specifiche. Tuttavia, le API v0 erano supportate solo da Chrome. Per garantire l'interoperabilità, lo scorso anno abbiamo annunciato che queste API di anteprima sono state ritirate e la loro rimozione è stata pianificata a partire da Chrome 73.

Poiché un numero sufficiente di sviluppatori ha richiesto più tempo per la migrazione, le API non sono state ancora rimosse da Chrome. Le API di anteprima v0 sono ora destinate alla rimozione 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

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

Per testare il tuo sito con le API v0 disattivate:

  1. Se utilizzi Mac OS, vai a chrome://version per trovare il percorso del file eseguibile di Chrome. Ti servirà 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 Eseguire Chromium con i flag. Ad esempio, su Windows, puoi 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 di DevTools esegui il seguente 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 true per una o tutte queste funzionalità, c'è un problema. Assicurati di aver chiuso completamente Chrome prima di riavviarlo con i flag.

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

Utilizzare i polyfill della versione 0

I polyfill di Web Components v0 forniscono il supporto per le API v0 sui browser che non supportano la versione nativa. Se il tuo sito non funziona su Chrome con le API v0 disattivate, probabilmente non stai caricando i polyfill. Esistono diverse possibilità:

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

In passato, il team del progetto Polymer e altri hanno consigliato di caricare i polyfill in modo condizionale in base al rilevamento delle funzionalità. Questo approccio dovrebbe funzionare correttamente con le API v0 disattivate.

Installa i polyfill della versione 0

I polyfill di Web Components v0 non sono mai stati pubblicati nel registry npm. Puoi installare i polyfill utilizzando Bower, se il tuo progetto utilizza già Bower. In alternativa, puoi installare il programma da un file ZIP.

  • Per l'installazione con Bower:

    bower install --save webcomponents/webcomponentsjs#^0.7.0

  • Per l'installazione da un file ZIP, scarica la versione 0.7.x più recente 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 viene rilasciata un'altra versione. Probabilmente ti consigliamo di controllare i polyfill nel codice.

Carica i polyfill v0

I polyfill di Web Components v0 sono forniti come due bundle distinti:

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

Sono inoltre disponibili singoli polyfill all'interno del pacchetto polyfill di componenti web. 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, devi fornire il percorso in cui li hai installati.

Se carichi i polyfill in modo condizionale in base al rilevamento delle funzionalità, il tuo sito dovrebbe continuare a funzionare quando il supporto della versione 0 viene rimosso.

Se carichi i polyfill in modo condizionale utilizzando lo sniffing del browser (ovvero caricandoli su browser diversi da Chrome), il tuo sito non funzionerà quando il supporto della versione 0 verrà rimosso 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 disattivare 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 Cmd+Opzione+J (Mac) per aprire la Console di DevTools.
  4. Controlla se nell'output della console sono presenti messaggi di ritiro. Se l'output della console è molto elevato, inserisci "Ritiro" nella casella Filtra.
Finestra della console che mostra gli avvisi di ritiro

Dovresti vedere i messaggi di ritiro per ogni API v0 in uso. L'output riportato sopra mostra i messaggi per HTML Imports, Custom Elements v0 e Shadow DOM v0.

Se utilizzi una o più di queste API, consulta la sezione Utilizzare i polyfill della versione 0.

Passaggi successivi: ritiro dalla versione 0

Assicurati che i polyfill della versione 0 vengano caricati per garantire il funzionamento del tuo sito quando le API v0 vengono rimosse. Ti consigliamo di passare alle API Web Components v1, che sono ampiamente supportate.

Se utilizzi una libreria di componenti web, come 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 una tua raccolta o hai scritto elementi personalizzati senza una raccolta, dovrai eseguire l'aggiornamento alle nuove API. Queste risorse potrebbero esserti utili:

Riepilogo

Le API di bozza Web Components v0 non saranno più disponibili. Se c'è una cosa che devi ricordare di questo post, assicurati di testare l'app con le API v0 disattivate e di caricare i polyfill in base alle necessità.

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