Guida all'upgrade dei componenti personalizzati

Perché conviene eseguire l'upgrade dei componenti personalizzati?

A partire da luglio 2021, Google Web Designer non supporta più i componenti personalizzati v0. Dovresti eseguire l'upgrade dei componenti personalizzati obsoleti affinché osservino la specifica Custom Elements v1.

Il mio componente personalizzato è obsoleto?

Google Web Designer ti avvisa quando apri un documento che contiene un componente personalizzato obsoleto. Viene inoltre visualizzato un indicatore di avviso nel riquadro Componenti accanto al nome del componente, mentre un'icona diversa indica i componenti personalizzati obsoleti presenti sullo stage.

Puoi anche controllare i file di origine del componente. Nel seguente esempio, utilizziamo la versione obsoleta del componente personalizzato del codice QR.

manifest.json

I file manifest dei nuovi componenti personalizzati contengono un campo denominato customElementsVersion. Questo campo indica per quale versione della specifica Custom Elements è stato scritto il componente:

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

I file manifest dei componenti personalizzati obsoleti non hanno questo campo.

myqrcode.js

I componenti obsoleti usano il metodo document.registerElement() durante la registrazione.

Obsoleto (Custom Elements v0)

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

I componenti aggiornati utilizzano invece il metodo customElements.define().

Corrente (Custom Elements v1)

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

Se il file del componente contiene il termine document.registerElement, è da considerarsi obsoleto. Puoi aggiornare il componente svolgendo i passaggi che seguono.

Procedura per eseguire l'upgrade

1. Aggiorna il file manifest del componente

Aggiorna il file manifest del componente includendo il nuovo campo customElementsVersion. Inoltre, aumenta il numero di versione affinché Google Web Designer possa rilevare la modifica del 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. Aggiorna il codice JavaScript del componente

Il codice JavaScript per i nuovi componenti deve essere scritto utilizzando la sintassi delle classi ES2015.

L'API JavaScript è stata modificata nella specifica Custom Elements v1. Fortunatamente, i precedenti metodi dell'API v0 si adattano perfettamente ai nuovi metodi v1.

Metodo v0	Metodo v1
document.registerElement()	customElements.define()
createdCallback()	constructor()
attachedCallback()	connectedCallback()
detachedCallback()	disconnectedCallback()
attributeChangedCallback()	attributeChangedCallback() (richiede observedAttributes)

Ecco un esempio pratico del componente my-qrcode aggiornato:

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

Aspetti importanti:

• Il nuovo componente deve estendere HTMLElement.
• È necessario chiamare super() nel costruttore.
• L'attributo attributeChangedCallback non verrà attivato a meno che non viene riportato in observedAttributes.

Scopri di più sulla nuova specifica Custom Elements v1 e sullo sviluppo di elementi personalizzati.

3. Esegui il transpile del codice JavaScript in ES5 (consigliato)

Il componente del codice QR aggiornato riportato sopra funziona con Google Chrome e altri browser che supportano la sintassi delle classi ES2015 (ES6). I browser meno recenti non riconoscono questa nuova sintassi JavaScript e richiedono la transcompilazione. Affinché il tuo componente personalizzato funzioni correttamente in tutti i browser, ti consigliamo vivamente di utilizzare un transpiler per convertire il codice JavaScript nella sezione 2 fino a ES5.

Babel è un noto transpiler di babeljs.io che può essere eseguito in qualsiasi sistema operativo. È disponibile anche una versione dell'app web online all'indirizzo babeljs.io/repl.

Quando utilizzi l'app web di Babel, assicurati che sia selezionata la preimpostazione es2015.

Inserisci il codice transcompilato all'interno del pacchetto del componente al posto del codice JavaScript originale.

4. Installa il componente aggiornato

In Google Web Designer, rimuovi il componente obsoleto dal riquadro Componenti usando il pulsante Elimina , quindi installa il file .zip della versione aggiornata usando il pulsante Aggiungi componente personalizzato .