Cette page a été traduite par l'API Cloud Translation.

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

Jonathan Bingham

Arthur Evans

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, touchant des milliards d'utilisateurs chaque jour. Les développeurs qui utilisent les API v0 provisoires ont fourni des commentaires précieux qui ont influencé les spécifications. Toutefois, les API v0 n'étaient compatibles qu'avec Chrome. Afin de garantir l'interopérabilité, nous avons annoncé à la fin de l'année dernière que ces API provisoires étaient obsolètes et qu'elles devaient être supprimées à partir de Chrome 73.

Étant donné que suffisamment de développeurs ont demandé plus de temps pour effectuer la migration, les API n'ont pas encore été supprimées de Chrome. Les API v0 provisoires devraient être supprimées de Chrome 80, vers février 2020.

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

Testez votre site avec les API v0 désactivées. Si votre site fonctionne comme prévu, félicitations ! C'est tout. Pour obtenir des instructions, consultez Retour vers le futur: désactiver les API v0.
Si vous utilisez la bibliothèque Polymer v1 ou v2, suivez les instructions publiées précédemment par l'équipe Polymer.
Si vous utilisez Shadow DOM v0, des éléments personnalisés v0 ou des importations HTML, vous devez charger des polyfills. Consultez Utiliser les polyfills v0.
Si vous n'êtes pas sûr de ce que vous utilisez, ne vous inquiétez pas. Consultez la section Aide ! Je ne sais pas quelles API j'utilise.

Retour vers le futur: désactivation des 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 démarrer à partir de la ligne de commande. Si vous avez installé Chrome Canary, vous pouvez exécuter le test dans Canary tout en laissant cette page chargée dans Chrome.

Pour tester votre site avec les API v0 désactivées:

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.
Quittez Chrome.
Redémarrez Chrome avec les options de ligne de commande:

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

Pour savoir comment démarrer Chrome avec des indicateurs, consultez la section Exécuter Chromium avec des indicateurs. Par exemple, sous Windows, vous pouvez exécuter:
```
chrome.exe --disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports
```
Pour vérifier que vous avez correctement démarré le navigateur, ouvrez un nouvel onglet, ouvrez la console DevTools et 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, le message suivant doit s'afficher:
```
Native HTML Imports? false Native Custom Elements v0? false Native Shadow DOM v0? false
```
Si le navigateur indique "true" pour l'une ou l'ensemble de ces fonctionnalités, un problème est présent. Assurez-vous d'avoir complètement fermé Chrome avant de le redémarrer avec les indicateurs.
Enfin, chargez votre application et explorez 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 ne les prennent pas en charge en mode natif. Si votre site ne fonctionne pas dans Chrome lorsque les API v0 sont 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, votre site devrait échouer dans d'autres navigateurs, comme Firefox et Safari.
Vous chargez les polyfills de manière conditionnelle en fonction de l'analyse du navigateur. Dans ce cas, votre site devrait fonctionner dans d'autres navigateurs. Passez directement à la section Charger les polyfills.

Par le passé, l'équipe du projet Polymer et d'autres personnes ont recommandé de charger les polyfills de manière conditionnelle en fonction de la détection des fonctionnalités. Cette approche devrait fonctionner correctement avec les API v0 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 utilise déjà Bower. Vous pouvez également installer l'extension à partir d'un fichier ZIP.

Pour l'installer avec Bower:

bower install --save webcomponents/webcomponentsjs#^0.7.0
Pour installer à partir d'un fichier ZIP, téléchargez la dernière version 0.7.x sur 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 est publiée. Vous devrez probablement vérifier les polyfills dans votre code.

Charger les polyfills v0

Les polyfills Web Components v0 sont fournis en deux bundles distincts:

`webcomponents-min.js`	Inclut tous les polyfills. Ce bundle inclut le polyfill DOM ombragé, qui est beaucoup plus volumineux que les autres polyfills et a un impact plus important sur les performances. N'utilisez ce bundle que si vous avez besoin de la compatibilité avec le DOM fantôme.
`webcomponents-lite-min.js`	Inclut tous les polyfills, à l'exception du DOM ombragé. Remarque: Les utilisateurs de Polymer 1.x doivent choisir ce bundle, car l'émulation du DOM ombragé était incluse directement dans la bibliothèque Polymer. Les utilisateurs de Polymer 2.x ont besoin d'une autre version des polyfills. Pour en savoir plus, consultez cet 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 sans condition:

<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 depuis GitHub, vous devez fournir le chemin d'accès où vous les avez installés.

Si vous chargez les polyfills de manière conditionnelle en fonction de la détection de fonctionnalités, votre site devrait continuer à fonctionner lorsque la prise en charge de la version 0 sera supprimée.

Si vous chargez les polyfills de manière conditionnelle à l'aide de l'analyse du navigateur (c'est-à-dire en chargeant les polyfills sur des navigateurs autres que Chrome), votre site échouera lorsque la prise en charge de la version 0 sera supprimée de Chrome.

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

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

Si vous avez déjà démarré Chrome avec les indicateurs pour désactiver les API v0, fermez Chrome et redémarrez-le normalement.
Ouvrez un nouvel onglet Chrome et chargez votre site.
Appuyez sur Ctrl+Maj+J (Windows, Linux, ChromeOS) ou Cmd+Option+J (Mac) pour ouvrir la console des outils pour les développeurs.
Recherchez les messages d'abandon dans la sortie de la console. Si la sortie de la console est volumineuse, saisissez "Obsolescence" dans la zone Filtrer.

Fenêtre de la console affichant des avertissements d'abandon

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

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

Étapes suivantes: abandon de la version 0

En vous assurant que les polyfills v0 sont chargés, vous devriez vous assurer que votre site continue de fonctionner lorsque les API v0 sont supprimées. Nous vous recommandons de passer aux API Web Components v1, qui sont largement compatibles.

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

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

Récapitulatif

Les API Web Components v0 provisoires vont disparaître. Si vous ne retenez qu'une chose de cet article, assurez-vous de tester votre application avec les API v0 désactivées et de charger les polyfills si nécessaire.

À long terme, nous vous encourageons à passer aux dernières API et à continuer à utiliser Web Components.