# @barkleapp/css-sanitizer 中文文档

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

版本：1\.0\.0
npm 元数据更新时间：2024-08-11T02:02:57.678Z
中文译文更新时间：2026-11-07T17:04:23.940Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：9.9 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2024-08-11T02:02:57.163Z
- 最新版本发布：2024-08-11T02:02:57.430Z
- 近 30 天下载量：25861（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

用于防止XSS攻击的 CSS 消毒器

## 安装

```sh
npm install @barkleapp/css-sanitizer
```

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

## README

# CSS 卫生剂

一种轻量级可配置的CSS消毒器,通过过滤出可能有害的CSS属性和值来防止XSS攻击.

## 安装

```bash
npm install @barkleapp/css-sanitizer
```

## 使用量

### 基本用途

```javascript
import { CssSanitizer } from 'css-sanitizer';

const sanitizer = new CssSanitizer();

const unsanitizedCss = `
  body {
    background: url('https://example.com/image.jpg');
    color: red;
  }
`;

const sanitizedCss = sanitizer.sanitizeCss(unsanitizedCss);
console.log(sanitizedCss);
```

### 自定义配置

您可以通过一个配置对象来自定义消毒器的行为 :

```javascript
const customSanitizer = new CssSanitizer({
  maxCssLength: 100000,
  allowedProperties: ['custom-property'],
  allowedAtRules: ['@custom-media'],
  allowedPseudoClasses: [':has'],
  validateUrl: (url) => {
    // Custom URL validation logic
    return url.startsWith('https://');
  },
  sanitizeUrl: (url) => {
    // Custom URL sanitization logic
    const allowedDomains = ['example.com', 'trusteddomain.com'];
    const parsedUrl = new URL(url);
    if (allowedDomains.includes(parsedUrl.hostname)) {
      return url;
    }
    return '';
  }
});
```

## API 密码

### `CssSanitizer`

进行CSS消毒的主要类.

#### 构造器

```javascript
new CssSanitizer(config)
```

-   `config` (可选) : 具有下列属性的对象:
    -   `maxCssLength` (数字): CSS字符串的最大允许长度.
    -   `allowedProperties` (Array):允许附加CSS属性.
    -   `allowedAtRules` 允许附加规则.
    -   `allowedPseudoClasses` (Array):允许附加的伪类.
    -   `validateUrl` (功能):自定义功能来验证 URL.
    -   `sanitizeUrl` (功能):自定义功能来消毒URL.

#### 方法

##### `sanitizeCss(css: string): string`

通过去除潜在的有害属性和值来对输入 CSS 字符串进行分级.

-   `css`: CSS字符串来消毒.
-   返回:已消毒的 CSS 字符串.

## 配置选项

### `maxCssLength` (违约:65536)

CSS 字符串的最大允许长度 。 如果输入的 CSS 超过此长度,则会被截取.

### `allowedProperties` (默认:参见代码)

一组允许的 CSS 属性 。 您可以通过提供构造器中的一系列附加属性来添加到此列表中 .

### `allowedAtRules` (默认: \['@media','@keyframes','@font-face','@import'\])

一套允许的规则。 您可以通过在构建器中提供一系列附加规则来添加到此列表中 .

### `allowedPseudoClasses` (默认:\[':hover','活性',':聚焦',':访问',':一胎',':最后一胎','nth-child','nth-th-fort','nth-fort','not',': before',':after'\])

一套允许的伪类. 您可以通过在构造器中提供一组额外的伪类来添加到此列表中.

### `validateUrl` (职务)

使用 URL 字符串并返回布尔表示 URL 是否有效的函数 。 默认情况下,它会检查字符串是否可以被解析为有效的URL.

### `sanitizeUrl` (职务)

如果不允许使用 URL, 则使用 URL 字符串并返回已静态 URL 字符串或空字符串的函数 。 默认情况下,它允许从'fonts.googleapis.com'获取URL.

## 许可证

麻省理工学院

## 常见问题

### @barkleapp/css-sanitizer 是什么？

用于防止XSS攻击的 CSS 消毒器

### 如何安装 @barkleapp/css-sanitizer？

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

### @barkleapp/css-sanitizer 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/barkleapp\_\_css-sanitizer 是否存在。

### @barkleapp/css-sanitizer 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @barkleapp/css-sanitizer 可以商用吗？

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

### @barkleapp/css-sanitizer 的下载量有多少？

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

### @barkleapp/css-sanitizer 还在维护吗？

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