实验性、已弃用和已过时的

这些术语通常与技术和规范相关联,并在 MDN Web 文档中用于标记技术的现状。对于这些术语的定义,MDN Web 文档与浏览器兼容性数据 (BCD) 存储库保持一致。这些术语在 MDN Web 文档的使用上下文中在下面进行了描述。

实验性

当 MDN Web 文档中将一项技术描述为实验性时,这意味着该技术尚处于起步阶段且不成熟,目前正在被添加到 Web 平台中(或正在考虑添加)。将技术标记为实验性表明读者在任何类型的生产项目(即,不仅仅是演示或实验的项目)中使用该技术之前都应仔细考虑。读者鼓励尝试实验性功能 并向浏览器供应商和标准作者提供反馈。

对于标记为实验性的技术,以下一个或多个条件适用

  • 它在仅一个现代主要浏览器渲染引擎的发布版本中实现并默认启用。
  • 它仅通过配置更改(例如首选项或标志)支持,无论支持多少个渲染引擎。
  • 其定义规范可能会以向后不兼容的方式发生重大更改(即,它可能会破坏依赖于该功能的现有代码)。

注意:即使在其他渲染引擎的预览版本中(或通过设置首选项或标志)可以使用,仅在一个渲染引擎上发布的功能仍被视为实验性。

如果满足以下一个或多个条件,技术的实验性状态可能会过期

  • 它在两个或多个主要浏览器渲染引擎中默认支持。
  • 它在一个浏览器渲染引擎中默认支持两年或两年以上,并且没有发生重大变化。
  • 其定义规范不太可能以破坏兼容性的方式发生更改。

有关这些条件的示例,请参阅实验性标志 BCD 文档。

通常,如果一项技术在多个主要浏览器中受支持,则规范将是稳定的,但并非总是如此。另一方面,某些技术可能具有稳定的规范,但在浏览器中没有原生支持。IMSC 例如,是通过 JavaScript polyfill 使用的。

属于活动规范或标准化过程且未标记为已弃用的功能或技术被称为处于标准轨道上。

已弃用

MDN Web 文档中的术语已弃用用于标记不再推荐的 API 或技术。已弃用的 API 或技术将来可能会被删除,或者可能仅出于兼容性目的而保留,并且可能仍然有效。我们建议避免使用标记为已弃用的功能。

有关已弃用定义的更多信息,请参阅已弃用标志 BCD 文档。

已过时

在 MDN Web 文档中,术语已过时在历史上用于指示不仅不再推荐而且也不再在浏览器中实现的 API 或技术。由于已过时已弃用之间的区别不是很有帮助,因此我们不再在 MDN Web 文档中使用术语已过时

注意:如果您遇到任何已过时的实例,则应将其删除或替换为术语已弃用

删除内容的指南

有时在开发新规范或在 HTML 等活动标准演变过程中,新的元素、方法、属性等会被添加到规范中,保留一段时间,然后删除。有时这种情况发生得很快,有时这些新项目会在被删除之前在规范中保留数月甚至数年。这使得决定如何处理从规范中删除该项目变得棘手。

以下是一些指南,可帮助您在从规范中删除某些内容时决定该怎么做。

注意:出于本讨论的目的,“项目”一词用于表示规范中可以包含的任何内容:元素或元素的属性、接口或任何单独的方法、属性或接口的其他成员,等等。

如果该项目从未实现

