如何查询 Web 平台信息中心以获取基准工具

Jeremy Wagner

发布时间：2025 年 3 月 4 日

基准由 Chrome 团队发起，目前由 WebDX 社区群组定义。基准测试可让您清晰了解哪些功能可在浏览器之间互操作。该工具旨在帮助您确定可以在所有主要浏览器引擎中使用或无法使用哪些功能。不过，您需要找到一种方法来确定这些特征。

幸运的是，您可以使用 Web 平台信息中心（由 web-features npm 软件包提供支持）查询哪些功能是“新基准”或“广泛提供”。您还可以使用其 HTTP API 访问这些信息，以将基准数据集成到您的工具工作流中，本指南将介绍具体方法。

Web 平台信息中心的相关基准查询语法

Web 平台信息中心使用特定的查询语法来帮助您搜索 Web 功能支持。您可以直接在信息中心内使用此查询语法。

Web 平台状态信息中心的功能列表，显示了 baseline_status 查询参数的运作方式，以显示“基准版 - 新推出的功能”。
Web 平台信息中心中的功能列表。此列表基于使用 baseline_status:newly 搜索查询的搜索结果，仅显示“基准版”下的“新推出的功能”。

当您在页面顶部的搜索框中输入内容时，系统会显示一些可用于过滤 Web 地图项的查询参数。

Web 平台状态信息中心的自动补全功能，显示初始值“基准”，并显示以该初始值开头的所有可用查询参数。
d Web 平台状态信息中心的搜索框会在您输入内容时显示可用的查询参数。在这种情况下，自动补全功能会建议与基准相关的参数，以便按基准状态或甚至日期范围进行过滤。

查询语法非常丰富，可让您灵活地过滤信息中心中显示的 Web 地图项。以下屏幕截图展示了如何使用 id 查询参数来缩小到特定地图项的范围：

Web 平台状态信息中心，显示了如何使用 id 参数在搜索框中按功能查询支持。
此示例中的 id 参数的值为 html，表示支持 <html> 元素，后者（毫不奇怪）属于“基准 - 广泛提供”类别。

查询语法已记录在案，但您无需了解所有这些内容，也无需了解所有这些内容即可查找功能的基准数据。您可以在信息中心内使用上述任一选项，但以下选项特别实用：

  • baseline_status：使用此参数可按以下三个枚举值过滤地图项：
    • limited：返回浏览器支持有限的功能。如果您按此值进行过滤，则只会收到尚未达到任何基准状态的功能。
    • newly：返回“新推出的基准”类别的功能。
    • widely：返回已广泛发布的基准功能，即已作为基准功能至少发布 30 个月的功能。您可以使用这些功能，而无需担心浏览器支持或 polyfill。
  • baseline_date：使用 YYYY-MM-DD..YYYY-MM-DD 格式指定特征达到基准的时间的上限和下限。例如，如需查找一年内的所有地图项，请使用 2024-01-01..2025-01-01 等值。
  • id：给定地图项的标识符。这些标识符在 web-features 软件包中定义。例如，Promise.try() 的地图项条目会映射到 ID 为 promise-try 的 ID。
  • group：特征的众多枚举组名称之一。如果您只想查询部分 Web 平台功能，此条件非常有用。例如，您可以过滤出值为 css 的 CSS 功能列表。

虽然信息中心前端非常实用，但它基于您可以直接查询的 HTTP API。例如，下面的端点会获取新推出的所有基准功能：

https://api.webstatus.dev/v1/features?q=baseline_status:newly

JSON 响应结构

您从 HTTP API 收到的 JSON 响应中的每个地图项的格式都是一致的。返回的响应在顶级包含 data 属性。此属性包含所有匹配地图项的数组。虽然这并不是 JSON 响应中所有可用字段的详尽列表，但下面列出了一些与基准相关的有用字段：

  • baseline：包含与给定地图项的基准状态相关的一般信息，其中包含以下子字段：
    • status：相应地图项的基准状态。值可以是 limited、newly 或 widely。注意：如果 status 的值为 limited，则这是唯一的子字段。
    • low_date：表示指定功能成为“基准新推出”功能的日期。只有当 status 为 newly 或 widely 时，此字段才会显示。
    • high_date：表示给定功能变为“广泛提供的基准”的日期。只有当 status 为 widely 时，此字段才可用。
  • feature_id：相应地图项的 ID。例如，对于 CSS 网格，此值为 "grid"。
  • name：地图项的格式化名称。在某些情况下，这可能与 feature_id 类似，但通常不同。例如，Promise.try() 的 feature_id 值为 "promise-try"，而同一地图项的 name 字段为 "Promise.try()"。
  • spec：此字段包含一个名为 links 的子字段，该子字段是一个指向规范和其他资源的链接数组。

还有其他字段，其中通常包含有关特定支持浏览器在哪个版本中实现了该功能、Web 平台测试相关数据，以及您可能或可能不关心的其他内容。

示例查询

