Mise à jour des composants Web : plus de temps pour passer aux API v1

Jonathan Bingham
X GitHub
Arthur Evans
X GitHub

Les API Web Components v1 sont une norme de plate-forme Web disponible dans Chrome, Safari, Firefox et (bientôt) Edge. Les API v1 sont utilisées par des millions de sites et touchent des milliards d'utilisateurs chaque jour. Les développeurs utilisant les versions préliminaires des API v0 ont fourni de précieux commentaires qui ont influencé les spécifications. Cependant, les API v0 n'étaient compatibles qu'avec Chrome. Afin d'assurer l'interopérabilité, nous avons annoncé à la fin de l'année dernière que ces brouillons d'API étaient obsolètes et seraient supprimés à partir de Chrome 73.

Étant donné que suffisamment de développeurs ont demandé plus de temps pour la migration, les API n'ont pas encore été supprimées de Chrome. Les versions préliminaires des API v0 devraient être supprimées dans Chrome 80, aux alentours de février 2020.

Voici ce que vous devez savoir si vous pensez utiliser les API v0:

Retour vers le futur: désactiver les API v0

Pour tester votre site avec les API v0 désactivées, vous devez démarrer Chrome à partir de la ligne de commande avec les indicateurs suivants:

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

Vous devez quitter Chrome avant de le lancer à partir de la ligne de commande. Si Chrome Canary est installé, vous pouvez exécuter le test dans Canary tout en laissant cette page chargée dans Chrome.

Pour tester votre site en désactivant les API v0:

  1. Si vous utilisez Mac OS, accédez à chrome://version pour trouver le chemin d'accès au fichier exécutable de Chrome. Vous en aurez besoin à l'étape 3.
  2. Quittez Chrome.

  3. Redémarrez Chrome à l'aide des indicateurs de ligne de commande:

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

    Pour obtenir des instructions sur le démarrage de Chrome avec des indicateurs, consultez Exécuter Chromium avec des indicateurs. Par exemple, sous Windows, vous pouvez exécuter la commande suivante:

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

  4. Pour vérifier que vous avez démarré le navigateur correctement, ouvrez un nouvel onglet, ouvrez la console DevTools, puis exécutez la commande suivante:

    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'));

    Si tout fonctionne comme prévu, vous devriez obtenir le résultat suivant:

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

    Si le navigateur indique "true" pour tout ou partie de ces fonctionnalités, il y a un problème. Assurez-vous d'avoir complètement quitté Chrome avant de redémarrer avec les indicateurs.

  5. Enfin, chargez votre application et passez en revue les fonctionnalités. Si tout fonctionne comme prévu, vous avez terminé.

Utiliser les polyfills v0

Les polyfills Web Components v0 sont compatibles avec les API v0 sur les navigateurs qui n'offrent pas de compatibilité native. Si votre site ne fonctionne pas sur Chrome avec les API v0 désactivées, vous ne chargez probablement pas les polyfills. Plusieurs possibilités s'offrent à vous:

  • Vous ne chargez pas du tout les polyfills. Dans ce cas, l'exécution de votre site échoue sur d'autres navigateurs, tels que Firefox et Safari.
  • Vous chargez les polyfills de manière conditionnelle en fonction du reniflage du navigateur. Dans ce cas, votre site devrait fonctionner sur d'autres navigateurs. Passez à l'étape Charger les polyfills.

Par le passé, l'équipe du projet Polymer et d'autres recommandaient de charger les polyfills de manière conditionnelle en fonction de la détection des caractéristiques. Cette approche devrait fonctionner correctement lorsque les API v0 sont désactivées.

Installer les polyfills v0

Les polyfills Web Components v0 n'ont jamais été publiés dans le registre npm. Vous pouvez installer les polyfills à l'aide de Bower si votre projet l'utilise déjà. Vous pouvez également l'installer à partir d'un fichier ZIP.

  • Pour effectuer l'installation avec Bower:

    bower install --save webcomponents/webcomponentsjs#^0.7.0

  • Pour effectuer l'installation à partir d'un fichier ZIP, téléchargez la dernière version 0.7.x depuis GitHub:

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

    Si vous effectuez l'installation à partir d'un fichier ZIP, vous devrez mettre à jour manuellement les polyfills si une autre version sort. Vous voudrez probablement vérifier les polyfills avec votre code.