如果该项目从未任何浏览器的发布版本中实现,即使是在首选项或标志后面,也请从文档中删除对该项目的任何引用。

  • 如果该项目有任何仅描述该项目的文档页面(例如RTCPeerConnection.close()),请删除该页面。如果已删除的项目是接口,则意味着还必须删除描述该接口上的属性和方法的任何子页面。
  • 从属性、特性、方法等的任何列表中删除该项目。例如,对于接口的方法,这意味着将其从接口概述页面上的“方法”部分中删除。
  • 搜索该接口、元素等的概述页面文本,查找对已删除项目的任何引用。删除这些引用,确保不会留下奇怪的语法问题或文本的其他问题。这可能不仅意味着删除单词,还意味着重写句子或段落以使其更有意义。如果对该项目用法的描述很长,则可能还需要删除整个内容部分。
  • 同样,查找相关 API 或技术的指南和教程中对该项目的任何讨论。删除这些引用,确保不会留下奇怪的语法问题或文本的其他问题。这可能不仅意味着删除单词,还意味着重写句子或段落以使其更有意义。如果对该项目用法的描述很长,则可能还需要删除整个内容部分。
  • 在 MDN Web 文档中搜索对已删除项目的引用,以防在其他地方有讨论。这种情况不太可能发生,因为如果它从未实现,则不太可能被广泛讨论。也请删除这些提及。
  • 如果浏览器兼容性数据存储库 中的 JSON 文件包含已删除项目的相关数据,请从 JSON 代码中删除这些对象并提交包含此更改的拉取请求,并在提交消息和拉取请求说明中解释原因。在执行此操作时,请务必仔细检查您不会破坏 JSON 语法。

如果该项目在浏览器中通过标志实现

如果该项目在任何一个或多个浏览器的任何发布版本中实现,但在首选项或标志后面实现,请不要立即从文档中删除该项目。而是按照以下步骤将该项目标记为已弃用

  • 通过提交拉取请求更新浏览器兼容性数据存储库中的项目状态数据。
  • 搜索该接口、元素等的概述页面的信息性文本,查找对已删除项目的任何引用。在适当的位置添加警告框,内容类似于“[项目]已从规范中删除,并将很快从浏览器中删除。请参阅[页面链接]以了解新的操作方法。”
  • 同样,查找相关 API 或技术的指南和教程中对该项目的任何讨论。添加类似的警告。
  • 在 MDN Web 文档中搜索对已删除项目的引用,以防在其他地方有讨论。也在那里添加类似的警告框。
  • 将来某个时候,可能会做出实际从文档中删除该项目的决定;我们通常不会这样做,但如果该项目特别不常用或不重要,我们可能会决定这样做。
  • 更新浏览器兼容性数据存储库 中的任何相关条目,以反映受影响的项目(s) 的过时性。

如果该项目在浏览器中未通过标志实现

如果某个项目在浏览器的一个或多个发行版本中已实现,并且无需任何偏好设置或标志,请将其标记为已弃用,如下所示

  • 通过提交拉取请求更新浏览器兼容性数据存储库中的项目状态数据。
  • 搜索该接口、元素等的概述页面中的信息性文本,查找任何对已删除项目的引用。在适当的位置添加警告框,内容类似于“ [项目] 已从规范中删除,并且已弃用。它可能会在将来从浏览器中删除,因此您不应使用它。请参阅[页面链接]以获取新的方法。”
  • 同样,查找相关 API 或技术的指南和教程中对该项目的任何讨论。添加类似的警告。
  • 在 MDN Web 文档中搜索对已删除项目的引用,以防在其他地方有讨论。也在那里添加类似的警告框。
  • 这些项目不太可能很快从文档中删除,即使将来也不会。
  • 更新浏览器兼容性数据存储库中的任何相关条目,以反映受影响项目的弃用。

请根据常识使用上述指南中建议的警告消息和其他文本更改的措辞。不同的项目需要不同的措辞和处理方式。如有疑问,请随时在MDN Web Docs 聊天室中寻求建议。

记录规范冲突的指南

有时,但很少见,不同规范版本(通常是 W3C 与 WHATWG)之间可能存在冲突。例如,一个版本可能将某个功能列为已弃用,而另一个版本则没有。在这种情况下,请考虑实际情况,即考虑浏览器实际执行的操作,并编写“重要”说明以总结最新状态。例如,截至 2019 年 1 月,inputmode 全局属性存在冲突,其总结如下

警告:规范冲突:WHATWG 规范列出了inputmode,并且现代浏览器正在努力支持它。然而,W3C HTML 5.2 规范不再列出它(即将其标记为已弃用)。在达成共识之前,您应将 WHATWG 定义视为正确。

另请参阅