Web 组件更新 - 有更多时间升级到 v1 API

Jonathan Bingham
Arthur Evans

Web 组件 v1 API 是一项 Web 平台标准,已在 Chrome、Safari、Firefox 和(即将推出的)Edge 中发布。数以百万计的网站都在使用 v1 API,每天触达数十亿用户。使用草稿 v0 API 的开发者提供了有价值的反馈,这些反馈影响了规范。但 v0 API 仅受 Chrome 支持。为确保互操作性,我们于去年年底宣布,这些草稿 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 Canary,则可以在 Canary 中运行测试,同时在 Chrome 中加载此页面。

如需在停用 v0 API 的情况下测试您的网站,请执行以下操作:

  1. 如果您使用的是 Mac OS,请浏览到 chrome://version 以查找 Chrome 的可执行文件路径。您将在第 3 步中需要用到该路径。
  2. 退出 Chrome。
  3. 使用命令行标志重启 Chrome:

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

    如需了解如何使用 flag 启动 Chrome,请参阅使用 flag 运行 Chromium。例如,在 Windows 上,您可以运行以下命令:

    chrome.exe --disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports
    
  4. 如需仔细检查您是否已正确启动浏览器,请打开一个新标签页,打开 DevTools 控制台,然后运行以下命令:

    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 polyfill 以两个单独的软件包的形式提供:

webcomponents-min.js 包含所有 polyfill。此软件包包含 shadow DOM polyfill,该 polyfill 比其他 polyfill 大得多,对性能的影响也更大。仅当您需要 shadow DOM 支持时才使用此软件包。
webcomponents-lite-min.js 包含除 shadow DOM 以外的所有 polyfill。 注意:Polymer 1.x 用户应选择此软件包,因为 Shadow DOM 模拟功能已直接包含在 Polymer 库中。Polymer 2.x 用户需要使用其他版本的 polyfill。如需了解详情,请参阅 Polymer 项目博文

Web 组件 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. 检查控制台输出,查找废弃消息。如果控制台输出很多,请在过滤条件框中输入“废弃”。
显示废弃警告的控制台窗口

您应该会看到您正在使用的每个 v0 API 的废弃消息。上面的输出显示了 HTML Imports、Custom Elements v0 和 Shadow DOM v0 的消息。

如果您使用的是其中一个或多个 API,请参阅使用 v0 polyfill

后续步骤:弃用 v0

确保加载 v0 polyfill 应可确保在移除 v0 API 后您的网站仍能正常运行。我们建议改用 Web Components v1 API,因为这些 API 得到广泛支持。

如果您使用的是 Web 组件库(例如 Polymer 库、X-Tag 或 SkateJS),第一步是检查是否有支持 v1 API 的较新版本的库。

如果您有自己的库,或者在不使用库的情况下编写了自定义元素,则需要更新到新 API。以下资源可能对您有所帮助:

总结

Web Components v0 草稿 API 即将停用。本文要传达的一点是,请务必在停用 v0 API 的情况下测试应用,并根据需要加载 polyfill

从长远来看,我们建议您升级到最新的 API,并继续使用 Web 组件!