網頁元件更新 - 有更多時間可以升級至 v1 API

Jonathan Bingham
Arthur Evans

Web Components v1 API 是網路平台標準,已在 Chrome、Safari、Firefox 和 (即將推出的) Edge 中推出。實際上,有數百萬個網站使用 v1 API,每天觸及數十億名使用者。使用草稿版 v0 API 的開發人員提供了寶貴意見,對規格造成影響。但只有 Chrome 支援 v0 API。為確保互通性,我們在去年年底宣布這些 API 草稿已淘汰,並預計在 Chrome 73 中移除。

由於有足夠的開發人員要求延長遷移時間,因此 API 尚未從 Chrome 中移除。v0 草稿 API 預計將於 2020 年 2 月左右的 Chrome 第 80 版中移除

如果您認為自己可能使用了 v0 API,請參閱以下重要資訊:

回顧未來:停用 v0 API

如要停用 v0 API 來測試網站,您必須透過指令列啟動 Chrome,並使用下列標記:

--disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports

您必須先關閉 Chrome,才能透過指令列啟動 Chrome。如果您已安裝 Chrome Canary,可以在 Canary 中執行測試,同時在 Chrome 中載入這個頁面。

如要測試停用 v0 API 的網站,請按照下列步驟操作:

  1. 如果您使用 Mac OS,請瀏覽 chrome://version 找出 Chrome 的執行檔路徑。您將在步驟 3 中使用這個路徑。
  2. 退出 Chrome。
  3. 使用指令列標記重新啟動 Chrome:

    --disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports

    如需使用旗標啟動 Chrome 的操作說明,請參閱「使用旗標執行 Chromium」。舉例來說,在 Windows 上,您可以執行:

    chrome.exe --disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports
    
  4. 如要再次確認您已正確啟動瀏覽器,請開啟新的分頁、開發人員工具控制台,然後執行下列指令:

    console.log(
    "Native HTML Imports?", 'import' in document.createElement('link'),
    "Native Custom Elements v0?", 'registerElement' in document,
    "Native Shadow DOM v0?", 'createShadowRoot' in document.createElement('div'));
    

    如果一切正常運作,您應該會看到:

    Native HTML Imports? false Native Custom Elements v0? false Native Shadow DOM v0? false
    

    如果瀏覽器針對上述任何或所有功能回報為 true,表示有問題。請務必先完全關閉 Chrome,再重新啟動並啟用旗標。

  5. 最後,請載入應用程式並執行各項功能。如果一切正常運作,表示您已完成設定。

使用 v0 polyfill

Web Components v0 polyfill 可在未提供原生支援的瀏覽器上支援 v0 API。如果您的網站在停用 v0 API 的情況下無法在 Chrome 上運作,可能是因為您沒有載入 polyfill。可能的原因如下:

  • 您根本沒有載入 polyfill。在這種情況下,您的網站應會在 Firefox 和 Safari 等其他瀏覽器中失敗。
  • 您會根據瀏覽器嗅探功能,有條件地載入 polyfill。在這種情況下,您的網站應可在其他瀏覽器上運作。請跳至「載入 polyfill」一節。

過去,Polymer 專案團隊和其他人建議根據功能偵測來有條件地載入 polyfill。在停用 v0 API 的情況下,這種方法應該可以正常運作。

安裝 v0 polyfill

Web Components v0 polyfill 從未發布至 npm 登錄檔。如果專案已使用 Bower,您可以使用 Bower 安裝 polyfill。或者,您也可以從 ZIP 檔案安裝。

  • 如要使用 Bower 安裝,請按照下列步驟操作:

    bower install --save webcomponents/webcomponentsjs#^0.7.0

  • 如要透過 zip 檔案安裝,請從 GitHub 下載最新的 0.7.x 版本:

    https://github.com/webcomponents/webcomponentsjs/releases/tag/v0.7.24

    如果您是從 ZIP 檔案安裝,則在其他版本推出時,您必須手動更新 polyfill。您可能會想在程式碼中檢查 polyfill。

載入 v0 polyfill

Web Components v0 polyfills 會以兩個獨立的套件提供:

webcomponents-min.js 包含所有 polyfill。這個套件包含陰影 DOM polyfill,其大小遠大於其他 polyfill,對效能影響也更大。只有在需要陰影 DOM 支援時,才使用這個套件。
webcomponents-lite-min.js 包含所有 polyfill,但陰影 DOM 除外。注意:Polymer 1.x 使用者應選擇這個套件,因為 Shadow DOM 模擬功能已直接納入 Polymer 程式庫。Polymer 2.x 使用者需要使用其他版本的 polyfill。詳情請參閱 Polymer 專案網誌文章

網頁元件 polyfill 套件中也提供個別的 polyfill。個別使用 polyfill 是進階主題,本文不會介紹。

如要無條件載入 polyfill,請按照下列步驟操作:

<script src="/bower_components/webcomponents/webcomponentsjs/webcomponents-lite-min.js">
</script>

或:

<script src="/bower_components/webcomponents/webcomponentsjs/webcomponents-min.js">
</script>

如果您是直接從 GitHub 安裝 polyfill,就必須提供安裝 polyfill 的路徑。

如果您根據功能偵測條件式地載入 polyfill,在移除 v0 支援時,您的網站應可繼續運作。

如果您使用瀏覽器嗅探功能 (也就是在非 Chrome 瀏覽器上載入 polyfill) 以有條件地載入 polyfill,當 Chrome 移除 v0 支援功能時,您的網站就會失敗。

我的抵用金消失不見了,我不知道自己使用哪些 API!

如果您不確定是否使用任何 v0 API,或使用哪些 API,可以查看 Chrome 中的主控台輸出內容。

  1. 如果您先前啟動 Chrome 時已使用標記停用 v0 API,請關閉 Chrome 並正常重新啟動。
  2. 開啟新的 Chrome 分頁並載入網站。
  3. 按下 Control + Shift + J 鍵 (Windows、Linux、ChromeOS) 或 Command + Option + J 鍵 (Mac),即可開啟 DevTools 控制台
  4. 檢查控制台輸出內容,查看是否有淘汰訊息。如果主控台輸出內容很多,請在「Filter」方塊中輸入「Deprecation」。
主控台視窗顯示淘汰警告

您應該會看到每個使用中的 v0 API 的淘汰訊息。上述輸出內容顯示 HTML Imports、Custom Elements v0 和 Shadow DOM v0 的訊息。

如果您使用了其中一個或多個 API,請參閱「使用 v0 polyfill」一文。

後續步驟:從 v0 移除

請務必載入 v0 polyfill,確保在移除 v0 API 時,網站仍能正常運作。建議您改用廣泛支援的 Web Components v1 API。

如果您使用的是 Web 元件程式庫 (例如 Polymer 程式庫、X-Tag 或 SkateJS),第一步請檢查是否有支援 v1 API 的新版程式庫。

如果您有自己的程式庫,或是在沒有程式庫的情況下編寫自訂元素,就必須更新至新的 API。以下資源可能有所幫助:

總結

Web Components v0 草稿 API 即將淘汰。如果您從這篇文章學到什麼,請務必在停用 v0 API 的情況下測試應用程式,並視需要載入 polyfill

長期來說,我們建議您升級至最新的 API,並繼續使用 Web 元件!