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

Jonathan Bingham
Arthur Evans

Web Components v1 API 是 Chrome、Safari、Firefox 和(即将推出)Edge 中提供的 Web 平台标准。事实上,有数百万个网站在使用 v1 API,每天覆盖数十亿用户。使用草稿 v0 API 的开发者提供了影响规范的宝贵反馈。但是只有 Chrome 支持 v0 API。为确保互操作性,我们在去年末宣布这些草稿 API 已废弃,并已计划从 Chrome 73 开始移除。

由于足够多的开发者要求更多时间进行迁移,因此这些 API 尚未从 Chrome 中移除。现在,预计将于 2020 年 2 月左右在 Chrome 80 中移除 v0 草稿 API

如果您认为自己可能在使用 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. 使用命令行 flag 重启 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 组件 v0 polyfill 支持在不提供原生支持的浏览器上使用 v0 API。如果您的网站在停用了 v0 API 的 Chrome 中无法正常运行,则可能是因为您没有加载 polyfill。有以下几种可能性:

  • 您根本没有加载 polyfill。在这种情况下,您的网站在 Firefox 和 Safari 等其他浏览器上应该会失败。
  • 您将根据浏览器嗅探有条件地加载 polyfill。在这种情况下,您的网站应该可以在其他浏览器上正常运行。请直接跳到加载 polyfill

过去,Polymer 项目团队和其他团队建议根据特征检测有条件地加载 polyfill。在停用 v0 API 的情况下,此方法应该可以正常运行。

安装 v0 polyfill

Web 组件 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 组件 v0 polyfill 作为两个单独的软件包提供:

webcomponents-min.js 包含所有 polyfill。此软件包包含 shadow DOM 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 支持后,您的网站应该会继续正常运行。

如果您使用浏览器嗅探功能有条件地加载 polyfill(即,在非 Chrome 浏览器上加载 polyfill),那么在 Chrome 停止支持 v0 后,您的网站将会失败。

请求帮助!我不知道自己使用的是哪些 API!

如果您不知道自己是否在使用任何 v0 API,或不知道您使用的是哪种 API,可以查看 Chrome 中的控制台输出。

  1. 如果您之前使用用于停用 v0 API 的标志启动了 Chrome,请关闭 Chrome 并正常重启。
  2. 打开新的 Chrome 标签页,然后加载您的网站。
  3. 按 Ctrl+Shift+J(Windows、Linux、ChromeOS)或 Command+Option+J (Mac) 打开开发者工具 控制台
  4. 查看控制台输出,了解弃用消息。如果控制台输出过多,请在过滤条件框中输入“Deprecation”。
显示弃用警告的控制台窗口

您应该会看到您所使用的每个 v0 API 的弃用消息。上面的输出显示了 HTML 导入、自定义元素 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 组件 v0 草稿 API 即将停用。如果您觉得本博文没有什么内容,请务必在停用 v0 API 的情况下测试应用,并根据需要加载 polyfill

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