為什麼要升級自訂元件？
自 2021 年 7 月起，Google Web Designer 將不再支援 v0 自訂元件。請將過時的自訂元件全數更新，以符合自訂元素 v1 規格。
我的自訂元件是否已過時？
當您開啟含有過時自訂元件的文件時，Google Web Designer 會顯示警告。此外，在「元件」面板中，過時元件的名稱旁邊會顯示警告指標 
。
您也可以查看元件的來源檔案。在以下範例中，我們使用的是過時版本的 QR code 自訂元件。
manifest.json
新自訂元件的資訊清單中，有一個名為 customElementsVersion 的欄位。這個欄位會指出編寫該元件時所採用的自訂元素規格版本：
{
...
"customElementsVersion": 1,
...
}
過時自訂元件的資訊清單中沒有這個欄位。
myqrcode.js
過時元件在註冊時會使用 document.registerElement() 方法。
過時版本 (自訂元素 v0)
document.registerElement('my-qrcode', {prototype: proto});
更新後的元件會改用 customElements.define() 方法。
現行版本 (自訂元素 v1)
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 程式碼
請使用 ES2015 類別語法編寫新元件的 JavaScript。
在自訂元素 v1 規格中，JavaScript API 有所異動，但舊的 v0 API 方法可以完美對應到新的 v1 方法。
| v0 方法 | v1 方法 |
|---|---|
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底下才會觸發。
進一步瞭解新的自訂元素 v1 規格和自訂元素編寫方法。
3. 將 JavaScript 程式碼轉譯為 ES5 (建議)
上方更新後的 QR code 元件可在支援 ES2015 (ES6) 類別語法的 Google Chrome 和其他瀏覽器中運作，但較舊的瀏覽器無法識別這種新的 JavaScript 語法，因此必須進行轉譯。為了讓自訂元件可在所有瀏覽器中正常運作，強烈建議您使用轉譯器，將第 2 部分中的 JavaScript 程式碼轉換為 ES5。
babeljs.io 的 Babel 是常用的轉譯器，可在任何作業系統中運作。您也可以在線上前往 babeljs.io/repl 使用網頁應用程式版本。
使用 Babel 網頁應用程式時，務必要勾選「es2015」預設設定。
最後在元件套件中加入轉譯完成的程式碼，取代原始的 JavaScript 程式碼。
4. 安裝更新後的元件
在 Google Web Designer 的「元件」面板中，使用「刪除」按鈕 移除過時的元件，然後使用「新增自訂元件」按鈕
