# @html-validate/w3c-data 中文文档

规范地址：https://npmcn.com/package/%40html-validate/w3c-data/

版本：1\.20261101\.0
npm 元数据更新时间：2026-11-01T07:13:45.839Z
中文译文更新时间：2026-11-01T08:49:47.052Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40html-validate/w3c-data
原文对照：https://npmcn.com/package/%40html-validate/w3c-data/?lang=original
项目主页：https://gitlab.com/html-validate/w3c-data#readme
源码仓库：https://gitlab.com/html-validate/w3c-data

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：257 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.16\.0 \|\| \>= 24\.0\.0
- 运行依赖：0 个
- 首次发布：2026-02-08T14:16:47.831Z
- 最新版本发布：2026-11-01T07:13:45.516Z
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

从W3C规范中抓取的机器可读数据

## 安装

```sh
npm install @html-validate/w3c-data
```

也可以使用：`pnpm add @html-validate/w3c-data`、`yarn add @html-validate/w3c-data`、`bun add @html-validate/w3c-data`

## README

# html -验证W3C数据

该项目包含从W3C规范中抓取的数据：

-   wai - aria

这个包不是供公众使用的，任何版本之间都可能发生破坏性的更改。 使用风险自负！

## wai - aria

该包提供了从W3C规范中抓取的关于WAI-ARIA角色、属性和状态的机器可读数据。

### 使用

您可以通过两种方式访问ARIA数据。

使用工厂函数获取特定版本的ARIA数据：

```ts
import { getAriaData } from "@html-validate/w3c-data/aria";

// Get data for a specific version
const { getRoleData } = getAriaData("latest"); // "latest", "1.3" or "1.2"

// Use the data
const alert = getRoleData("alert");
console.log(alert?.category); // "live"
```

或者直接导入特定的ARIA版本以获得更好的摇树效果：

```ts
// Import latest ARIA data
import { getRoleData } from "@html-validate/w3c-data/aria-latest";
```

```ts
// Or import specific versions
import { getRoleData } from "@html-validate/w3c-data/aria-1.3";
```

### 可用的版本

-   `"latest"` - W3C最新编辑稿([https://w3c.github.io/aria/](https://w3c.github.io/aria/)）
-   `"1.3"` - wai-aria 1.3 ([https://www.w3.org/TR/wai-aria-1.3/](https://www.w3.org/TR/wai-aria-1.3/)）
-   `"1.2"` - wai-aria 1.2 ([https://www.w3.org/TR/wai-aria-1.2/](https://www.w3.org/TR/wai-aria-1.2/)）

### 数据结构

这个 `getRoleData()` Helper返回 `NormalizedRole` 对象:

```ts
const alert = getRoleData("alert");
console.log(alert?.category); // "live"
console.log(alert?.superclasses); // ["section"]
console.log(alert?.properties["aria-atomic"]); // { inherited: true, required: false, deprecated: false, default: "true" }
```

每个角色包含：

-   `role` -角色名称
-   `category` -角色类别(`abstract`， `widget`， `structure`， `landmark`， `live`，或者 `window`）
-   `superclasses` -该角色继承的角色列表
-   `subclasses` -从该角色继承的角色列表
-   `properties` -此角色可用的ARIA属性
-   `states` —此角色可用的ARIA状态
-   `name` -可访问的名称要求
    -   `fromAuthor` —名称可以从作者开始设置
    -   `fromContents` —名称可以根据内容设置
    -   `prohibited` —“名称”不能设置
    -   `required` -填写姓名
-   `requiredParent` -所需父角色列表
-   `allowedChildren` -允许的子角色列表
-   `childrenPresentational` - DOM后代是否具有表示性

中的每个属性和状态 `properties` 和 `states` 对象包含:

-   `inherited` （boolean） -属性是否继承自超类角色
-   `required` （boolean） -此角色是否需要该属性
-   `deprecated` （boolean） -是否弃用该属性
-   `default` （string | undefined） -属性的默认值，如果有的话

注意：所有属性和状态键都包含 `aria-` 前缀(例如, `"aria-atomic"`， `"aria-expanded"`）。

### 辅助函数和类型

该包提供了用于ARIA角色的辅助函数和类型：

-   `isValidRole(role: string): role is AriaRole`：检查字符串是否为有效的ARIA角色名。
-   `getRoleData(role: AriaRole): NormalizedRole`获取给定角色的ARIA角色元数据。
-   `getRoleData(role: string): NormalizedRole | null`获取给定角色的ARIA角色元数据。

## 版本控制

这个包裹可以 **不** 遵循语义版本控制，而不是最后一次抓取的日期。 中断更改可能发生在任何更改之间。

## 常见问题

### @html-validate/w3c-data 是什么？

从W3C规范中抓取的机器可读数据

### 如何安装 @html-validate/w3c-data？

在项目目录运行 npm install @html-validate/w3c-data，或使用 pnpm add / yarn add / bun add。

### @html-validate/w3c-data 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @html-validate/w3c-data 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @html-validate/w3c-data 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.16\.0 \|\| \>= 24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @html-validate/w3c-data 可以商用吗？

@html-validate/w3c-data 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @html-validate/w3c-data 还在维护吗？

最新版本 1\.20261101\.0 发布于 2026/11/01（2 天前）；至今共发布 33 个版本，其中过去 12 个月发布了 33 个；首次发布于 2026/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。