# @bramus/specificity 中文文档

规范地址：https://npmcn.com/package/%40bramus/specificity/

版本：2\.4\.3
npm 元数据更新时间：2026-10-05T19:38:28.595Z
中文译文更新时间：2026-11-08T13:53:20.116Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bramus/specificity
原文对照：https://npmcn.com/package/%40bramus/specificity/?lang=original
项目主页：https://github.com/bramus/specificity#readme
源码仓库：https://github.com/bramus/specificity

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

- 包体积（解压后）：802 kB，16 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2022-02-23T11:07:27.859Z
- 最新版本发布：2026-10-05T19:38:28.330Z
- 近 30 天下载量：191698498（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 1 个）

## 中文简介

CSS 选择器的计算特性

## 安装

```sh
npm install @bramus/specificity
```

也可以使用：`pnpm add @bramus/specificity`、`yarn add @bramus/specificity`、`bun add @bramus/specificity`

## README

[![Calculate CSS Specificity](https://npmcn.com/package/%40bramus/specificity/screenshots/calculate-specificity.png)](https://codepen.io/bramus/pen/WNXyoYm)

# 具体性

`@bramus/specificity` 是计算 CSS 选择器特性的软件包。 它还包括一些方便功能来比较,排序和过滤一系列特异性值.

支助 [选择器等级 4](https://www.w3.org/TR/selectors-4/),包括那些特殊情况 `:is()`, (中文(简体) ), `:where()`, (中文(简体) ), `:not()`等 (中文(简体) ).

发音: [https://codepen.io/bramus/pen/WNXyoym 互联网档案馆的存檔,存档日期2013-12-02](https://codepen.io/bramus/pen/WNXyoYm)

## 安装

```bash
npm i @bramus/specificity
```

## 用法/ 实例

在其核心, `@bramus/specificity` 暴露一个 `Specificity` 课。 它的静态 `calculate` 用于计算给定 CSS 的特异性的方法 [选择列表](https://www.w3.org/TR/selectors-4/#grouping) 绳子.

```js
import Specificity from '@bramus/specificity';

const specificities = Specificity.calculate('header:where(#top) nav li:nth-child(2n), #doormat');
```

因为 `calculate` 接受一个 [选择列表](https://www.w3.org/TR/selectors-4/#grouping) ——可包含1个以上 [选择器](https://www.w3.org/TR/selectors-4/#selector) 它总是返回一个阵列,每个条目都是一个 `Specificity` 实例——每个找到的选择器一个.

```js
const specificities = Specificity.calculate('header:where(#top) nav li:nth-child(2n), #doormat');
specificities.map((s) => s.toString()); // ~> ["(0,1,3)","(1,0,0)"]
```

如果您知道您只经过一个选择器 `calculate()`,您可以使用 JavaScript 的内置解结构来保持您变量名称的清洁 .

```js
const [s] = Specificity.calculate('header:where(#top) nav li:nth-child(2n)');
s.toString(); // ~> "(0,1,3)"
```

在引擎盖下, `@bramus/specificity` 用途 [CSSTree (英语)](https://github.com/csstree/csstree) 来解析选择者的字符串。 因此 `calculate` 方法也接受一个 [CSSTree AST (英语)](https://github.com/csstree/csstree/blob/master/docs/ast.md) 类型 `Selector` 财务报告和审定财务报表 `SelectorList`。 。 。 .

如果您拥有该类型预分的 CSSTree AST `Selector` 可以传入 `Specificity.calculateForAST()`。 [表现稍好](https://npmcn.com/package/%40bramus/specificity/#readme-benchmark) 比起来 `Specificity.calculate()` 因为它需要检查更少的东西。 这和 `Specificity.calculate()` 它不返回一系列 `Specificity` 实例,但只有一个值.

## 返回格式

计算出的特异性作为实例说明 `Specificity` 课。 这个 `Specificity` 类包括以某种格式获得特异性值的方法,以及一些将特异性值与其他实例进行比较的方便方法.

```js
// 🚀 Thunderbirds are go!
import Specificity from '@bramus/specificity';

// ✨ Calculate specificity for each Selector in the given Selector List
const specificities = Specificity.calculate('header:where(#top) nav li:nth-child(2n), #doormat');

// 🚚 The values in the array are instances of the Specificity class
const s = specificities[0]; // Instance of Specificity

// 👀 Read the specificity value using one of its accessors
s.value; // { a: 0, b: 1, c: 3 }
s.a; // 0
s.b; // 1
s.c; // 3

// 🛠 Convert the calculated value to various formats using one of the toXXX() instance methods
s.toString(); // "(0,1,3)"
s.toArray(); // [0, 1, 3]
s.toObject(); // { a: 0, b: 1, c: 3 }

// 💡 Extract the matched selector string
s.selectorString(); // "header:where(#top) nav li:nth-child(2n)"

// 🔀 Use one of its instance comparison methods to compare it to another Specificity instance
s.isEqualTo(specificities[1]); // false
s.isGreaterThan(specificities[1]); // false
s.isLessThan(specificities[1]); // true

// 💻 Don’t worry about JSON.stringify()
JSON.stringify(s);
// {
//    "selector": 'header:where(#top) nav li:nth-child(2n)',
//    "asObject": { "a": 0, "b": 1, "c": 3 },
//    "asArray": [0, 1, 3],
//    "asString": "(0,1,3)",
// }
```

## 功用函数(稳态方法)

这个软件包还暴露出一些根据具体情况开展工作的实用功能. 这些公用功能都作为静态方法在 `Specificity` 课.

-   比较:
    
    -   `Specificity.compare(s1, s2)`: 将 s1 与 s2. 返回一个值,可以是:
        -   `> 0` = 在 s1 之前排序 s2 _(即s1比s2更具体)_
        -   `0` = 保持S1和S2的原始顺序 _(即s1和s2同样具体)_
        -   `< 0` = 在 s2 之前排序 s1 _(即 s1 不如 s2 )_
    -   `Specificity.equals(s1, s2)`: 回归 `true` 如果S1和S2具有相同的特性。 如果没有, `false` 已返回.
    -   `Specificity.greaterThan(s1, s2)`: 回归 `true` 如果 s1 的特异性高于 s2 。 如果没有, `false` 已返回.
    -   `Specificity.lessThan(s1, s2)`: 回归 `true` 如果 s1 的特异性低于 s2. 如果没有, `false` 已返回.
-   排序 :
    
    -   `Specificity.sortAsc(s1, s2, …, sN)`: 按升序排序给定的特性 _(低特异性到高特异性)_
    -   `Specificity.sortDesc(s1, s2, …, sN)`: 将给定的特性按下行顺序排序 _(高度特异性与低特异性)_
-   过滤 :
    
    -   `Specificity.min(s1, s2, …, sN)`: 筛选出特性最低的值
    -   `Specificity.max(s1, s2, …, sN)`: 以最特殊性过滤出值

在其中任何一种公用事业职能中,可以采用以下任何一种特性:

-   包括的事例 `Specificity` 类
-   简单对象, 如 `{'a': 1, 'b': 0, 'c': 2}`

## 工具函数( 单独)

所有静态方法 `Specificity` 类曝光也被导出为独立函数 [子路径导出](https://nodejs.org/api/packages.html#subpath-exports)。 。 。 .

如果你只有兴趣将这些功能纳入您的项目, 你可以从他们的子路径导入它们。 因此,你的捆绑尺寸会大大缩小 _(不包括单独的 `calculate`,当它返回一系列 `Specificity` 依赖整个批量的示例)_

```js
import { calculate, calculateForAST } from '@bramus/specificity/core';
import { compare, equals, greaterThan, lessThan } from '@bramus/specificity/compare';
import { min, max } from '@bramus/specificity/filter';
import { sortAsc, sortDesc } from '@bramus/specificity/sort';
```

## 类型定义

虽然 `@bramus/specificity` 以 Vanilla JavaScript 写成,它确实包括 [类型定义](https://www.typescriptlang.org/docs/handbook/2/type-declarations.html) 暴露于其 `package.json`。 。 。 .

## 二进制/CLI

`@bramus/specificity` 曝光二进制名称 `specificity` 用于计算CLI中特定选择器列表的特异性。 对于每一个它找到的选取者,它将打印出计算出来的特异性,作为新行上的字符串.

```bash
$ specificity "header:where(#top) nav li:nth-child(2n), #doormat"
(0,1,3)
(1,0,0)
```

## 基准

包含一个基准,您可以引用 `npm run benchmark`。 。 。 .

样本结果(在MacBook Air M3上测试):

```
Specificity.calculate(string) x 420,682 ops/sec ±0.34% (98 runs sampled)
Specificity.calculate(ast) - using SelectorList x 8,994,080 ops/sec ±0.25% (98 runs sampled)
Specificity.calculate(ast) - using Selector x 11,054,856 ops/sec ±0.39% (91 runs sampled)
Specificity.calculateForAST(ast) x 12,652,322 ops/sec ±0.35% (96 runs sampled)
```

## 许可证

`@bramus/specificity` 以麻省理工学院公共许可证发放。 见附件 `LICENSE` 详细情况.

## 鸣谢

创建此软件包的想法是由 [由 Kilian Valkhof / Polypane 创建的美妙特性计算器](https://polypane.app/css-specificity-calculator/),一个高度教育性的工具,它不仅计算特异性,还解释了哪些部分对此负责.

对选择者进行实际分析的举重方式是: [CSSTree (英语)](https://github.com/csstree/csstree)。 。 。 .

## 常见问题

### @bramus/specificity 是什么？

CSS 选择器的计算特性

### 如何安装 @bramus/specificity？

在项目目录运行 npm install @bramus/specificity，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 specificity，可以用 npx specificity 直接运行。

### @bramus/specificity 支持 TypeScript 吗？

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

### @bramus/specificity 支持 ESM 还是 CommonJS？

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

### @bramus/specificity 可以商用吗？

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

### @bramus/specificity 的下载量有多少？

根据 npm 官方下载统计，@bramus/specificity 在 2026/10/09 – 2026/11/07 这 30 天内被下载 191,698,498 次，日均约 6,389,950 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bramus/specificity 还在维护吗？

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