Charger les polyfills v0

Les polyfills Web Components v0 sont fournis sous la forme de deux groupes distincts:

webcomponents-min.js Inclut tous les polyfills. Ce bundle inclut le polyfill Shadow DOM, beaucoup plus grand que les autres polyfills, et qui a un impact plus important sur les performances. N'utilisez ce lot que si vous avez besoin de la compatibilité avec le Shadow DOM.
webcomponents-lite-min.js Inclut tous les polyfills, à l'exception du Shadow DOM. Remarque: Les utilisateurs de Polymer 1.x doivent choisir ce bundle, car l'émulation Shadow DOM a été incluse directement dans la bibliothèque Polymer. Les utilisateurs de Polymer 2.x ont besoin d'une version différente des polyfills. Pour en savoir plus, consultez l'article de blog sur le projet Polymer.

Des polyfills individuels sont également disponibles dans le package de polyfills Web Components. L'utilisation de polyfills individuels séparément est un sujet avancé qui n'est pas abordé ici.

Pour charger les polyfills de manière inconditionnelle:

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

soit :

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

Si vous avez installé les polyfills directement à partir de GitHub, vous devez indiquer le chemin où vous avez installé les polyfills.

Si vous chargez les polyfills de manière conditionnelle en fonction de la détection de caractéristiques, votre site devrait continuer à fonctionner lorsque la version v0 ne sera plus prise en charge.

Si vous chargez les polyfills de manière conditionnelle à l'aide du reniflage du navigateur (c'est-à-dire, en chargeant les polyfills sur des navigateurs autres que Chrome), votre site échouera lorsque Chrome ne sera plus compatible avec la version v0.

Aidez-moi ! Je ne sais pas quelles API j'utilise !

Si vous ne savez pas si vous utilisez l'une des API v0 ou quelles API vous utilisez, vous pouvez consulter la sortie de la console dans Chrome.

  1. Si vous avez déjà démarré Chrome avec les indicateurs permettant de désactiver les API v0, fermez Chrome et redémarrez-le normalement.
  2. Ouvrez un nouvel onglet Chrome et chargez votre site.
  3. Appuyez sur Ctrl+Maj+J (Windows, Linux, ChromeOS) ou Commande+Option+J (Mac) pour ouvrir la console DevTools.
  4. Vérifiez si des messages d'abandon s'affichent dans la sortie de la console. Si les résultats de la console sont nombreux, saisissez "Deprecation" (Abandon) dans la zone Filter (Filtre).
Fenêtre de la console affichant des avertissements d&#39;abandon

Des messages d'abandon doivent s'afficher pour chaque API v0 que vous utilisez. La sortie ci-dessus affiche les messages pour les importations HTML, les éléments personnalisés v0 et le Shadow DOM v0.

Si vous utilisez une ou plusieurs de ces API, consultez Utiliser les polyfills v0.

Étapes suivantes: quitter la version v0

En vous assurant que les polyfills v0 sont chargés, vous devez vous assurer que votre site continue de fonctionner après la suppression des API v0. Nous vous recommandons de passer aux API Web Components v1, qui sont largement compatibles.

Si vous utilisez une bibliothèque de composants Web, telle que la bibliothèque Polymer, X-Tag ou SkateJS, la première étape consiste à vérifier si de nouvelles versions de la bibliothèque compatibles avec les API v1 sont disponibles.

Si vous disposez de votre propre bibliothèque ou si vous avez écrit des éléments personnalisés sans bibliothèque, vous devez passer aux nouvelles API. Ces ressources peuvent vous être utiles:

Récapitulatif

Les versions préliminaires des API Web Components v0 vont disparaître. S'il y a une chose à retenir de cet article, assurez-vous de tester votre application avec les API v0 désactivées et de charger les polyfills si nécessaire.

Sur le long terme, nous vous encourageons à passer aux dernières API et à continuer à utiliser les composants Web.