Actualización de los componentes web: más tiempo para actualizar a las APIs v1

Jonathan Bingham

Arthur Evans

Las APIs de Web Components v1 son un estándar de plataforma web que se envió en Chrome, Safari, Firefox y, próximamente, Edge. Millones de sitios usan las APIs v1 y llegan a miles de millones de usuarios cada día. Los desarrolladores que usaban las APIs de borrador v0 proporcionaron comentarios valiosos que influyeron en las especificaciones. Sin embargo, las APIs v0 solo eran compatibles con Chrome. Para garantizar la interoperabilidad, a fines del año pasado, anunciamos que estas APIs en borrador dejaron de estar disponibles y se programó su eliminación a partir de Chrome 73.

Debido a que suficientes desarrolladores solicitaron más tiempo para la migración, aún no se quitaron las APIs de Chrome. Ahora, se quitará la versión 0 de las APIs de borrador en Chrome 80, alrededor de febrero de 2020.

Esto es lo que debes saber si crees que podrías estar usando las APIs de la versión 0:

• Prueba tu sitio con las APIs de la versión 0 inhabilitadas. Si tu sitio funciona como se esperaba, felicitaciones. ¡Listo! Consulta Volver al futuro: Cómo inhabilitar las APIs v0 para obtener instrucciones.
• Si usas la biblioteca de Polymer v1 o v2, sigue las instrucciones publicadas anteriormente por el equipo de Polymer.
• Si usas shadow DOM v0, elementos personalizados v0 o importaciones HTML, deberás cargar algunos polyfills. Consulta Cómo usar los polyfills v0.
• Si no estás seguro de qué estás usando, no te preocupes. Consulta la sección Help! ¡No sé qué APIs estoy usando!

Vuelve al futuro: Inhabilita las APIs de la versión 0

Para probar tu sitio con las APIs de la versión 0 inhabilitadas, debes iniciar Chrome desde la línea de comandos con las siguientes marcas:

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

Deberás salir de Chrome antes de iniciarlo desde la línea de comandos. Si tienes Chrome Canary instalado, puedes ejecutar la prueba en Canary mientras mantienes esta página cargada en Chrome.

Para probar tu sitio con las APIs v0 inhabilitadas, haz lo siguiente:

1. Si usas Mac OS, navega a chrome://version para encontrar la ruta ejecutable para Chrome. Necesitarás la ruta del paso 3.
2. Sal de Chrome.

3. Reinicia Chrome con las funciones experimentales de línea de comandos:

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

   Para obtener instrucciones sobre cómo iniciar Chrome con funciones experimentales, consulta Cómo ejecutar Chromium con marcas. Por ejemplo, en Windows, puedes ejecutar lo siguiente:

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

4. Para verificar que iniciaste correctamente el navegador, abre una pestaña nueva y la consola de Herramientas para desarrolladores, y ejecuta el siguiente 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'));
   

   Si todo funciona como se esperaba, deberías ver lo siguiente:

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

   Si el navegador informa que algunas de estas funciones son verdaderas, significa que algo anda mal. Asegúrate de haber cerrado Chrome por completo antes de reiniciarlo con las funciones experimentales.

5. Por último, carga tu app y repasa las funciones. Si todo funciona como se espera, no necesitas hacer nada más.

Usa los polyfills v0

Los polyfills de Web Components v0 ofrecen compatibilidad con las APIs de la versión 0 en navegadores que no ofrecen compatibilidad nativa. Si tu sitio no funciona en Chrome con las APIs de la versión 0 inhabilitadas, es probable que no estés cargando los polyfills. Existen varias posibilidades:

• No cargas los polyfills en absoluto. En este caso, el sitio debería fallar en otros navegadores, como Firefox y Safari.
• Cargarás los polyfills de forma condicional en función del reconocimiento del navegador. En este caso, tu sitio debería funcionar en otros navegadores. Avanza hasta Carga los polyfills.

En el pasado, el equipo del proyecto Polymer y otros recomendaron cargar los polyfills de manera condicional según la detección de funciones. Este enfoque debería funcionar bien con las APIs v0 inhabilitadas.

Instala polyfills v0

