# @adguard/css-tokenizer 中文文档

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

版本：1\.2\.0
npm 元数据更新时间：2026-08-19T10:43:18.364Z
中文译文更新时间：2026-11-05T22:25:57.148Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：190 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-10-30T16:59:57.167Z
- 最新版本发布：2025-02-03T15:28:16.439Z
- 近 30 天下载量：12501（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 0 个）

## 中文简介

CSS / 扩展 CSS 标识器

## 安装

```sh
npm install @adguard/css-tokenizer
```

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

## README

# CSS / 扩展 CSS 调试器

[![npm-badge](https://img.shields.io/npm/v/@adguard/css-tokenizer)](https://www.npmjs.com/package/@adguard/css-tokenizer) [![install-size-badge](https://packagephobia.com/badge?p=@adguard/css-tokenizer)](https://packagephobia.com/result?p=@adguard/css-tokenizer) [![license-badge](https://img.shields.io/npm/l/@adguard/css-tokenizer)](https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/css-tokenizer/LICENSE)

这个库提供了两种不同的 CSS 符号化器:

1.  **标准CSS 切换器**: 此标识符严格遵循 CSS 语法 3 规格, 由 : [W3C 战车](https://www.w3.org/TR/css-syntax-3/)。 。 。 .
2.  **扩展 CSS 调试器**: 设计以扩展标准示标器的能力,此组件引入 支持特殊伪类,例如 `:contains()` 财务报告和审定财务报表 `:xpath()`。 。 。 .

目录 :

-   [安装](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-installation)
-   [动机](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-motivation)
    -   [什么是扩展CSS?](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-what-is-extended-css)
    -   [为什么我们需要定制的装饰剂?](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-why-do-we-need-a-custom-tokenizer)
-   [解决方案: 自定义函数处理器](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-the-solution-custom-function-handlers)
    -   [没有新的符号类型](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-no-new-token-types)
-   [示例用途](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-example-usage)
-   [API 密码](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-api)
    -   [切换器函数](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-tokenizer-functions)
        -   [`tokenize`](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-tokenize)
        -   [`tokenizeExtended`](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-tokenizeextended)
    -   [公用事业](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-utilities)
        -   [`hasToken`](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-hastoken)
        -   [`TokenizerContext`](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-tokenizercontext)
        -   [`decodeIdent`](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-decodeident)
    -   [`CSS_TOKENIZER_VERSION`](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-css_tokenizer_version)
    -   [托肯类型](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-token-types)
        -   [`TokenType`](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-tokentype)
        -   [`getBaseTokenName`](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-getbasetokenname)
        -   [`getFormattedTokenName`](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-getformattedtokenname)
-   [基准结果](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-benchmark-results)
-   [想法和问题](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-ideas--questions)
-   [许可证](https://npmcn.com/package/%40adguard/css-tokenizer/#readme-license)

## 安装

您可以使用

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

## 动机

为了理解定制标志剂的必要性,必须理解扩展CSS的概念,认识到 并发现我们如何能够有效地解决这些问题.

### 什么是扩展CSS?

扩展CSS(英語:Extended CSS)是被阻塞器用来提供更强大的过滤能力的一款CSS的超级集. 实际上, 扩展CSS引入了CSS规格中没有定义的额外伪类. 有关更多信息, 请参考以下资源:

-   ![AdGuard logo](https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg) [守护者 : _扩展CSS能力_](https://github.com/AdguardTeam/ExtendedCss/blob/master/README.md)
-   ![uBlock Origin logo](https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg) [uBlock 来源 : _程序性化妆品过滤器_](https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters)
-   ![Adblock Plus logo](https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg) [附加障碍 : _扩展 CSS 选择器_](https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide-emulation)

### 为什么我们需要定制的装饰剂?

标准的 CSS 指示器无法处理扩展 CSS 的伪类 _在所有情况下_。例如 `:contains()` 伪类可以有下列语法:

```css
div:contains(i'm a parameter)
```

标准 CSS 标注器解释单引号(`'`)作为字符串分隔符,由于 缺乏结束 `)` 字符键。 这种偏离预期的语法导致解析问题.

这个 `:xpath()` 伪类对标准的 CSS 代号器构成类似的挑战,因为它可以有这样的语法:

```css
div:xpath(//*...)
```

标准标识符错误地识别 `/*` 序列作为注释的起始,导致不正确的解析, 不过 `/*` 顺序是 [XPath 表达式](https://developer.mozilla.org/en-US/docs/Web/XPath)。 。 。 .

## 解决方案: 自定义函数处理器

我们设计了标准的 CSS 指示器 来严格遵循 CSS 语法三级规格. 然而,我们 还引入了以自定义方式处理某些伪类的能力,类似于 `<url-token>` 实值 cSS 规格管理。 当标识器遇到函数符( 模式 : `function-name(`,它搜索一个 操作器函数在 `functionHandlers` 基于函数名的映射,如果自定义处理器存在,则使用它.

自定义处理器收到一个单一的参数: 共享指示器上下文对象,可用于管理 函数,类似于库中处理其他符号的方式.

这种方法使我们能够保持一个符合规格的本地CSS标识器,其管理费用最低,同时 以自定义的方式提供管理特殊伪类的灵活性.

从本质上讲,扩展 CSS 代码化器是标准 CSS 代码化器,具有特殊功能处理器 伪等相.

### 没有新的符号类型

必须强调,我们的执行仍然致力于CSS W3C规定的象征性类型 标准。 我们不推出新的标志类型,确保我们的标致器与官方CSS保持和谐 语法三级规格. 我们致力于遵守行业标准和最佳做法,这保证了我们 库与CSS相关的工具和工作流程保持相容性和一致性.

通过保留标准CSS标志类型,我们的目标是为用户提供可靠而无缝的经验,同时 与CSS合作,维护W3C定义的语言完整性.

## 示例用途

以下是一个如何使用图书馆的简单例子:

```js
// `tokenize` is a regular CSS tokenizer (and doesn't support Extended CSS)
// `tokenizeExtended` is an Extended CSS tokenizer
const { tokenize, tokenizeExtended, getFormattedTokenName } = require('@adguard/css-tokenizer');

// Input to tokenize
const CSS_SOURCE = `div:contains(aa'bb) { display: none !important; }`;

const COLUMNS = Object.freeze({
    TOKEN: 'Token',
    START: 'Start',
    END: 'End',
    FRAGMENT: 'Fragment'
});

// Prepare the data array
const data = [];

// Tokenize the input - feel free to try `tokenize` and `tokenizeExtended`
tokenizeExtended(CSS_SOURCE, (token, start, end) => {
    data.push({
        [COLUMNS.TOKEN]: getFormattedTokenName(token),
        [COLUMNS.START]: start,
        [COLUMNS.END]: end,
        [COLUMNS.FRAGMENT]: CSS_SOURCE.substring(start, end),
    });
});

// Print the tokenization result as a table
console.table(data, Object.values(COLUMNS));
```

## API 密码

### 切换器函数

#### `tokenize`

```ts
/**
 * CSS tokenizer function
 *
 * @param source Source code to tokenize
 * @param onToken Tokenizer callback which is called for each token found in source code
 * @param onError Error callback which is called when a parsing error is found (optional)
 * @param functionHandlers Custom function handlers (optional)
 */
function tokenize(
    source: string,
    onToken: OnTokenCallback,
    onError: OnErrorCallback = () => {},
    functionHandlers?: Map<number, TokenizerContextFunction>,
): void;
```

地点

```ts
/**
 * Callback which is called when a token is found
 *
 * @param type Token type
 * @param start Token start offset
 * @param end Token end offset
 * @param props Other token properties (if any)
 * @param stop Function to halt the tokenization process
 * @note Hash tokens have a type flag set to either "id" or "unrestricted". The type flag defaults to "unrestricted" if
 * not otherwise set
 */
type OnTokenCallback = (
    type: TokenType,
    start: number,
    end: number,
    props: Record<string, unknown> | undefined,
    stop: () => void
);
```

```ts
/**
 * Callback which is called when a parsing error is found. According to the spec, parsing errors are not fatal and
 * therefore the tokenizer is quite permissive, but if needed, the error callback can be used.
 *
 * @param message Error message
 * @param start Error start offset
 * @param end Error end offset
 * @see {@link https://www.w3.org/TR/css-syntax-3/#error-handling}
 */
type OnErrorCallback = (message: string, start: number, end: number) => void;
```

```ts
/**
 * Function handler
 *
 * @param context Reference to the tokenizer context instance
 * @param ...args Additional arguments (if any)
 */
type TokenizerContextFunction = (context: TokenizerContext, ...args: any[]) => void;
```

#### `tokenizeExtended`

`tokenizeExtended` 是扩展版本 `tokenize` 函数,用于支持自定义函数处理器。 这个 函数用于处理特殊伪类,如 `:contains()` 财务报告和审定财务报表 `:xpath()`。 。 。 .

```ts
/**
 * Extended CSS tokenizer function
 *
 * @param source Source code to tokenize
 * @param onToken Tokenizer callback which is called for each token found in source code
 * @param onError Error callback which is called when a parsing error is found (optional)
 * @param functionHandlers Custom function handlers (optional)
 * @note If you specify custom function handlers, they will be merged with the default function handlers. If you
 * duplicate a function handler, the custom one will be used instead of the default one, so you can override the default
 * function handlers this way, if you want to.
 */
function tokenizeExtended(
    source: string,
    onToken: OnTokenCallback,
    onError: OnErrorCallback = () => {},
    functionHandlers: Map<number, TokenizerContextFunction> = new Map(),
): void
```

### 公用事业

#### `hasToken`

```ts
/**
 * Checks if the given raw string contains any of the specified tokens.
 *
 * @param raw - The raw string to be tokenized and checked.
 * @param tokens - A set of token types to check for in the raw string.
 * @param tokenizer - The tokenizer function to use. Defaults to `tokenizeExtended`.
 *
 * @example hasToken('div:contains("foo")', new Set([TokenType.Function]), tokenizeExtended); // true
 *
 * @returns `true` if any of the specified tokens are found in the raw string, otherwise `false`.
 */
function hasToken = (
    raw: string,
    tokens: Set<TokenType>,
    tokenizer: TokenizerFunction = tokenizeExtended,
): boolean
```

#### `TokenizerContext`

代表标致上下文的类 。 用于管理标致器状态,并提供访问 源代码,当前位置等相关信息.

#### `decodeIdent`

```ts
/**
 * Decodes a CSS identifier according to the CSS Syntax Module Level 3 specification.
 *
 * @param ident CSS identifier to decode.
 *
 * @example
 * ```ts
 * decodeIdent(String.raw`\00075\00072\0006C`); // 'url'
 * decodeIdent('url'); // 'url'
 * ```
 *
 * @returns Decoded CSS identifier.
 */
function decodeIdent(ident: string): string;
```

### `CSS_TOKENIZER_VERSION`

```ts
/**
 * @adguard/css-tokenizer version
 */
const CSS_TOKENIZER_VERSION: string;
```

### 托肯类型

#### `TokenType`

描述器确认的标志类型. 它们严格基于CSS语法三级规格.

见 [https://www.w3.org/TR/css-syntax-3/#tokenization (中文(简体) )](https://www.w3.org/TR/css-syntax-3/#tokenization) 更多细节.

#### `getBaseTokenName`

```ts
/**
 * Get base token name by token type
 *
 * @param type Token type
 *
 * @example
 * ```ts
 * getBaseTokenName(TokenType.Ident); // 'ident'
 * getBaseTokenName(-1); // 'unknown'
 * ```
 *
 * @returns Base token name or 'unknown' if token type is unknown
 */
function getBaseTokenName(type: TokenType): string;
```

#### `getFormattedTokenName`

```ts
/**
 * Get formatted token name by token type
 *
 * @param type Token type
 *
 * @example
 * ```ts
 * getFormattedTokenName(TokenType.Ident); // '<ident-token>'
 * getFormattedTokenName(-1); // '<unknown-token>'
 * ```
 *
 * @returns Formatted token name or `'<unknown-token>'` if token type is unknown
 */
function getFormattedTokenName(type: TokenType): string;
```

> \[注\] 我们的API和令牌列表也符合 [CSSTree (英语)](https://github.com/csstree/csstree)从长远来看,我们 计划通过我们把这个图书馆并入CSSTree [ECSSTree 图书馆](https://github.com/AdguardTeam/ecsstree),参见 [这个问题](https://github.com/csstree/csstree/issues/253) 更多细节.

## 基准结果

您可以在 [基准/成果](https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/css-tokenizer/benchmark/RESULTS.md) 文档.

## 想法和问题

如果您有任何问题或想法 新的功能,请 [打开一个问题](https://github.com/AdguardTeam/tsurlfilter/issues/new) 或一个 [讨论情况](https://github.com/AdguardTeam/tsurlfilter/discussions)我们很乐意跟你讨论.

## 许可证

这个项目根据麻省理工学院的许可证获得许可。 见 [自由主义](https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/css-tokenizer/LICENSE) 详细文件.

## 常见问题

### @adguard/css-tokenizer 是什么？

CSS / 扩展 CSS 标识器

### 如何安装 @adguard/css-tokenizer？

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

### @adguard/css-tokenizer 支持 TypeScript 吗？

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

### @adguard/css-tokenizer 支持 ESM 还是 CommonJS？

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

### @adguard/css-tokenizer 可以商用吗？

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

### @adguard/css-tokenizer 的下载量有多少？

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

### @adguard/css-tokenizer 还在维护吗？

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