Руководство по обновлению пользовательских компонентов

Зачем нужно обновлять пользовательские компоненты?

С июля 2021 г. в Google Web Designer прекращается поддержка пользовательских компонентов версии 0. Все устаревшие компоненты нужно обновить в соответствии со спецификацией пользовательских элементов версии 1.

Как понять, устарел ли мой пользовательский компонент?

Открыв документ с устаревшим пользовательским компонентом, вы увидите соответствующее предупреждение от Google Web Designer. Вы также увидите значок рядом с названием такого компонента на панели Компоненты или значок icon for unsupported custom component в рабочей области.

Кроме того, можно проверить файлы источника компонента. В примере ниже использована устаревшая версия пользовательского компонента QR-кода.

`manifest.json`

В манифестах пользовательских компонентов новой версии присутствует поле customElementsVersion. Это поле указывает на версию спецификации пользовательского компонента:

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

В манифестах устаревших пользовательских компонентов этого поля нет.

`myqrcode.js`

Устаревшие компоненты используют при регистрации метод document.registerElement().

Устаревшие пользовательские элементы версии 0

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

Обновленные компоненты используют метод customElements.define().

Обновленные пользовательские элементы версии 1

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

Файлы устаревших компонентов содержат слово document.registerElement. Чтобы обновить компонент, выполните указанные ниже действия.

Пошаговые инструкции по обновлению

1. Обновите манифест компонента

Обновите манифест компонента, включив в него поле customElementsVersion. Кроме этого, увеличьте номер версии, чтобы Google Web Designer удалось распознать измененный компонент.

`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 компонента

Код JavaScript должен быть написан с использованием синтаксиса класса ES2015.

JavaScript API в спецификации пользовательских элементов версии 1 изменился, однако старые методы API для версии 0 хорошо соотносятся с методами версии 1.

Метод версии 0	Метод версии 1
`document.registerElement()`	`customElements.define()`
`createdCallback()`	`constructor()`
`attachedCallback()`	`connectedCallback()`
`detachedCallback()`	`disconnectedCallback()`
`attributeChangedCallback()`	`attributeChangedCallback()` (требует `observedAttributes`)

Ниже приведен рабочий пример обновленного компонента 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);
}

Примечания:

Новый компонент должен наследовать HTMLElement.
super() должен вызываться в конструкторе.
Обратный вызов attributeChangedCallback запускается, только если атрибут указан в геттере observedAttributes.

Подробнее о новой спецификации пользовательских элементов версии 1 и их создании…

3. Транспилируйте код JavaScript в ES5 (рекомендуется)

Обновленный компонент QR-кода выше работает в Google Chrome и в других браузерах, поддерживающих класс синтаксиса ES2015 (ES6). Более старые браузеры не распознают новый синтаксис JavaScript и требуют транспиляции. Чтобы ваш пользовательский компонент правильно работал во всех браузерах, преобразовывайте код JavaScript в разделе 2 в код ES5 с помощью транспилятора.

Babel (babeljs.io) – это популярный транспайлер, который поддерживается всеми операционными системами. Веб-приложение Babel доступно на странице babeljs.io/repl.

Используя его, убедитесь, что в настройках установлен флажок возле пункта es2015.

Замените исходный код JavaScript в пакете компонента транспилированным.

4. Установите обновленный компонент

В Google Web Designer уберите устаревший компонент с панели Компоненты, нажав кнопку Удалить . Затем установите ZIP-файл обновленной версии, нажав кнопку Добавить собственный компонент .

Эта информация оказалась полезной?

Как можно улучшить эту статью?