Guía de actualización de componentes personalizados

¿Por qué debería actualizar los componentes personalizados?

Desde julio del 2021, Google Web Designer ya no admite componentes personalizados de la versión 0. Debe actualizar los componentes personalizados obsoletos para que sigan la especificación Elementos personalizados v. 1.

¿Está obsoleto mi componente personalizado?

Cuando abra un documento que contenga un componente personalizado obsoleto, Google Web Designer se lo advertirá. Además, en el panel Componentes, aparecerá un indicador de advertencia junto al nombre del componente en cuestión, y un icono diferente indicará cuáles son los componentes personalizados obsoletos en la escena.

También puede comprobar los archivos de origen del componente. En el siguiente ejemplo, se usa la versión obsoleta del componente personalizado de código QR.

manifest.json

Los componentes personalizados nuevos tienen un campo denominado customElementsVersion en sus archivos de manifiesto. En este campo se indica la versión de la especificación Elementos personalizados para la que se ha escrito el componente:

{
  ...
  "customElementsVersion": 1,
  ...
}

Este campo no se incluye en los archivos de manifiesto de componentes personalizados obsoletos.

myqrcode.js

Los componentes obsoletos utilizan el método document.registerElement() durante el registro.

Componentes obsoletos (Elementos personalizados v. 0)

document.registerElement('my-qrcode', {prototype: proto});

En cambio, los componentes actualizados utilizan el método customElements.define().

Componentes actualizados (Elementos personalizados v. 1)

customElements.define('my-qrcode', MyQrcode);

Si el archivo del componente incluye el término document.registerElement, significa que está obsoleto. Puede actualizar el componente siguiendo los pasos que se indican a continuación.

Pasos para actualizar el componente

1. Modificar el archivo de manifiesto del componente

Incluya el nuevo campo customElementsVersion en el archivo de manifiesto del componente y aumente el número de la versión para que Google Web Designer detecte que el componente ha cambiado.

manifest.json

{
  "name": "QR Code",
  "type": "my-qrcode",
  "tagName": "my-qrcode",
  "customElementsVersion": 1,
  "version": 2,
  "description": "Generates a QR code image for the specified data.",
  "files": {
    "js": [
      "qr.js",
      "myqrcode.js"
    ]
  },
  "attributes": [
   {
    "name": "data",
    "label": "Data",
    "type": "string",
    "required": true,
    "description": "The data to encode in the QR code image"
   }
  ],
  "events": [
  ],
  "methods": [
  ],
  "nestable": false
}

2. Actualizar el código JavaScript del componente

El código JavaScript de los nuevos componentes se debe escribir con la sintaxis de clase ES2015.

En la especificación de Elementos personalizados v. 1, la API de JavaScript ha cambiado. Afortunadamente, los antiguos métodos de la API versión 0 se corresponden con los nuevos métodos de la versión 1.

Método de la versión 0	Método de la versión 1
document.registerElement()	customElements.define()
createdCallback()	constructor()
attachedCallback()	connectedCallback()
detachedCallback()	disconnectedCallback()
attributeChangedCallback()	attributeChangedCallback() (requiere observedAttributes)

A continuación se muestra un ejemplo funcional del componente my-qrcode actualizado:

myqrcode.js

/** @fileoverview Implementation of the my-qrcode component. */
if (window.customElements && window.customElements.define) {
  class MyQrcode extends HTMLElement {
    constructor() {
      super();
      this.img = null;
    }

    connectedCallback() {
      this.generateImage();
    }

    static get observedAttributes() {
      return ['data'];
    }

    attributeChangedCallback(attributeName) {
      if (!this.img) {
        return;
      }
      switch (attributeName) {
        case 'data':
          this.generateImage();
          break;
      }
    }

    generateImage() {
      const data = this.getAttribute('data');
      if (data) {
        if (!this.img) {
          this.img = document.createElement('img');
          this.img.style.height = '100%';
          this.appendChild(this.img);
        }
        this.img.setAttribute('src', QRCode.generatePNG(data));
      } 
    }
  }

  customElements.define('my-qrcode', MyQrcode);
}

Hay que tener en cuenta lo siguiente:

• El nuevo componente debe ampliar HTMLElement.
• En el constructor, debe llamarse a super().
• No se activará la función attributeChangedCallback a menos que el atributo especificado aparezca en observedAttributes.

Consulte más información sobre la nueva especificación Elementos personalizados v. 1 y la creación de elementos personalizados.

3. Transpilar el código JavaScript a ES5 (recomendado)

El componente de código QR actualizado que se incluye más arriba funciona en Google Chrome y en otros navegadores compatibles con la sintaxis de clase ES2015 (ES6). Los navegadores antiguos no reconocen esta nueva sintaxis de JavaScript, por lo que deberá transpilar el código. Para que el componente personalizado funcione correctamente en todos los navegadores, le recomendamos que utilice un transpilador para convertir el código JavaScript de la sección 2 a ES5.

Babel es un conocido transpilador que está disponible en babeljs.io y que se puede ejecutar en cualquier sistema operativo. También hay una versión de aplicación web disponible online, en babeljs.io/repl.

Si decide usar la aplicación web de Babel, compruebe que el preajuste es2015 esté seleccionado.

Incluya el código transpilado en el paquete del componente en lugar del código JavaScript original.

4. Instalar el componente actualizado

En Google Web Designer, elimine el componente obsoleto del panel Componentes con el botón Eliminar y, luego, instale el archivo .zip de la versión actualizada con el botón Añadir componente personalizado .