此页面由 Cloud Translation API 翻译。

使用 web-features 软件包创建基准工具

Jeremy Wagner

Rick Viscomi

发布时间：2025 年 9 月 12 日

Baseline 的新兴工具可帮助您确定目前可以在 Web 应用中安全使用哪些 Web 功能。这些工具（例如代码检查工具和 IDE 功能）使用 Web 平台功能的数据源，其中包含有关这些功能在现代浏览器中的支持情况的数据。

Web 平台状态信息中心是这些功能的数据源之一，并提供可查询的 HTTP API。对于某些工具，按需查询此数据源并不实际。对于许多工具使用情形，web-features npm 软件包是您在本地使用的更可靠、更实用的 Web 功能数据版本。本指南将介绍如何使用 web-features 软件包开发自己的基准工具。

`web-features`软件包使用入门

首先，在项目中安装该软件包作为依赖项：

npm install web-features

安装后，将 web-features 软件包中的一个或多个已命名导出项导入到您的项目中：

import { features, groups, browsers, snapshots } from 'web-features';

根据您的目标，您可能不需要导出所有这些数据。这些导出文件提供以下信息：

features：一个对象数组，其中每个对象都表示一项 Web 功能。这是您最常使用的导出方式。
browsers：一个描述浏览器的对象数组。
groups：一个对象数组，用于定义特征的逻辑分组。如果您想定位到一部分 Web 平台功能（例如 CSS、JavaScript 和更具体的分组），这些功能会很有用。
snapshots：包含相应 JavaScript 功能的 ECMAScript 版本，例如 ES2023、ES2022 和其他 ECMAScript 版本。

功能导出为构建基准工具提供了以下属性：

id：功能的唯一标识符。例如，CSS 网格的标识符为 "grid"。注意：这不是数据对象中的属性。这是对象键。
compat_features：相应功能中包含的各个 BCD 密钥的数组。
name：功能名称的人类可读字符串，例如 "Container Queries"。
description：功能的简短说明。
group：相应功能所属的群组。这对应于在 groups 导出中找到的群组数据。
baseline：相应功能的基本状态。可以是以下三个值之一：
1. false：相应功能的状态为“限量版”。
2. "low：表示相应功能属于“Baseline 新近可用”。
3. "high：相应功能处于“Baseline 广泛可用”阶段。
4. baseline_high_date：相应功能成为“Baseline 广泛可用”功能的日期。注意：如果相应功能不是基准广泛可用功能，则无法使用此方法。
5. baseline_low_date：相应功能成为基准新近可用功能的日期。注意：此功能不适用于“限时提供”功能。

以下示例是 CSS 子网格功能的完整数据对象：

"subgrid": {
  "caniuse": "css-subgrid",
  "compat_features": [
    "css.properties.grid-template-columns.subgrid",
    "css.properties.grid-template-rows.subgrid"
  ],
  "description": "The subgrid value for the grid-template-columns and grid-template-rows properties allows a grid item to inherit the grid definition of its parent grid container.",
  "description_html": "The <code>subgrid</code> value for the <code>grid-template-columns</code> and <code>grid-template-rows</code> properties allows a grid item to inherit the grid definition of its parent grid container.",
  "group": "grid",
  "name": "Subgrid",
  "spec": "https://drafts.csswg.org/css-grid-2/#subgrids",
  "status": {
    "baseline": "low",
    "baseline_low_date": "2023-09-15",
    "support": {
      "chrome": "117",
      "chrome_android": "117",
      "edge": "117",
      "firefox": "71",
      "firefox_android": "79",
      "safari": "16",
      "safari_ios": "16"
    }
  }
}

groups 导出功能可提供有关功能分组的数据，这些数据具有以下结构：

id：群组的唯一标识符。例如，CSS 功能的 ID 为“css”。注意：这不是 groups 对象中的属性。即对象键本身。
name：简单易懂的群组名称。
parent：相应群组的父群组的 ID。如果相应群组没有父群组，则此属性不可用。

示例

以下示例展示了如何使用 web-features package 获取构建基准测试工具所需的数据。

查找特定功能的基准状态

import { features } from 'web-features';

function getBaselineStatus (featureId) {
  return features[featureId]?.status.baseline;
}

此示例展示了 web-features 软件包最直接的用例，即指定功能的 ID 以获取其在 status.baseline 属性中提供的基准数据。此属性用于指示某项功能处于“有限可用”“新近可用”还是“广泛可用”阶段。在后两种情况下，您还可以访问描述相应功能何时达到特定基准阈值的日期。

查找特定 BCD 密钥的基准状态

BCD 是 browser-compat-data 的缩写，这是由 MDN 维护的一个项目，用于编目各种浏览器对功能的支持情况。一个 BCD 键对应于一个精细的功能，例如特定的 CSS 属性值或规范定义的行为子功能。

web-features 项目将相关的 BCD 键分组到每个功能的 compat_features 数组中。有时，您需要的是某个 BCD 键的基准状态，而不是整个功能的总体基准状态。例如，如果您构建了一个 CSS 代码检查工具，并且需要了解某个属性-值对是否在主要浏览器中兼容，那么功能级数据就过于粗略了。之所以会发生这种情况，是因为软件包会汇总所有组成 BCD 键的各项功能，而某些键的浏览器支持程度要优于其他键。

如需查找 BCD 密钥的基准状态，请检查功能对象的 status.by_compat_key 属性（可在 web-features 3.6.0 及更高版本中使用）：

import { features } from 'web-features';

function getBaselineStatus (featureId, bcdKey) {
  return features[featureId]?.status.by_compat_key[bcdKey];
}

