# @eyeo/snippets 中文文档

规范地址：https://npmcn.com/package/%40eyeo/snippets/

版本：2\.18\.0
npm 元数据更新时间：2026-10-23T14:15:10.845Z
中文译文更新时间：2026-11-14T06:32:08.467Z
软件包许可：GPL-3\.0-only

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

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

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

- 包体积（解压后）：6.8 MB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2022-03-30T12:21:43.169Z
- 最新版本发布：2026-10-23T14:15:10.622Z
- 近 30 天下载量：7244（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 17 个）

## 中文简介

ads 阻断器的眼/o片段

## 安装

```sh
npm install @eyeo/snippets
```

也可以使用：`pnpm add @eyeo/snippets`、`yarn add @eyeo/snippets`、`bun add @eyeo/snippets`

## README

# @ eyeo/ 片段

本单元的目标是提供一个预先捆绑、预先测试和提前优化的版本 _片断_ 用于各种移动,或桌面, Ads 阻断器.

### 简言之,片段

每个片段都以过滤文本表示,通过 `#$#` 语法, 然后是片断 _名称_ 和 0,用空格分隔出一个或多个参数,或者当空格是参数的一部分时,包含在引文中.

```
! logs 1 2 3 in the console
evilsite.com#$#log 1 2 3
```

每个过滤器可以通过分号执行多个片段 `;` 在电话之间.

```
! logs 1 2 then 3 4 5 in the console
evilsite.com#$#log 1 2; log 3 4 5
```

#### 两种片段