Los polyfills de Web Components v0 nunca se publicaron en el registro de npm. Si tu proyecto ya lo usa, puedes instalar los polyfills con Bower. También puedes instalarlo desde un archivo ZIP.

• Para instalar con Bower, sigue estos pasos:

  bower install --save webcomponents/webcomponentsjs#^0.7.0

• Para realizar la instalación desde un archivo ZIP, descarga la versión 0.7.x más reciente de GitHub:

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

  Si realizas la instalación desde un archivo ZIP, tendrás que actualizar los polyfills de forma manual si sale otra versión. Te recomendamos verificar los polyfills con tu código.

Carga los polyfills v0

Los polyfills de Web Components v0 se proporcionan como dos paquetes independientes:

webcomponents-min.js	Incluye todos los polyfills. Este paquete incluye el polyfill del shadow DOM, que es mucho más grande que los otros polyfills, y tiene un mayor impacto en el rendimiento. Usa este paquete solo si necesitas compatibilidad con shadow DOM.
webcomponents-lite-min.js	Incluye todos los polyfills, excepto el shadow DOM. Nota: Los usuarios de Polymer 1.x deben elegir este paquete, ya que la emulación de Shadow DOM se incluyó directamente en la biblioteca de Polymer. Los usuarios de Polymer 2.x necesitan una versión diferente de los polyfills. Consulta la entrada de blog sobre el proyecto Polymer para obtener más detalles.

También hay polyfills individuales disponibles como parte del paquete de polyfills de los componentes web. El uso de polyfills individuales por separado es un tema avanzado que no se aborda aquí.

Sigue estos pasos para cargar los polyfills de forma incondicional:

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

o:

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

Si instalaste los polyfills directamente desde GitHub, deberás proporcionar la ruta de acceso en la que instalaste los polyfills.

Si cargas condicionalmente los polyfills según la detección de funciones, tu sitio debería seguir funcionando cuando se quite la compatibilidad con v0.

Si cargas condicionalmente los polyfills mediante análisis del navegador (es decir, cuando se cargan los polyfills en navegadores que no son Chrome), el sitio fallará cuando se quite la compatibilidad con la versión 0 de Chrome.

Ayuda, ¡No sé qué APIs estoy usando!

Si no sabes si estás usando alguna de las APIs de la versión 0 (o qué APIs estás usando), puedes verificar el resultado de la consola en Chrome.

1. Si anteriormente iniciaste Chrome con las funciones experimentales para inhabilitar las APIs de la versión 0, cierra Chrome y reinícialo normalmente.
2. Abre una nueva pestaña de Chrome y carga tu sitio.
3. Presiona Control + Mayúsculas + J (Windows, Linux y ChromeOS) o Comando + Opción + J (Mac) para abrir la Consola de Herramientas para desarrolladores.
4. Verifica el resultado de la consola para ver los mensajes de baja. Si hay muchos resultados en la consola, ingresa “Baja” en el cuadro Filtro.

Deberías ver mensajes de baja para cada API v0 que usas. El resultado anterior muestra mensajes para importaciones de HTML, elementos personalizados v0 y shadow DOM v0.

Si usas una o más de estas APIs, consulta cómo usar los polyfills v0.

Próximos pasos: Salir de la versión 0

Asegurarse de que se carguen los polyfills de la versión 0 debería garantizar que el sitio siga funcionando cuando se quiten las APIs de la versión 0. Te recomendamos que comiences a usar las APIs de Web Components v1, que tienen compatibilidad general.

Si usas una biblioteca de componentes web, como la biblioteca de Polymer, X-Tag o SkateJS, el primer paso es verificar si hay versiones más recientes de la biblioteca disponibles que admitan las APIs v1.

Si tienes tu propia biblioteca o escribiste elementos personalizados sin una biblioteca, deberás realizar la actualización a las nuevas APIs. Estos recursos pueden ayudarte:

• Novedades sobre los elementos personalizados
• Novedades de Shadow DOM v1

En resumen

Las APIs de borrador de Web Components v0 dejarán de estar disponibles. Si quitas algo de esta publicación, asegúrate de probar tu app con las APIs de la versión 0 inhabilitadas y cargar los polyfills según sea necesario.

A largo plazo, te recomendamos que actualices a las APIs más recientes y sigas usando componentes web.