Guia de upgrade de componentes personalizados

Por que você deve fazer upgrade dos seus componentes personalizados?

Desde julho de 2021, o Google Web Designer não é mais compatível com componentes personalizados v0. É necessário fazer upgrade de todos os componentes personalizados desatualizados para que eles sigam a especificação de elementos personalizados v1.

Meu componente personalizado está desatualizado?

Você receberá um aviso do Google Web Designer ao abrir um documento que contém um componente personalizado desatualizado. Além disso, um ícone de aviso aparecerá no painel Componentes ao lado do nome do componente. Um outro ícone indica componentes personalizados desatualizados no cenário.

Você também pode verificar os arquivos de origem do componente. No exemplo a seguir, usamos a versão desatualizada do componente personalizado do código QR.

manifest.json

Os novos componentes personalizados têm um campo chamado customElementsVersion nos próprios manifestos. Esse campo indica para qual versão da especificação de elementos personalizados o componente foi escrito:

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

Os manifestos de componentes desatualizados não apresentam esse campo.

myqrcode.js

Os componentes desatualizados usam o método document.registerElement() durante o registro.

Desatualizado (elementos personalizados v0)

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

Os componentes atualizados usam o método customElements.define().

Atual (elementos personalizados v1)

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

Se o arquivo do componente tiver o termo document.registerElement, ele está desatualizado. Você pode atualizar seu componente seguindo as etapas abaixo.

Etapas do upgrade

1. Atualizar o manifesto do componente

Atualize o manifesto do componente para incluir o novo campo customElementsVersion. Além disso, aumente o número da versão para que o Google Web Designer reconheça a alteração do componente.

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. Atualizar o código JavaScript do componente

O JavaScript para novos componentes precisa ser escrito usando a sintaxe da classe ES2015.

A API JavaScript foi alterada na especificação de elementos personalizados v1. A boa notícia é que os métodos antigos da API v0 mapeiam corretamente os novos métodos da v1.

Método da v0	Método da v1
document.registerElement()	customElements.define()
createdCallback()	constructor()
attachedCallback()	connectedCallback()
detachedCallback()	disconnectedCallback()
attributeChangedCallback()	attributeChangedCallback() (exige observedAttributes)

Veja um exemplo prático do componente my-qrcode atualizado:

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

Observações:

• O novo componente precisa estender HTMLElement.
• super() precisa ser chamado no construtor.
• O attributeChangedCallback não será acionado, a menos que o atributo esteja listado em observedAttributes.

Saiba mais sobre a nova especificação de elementos personalizados v1 e entenda a criação desses recursos.

3. Transpilar o código JavaScript para ES5 (recomendado)

O componente atualizado do código QR acima funciona no Google Chrome e em outros navegadores compatíveis com a sintaxe da classe ES2015 (ES6). Os navegadores mais antigos não reconhecem essa nova sintaxe do JavaScript e exigem a transpilação. Para que seu componente personalizado funcione corretamente em todos os navegadores, recomendamos o uso de um transpilador e a conversão do código JavaScript na seção 2 para ES5.

O Babel é um transpilador conhecido em babeljs.io (em inglês), que funciona em qualquer sistema operacional. Há também uma versão do app da Web disponível on-line em babeljs.io/repl (em inglês).

Ao usar esse recurso, verifique se a predefinição es2015 está marcada.

Inclua o código transpilado no seu pacote de componentes no lugar do código JavaScript original.

4. Instalar o componente atualizado

No Google Web Designer, remova o componente desatualizado do painel Componentes usando o botão Excluir . Depois clique no botão Adicionar componente personalizado para instalar o arquivo ZIP da versão atualizada.