# @adguard/ecss-tree 中文文档

规范地址：https://npmcn.com/package/%40adguard/ecss-tree/

版本：2\.0\.3
npm 元数据更新时间：2026-08-19T10:43:20.027Z
中文译文更新时间：2026-11-06T00:59:37.791Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40adguard/ecss-tree
原文对照：https://npmcn.com/package/%40adguard/ecss-tree/?lang=original
项目主页：https://github.com/AdguardTeam/ecsstree#readme
源码仓库：https://github.com/AdGuardSoftwareLimited/ext-ecsstree

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

- 包体积（解压后）：144 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2023-02-21T16:51:52.151Z
- 最新版本发布：2026-06-30T02:08:43.535Z
- 近 30 天下载量：7596（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 3 个）

## 中文简介

CSSTree 扩展 CSS 叉

## 安装

```sh
npm install @adguard/ecss-tree
```

也可以使用：`pnpm add @adguard/ecss-tree`、`yarn add @adguard/ecss-tree`、`bun add @adguard/ecss-tree`

## README

![CSSTree logo](https://raw.githubusercontent.com/csstree/csstree/master/assets/csstree-logo-rounded.svg)

# ECSSTree 欧统局

[![NPM version](https://img.shields.io/npm/v/@adguard/ecss-tree.svg)](https://www.npmjs.com/package/@adguard/ecss-tree) [![NPM Downloads](https://img.shields.io/npm/dm/@adguard/ecss-tree.svg)](https://www.npmjs.com/package/@adguard/ecss-tree) [![LICENSE](https://img.shields.io/github/license/AdguardTeam/ecsstree)](https://github.com/AdguardTeam/ecsstree/blob/main/LICENSE)

附加块扩展 CSS 补充 [CSSTree (英语)](https://github.com/csstree/csstree)。 。 。 . 我们的首要目标是改变CSSTree分析器的内部行为以支持 扩展CSS(ECSS)语言元素,但我们不改变API或AST结构. 因此 ECSSTree 完全向后兼容 CSSTree, 这样您就可以将我们的 AST 函数传递到 CSSTree 反之亦然,没有任何问题.

> **说明:** 此软件包开发于 [辅助软件Limited/ext-ecstree](https://github.com/AdGuardSoftwareLimited/ext-ecsstree)。 。 。 . 这个 [护卫队/护卫队](https://github.com/AdguardTeam/ecsstree) 寄存器是一个公共镜像.
> 
> \[注\] 如果你要找一个可以分析CSS的图书馆 但你不知道Adblock是什么 或扩展 CSS,您可能应该使用 [CSSTree (英语)](https://github.com/csstree/csstree) 代替此库 :)

## 目录

-   [目录](https://npmcn.com/package/%40adguard/ecss-tree/#readme-table-of-contents)
-   [安装](https://npmcn.com/package/%40adguard/ecss-tree/#readme-installation)
-   [支持扩展CSS元素](https://npmcn.com/package/%40adguard/ecss-tree/#readme-supported-extended-css-elements)
-   [动机](https://npmcn.com/package/%40adguard/ecss-tree/#readme-motivation)
    -   [高级验证](https://npmcn.com/package/%40adguard/ecss-tree/#readme-advanced-validation)
-   [处理有问题的案件](https://npmcn.com/package/%40adguard/ecss-tree/#readme-handle-problematic-cases)
-   [实例](https://npmcn.com/package/%40adguard/ecss-tree/#readme-examples)
-   [报告问题/请求特征](https://npmcn.com/package/%40adguard/ecss-tree/#readme-reporting-problems--requesting-features)
    -   [捐款](https://npmcn.com/package/%40adguard/ecss-tree/#readme-contributing)
    -   [发展](https://npmcn.com/package/%40adguard/ecss-tree/#readme-development)
        -   [先决条件](https://npmcn.com/package/%40adguard/ecss-tree/#readme-prerequisites)
        -   [图标](https://npmcn.com/package/%40adguard/ecss-tree/#readme-commands)
-   [许可证](https://npmcn.com/package/%40adguard/ecss-tree/#readme-license)
-   [鸣谢](https://npmcn.com/package/%40adguard/ecss-tree/#readme-acknowledgements)
-   [参考资料](https://npmcn.com/package/%40adguard/ecss-tree/#readme-references)

## 安装

您可以使用

-   [菲律宾](https://pnpm.io/)数字 : `pnpm add @adguard/ecss-tree`
-   [国家预防机制](https://www.npmjs.com/get-npm)数字 : `npm install @adguard/ecss-tree`
-   [雅伦](https://yarnpkg.com/en/docs/install)数字 : `yarn add @adguard/ecss-tree`

或者你可以通过esm.run使用: [https://esm.run/@adguard/ecss-tree 互联网档案馆的存檔,存档日期2013-12-22](https://esm.run/@adguard/ecss-tree)

## 支持扩展CSS元素

目前,支持以下扩展CSS伪类:

-   `:-abp-contains(raw)`数字 : [\[ABP参考\]](https://help.adblockplus.org/hc/en-us/articles/360062733293#elemhide_css)
-   `:-abp-has(selector list)`数字 : [\[ABP参考\]](https://help.adblockplus.org/hc/en-us/articles/360062733293#elemhide_css)
-   `:contains(raw)`数字 : [\[总干事参考\]](https://github.com/AdguardTeam/ExtendedCss#extended-css-contains)
-   `:has-text(raw)`数字 : [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjecthas-textneedle)
-   `:if-not(selector)`数字 : [\[总干事参考\]](https://github.com/AdguardTeam/ExtendedCss#extended-css-if-not)
-   `:matches-css-after(raw)`数字 : [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjectmatches-css-afterarg)
-   `:matches-css-before(raw)`数字 : [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjectmatches-css-beforearg)
-   `:matches-css(raw)`数字 : [\[总干事参考\]](https://github.com/AdguardTeam/ExtendedCss#extended-css-matches-css), (中文(简体) ), [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjectmatches-cssarg)
-   `:matches-media(media query list)`数字 : [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjectmatches-mediaarg)
-   `:min-text-length(number)`数字 : [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjectmin-text-lengthn)
-   `:nth-ancestor(number)`数字 : [\[总干事参考\]](https://github.com/AdguardTeam/ExtendedCss#extended-css-nth-ancestor)
-   `:style(declaration list)`数字 : [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#subjectstylearg)
-   `:upward(selector list / number)`数字 : [\[总干事参考\]](https://github.com/AdguardTeam/ExtendedCss#extended-css-upward), (中文(简体) ), [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjectupwardarg)
-   `:xpath(raw)`数字 : [\[总干事参考\]](https://github.com/AdguardTeam/ExtendedCss#-pseudo-class-xpath), (中文(简体) ), [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjectxpatharg)

此外,CSSTree支持以下伪类 [默认](https://github.com/csstree/csstree/blob/master/lib/syntax/pseudo/index.js)数字 :

-   `:has(selector list)`数字 : [\[W3C参考\]](https://drafts.csswg.org/selectors-4/#has-pseudo), (中文(简体) ), [\[总干事参考\]](https://github.com/AdguardTeam/ExtendedCss#extended-css-has), (中文(简体) ), [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjecthasarg)
-   `:not(selector list)`数字 : [\[W3C参考\]](https://drafts.csswg.org/selectors-4/#negation-pseudo), (中文(简体) ), [\[总干事参考\]](https://github.com/AdguardTeam/ExtendedCss#extended-css-not), (中文(简体) ), [\[UBO参考\]](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters#subjectnotarg)
-   `:is(selector list)`数字 : [\[W3C参考\]](https://drafts.csswg.org/selectors-4/#is-pseudo), (中文(简体) ), [\[总干事参考\]](https://github.com/AdguardTeam/ExtendedCss#extended-css-is), (中文(简体) ), [\[UBO参考\]](https://github.com/AdguardTeam/ExtendedCss#extended-css-is)

另外, CSSTree 默认支持遗留扩展 CSS 元素( 属性选择器) : `[-ext-name="value"]`时 `name` 是扩展 CSS 元素的名称,并且 `value` 是它的价值. 例如,以下选择器可以通过 CSSTree 解析:

```css
[-ext-has="selector list"]
```

如果CSSTree不知道一个伪类,它试图将其描述为 `Raw` 元素 (如果可能 - 见 [有问题的案件](https://github.com/AdguardTeam/ecsstree#handle-problematic-cases)) (中文(简体) ).

CSSTree 库本身是相当灵活和耐错的, 因此,它基本上很好地管理了此处不包括的扩展CSS元素.

## 动机

例如,以下选择器

```css
div:-abp-has(> section)
```

将被默认 CSSTree 解析如下:

```json
{
    "type": "Selector",
    "loc": null,
    "children": [
        {
            "type": "PseudoClassSelector",
            "loc": null,
            "name": "-abp-has",
            "children": [
                {
                    "type": "Raw",
                    "loc": null,
                    "value": "> section"
                }
            ]
        }
    ]
}
```

问题在于 `-abp-has` 参数解析为 `Raw`,而不是作为一个 `Selector`, (中文(简体) ), 自此以来 `-abp-has` 是CSS / CSSTree 中的一个未知的伪类.

这就是ECSSTree图书馆开始运行的地方. 它发现 `-abp-has` 期望一个选择器作为参数, 即它将通过的参数解为 `Selector`。这意味着上面的选取者将被解析如下:

```json
{
    "type": "Selector",
    "loc": null,
    "children": [
        {
            "type": "PseudoClassSelector",
            "loc": null,
            "name": "-abp-has",
            "children": [
                {
                    "type": "Selector",
                    "loc": null,
                    "children": [
                        {
                            "type": "Combinator",
                            "loc": null,
                            "name": ">"
                        },
                        {
                            "type": "TypeSelector",
                            "loc": null,
                            "name": "section"
                        }
                    ]
                }
            ]
        }
    ]
}
```

`Combinator` 和相类似的节点是 CSSTree 的一部分,这个叉子只是指定 `-abp-has` 参数 应被解析为选择者。 节点本身是CSSTree的一部分.

### 高级验证

此外,这种方法还能够进行更先进的验证。 譬如说, 默认 CSSTree 在解析以下选择器时不会出错 :

```css
div:-abp-has(42)
```

因为它不知道什么 `-abp-has` 意思是,它只是将42描述为 `Raw`. ECSSTree 将参数解释为选择器, 它将丢出一个错误,因为42 只是一个无效的选择器.

## 处理有问题的案件

图书馆还处理有问题的选择者,例如:

```css
div:contains(aaa'bbb)
```

这个选择器并不完全符合CSS标准,所以即使CSSTree灵活, 它无法正确分析它,因为它将把它标出如下:

| 托肯类型 | 开始索引 | 结束索引 | 来源部分 |
| --- | --- | --- | --- |
| 缩写 | 0 个 | 3个 | 数字 |
| 结肠 | 3个 | 页:1 | 数字 : |
| 函数键 | 页:1 | 第13条 | 包含( c) |
| 缩写 | 第13条 | 16个 | 页:1 |
| 字符串键 | 16个 | 21国 | 'bbb' (英语) |

引号`'`) 符号化器会认为一个字符串正在开始,它将其余的输入作为字符串来表示. 这是普通的行为 对于象征性的, 但我们错了, 因为分析器会失败 `")" is expected` 错误,因为它没有找到收尾括号,因为它认为字符串仍然开着.

ECSSTree 将在解析过程中, 当解析器到达时, 通过一个特殊的重接算法来处理此例 这个问题 这样,ECSSTree的剖析器将能够正确剖析这个选择器. 这对 `xpath`。 。 。 .

_说明:_ ECSSTree 剖析 `:contains` 财务报告和审定财务报表 `:xpath` 参数为 `Raw`该图书馆的主要目标是改变 cSSTree的解析器的内部行为,使其能正确解析扩展CSS选择器, 不改变AST本身。 AST应该和CSSTree中一样,这样可以使用库 作为CSSTree的倒置替代. 分析 `:xpath` 详细表达式或正则表达式将是一项艰巨的任务,需要新的AST节点, 这将是一个突破性的变化。 但它总是解释 正确的原始表达给你, 如果你愿意,你可以自己分析/验证这些表达式。 有很多图书馆, 例如 [ưμ㼯a](https://www.npmjs.com/package/xpath) 或者说 [缩写](https://www.npmjs.com/package/regexpp)。 。 。 . 见 [示例代码](https://npmcn.com/examples) 更多细节.

## 实例

以下是一个非常简单的例子来说明如何使用ECSSTree:

```javascript
import { parse, generate, toPlainObject, fromPlainObject } from "@adguard/ecss-tree";
import { inspect } from "util";

// Some inputs to test
const inputs = [
    // Valid selectors
    `div:-abp-has(> .some-class > a[href^="https://example.com"])`,
    `body:style(padding-top: 0 !important;):matches-media((min-width: 500px) and (max-width: 1000px))`,
    `section:upward(2):contains(aaa'bbb):xpath(//*[contains(text(),"()(cc")])`,

    // Missing closing bracket at the end
    `div:-abp-has(> .some-class > a[href^="https://example.com"]`,
];

// Iterate over inputs
for (const input of inputs) {
    try {
        // Parse raw input to AST. This will throw an error if the input is not valid.
        // Don't forget to set context to 'selector', because CSSTree will try to parse
        // 'stylesheet' by default.
        const ast = parse(input, { context: "selector" });

        // By default, AST uses a doubly linked list. To convert it to plain object, you can
        // use toPlainObject() function.
        // If you want to convert AST back to doubly linked list version, you can use
        // fromPlainObject() function.
        const astPlain = toPlainObject(ast);
        const astAgain = fromPlainObject(astPlain);

        // Print AST to console
        console.log(inspect(astPlain, { colors: true, depth: null }));

        // You can also generate string from AST (don't use plain object here)
        console.log(generate(astAgain));
    } catch (e) {
        // Mark invalid selector
        console.log(`Invalid selector: ${input}`);

        // Show CSSTree's formatted error message
        console.log(e.formattedMessage);
    }
}
```

API与CSSTree中相同,因此您可以使用 [CSSTree 文档](https://github.com/csstree/csstree/tree/master/docs) 作为参考.

您可以在 [实例](https://npmcn.com/examples) 文件夹.

## 报告问题/请求特征

如果您找到错误或想要请求新功能, 请请 [打开一个问题](https://github.com/AdguardTeam/ecsstree/issues/new) (原始内容存档于2018-09-29). on GitHub. 请详细说明问题或你要求的特征,如有可能, 显示问题或特征的代码示例.

### 捐款

你可以通过打开拉出请求来为项目做出贡献. 向AdGuard项目捐款的人可以接受 各种奖励,见 [此页面](https://adguard.com/contribute.html) 详细情况.

### 发展

#### 先决条件

确保您安装了以下工具 :

1.  节点.js(建议使用最新的LTS版本)
2.  [小时](https://pnpm.io/)

#### 图标

开发期间,您可以使用以下命令(列于 `package.json`:

-   `pnpm lint` - 输入代码 [ESLint 语录](https://eslint.org/)
-   `pnpm test` - 与 [欢乐](https://jestjs.io/) (您也可以使用 `pnpm test <test-name>`(中文(简体) )
-   `pnpm build` - 把图书馆建到 `dist` 通过使用 [滚动](https://rollupjs.org/)

## 文档

-   [发展](https://npmcn.com/package/%40adguard/ecss-tree/DEVELOPMENT.md)
-   [部署](https://npmcn.com/package/%40adguard/ecss-tree/DEPLOYMENT.md)
-   [更改日志](https://npmcn.com/package/%40adguard/ecss-tree/CHANGELOG.md)
-   [LLM 代理规则](https://npmcn.com/package/%40adguard/ecss-tree/AGENTS.md)

## 许可证

这个图书馆根据麻省理工学院的许可证颁发执照. 见 [自由主义](https://github.com/AdguardTeam/ecsstree/blob/main/LICENSE) 需要更多信息的文件.

## 鸣谢

在本节中,我们要感谢下列人士所做的工作:

-   罗马·德沃尔诺夫(签名)[拉哈马蒂](https://github.com/lahmatiy)用于创建和维护 [CSSTree (英语)](https://github.com/csstree/csstree) 图书馆

## 参考资料

以下是更多关于扩展 CSS 选择器的有用链接 :

-   CSSTree 文档 : [https://github.com/csstree/csstree/tree/master/docs. 页面存档备份,存于互联网档案馆](https://github.com/csstree/csstree/tree/master/docs)
-   守护 _扩展CSS_数字 : [https://github.com/AdguardTeam/ExtendCs 互联网档案馆的存檔,存档日期2014-12-21](https://github.com/AdguardTeam/ExtendedCss)
-   uBlock 键 _"程序化妆品过滤器"_数字 : [https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters (中文(简体) )](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters)
-   附加障碍 _扩展CSS_数字 : [https://help.adblockplus.org/hc/en-us/articles/360062733293#elemhide-emulation (英语)](https://help.adblockplus.org/hc/en-us/articles/360062733293#elemhide-emulation)

## 常见问题

### @adguard/ecss-tree 是什么？

CSSTree 扩展 CSS 叉

### 如何安装 @adguard/ecss-tree？

在项目目录运行 npm install @adguard/ecss-tree，或使用 pnpm add / yarn add / bun add。

### @adguard/ecss-tree 支持 TypeScript 吗？

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

### @adguard/ecss-tree 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @adguard/ecss-tree 可以商用吗？

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

### @adguard/ecss-tree 的下载量有多少？

根据 npm 官方下载统计，@adguard/ecss-tree 在 2026/10/05 – 2026/11/03 这 30 天内被下载 7,596 次，日均约 253 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adguard/ecss-tree 还在维护吗？

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