片段可以运行为 [内容脚本](https://developer.chrome.com/docs/extensions/mv3/content_scripts/#isolated_world),这是一个单独的环境,可以复制 _管理部_ 但绝不干涉 _联合来文_ 在用户页面上运行(反之亦然),或作为 [注入脚本](https://developer.chrome.com/docs/extensions/mv3/content_scripts/#programmatic) 在网页上运行 在第3党和普通网站 _联合来文_ 代码.

前一种叫做 **单独**,因为它通过Web扩展API运行沙盒,而后一种则称为 **主要**,或 **已注射**因为它需要在页中运行的代码的其余部分中进行评价,因此它被字面地注入了这样的一页.

一些片段可能只是一种用途,因此,可在两个数据库中查阅 _主要_ 编辑 _单独_ 诸世界. 片段的执行方式及其可能的副作用仍被限制在孤立或主要部分 " _世界_" 它会碰到.

## 如何使用此模块

本单元目前提供以下出口:

-   `@eyeo/snippets` 包括两个 `isolated` 财务报告和审定财务报表 `main`,又作 `injected`,导出名称
-   `@eyeo/snippets/isolated` 仅包括 `isolated` 导出
-   `@eyeo/snippets/main`,别名为 `@eyeo/snippets/injected` 仅包括 `main` 导出
-   `@eyeo/all` 它会输出所有片段,作为这些环境的单个回调 _单独_ 这个世界是 _不支持_标准 _无害环境管理_ 用于

因此,根据项目需要,本单元可采用各种方式.

## 发布后如何直接到达我们的文件

请随时检查 [我们的新闻稿页面](https://gitlab.com/eyeo/snippets/-/releases) 并自由使用 URL 指向我们释放的分支,通过 `https://gitlab.com/eyeo/snippets/-/raw/RELEASE_VERSION/dist/YOUR_FILE_HERE.js`时 `RELEASE_VERSION` 可能会是 `v0.5.0` 或他人,以及 `YOUR_FILE_HERE` 为:

-   页:1 _铬_ 基于产品,我们有一个 _标准化_ 世界第一件文物,可以通过这个模块的 [独立第一.jst](https://npmcn.com/package/%40eyeo/snippets/dist/isolated-first.jst) 文件
-   页:1 _网络Kit_ 基础产品,我们是一个 _主要_ 所有文物都可以通过这个模块 [片断.js](https://npmcn.com/package/%40eyeo/snippets/dist/snippets.js) 文件

两者 `main.js` 财务报告和审定财务报表 `isolated.js` 包含其他文件的相同代码.

他们的源代码完全相同 [网页文件夹](https://npmcn.com/package/%40eyeo/snippets/webext/) 及其源文件.

## XPath 3.1 支助

随着片段模块版本0.8.0的发布,我们引入了一个新的片段,叫做: `hide-if-matches-xpath3` 允许使用 XPath 3.1 函数来瞄准广告。 由于XPath 3.1并非由浏览器本土支持,片段需要向被隔离的上下文注入依赖性才能正常工作. 如果您正在使用, 此依赖会自动使用现有的网络扩展机制注入 [iyo 网页扩展屏蔽工具箱](https://gitlab.com/eyeo/adblockplus/abc/webext-sdk)对于以铬为原料的产品,依赖性注射逻辑将得到支持 [iyo 浏览器 Ad- Filtering 解决方案](https://gitlab.com/eyeo/adblockplus/chromium-sdk) 。 。 。 .

作为以铬为原料的产品,如果使用 `@eyeo/snippets` 作为独立库的模块,您需要积极选择使用才能使用 `hide-if-matches-xpath3` 片断。 你可以继续使用 `isolated-first.jst` 现有建筑阶梯没有任何改变. `isolated-first.jst` 不包含 `hide-if-matches-xpath3` 片段,但它会继续被支持。 如果你想包括 `hide-if-matches-xpath3` 片段你需要做两步。 首先你必须用 [(原始内容存档于2018-03-13) (英语). select-sign-first.jst](https://npmcn.com/package/%40eyeo/snippets/dist/isolated-first-all.jst) 取而代之的是文物。 其次,您需要执行依赖性注入逻辑,以便在片断运行前包含所需的依赖性。 你可以注射这个 [依赖关系.jst](https://npmcn.com/package/%40eyeo/snippets/dist/dependencies.jst) 保存到页面并调用依赖函数: `hideIfMatchesXPath3Dependency()`。片段应如预期的那样工作.

### 第三方图书馆

-   [字体氧化路径](https://github.com/FontoXML/fontoxpath) - 说吧 [许可证](https://github.com/FontoXML/fontoxpath/blob/master/LICENSE.md)
-   [页:1](https://github.com/bwrrp/prsc.js) - 说吧 [许可证](https://github.com/bwrrp/prsc.js/blob/main/LICENSE)
-   [\[永久失效連結\] (简体中文)](https://github.com/bwrrp/xspattern.js) - 说吧 [许可证](https://github.com/bwrrp/xspattern.js/blob/main/LICENSE)
-   [为什么不呢](https://github.com/bwrrp/whynot.js) - 说吧 [许可证](https://github.com/bwrrp/whynot.js/blob/main/LICENSE)

## 模块结构

这个 [源文件夹](https://npmcn.com/package/%40eyeo/snippets/source) 包含用于创建此两个中的所有文件 [磁盘文件夹](https://npmcn.com/package/%40eyeo/snippets/dist) 财务报告和审定财务报表 [网页文件夹](https://npmcn.com/package/%40eyeo/snippets/webext)。 。 。 .

前者包含由第三方使用的文件,非网络扩展相关,项目,而 _网络ext_ 文件夹包含文件的优化版本和源版本,以便最终能够提供 _调试_ 模式而不是模式 _生产_ 一个.

### 建筑概况

这个模块被Web扩展和第三党合作伙伴使用,即使源代码总是相同的,这些是不同的目标.

本节要从高层次解释这些文件夹之间的差异.

#### 网页

此文件夹包含所有定义的导出 _ECMAS脚本_ 标准模块(aka) _无害环境管理_(a) 国家 `package.json` 文档.

两者 _主要_ 财务报告和审定财务报表 _单独_ 出口为: _纯函数_ 能够传递到宣言 v3 [脚本 API](https://developer.chrome.com/docs/extensions/reference/scripting/)。 。 。 .

这些功能被扩充成只读 _地图_ 通过a `.has(snippetName)` 财务报告和审定财务报表 `.get(snipetName)` 其中:

-   `.has(...)` 返回时 _真实_ 如果片段因这个特定世界而出名(或 _主要_ 或者说 _标准化_(中文(简体) )
-   `.get(...)` 返回( n) _无效_ 或一个 _回调_ 用作 _依赖性_ 对于非常具体的脚本

这种方法赋予了我们能力,只要该特定页面不需要这样的片段,就可以执行最小的代码量,因为依赖性确实可以相当大(在此情况下是被剥去的"TensorFlow库"版本+二进制模型).

这些回调通常不为第三党片段的其他消费者所使用或需要.

#### 位点

此文件夹包含的文件可以是 _内嵌_ 直接作为任何 _HTML 语言_ 页面,然后立即通过周围文本执行 :

```js
// example of distFileContent source code
// distFileContent = readFileSync("dist/snippets.js")
// distFileContent = readFileSync("dist/isolated-first.jst")
page.evaluate(`(${distFileContent})(...${JSON.stringify([env, ...snippets])})`);
```

在那个 `snippets.js` 我们只有片段 _货币_ 一个嵌入到一个单调回, 所有片段运行在 _主要_ 这个世界.

这个 `isolated-first.jst` 文件将立即执行 _标准化_ 片段和, 如果有什么 _主要_ 用于执行的世界, 它包含一些逻辑来附加运行在用户页面上的脚本 _主要_ 世界的片段紧接着, 仍然传递着同样的论点 通过它通过 `[env, ...snippets]` 连载化.

这个 `.jst` 扩展名 _JS 模板_ 之所以选择它 是因为否则某些工具链 可能会试图自动修改这样的文件 并且,因为它的内容 并没有被引用 因为这只是一个召回, 甚至没有马上执行.

我们想出了一个模板扩展,以避免嵌入工具链(即Android)的分解器,从而在注入后实际破解我们的代码.

该页面中的其他文件 _数字_ 文件夹提供,就像它用于 _网络ext_ 一、完整源代码的替代品或任何其他可能的替代品 _被隔离_ 或者说 _主语.js_ 也许吧.

**笔记** 这些文件在 _数字_ 文件夹不导出为模块 _不过_ 如上一个会话所解释的,通过释放标记使用.

## 地方发展

安装建造工具并建造文物:

```
npm install
npm run build
```

`npm run build` 重新生成 `dist/` 财务报告和审定财务报表 `webext/` 然后进行测试. `npm test` 自己进行测试.

### 工具版本( 可选)

节点和承诺前版本被固定在 `mise.toml`。安装 [爱](https://mise.jdx.dev/) 运行 `mise install` 在寄存器根中获取它们,或者自己安装相同的版本.

### 承诺前钩

存储器使用 [承诺前](https://pre-commit.com/) 以本地运行的相同安全扫描仪(semgrep和gitleaks)。 安装预承诺, 然后启用钩子一次 :

```
pre-commit install
```

钩子会自动运行在每一个承诺上。 根据要求运行它们与整个存储库:

```
pre-commit run --all-files
```

## 关于释放

我们试图遵循官方的指导 [吉特拉布语Name](https://docs.gitlab.com/ee/user/project/releases/) 通过下列步骤:

1.  确保内部源代码和寄存点 在发布代码,我们希望作为模块运送
2.  从 `main`,运行发行准备脚本 :
    
    ```
    ./prepare-release.sh [major|minor|patch] [path-to-abp-snippets/source]
    ```
    
    脚本将以下步骤自动化(并在第5步暂停进行人工干预):
    -   创建分支 `vX.X.X`
    -   将版本在 `package.json` 不创建标签
    -   从提供的源代码文件导入 `abp-snippets/source` 路径( 可选; 可在之后手动运行) `npm run build.assets <path>`(中文(简体) )
    -   **暂停** 因此,如果需要,您可以做任何手工修改,例如:
        -   注册新片段 `bundle/main.js` (主要上下文)或 `bundle/isolated.js` (单独上下文)
        -   更新外部文件 `source`
    -   运行 `npm run build` 创造这些文物
    -   以信息承诺一切 **@eyeo/片段 vX.X**
    -   推动树枝 `git push --set-upstream origin vX.X.X`
3.  在审查MR时,忽略 `dist`, (中文(简体) ), `webext`,以及 `source` - 这些总是不一样的
4.  在 GitLab 中使用发布模板创建描述性发布 MR
5.  一旦审查和批准,将释放分支合并为主挤压承诺 **不删除分支**
6.  合并后, 手动触发管道中的发布任务: 它会负责发布标签并创建 gitLab 发布
7.  如果 CI 中的发布命令失败: 退出 `main`中,拉,如果确定你有访问权和 a _2个FA_ 保护账户运行 :
    -   `npm login`
    -   `npm publish`

## 常见问题

### @eyeo/snippets 是什么？

ads 阻断器的眼/o片段

### 如何安装 @eyeo/snippets？

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

### @eyeo/snippets 支持 TypeScript 吗？

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

### @eyeo/snippets 支持 ESM 还是 CommonJS？

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

### @eyeo/snippets 可以商用吗？

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

### @eyeo/snippets 的下载量有多少？

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

### @eyeo/snippets 还在维护吗？

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