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。
- 如果您使用的是 Polymer 库 v1 或 v2,请按照 Polymer 团队之前发布的说明进行操作。
- 如果您使用的是 shadow DOM v0、自定义元素 v0 或 HTML 导入,将需要加载一些 polyfill。请参阅使用 v0 polyfill。
- 如果您不确定自己使用的是什么,也不用担心。有关详情,请参阅帮助!我不知道自己使用的是哪些 API!
回到未来:停用 v0 API
如需在停用 v0 API 的情况下测试您的网站,您需要从命令行启动 Chrome,并添加以下标志:
--disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports
您需要先退出 Chrome,然后再通过命令行启动它。如果您安装了 Chrome Canary 版,则可以在 Canary 版中运行测试,同时在 Chrome 中保持此页面处于加载状态。
要在停用 v0 API 的情况下测试您的网站,请执行以下操作:
- 如果您使用的是 Mac OS,请前往
chrome://version
查找 Chrome 的可执行文件路径。 您需要使用第 3 步中的路径。 - 退出 Chrome。
使用命令行 flag 重启 Chrome:
--disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports
如需了解如何使用标志启动 Chrome,请参阅使用标志运行 Chromium。 例如,在 Windows 上,您可以运行以下命令:
chrome.exe --disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports
如需仔细检查浏览器是否已正确启动,请打开一个新标签页,打开开发者工具控制台,然后运行以下命令:
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。
最后,加载您的应用并运行各项功能。如果一切正常,那就大功告成了。
使用 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 中的控制台输出。
- 如果您之前使用用于停用 v0 API 的标志启动了 Chrome,请关闭 Chrome 并正常重启。
- 打开新的 Chrome 标签页,然后加载您的网站。
- 按 Ctrl+Shift+J(Windows、Linux、ChromeOS)或 Command+Option+J (Mac) 打开开发者工具 控制台。
- 查看控制台输出,了解弃用消息。如果控制台输出过多,请在过滤条件框中输入“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 组件!