如何查询 Baseline 工具的 Web 平台仪表板

发布日期：2025 年 3 月 4 日

Baseline 最初由 Chrome 团队创建，目前由 WebDX 社区团体定义。它明确了浏览器间可互操作的特性，帮助开发者识别哪些功能已在所有主流浏览器引擎中得到支持，哪些尚未支持。然而，要有效利用这些信息，我们需要一种方法来准确识别这些特性。

幸运的是，我们可以使用基于 web-features npm 包的 Web Platform Dashboard 查询 Baseline 中新增或广泛可用的功能。此外，我们还能够通过 HTTP API 获取这些信息，并将 Baseline 数据集成到工具的工作流中。本指南将介绍具体实现方法。

Web Platform Dashboard 中 Baseline 查询语法

在 Web Platform Dashboard 中，可以使用特定的查询语法来搜索 Web 功能的支持情况。这套语法可直接在 Dashboard 界面中使用。

在页面顶部的搜索框中输入内容时，会显示可用于筛选 Web 功能的查询参数。

查询语法具有丰富的表达能力，能够灵活筛选 Dashboard 中展示的 Web 功能。以下截图展示了如何使用 id 查询参数精确筛选特定功能。

虽然查询语法有完整文档，但你无需掌握全部细节即可查询功能的 Baseline 数据。Dashboard 支持多种选项，下面介绍几个特别实用的参数：

• baseline_status：使用此参数可通过以下三个枚举值筛选功能：

  • limited：返回浏览器支持有限的功能。使用此值筛选将仅返回尚未达到 Baseline 状态的功能。
  • newly：返回 Baseline 中新增可用的功能。
  • widely：返回 Baseline 中广泛可用的功能（已在 Baseline 中提供超过 30 个月）。这些功能可放心使用，无需担心浏览器支持或 polyfill 问题。

• baseline_date：使用 YYYY-MM-DD..YYYY-MM-DD 格式指定功能达到 Baseline 状态的时间范围。例如，要查询一年内所有新增功能，可使用 2024-01-01..2025-01-01。

• id：特定功能的标识符。这些标识符在 web-features 包中定义。例如，Promise.try() 的功能条目对应 ID 为 promise-try。

• group：功能所属的枚举分组名称之一。这在只需查询 Web 平台功能特定子集时非常有用。例如，可使用 css 值筛选 CSS 功能列表。

Dashboard 前端界面固然方便，但其底层基于可直接查询的 HTTP API。例如，获取所有新增 Baseline 功能的端点如下：

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

注：查询语法还支持逻辑修饰符（如 AND、OR 关键字）以及使用 - 运算符的否定查询。完整文档请参阅查询语法说明。

JSON 响应结构

从 HTTP API 接收的 JSON 响应对所有功能保持一致的格式。返回的响应在顶层包含 data 属性，该属性是一个包含所有匹配功能的数组。以下并非 JSON 响应中所有可用字段的完整列表，但涵盖了几个与 Baseline 相关的重要字段：

• baseline：特定功能的 Baseline 状态信息，包含以下子字段：

  • status：功能的 Baseline 状态，值为 limited、newly 或 widely。注意：当 status 为 limited 时，这是唯一的子字段。
  • low_date：功能首次在 Baseline 中变为新可用状态的日期。此字段仅在 status 为 newly 或 widely 时出现。
  • high_date：功能在 Baseline 中变为广泛可用状态的日期。此字段仅在 status 为 widely 时可用。

• feature_id：功能的 ID。例如，CSS Grid 的值为 "grid"。

• name：功能的格式化名称。有时可能与 feature_id 相似，但通常不同。例如，Promise.try() 的 feature_id 为 "promise-try"，而同一功能的 name 字段为 "Promise.try()"。

• spec：此字段包含 links 子字段，这是一个链接到规范和其他资源的数组。

响应中还可能包含其他字段，如各浏览器实现该功能的版本信息、Web 平台测试相关数据等。

查询示例

在简要了解可用查询参数后，我们来看一些可在工具或脚本中使用的查询示例。这些查询可帮助你筛选对工作流有用的 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 Grid 在 Baseline 中广泛可用的功能支持信息。这些信息可用于检测该功能的使用情况，并告知用户所有现代浏览器引擎均已支持。

不过，这只是开始。HTTP API 的功能远不止获取单个功能数据。

获取所有新增和广泛可用的 Baseline 功能

假设你有一个脚本，需要获取 Baseline 中所有新增或广泛可用的功能。这对于需要定期运行并获取更新列表的场景非常有用，例如跟踪功能从有限支持状态升级到 Baseline 状态的情况。

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);
}

注：查询中使用的 -baseline_status:limited 会排除状态为 limited 的功能。等效查询为 baseline_status:newly AND baseline_status:widely。

此查询默认最多返回 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');

注意：以上代码示例展示了如何访问分页结果，不建议直接在生产环境使用。

获取 Baseline 中所有新增的 CSS 功能

假设一位专注于 CSS 的工程师希望了解哪些 CSS 功能已成为 Baseline 的新增可用功能。这正好展示了 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);
}

使用值为 css 的 group 参数，可以查询 Baseline 中所有新增可用的功能。如果需要扩大范围以包含 Baseline 中广泛可用的 CSS 功能，可采用最后一个代码示例中的方法，使用类似 -baseline_status:limited AND group:css 的查询语句结合否定运算符。

注：有关所有可用 group 值的列表，请参阅 web-features GitHub 仓库。

另一个可查询的字段是 snapshot，适用于搜索包含在特定 ECMAScript 功能集中的 JavaScript 功能。以下代码检查属于 ecmascript-2023 快照且为 Baseline 新增可用的所有功能。

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);
}

注：有关所有可查询快照的列表，请参阅 web-features GitHub 仓库。

获取特定时间段内的所有 Baseline 功能

通过查询 baseline_date 字段，可以找到在指定时间段内达到 Baseline 状态的所有功能。

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 年任何时间点变为 Baseline 广泛可用的 CSS 功能。baseline_date 的查询语法使用 .. 分隔开始日期和结束日期。

总结

本指南中的查询示例旨在作为你测试 webstatus.dev 后端查询方法的起点。可用查询参数没有数量限制，你可以灵活组合以获取适合应用程序的特定结果。

掌握查询 Web Platform Dashboard 的 HTTP API 的方法，能够帮助你构建实用的工具，并确认项目所用功能是否已获得广泛的浏览器支持。这意味着你可以在构建 Web 应用时安全地使用最新的浏览器功能，从而显著提升开发体验。