Upgrade-Leitfaden für benutzerdefinierte Komponenten

Warum sollte ich meine benutzerdefinierten Komponenten aktualisieren?

Seit Juli 2021 unterstützt Google Web Designer keine veralteten benutzerdefinierten V0-Komponenten mehr. Aktualisieren Sie alle veralteten benutzerdefinierten Komponenten, damit sie der Spezifikation von Custom Elements V1 entsprechen.

Ist meine benutzerdefinierte Komponente veraltet?

Sie sehen in Google Web Designer eine Warnung, wenn Sie ein Dokument öffnen, das eine veraltete benutzerdefinierte Komponente enthält. Außerdem wird im Bereich Komponenten neben dem Komponentennamen ein Warnsymbol  angezeigt und ein weiteres Symbol weist auf veraltete benutzerdefinierte Komponenten im Anzeigebereich hin.

Sie können auch die Quelldateien der Komponente prüfen. Im folgenden Beispiel verwenden wir die veraltete Version der benutzerdefinierten QR-Code-Komponente.

manifest.json

Die Manifestdateien neuer benutzerdefinierter Komponenten enthalten das Feld customElementsVersion. Darin wird angegeben, für welche Version der Custom Elements-Spezifikation die Komponente erstellt wurde:

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

In den Manifestdateien veralteter benutzerdefinierter Komponenten ist dieses Feld nicht enthalten.

myqrcode.js

Bei veralteten Komponenten wird bei der Registrierung die Methode document.registerElement() verwendet.

Veraltet (Custom Elements V0)

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

Für aktualisierte Komponenten wird stattdessen die Methode customElements.define() verwendet.

Aktuell (Custom Elements V1)

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

Wenn Ihre Komponentendatei document.registerElement enthält, ist sie veraltet. Sie können Ihre Komponente anhand der folgenden Schritte aktualisieren.

Anleitung

1. Manifestdatei der Komponente aktualisieren

Aktualisieren Sie die Manifestdatei der Komponente so, dass sie das neue Feld customElementsVersion enthält. Erhöhen Sie außerdem die Versionsnummer, damit in Google Web Designer erkannt wird, dass die Komponente geändert wurde.

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. JavaScript-Code der Komponente aktualisieren

Der JavaScript-Code neuer Komponenten muss mit der Klassensyntax ES2015 geschrieben werden.

Die JavaScript API wurde in der Spezifikation von Custom Elements V1 geändert. Glücklicherweise lassen sich die alten API-Methoden aus V0 gut mit den neuen Methoden aus V1 abstimmen.

Methode aus V0	Methode aus V1
document.registerElement()	customElements.define()
createdCallback()	constructor()
attachedCallback()	connectedCallback()
detachedCallback()	disconnectedCallback()
attributeChangedCallback()	attributeChangedCallback() (erfordert observedAttributes)

Hier ist ein funktionierendes Beispiel für die aktualisierte Komponente „my-qrcode“:

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

Hinweise:

• Die neue Komponente muss HTMLElement erweitern.
• super() muss im Konstruktor aufgerufen werden.
• attributeChangedCallback wird nur ausgelöst, wenn das Attribut unter observedAttributes aufgeführt ist.

Weitere Informationen zur neuen Spezifikation von Custom Elements V1 und zum Erstellen benutzerdefinierter Elemente

3. JavaScript-Code in ES5 übertragen (empfohlen)

Die aktualisierte QR-Code-Komponente oben funktioniert in Google Chrome und anderen Browsern, die die Klassensyntax ES2015 (ES6) unterstützen. In älteren Browsern wird diese neue JavaScript-Syntax nicht erkannt. Der Code muss hier mit einem Transcompiler übersetzt werden. Damit Ihre benutzerdefinierte Komponente in allen Browsern ordnungsgemäß funktioniert, empfehlen wir Ihnen dringend, einen Transcompiler zu verwenden, um den JavaScript-Code aus Schritt 2 in ES5 zu übersetzen.

Babel (babeljs.io) ist ein beliebter Transcompiler für jedes Betriebssystem. Unter babeljs.io/repl gibt es auch eine Web-App-Version.

Falls Sie diese verwenden, achten Sie darauf, dass die Einstellung es2015 aktiviert ist.

Fügen Sie Ihrem Komponentenpaket statt Ihrem ursprünglichen JavaScript-Code den vom Transcompiler erstellten Code hinzu.

4. Die aktualisierte Komponente installieren

Entfernen Sie in Google Web Designer die veraltete Komponente aus dem Steuerfeld Komponenten. Verwenden Sie dazu die Schaltfläche Löschen . Installieren Sie dann die ZIP-Datei der aktualisierten Version mithilfe der Schaltfläche Benutzerdefinierte Komponente hinzufügen .