# @adguard/scriptlets 中文文档

规范地址：https://npmcn.com/package/%40adguard/scriptlets/

版本：2\.5\.1
npm 元数据更新时间：2026-08-25T02:51:08.751Z
中文译文更新时间：2026-11-06T00:39:49.916Z
软件包许可：GPL-3\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40adguard/scriptlets
原文对照：https://npmcn.com/package/%40adguard/scriptlets/?lang=original
项目主页：https://github.com/AdguardTeam/Scriptlets#adguard-scriptlets-and-redirect-resources
源码仓库：https://github.com/AdguardTeam/Scriptlets

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

- 包体积（解压后）：2.1 MB，66 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2021-07-01T10:33:56.289Z
- 最新版本发布：2026-08-25T02:51:08.602Z
- 近 30 天下载量：8111（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：95（近 12 个月 14 个）

## 中文简介

AdGuard 的 JavaScript 脚本和重定向资源库

## 安装

```sh
npm install @adguard/scriptlets
```

也可以使用：`pnpm add @adguard/scriptlets`、`yarn add @adguard/scriptlets`、`bun add @adguard/scriptlets`

## README

# 守护脚本和重定向资源

AdGuard的脚本和再定向资源库提供了内容阻塞的扩展能力.

> **说明:** 此软件包开发于 [辅助软件Limited/ext-scripletes](https://github.com/AdGuardSoftwareLimited/ext-scriptlets)。 。 。 . 这个 [守护小组/脚本](https://github.com/AdguardTeam/Scriptlets) 寄存器是一个公共镜像.

-   [脚本](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets)
    -   [语法](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlet-syntax)
        -   [封锁规则](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlet-syntax--blocking)
        -   [例外规则](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlet-syntax--exceptions)
    -   [可用的脚本](https://npmcn.com/package/%40adguard/scriptlets/wiki/about-scriptlets.md#scriptlets)
    -   [脚本兼容表](https://npmcn.com/package/%40adguard/scriptlets/wiki/compatibility-table.md#scriptlets)
    -   [信任的脚本](https://npmcn.com/package/%40adguard/scriptlets/#readme-trusted-scriptlets)
        -   [限制](https://npmcn.com/package/%40adguard/scriptlets/#readme-trusted-scriptlets-restriction)
        -   [可用的可信任脚本](https://npmcn.com/package/%40adguard/scriptlets/wiki/about-trusted-scriptlets.md#trusted-scriptlets)
-   [重新定向资源](https://npmcn.com/package/%40adguard/scriptlets/#readme-redirect-resources)
    -   [语法](https://npmcn.com/package/%40adguard/scriptlets/#readme-redirect-syntax)
    -   [现有改用资源](https://npmcn.com/package/%40adguard/scriptlets/wiki/about-redirects.md#redirect-resources)
    -   [重定向资源兼容表](https://npmcn.com/package/%40adguard/scriptlets/wiki/compatibility-table.md#redirects)
-   [发展](https://npmcn.com/package/%40adguard/scriptlets/#readme-development)
    -   [如何建设](https://npmcn.com/package/%40adguard/scriptlets/#readme-how-to-build)
    -   [如何测试](https://npmcn.com/package/%40adguard/scriptlets/#readme-how-to-test)
    -   [如何链接软件包](https://npmcn.com/package/%40adguard/scriptlets/#readme-how-to-link-packages)
    -   [如何更新wiki](https://npmcn.com/package/%40adguard/scriptlets/#readme-how-to-update-wiki)
-   [使用量](https://npmcn.com/package/%40adguard/scriptlets/#readme-usage)
    -   [核心文件夹](https://npmcn.com/package/%40adguard/scriptlets/#readme-corelibs)
    -   [国家预防机制模块](https://npmcn.com/package/%40adguard/scriptlets/#readme-npm-module)
-   [API 描述](https://npmcn.com/package/%40adguard/scriptlets/#readme-api-description)
    -   [脚本 API](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets-api)
        -   [`invoke()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets-api--invoke)
        -   [`getScriptletFunction()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets-api--getScriptletFunction)
        -   [属性](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets-api-properties)
            -   [`SCRIPTLETS_VERSION`](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets-api--version)
        -   [`ContentScriptApi`](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets-api--content-script-api)
            -   [`PolicyApi`](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets-api--content-script-api--policy-api)
    -   [重定向 API](https://npmcn.com/package/%40adguard/scriptlets/#readme-redirects-api)
        -   [重定向类](https://npmcn.com/package/%40adguard/scriptlets/#readme-redirects-api--redirects-class)
        -   [`getRedirect()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-redirects-api--getRedirect)
        -   [`isBlocking()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-redirects-api--isBlocking)
        -   [`getRedirectFilename()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-redirects-api--getRedirectFilename)
    -   [验证器 API](https://npmcn.com/package/%40adguard/scriptlets/#readme-validators-api)
        
        -   [`isValidScriptletName()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-validators-api--isValidScriptletName)
        -   [`isValidScriptletRule()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-validators-api--isValidScriptletRule)
        
        -   [`isAdgScriptletRule()`, (中文(简体) ), `isUboScriptletRule()`, (中文(简体) ), `isAbpSnippetRule()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets-api--is-Abg-Ubo-Abp-ScriptletRule)
        -   [`isValidAdgRedirectRule()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-redirects-api--isValidAdgRedirectRule)
        -   [`isRedirectResourceCompatibleWithAdg()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-redirects-api--isRedirectResourceCompatibleWithAdg)
    -   [转换器 API](https://npmcn.com/package/%40adguard/scriptlets/#readme-converters-api)
        -   [`convertUboToAdg()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-converters-api--convertUboToAdg)
        -   [`convertAbpToAdg()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-converters-api--convertAbpToAdg)
        -   [`convertScriptletToAdg()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-converters-api--convertScriptletToAdg)
        -   [`convertAdgToUbo()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-converters-api--convertAdgToUbo)
        -   [`convertAdgRedirectToUbo()`](https://npmcn.com/package/%40adguard/scriptlets/#readme-converters-api--convertAdgRedirectToUbo)
-   [浏览器兼容性](https://npmcn.com/package/%40adguard/scriptlets/#readme-browser-compatibility)
-   [使用脚本的项目](https://npmcn.com/package/%40adguard/scriptlets/#readme-used-by)

* * *

## 脚本

Scriptlet是一种JavaScript函数,可以在AdGuard过滤规则中以声明方式使用.

AdGuard支持许多不同的脚本. 请注意,为了实现交叉阻塞相容性,我们也支持uBO和ABP的语法.

### 语法

#### 封锁规则

```text
[domains]#%#//scriptlet(name[, arguments])
```

-   `domains` - 可选,应适用该规则的领域清单;
-   `name` 需要,AdGuard脚本库的脚本名称;
-   `arguments` ——可选,列表 `string` 参数(不支持其他类型的参数).

> **备注**
> 
> -   论据的意义取决于脚本.
>     
> -   脚本参数中的特殊字符必须适当逃脱:
>     
>     -   无效 :
>         -   `'prop["nested"]'`
>         -   `"prop['nested']"`
>         -   `'prop[\'nested\']'`
>         -   `"prop[\"nested\"]"`
>     -   无效 :
>         -   `'prop['nested']'`
>         -   `"prop["nested"]"`
> -   脚本 `name` 和每个 `arguments` 应该用引号包起来. 您可以为脚本名称和参数使用单引出或双引出. 建议采用单一引文,但如果使用该引文会使可读性更差,则不予采用, 譬如说. `".css('display','block');"` 比较喜欢 `'.css(\'display\',\'block\');'`。 。 。 .
>     

#### 例外规则

```text
[domains]#@%#//scriptlet([name[, arguments]])
```

-   `domains` - 可选,应适用该规则的领域清单;
-   `name` - 可选的,除申请外的脚本名称; 如果不设定,则不会应用全部脚本;
-   `arguments` ——可选,列表 `string` 参数来匹配相同的阻塞规则并禁用它.

#### 实例

1.  应用 `abort-on-property-read` 所有页面的脚本 `example.org` 及其子域, 并传递一个论据`alert`:
    
    ```adblock
    example.org#%#//scriptlet('abort-on-property-read', 'alert')
    ```
    
2.  删除 `branding` 从所有类别 `div[class^="inner"]` 要素 在所有页面上 `example.org` 及其子域 :
    
    ```adblock
    example.org#%#//scriptlet('remove-class', 'branding', 'div[class^="inner"]')
    ```
    
3.  应用 `set-constant` 财务报告和审定财务报表 `set-cookie` 在任何网页上, 但因为特定的脚本例外规则 仅限 `set-constant` 脚本将应用在 `example.org` 及其子域 :
    
    ```adblock
    #%#//scriptlet('set-constant', 'adList', 'emptyArr')
    #%#//scriptlet('set-cookie', 'accepted', 'true')
    example.org#@%#//scriptlet('set-cookie')
    ```
    
4.  应用 `adjust-setInterval` 在任何网页上, 财务报告和审定财务报表 `set-local-storage-item` 在所有页面上 `example.com` 及其子域, 但也有多个脚本例外规则, 因此不应用脚本规则 `example.com` 及其子域 :
    
    ```adblock
    #%#//scriptlet('adjust-setInterval', 'count', '*', '0.001')
    example.com#%#//scriptlet('set-local-storage-item', 'ALLOW_COOKIES', 'false')
    example.com#@%#//scriptlet()
    ```
    

#### 限制

允许的脚本来源有:

1.  由AdGuard 团队创建的过滤器;
2.  自定义已安装为 `Trusted`· ;
3.  用户规则.

-   **[脚本列表](https://npmcn.com/package/%40adguard/scriptlets/wiki/about-scriptlets.md#scriptlets)**
-   **[脚本兼容表](https://npmcn.com/package/%40adguard/scriptlets/wiki/compatibility-table.md#scriptlets)**

### 信任的脚本

信任的脚本是具有扩展功能的脚本. 他们的名字前缀为 `trusted-`,例如 `trusted-click-element`, (中文(简体) ), 很容易与普通脚本区分开来.

#### 限制

信任的脚本无法与其它阻塞器兼容 .

**[信任的脚本列表](https://npmcn.com/package/%40adguard/scriptlets/wiki/about-trusted-scriptlets.md#trusted-scriptlets)**

## 重新定向资源

AdGuard能够将网络请求重定向到本地的"资源".

### 语法

AdGuard 使用的过滤规则语法与 [uBlock 来源](https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#redirect)。 。 。 . 另外,它与ABP兼容 `$rewrite=abp-resource` 修饰相.

`$redirect` 是用于修改 [基本过滤规则](https://adguard.com/kb/general/ad-filtering/create-own-filters/#basic-rules) 因此,使用这个修改符的规则支持所有其他基本修改符,例如: `$domain`, (中文(简体) ), `$third-party`, (中文(简体) ), `$script`等 (中文(简体) ).

其价值 `$redirect` 修改符必须是用于重定向的资源的名称. 见 [资源](https://npmcn.com/package/%40adguard/scriptlets/wiki/about-redirects.md#redirect-resources)。 。 。 .

> 优先权 `$redirect` 规则在 [知识库](https://adguard.com/kb/general/ad-filtering/create-own-filters/#redirect-rule-priorities)。 。 。 .

### 实例

-   `||example.org/script.js$script,redirect=noopjs` ——将所有请求重定向到 `script.js` 转到命名的资源 `noopjs`。 。 。 .
-   `||example.org/test.mp4$media,redirect=noopmp4-1s` - 要求 `example.org/test.mp4` 将重新定向 转到命名的资源 `noopmp4-1s`。 。 。 .

> uBlock 来源指定了额外的资源名称 `none` 可以禁用其他重定向规则. AdGuard 不支持, 使用 `$badfilter` 以禁用特定规则.

-   **[重新定向资源列表](https://npmcn.com/package/%40adguard/scriptlets/wiki/about-redirects.md#redirect-resources)**
-   **[重定向资源兼容表](https://npmcn.com/package/%40adguard/scriptlets/wiki/compatibility-table.md#redirects)**

* * *

## 发展

### 如何建设

安装依赖性 :

```bash
pnpm install
```

构建 :

```bash
pnpm build
```

在tsurlfilter目录安装和链接依赖,链接脚本, 移动到软件包并构建,并创建tsurlfilter链接.

```bash
lerna bootstrap

pnpm link --global "@adguard/scriptlets"

cd ./packages/tsurlfilter

pnpm build

pnpm link --global
```

在扩展目录中安装依赖性、链接软件包并构建

```bash
pnpm install

pnpm link --global "@adguard/scriptlets"

# run build script
```

### 如何测试

有些测试在QUnit进行,有些在Vitest进行.

运行所有测试 :

```bash
pnpm test
```

1.  QUnit用于测试脚本、重定向和助手:
    
    ```text
    pnpm test:qunit [scriptlets | redirects | helpers]
    ```
    
    对于脚本和重定向测试运行可以更具体:
    
    ```bash
    // node test run
    pnpm test:qunit scriptlets --name set-cookie
    pnpm test:qunit redirects --name ati-smarttag
    
    // gui test run
    pnpm test:qunit scriptlets --name set-cookie --gui
    pnpm test:qunit redirects --name ati-smarttag --gui
    ```
    
    为了在Gui模式下进行测试后调试, 您可以更改脚本/ 重定向代码, 而不停止服务器 在新终端运行 :
    
    ```bash
    pnpm test:qunit scriptlets --name set-cookie --build
    ```
    
2.  运行所有滑稽测试 :
    
    ```bash
    pnpm test:vitest
    ```
    
    或限制试验—— `include` 可在 `vitest.config.ts` 或指定 [测试名称](https://vitest.dev/guide/filtering#cli) 在命令行中,例如:
    
    ```bash
    pnpm test:vitest -t isValidScriptletRule
    ```
    

运行测试 `jest` 应当命名 `.spec.js`,因此它们不会被列入 `QUnit` 测试.

#### 调试

使用 `debugger;` 需要时,请运行

```bash
pnpm test
```

打开所需的 HTML 文件 `tests/dist` 在您的浏览器中, 带有devtools

### 如何链接软件包

脚本库依赖于外部软件包,例如 `@adguard/agtree`。 。 。 . 在开发过程中,您可能需要使用 `pnpm link`。 。 。 .

### 如何更新wiki

维基文库中相关的原始文献: 有2个要更新的脚本:

1.  `pnpm wiki:build-table` ——检查相容性数据更新并更新相容性表. 在准备发行时应该手动运行.
2.  `pnpm wiki:build-docs` ——更新维基页面 `about-scriptlets.md` 财务报告和审定财务报表 `about-redirects.md`。 。 。 . 正在从 JSDoc 类型对相应脚本的注释生成,并重定向源文件 应付 `@scriptlet`编号 :`@redirect` 财务报告和审定财务报表 `@description` 标签。 发行时自动运行.

## 使用量

### 核心文件夹

对于 [核心文件夹](https://github.com/AdguardTeam/CoreLibs) 您应该使用 `dist/scriptlets.corelibs.json` 财务报告和审定财务报表 `dist/redirects.json`。 。 。 .

文件示例 :

```json
{
    "version": "1.0.0",
    "scriptlets": [
        {
            "names": [
                "abort-on-property-read",
                "ubo-abort-on-property-read.js",
                "abp-abort-on-property-read"
            ],
            "scriptlet": "function() { ...code... }"
        }
    ]
}
```

司马:

```json
{
    "type": "object",
    "properties": {
        "version": {
            "type": "string"
        },
        "scriptlets": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "names": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "scriptlet": {
                        "type": "string"
                    }
                }
            }
        }
    }
}
```

### 国家预防机制模块

#### 安装

您可以使用

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

## API 描述

### 脚本 API

欢迎您使用脚本作为CJS模块或无害环境管理模块:

```typescript
const { scriptlets } = require('@adguard/scriptlets');
// or
import { scriptlets } from '@adguard/scriptlets';
```

#### `invoke()`

```typescript
/**
 * Returns scriptlet code by `source`.
 *
 * @param source Scriptlet properties.
 *
 * @returns Scriptlet code.
 * @throws An error on unknown scriptlet name.
 */
declare function getScriptletCode(source: Source): string;
declare const scriptlets: {
    invoke: typeof getScriptletCode;
};
```

地点 `Source` 为:

```typescript
interface Source {
    /**
     * Scriptlet name
     */
    name: string;
    /**
     * Arguments for scriptlet function
     */
    args: string[];
    /**
     * {'extension'|'corelibs'} engine Defines the final form of scriptlet string presentation
     */
    engine: string;
    /**
     * Version
     */
    version: string;
    /**
     * flag to enable printing to console debug information
     */
    verbose: boolean;
    /**
     * Source rule text is used for debugging purposes.
     *
     * @deprecated since it is not used in the code anymore.
     */
    ruleText?: string;
    /**
     * Domain name, used to improve logging
     */
    domainName?: string;
    /**
     * Optional unique identifier for a scriptlet instance.
     *
     * This identifier is used to prevent multiple executions of the same scriptlet on the page.
     * If provided, this `uniqueId` will be combined with the scriptlet's `name` and `args`
     * to create a unique identifier for the scriptlet call. This identifier is
     * stored in the `Window.prototype.toString` object to ensure the scriptlet
     * is not executed more than once in the same context.
     *
     * By avoiding multiple executions, it helps in reducing redundant operations and
     * potential side effects that might occur if the same scriptlet is called multiple times.
     *
     * If `uniqueId` is not specified, no such unique identifier is created, and the
     * scriptlet can be called multiple times.
     */
    uniqueId?: string;
    /**
     * Instance of content script provided API.
     *
     * Property optional because:
     * - for backwards compatibility.
     * - currently only CoreLibs provides this API.
     */
    api?: ContentScriptApi;
}
```

另见 [`ContentScriptApi`](https://npmcn.com/package/%40adguard/scriptlets/#readme-scriptlets-api--content-script-api) 更多细节.

#### `getScriptletFunction()`

```typescript
/**
 * Returns scriptlet function by `name`.
 *
 * @param {string} name Scriptlet name
 *
 * @returns {Function} — Scriptlet function.
 */
declare function getScriptletFunction(name: any): string;
declare const scriptlets: {
    getScriptletFunction: typeof getScriptletFunction;
};
```

#### 属性

##### `SCRIPTLETS_VERSION`

类型 : `string`

当前版本的脚本库.

#### `ContentScriptApi`

API 提供 [核心文件夹](https://github.com/AdguardTeam/CoreLibs) 内容脚本.

此 API 用于为脚本提供一套公用设施和共享状态 在网页上运行。 它特别包括:

```typescript
export interface ContentScriptApi {
    /**
     * Trusted Types Policy API utilities.
     */
    readonly policy: PolicyApi;

    /**
     * Shared state between different script and scriptlet rules.
     *
     * This object acts as a centralized repository for shared data.
     * - Keys represent the unique identifiers or names of the shared data.
     * - Values can be of any type and should correspond to the specific data shared across script rules.
     *
     * Example:.
     * ```adguard
     * ! Modify in one script rule
     * #%#api.shared.testKey = 'testValue'
     *
     * ! Access in another (logs 'testValue')
     * #%#console.log(api.shared.testKey)
     * ```
     */
    readonly shared: Record<string, unknown>;
}
```

##### `PolicyApi`

信任类型 API 工具 .

此界面扩展本地 `TrustedTypePolicy` 财务报告和审定财务报表 `TrustedTypePolicyFactory` 提供更方便用户的API,用于与信任类型合作。 如果出现 环境不支持信任类型 API, 它提供了多填充方法 和属性以确保兼容性.

```typescript
export interface PolicyApi extends TrustedTypePolicy, TrustedTypePolicyFactory {
    /**
     * Is Trusted Types API supported.
     */
    isSupported: boolean;

    /**
     * TrustedType enum attached to PolicyApi.
     *
     * Reason why we attach it to instance because inside
     * of script and scriptlet we can't import and to not
     * pollute global env with custom variables.
     *
     * @example
     * api.policy.TrustedType.HTML // "TrustedHTML"
     */
    TrustedType: typeof TrustedType;

    /**
     * Creates Trusted Type depending on `type`:
     * - `TrustedHTML`
     * - `TrustedScript`
     * - `TrustedScriptURL`
     * - or returns back `input` if none of them applicable.
     *
     * @example
     * divElement.innerHTML = api.policy.create(api.policy.TrustedType.HTML, '<div></div>');
     *
     * @param type Trusted Type.
     * @param input Input from which creates Trusted Type.
     * @returns Created value.
     */
    create(type: TrustedType, input: string): string;

    /**
     * Converts `value` of `attribute` into one of the Trusted Types:
     * - `TrustedHTML`
     * - `TrustedScript`
     * - `TrustedScriptURL`
     * - or returns back `value` if none of them applicable (`null`).
     *
     * @example
     * const trustedScriptURL = api.policy.convertAttributeToTrusted("script", "src", 'SOME_URL');
     * scriptElement.setAttribute("src", trustedScriptURL);
     *
     * @param tagName Name of an HTML tag.
     * @param attribute Attribute.
     * @param value Value of attribute that needs to be converted.
     * @param elementNS Element namespace, if empty defaults to the HTML namespace.
     * @param attrNS Attribute namespace, if empty defaults to null.
     * @returns Converted value.
     */
    convertAttributeToTrusted(
        tagName: string,
        attribute: string,
        value: string,
        elementNS?: string,
        attrNS?: string,
    ): string;

    /**
     * Converts `value` of `property` into one of the Trusted Types:
     * - `TrustedHTML`
     * - `TrustedScript`
     * - `TrustedScriptURL`
     * - or returns back `value` if none of them applicable (`null`).
     *
     * @example
     * divElement.innerHTML = api.policy.convertPropertyToTrusted("div", "innerHTML", "<div></div>");
     *
     * @param tagName Name of an HTML tag.
     * @param property Property.
     * @param value Value or property.
     * @param elementNS Element namespace, if empty defaults to the HTML namespace.
     * @returns Converted value.
     */
    convertPropertyToTrusted(
        tagName: string,
        property: string,
        value: string,
        elementNS?: string,
    ): string;
}
```

-   [信任的类型政策](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy) 接口
-   [信任的Type 政策事实](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory) 接口

### 重定向 API

欢迎您使用重定向器作为CJS模块或无害环境管理模块:

```javascript
const { Redirects } = require('@adguard/scriptlets/redirects');
// or
import { Redirects, getRedirectFilename } from '@adguard/scriptlets/redirects';
```

#### 重定向类

```typescript
import { Redirects } from '@adguard/scriptlets';

/**
 * Converts rawYaml into JS object with sources titles used as keys
 */
const redirects = new Redirects(rawYaml)
```

地点 `rawYaml` 有 YAML 内容的字符串位于 `dist/redirects.yml`。 。 。 .

#### `getRedirect()`

```typescript
/**
 * Returns redirect source object by title
 */
const redirect = redirects.getRedirect('noopjs');

/**
 * Redirect is an object with following props:
 * {
 *     title: 1x1-transparent.gif
 *     comment: http://probablyprogramming.com/2009/03/15/the-tiniest-gif-ever
 *     contentType: image/gif;base64
 *     content: R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==
 * }
 */
```

#### `isBlocking()`

```typescript
/**
 * Check if redirect is blocking, e.g. click2load.html
 */
const isBlocking = redirect.isBlocking('click2load.html');
```

#### `getRedirectFilename()`

```typescript
import { getRedirectFilename } from '@adguard/scriptlets/redirects';
/**
 * For a given name or alias of redirect returns the corresponding filename
 * @param name Name or alias of redirect
 * @returns Redirect's filename with extension
 */
declare function getRedirectFilename(name: string): string;
```

### 验证器 API

#### `isValidScriptletName()`

```typescript
import { isValidScriptletName } from '@adguard/scriptlets/validators';

/**
 * Checks whether the `name` is valid scriptlet name.
 * Uses cache for better performance.
 *
 * @param name Scriptlet name.
 * @returns True if scriptlet name is a valid one or an empty string,
 * otherwise false.
 */
declare function isValidScriptletName(name: string | null): boolean;
```

#### `isValidScriptletRule()`

```typescript
/**
 * 1. For ADG scriptlet checks whether the scriptlet syntax and name are valid.
 * 2. For UBO and ABP scriptlet first checks their compatibility with ADG
 * by converting them into ADG syntax, and after that checks the name.
 *
 * ADG or UBO rules are "single-scriptlet", but ABP rule may contain more than one snippet
 * so if at least one of them is not valid — whole `ruleText` rule is not valid too.
 *
 * @param rule Any scriptlet rule — ADG or UBO or ABP.
 *
 * @returns True if scriptlet name is valid in rule.
 */
declare function isValidScriptletRule(rule: string | ScriptletInjectionRule): boolean;
```

#### `isAdgScriptletRule()`, (中文(简体) ), `isUboScriptletRule()`, (中文(简体) ), `isAbpSnippetRule()`

```typescript
/**
 * Checks if the `rule` is AdGuard scriptlet rule
 *
 * @param rule - rule text
 * @returns true if given rule is adg rule
 */
declare function isAdgScriptletRule(rule: string): boolean;

/**
 * Checks if the `rule` is uBO scriptlet rule
 *
 * @param rule rule text
 * @returns true if given rule is ubo rule
 */
declare function isUboScriptletRule(rule: string): boolean;

/**
 * Checks if the `rule` is AdBlock Plus snippet
 *
 * @param rule rule text
 * @returns true if given rule is abp rule
 */
declare function isAbpSnippetRule(rule: string): boolean;
```

#### `isValidAdgRedirectRule()`

```typescript
/**
 * Checks if the `rule` is **valid** AdGuard redirect resource rule
 *
 * @param rule - rule text
 * @returns true if given rule is valid adg redirect
 */
declare function isValidAdgRedirectRule(rule: string): boolean
```

#### `isRedirectResourceCompatibleWithAdg()`

```typescript
/**
 * Checks if the specified redirect resource is compatible with AdGuard
 *
 * @param redirectName - Redirect resource name to check
 * @returns - true if the redirect resource is compatible with AdGuard
 */
declare function isRedirectResourceCompatibleWithAdg(redirectName: string): boolean;
```

### 转换器 API

```typescript
import {
    convertUboToAdg,
    convertAbpToAdg,
    convertScriptletToAdg,
    convertAdgToUbo
} from '@adguard/scriptlets/converters';
```

#### `convertUboToAdg()`

```typescript
/**
 * Converts string of UBO scriptlet rule to AdGuard scriptlet rule
 *
 * @param rule UBO scriptlet rule
 * @returns array with one AdGuard scriptlet rule
 *
 * @deprecated
 */
declare function convertUboToAdg(rule: string | ScriptletInjectionRule): string[];
```

> 注意UBO规则中的参数应该由逗号+空格来分隔. 否则,该规则无效.

#### `convertAbpToAdg()`

```typescript
/**
 * Convert string of ABP snippet rule to AdGuard scriptlet rule
 *
 * @param rule ABP snippet rule
 * @returns array of AdGuard scriptlet rules, one or few items depends on Abp-rule
 */
declare function convertAbpToAdg(rule: string | ScriptletInjectionRule): string[];
```

#### `convertScriptletToAdg()`

```typescript
/**
 * Converts any scriptlet rule into AdGuard syntax rule.
 * Comments and non-scriptlet rules are returned without changes.
 *
 * @param rule Rule.
 *
 * @returns Array of AdGuard scriptlet rules: one array item for ADG and UBO or few items for ABP.
 * For the ADG `rule` validates its syntax, and returns an empty array if it is invalid.
 */
declare function convertScriptletToAdg(rule: string | ScriptletInjectionRule): string[];
```

#### `convertAdgToUbo()`

```typescript
/**
 * Converts AdGuard scriptlet rule to UBO syntax.
 *
 * @param rule AdGuard scriptlet rule
 * @returns UBO scriptlet rule
 * or undefined if `rule` is not valid AdGuard scriptlet rule.
 */
declare function convertAdgToUbo(rule: string | ScriptletInjectionRule): string | undefined;
```

#### `convertAdgRedirectToUbo()`

```typescript
/**
 * Converts Adg redirect rule to Ubo one
 * 1. Checks if there is Ubo analog for Adg rule
 * 2. Parses the rule and checks if there are any source type modifiers which are required by Ubo
 *    and if there are no one we add it manually to the end.
 *    Source types are chosen according to redirect name
 *    e.g. ||ad.com^$redirect=<name>,important  ->>  ||ad.com^$redirect=<name>,important,script
 * 3. Replaces Adg redirect name by Ubo analog
 *
 * Note: if adg redirect uses UBO's priority syntax, it will be lost on conversion, e.g:
 * ||example.com$redirect=noopjs:99 => ||example.com$redirect=noop.js
 *
 * @param rule adg rule
 * @returns converted ubo rule
 * @throws on incompatible rule
 */
declare function convertAdgRedirectToUbo(rule: string): string;
```

## 浏览器兼容性

| 浏览器 | 版本 |
| --- | :-- |
| 颜色 | ✅55 |
| 火花 | 第52条 |
| 边缘 | 第15条 |
| 歌剧 | 第42条 |
| 萨法里 | ✅ 13 |
| Internet 浏览器 | ❌ |

## 使用脚本的项目

-   [核心文件夹](https://github.com/AdguardTeam/CoreLibs) — 自动更新
-   [TSUrlFilter 单簧管](https://github.com/AdguardTeam/tsurlfilter) —— 说 [过滤器](https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/tsurlfilter) 财务报告和审定财务报表 [tsweb扩展](https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/tswebextension) 软件包
-   [过滤器编译器](https://github.com/AdguardTeam/FiltersCompiler) —— 说 [过滤器](https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/tsurlfilter) 应更新
-   [守护浏览器扩展](https://github.com/AdguardTeam/AdguardBrowserExtension) 两者 [过滤器](https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/tsurlfilter) 财务报告和审定财务报表 [tsweb扩展](https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/tswebextension) 应更新
-   [萨法里科克特利布](https://github.com/AdguardTeam/SafariConverterLib) 需要用于 [守护者MiniForMac](https://github.com/AdguardTeam/AdGuardMiniForMac) 财务报告和审定财务报表 [护卫论坛](https://github.com/AdguardTeam/AdguardForiOS)

## 常见问题

### @adguard/scriptlets 是什么？

AdGuard 的 JavaScript 脚本和重定向资源库

### 如何安装 @adguard/scriptlets？

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

### @adguard/scriptlets 支持 TypeScript 吗？

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

### @adguard/scriptlets 支持 ESM 还是 CommonJS？

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

### @adguard/scriptlets 可以商用吗？

@adguard/scriptlets 使用 GPL-3\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @adguard/scriptlets 的下载量有多少？

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

### @adguard/scriptlets 还在维护吗？

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