Przewodnik po uaktualnianiu komponentów niestandardowych

Dlaczego warto uaktualnić komponenty niestandardowe?

Od lipca 2021 r. program Google Web Designer nie będzie obsługiwać komponentów niestandardowych w wersji 0. Zalecamy zaktualizowanie wszystkich nieaktualnych komponentów, aby były zgodne ze specyfikacją elementów niestandardowych w wersji 1.

Czy mój niestandardowy komponent jest nieaktualny?

Gdy otworzysz dokument zawierający nieaktualny komponent niestandardowy, Google Web Designer wyświetli ostrzeżenie. Dodatkowo w panelu Komponenty obok nazwy pojawi się wskaźnik ostrzegawczy . Z kolei ikona  wskaże, że komponenty niestandardowe na scenie są nieaktualne.

Możesz też sprawdzić pliki źródłowe komponentu. W poniższym przykładzie używamy nieaktualnej wersji komponentu niestandardowego kodu QR.

manifest.json

Nowe komponenty niestandardowe mają w plikach manifestu pole o nazwie customElementsVersion. Wskazuje ono, dla której wersji specyfikacji elementów niestandardowych został napisany komponent:

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

Nieaktualne pliki manifestu komponentów niestandardowych nie zawierają tego pola.

myqrcode.js

Podczas rejestracji nieaktualne komponenty używają metody document.registerElement().

Nieaktualne (elementy niestandardowe w wersji 0)

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

Zaktualizowane komponenty używają metody customElements.define().

Aktualne (elementy niestandardowe w wersji 1)

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

Jeśli plik komponentu zawiera termin document.registerElement, jest nieaktualny. Aby zaktualizować komponent, wykonaj czynności opisane poniżej.

Jak dokonać aktualizacji

1. Zaktualizuj plik manifestu komponentu

Zaktualizuj plik manifestu komponentu, dodając nowe pole customElementsVersion. Zwiększ też numer wersji, by Google Web Designer rozpoznał, że komponent się zmienił.

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. Zaktualizuj kod JavaScript komponentu

Kod JavaScript nowych komponentów musi być zgodny ze składnią klas, które zostały wprowadzone w specyfikacji ES2015.

Interfejs API JavaScript zmienił się w specyfikacji elementów niestandardowych w wersji 1. Na szczęście stare metody API w wersji 0 dobrze pasują do nowych metod w wersji 1.

Metoda w wersji 0	Metoda w wersji 1
document.registerElement()	customElements.define()
createdCallback()	constructor()
attachedCallback()	connectedCallback()
detachedCallback()	disconnectedCallback()
attributeChangedCallback()	attributeChangedCallback() (wymaga observedAttributes)

Oto działający przykład zaktualizowanego komponentu 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);
}

Warto wiedzieć:

• Nowy komponent musi być rozszerzeniem elementu HTMLElement.
• Metoda super() musi zostać wywołana w konstruktorze.
• Metoda attributeChangedCallback nie zostanie wyzwolona, jeśli atrybut nie jest wymieniony w sekcji observedAttributes.

Więcej informacji o nowej specyfikacji elementów niestandardowych w wersji 1 i tworzeniu elementów niestandardowych.

3. Transpilacja kodu JavaScript do wersji ES5 (zalecane)

Powyższy zaktualizowany komponent kodu QR działa w Google Chrome i innych przeglądarkach, które obsługują składnię klas zgodnie ze specyfikacją ES2015 (wersja ES6). Starsze przeglądarki nie rozpoznają tej nowej składni JavaScriptu. W takim przypadku kod musi zostać przetworzony metodą transpilacji. Aby Twój komponent niestandardowy działał poprawnie we wszystkich przeglądarkach, zdecydowanie zalecamy użycie transpilatora w celu przekonwertowania kodu JavaScript w sekcji 2 na taki, który będzie zgodny z wersją ES5.

Popularnym transpilatorem, który można uruchomić w dowolnym systemie operacyjnym, jest Babel. Jest on dostępny na babeljs.io. Dostępna jest również wersja internetowa tej aplikacji na babeljs.io/repl.

Jeśli korzystasz z aplikacji w wersji internetowej, upewnij się, że jest w niej zaznaczone ustawienie es2015.

Umieść kod po transpilacji w pakiecie komponentu w miejsce pierwotnego kodu JavaScript.

4. Zainstaluj zaktualizowany komponent

W aplikacji Google Web Designer usuń przestarzały komponent z panelu Komponenty, używając przycisku Usuń , a następnie zainstaluj plik ZIP zaktualizowanej wersji za pomocą przycisku Dodaj komponent niestandardowy .