例如，getBaselineStatus('outline', 'css.properties.outline') 的输出为：

{
  "baseline": "low",
  "baseline_low_date": "2023-03-27",
  "support": {
    "chrome": "94",
    "chrome_android": "94",
    "edge": "94",
    "firefox": "88",
    "firefox_android": "88",
    "safari": "16.4",
    "safari_ios": "16.4"
  }
}

按基准状态对功能进行排序

此示例会遍历 features 对象中的每个功能，并根据每个功能的基准状态将其归类到数组中。

import { features } from "web-features";

const webFeatures = Object.values(features);

const widelyAvailable = webFeatures.filter(feature => {
  return feature.status.baseline === 'high';
});

const newlyAvailable = webFeatures.filter(feature => {
  return feature.status.baseline === 'low';
});

const limitedAvailability = webFeatures.filter(feature => {
  return feature.status.baseline === false;
});

此示例说明了如何在工具中使用 status.baseline 属性。例如，您可以在 Web 应用中使用此方法按基准状态显示所有 Web 功能的列表。

查找群组中的所有功能

到目前为止，所有显示的示例都使用 features 导出，但 groups 导出会在组内按逻辑方式整理所有功能。这意味着，您可以找到属于视图过渡的所有功能，例如：

import { features, groups } from 'web-features';

const groupKeys = Object.keys(groups);
const featuresData = Object.values(features);

const viewTransitionsGroup = groupKeys.find(groupKey => {
  return groupKey === 'view-transitions';
});

const viewTransitionsFeatures = featuresData.filter(feature => {
  return feature.group === viewTransitionsGroup;
});

通过 features 和 group 导出之间的交集，您可以按网络功能所属的群组缩小搜索范围。

综合应用

您可以使用这些查找功能来构建实用工具，例如创建 CSS 代码检查器。

CSS Linter 会评估 at 规则、伪元素、属性和属性值对。对于基准 lint，请按每个令牌的 BCD 键（而非其父功能）查找其状态。

CSSTree 等解析器会对 CSS 进行标记化处理，将样式表分解为抽象语法树 (AST)。以下示例展示了使用通用类选择器和样式声明的 CSS 规则：

.foo {
  word-break: auto-phrase;
}

AST 将如下所示：

{
  "type": "StyleSheet",
  "children": [
    {
      "type": "Rule",
      "prelude": {
        "type": "SelectorList",
        "children": [
          {
            "type": "Selector",
            "children": [
              {
                "type": "ClassSelector",
                "name": "foo"
              }
            ]
          }
        ]
      },
      "block": {
        "type": "Block",
        "children": [
          {
            "type": "Declaration",
            "important": false,
            "property": "word-break",
            "value": {
              "type": "Value",
              "children": [
                {
                  "type": "Identifier",
                  "name": "auto-phrase"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

当您遍历 AST 时，如果找到属性声明，请将该属性名称映射到其对应的 BCD 键，以检查其基准状态。BCD 将 CSS 属性归类到 css.properties 对象下，因此对应的 BCD 键为 css.properties.word-break。

然后，找到与该 BCD 键关联的功能，并查找其状态。

// Assuming we only know the BCD key and not the feature ID.
const bcdKey = 'css.properties.word-break';
const [featureId, feature] = Object.entries(features).find(([id, feature]) =>
  feature.compat_features?.includes(bcdKey)
) || [];
const status = feature?.status.by_compat_key[bcdKey];

word-break 属性的基准状态如下：

{
  "baseline": "high",
  "baseline_high_date": "2018-03-30",
  "baseline_low_date": "2015-09-30",
  "support": {
    "chrome": "44",
    "chrome_android": "44",
    "edge": "12",
    "firefox": "15",
    "firefox_android": "15",
    "safari": "9",
    "safari_ios": "9"
  }
}

"high" 基准状态表示相应属性已广泛可用，因此您的 lint 工具无需发出警告。接下来，检查该属性的值。

AST 显示此属性的值为 auto-phrase。如需获取相应的 BCD 键，请将该值添加到父属性的 BCD 键中：css.properties.word-break.auto-phrase。

注意：此方法仅适用于属性规范所命名的值。数字或颜色名称等通用值类型没有自己的 BCD 键。如果 web-features 未针对给定的 BCD 键返回数据，则无需进行验证，因此请忽略该情况。

在此示例中，web-features 表明 word-break: auto-phrase 属性-值对的状态不是基准：

{
  "baseline": false,
  "support": {
    "chrome": "119",
    "chrome_android": "119",
    "edge": "119"
  }
}

使用此 lint 示例中的信息来警告开发者，此属性-值对不是基准。此警告可确保开发者知道，该代码在主要浏览器引擎中无法按预期运行。

真实情景示例

前面的示例展示了 web-features 软件包的基本用法。目前已有许多工具在利用这些数据。例如：

eslint-css 使用其 use-baseline 规则中的 web-features 软件包来检查特定功能。
Visual Studio Code 中的悬停卡片使用 web-features 软件包来显示 CSS 功能和 HTML 功能的 Baseline 信息。
MDN 会在大多数功能页面（例如 abs()）的横幅中使用 web-features 数据来传达相应功能的 Baseline 状态。

还有更多示例展示了如何使用此数据源来构建基准工具，我们希望您的项目也能成为其中之一！

使用 web-features 软件包创建基准工具 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

web-features软件包使用入门

示例

查找特定功能的基准状态

查找特定 BCD 密钥的基准状态

按基准状态对功能进行排序

查找群组中的所有功能

综合应用

真实情景示例

使用 web-features 软件包创建基准工具

`web-features`软件包使用入门