现在，您已经快速了解了一些可用查询参数，接下来请查看一些查询示例，了解如何在工具和脚本中使用这些查询来选择对您的工作流程有用的网站状态功能。

获取单个地图项的数据

如需熟悉该 API，不妨先从获取单个 Web 地图项数据的基本示例入手。

// Specify and encode the query for a query string:
const query = encodeURIComponent('id:grid');

// Construct the URL:
let url = `https://api.webstatus.dev/v1/features?q=${query}`;

// Fetch the resource:
const response = await fetch(url);

if (response.ok) {
  // Convert the response to JSON:
  const { data } = await response.json();

  // Log data for each feature to the:
  console.log(data);
}

在本例中，我们指定 id 参数的值为 grid，以获取 CSS 网格的功能支持信息，该信息为“基准版，广泛提供”。例如，您可以使用这些信息来检测该功能的使用情况，并让用户知道他们可以在所有现代浏览器引擎中使用该功能，而无需担心支持问题。

不过，这只是一个开始，HTTP API 不仅可以获取单个地图项的数据，还可以执行更多操作。

获取所有“基准”新功能和广泛提供的功能

假设您希望使用一个脚本提取所有已纳入基准版的“新功能”或“广泛推出”的功能。例如，如果您有一个按一定时间间隔运行的脚本，并且希望获取一个更新后的列表，以便在功能从“仅限部分用户”状态变为“基准”状态时进行更改，这可能会很有用：

const query = encodeURIComponent('-baseline_status:limited');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

此查询不会获取所有“新推出”和“广泛推出”基准功能，只会获取前 100 个功能。如果检索到的地图项数量超出此上限，JSON 响应的顶级将包含一个 metadata 字段，该字段最多可包含两个子字段：

  • next_page_token：包含令牌的字符串，您可以将其添加到发送到后端的 GET 请求的查询字符串中。当您使用该 ID 并从 webstatus.dev 后端重新提取数据时，它会返回下一批匹配的功能。注意：如果当前查询返回的结果少于 100 个，或者当前查询位于结果集中的末尾，则此字段将不可用。
  • total：一个整数，表示当前查询可用的地图项总数。

这些字段对分页很有用。有了这些知识，我们可以尝试使用以下代码来获取返回大量数据的查询的所有结果：

async function queryWebStatusDashboard (query, token) {
  const urlBase = 'https://api.webstatus.dev/v1/features?q=';
  let queryUrl = `${urlBase}${encodeURIComponent(query)}`;

  if (token) {
    queryUrl += `&page_token=${encodeURIComponent(token)}`;
  }

  const response = await fetch(queryUrl);

  if (response.ok) {
    const { data, metadata } = await response.json();

    console.log(data);

    // See if there's a page token in this query:
    if ('next_page_token' in metadata) {
      const { next_page_token } = metadata;
      queryWebStatusDashboard(query, next_page_token);
    } else {
      console.log('All results collected');
    }
  }
}

// Make the first query, and if there are more
// than 100 entries, the function will run
// recursively until all features are fetched
queryWebStatusDashboard('-baseline_status:limited');

获取所有基准版新推出的 CSS 功能

假设您是一名专注于 CSS 的工程师，并且想要了解哪些 CSS 功能会成为“新推出的基准”功能。这是 group 查询值的绝佳用例，以及在查询 webstatus.dev 时如何使用 AND 运算符：

const query = encodeURIComponent('baseline_status:newly AND group:css');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

为 group 指定 css 值时，您可以查询所有“基准”新推出的功能。如果您想扩大范围，将基准版广泛提供的 CSS 功能也纳入考量范围，可以使用上一个代码示例中的方法，并将否定运算符与 -baseline_status:limited AND group:css' 等查询搭配使用。

您可以查询的另一个字段是 snapshot 字段，该字段对于查找属于特定 ECMAScript 功能集的 JavaScript 功能非常有用。以下代码会检查 ecmascript-2023 快照中包含的所有基准“新推出”功能：

const query = encodeURIComponent('baseline_status:newly AND snapshot:ecmascript-2023');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

获取日期范围内的所有基准功能

您可以查询 baseline_date 字段，以查找在特定日期范围内变为基准的所有地图项：

const query = encodeURIComponent('baseline_status:widely AND baseline_date:2022-01-01..2022-12-31 AND group:css');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

上述代码示例将查询在 2022 年的任何时间成为基准广泛提供的 CSS 功能。baseline_date 的查询语法允许您指定开始日期和结束日期，以 .. 分隔。

总结

本指南中的查询旨在帮助您开始实验如何查询 webstatus.dev 后端。您可以使用任意数量的可用查询参数，获取特定于您应用的结果。

了解如何查询 Web 平台信息中心的 HTTP API 后，您就可以构建对您的工作可能有用的工具，并及时了解您要为项目使用的功能是否有足够广泛的浏览器支持。这意味着，您可以使用安全可靠的现代浏览器功能构建 Web 应用，从而获得更愉快的开发者体验。