# @blowfishxyz/blocklist 中文文档

规范地址：https://npmcn.com/package/%40blowfishxyz/blocklist/

版本：0\.0\.11
npm 元数据更新时间：2026-02-02T08:29:04.089Z
中文译文更新时间：2026-11-08T08:07:02.398Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40blowfishxyz/blocklist
原文对照：https://npmcn.com/package/%40blowfishxyz/blocklist/?lang=original

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

- 包体积（解压后）：32 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2023-02-09T13:46:21.866Z
- 最新版本发布：2026-02-02T08:29:03.943Z
- 近 30 天下载量：96196（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 1 个）

## 中文简介

获取并执行 Blowfish 块列表上的搜索

## 安装

```sh
npm install @blowfishxyz/blocklist
```

也可以使用：`pnpm add @blowfishxyz/blocklist`、`yarn add @blowfishxyz/blocklist`、`bun add @blowfishxyz/blocklist`

## README

# Blowfish 本地块列表

这是一个 Javascript/ Typescript 库, 方便访问 Blowfish 本地封装列表 API : 例如从 API 中获取封装列表对象, 扫描一个域与封装列表相对并保存开花过滤器.

它旨在支持React Indigen,Chrome扩展和Node.js环境.

## 安装

```bash
npm install @blowfishxyz/blocklist
```

还推荐React 原生应用程序安装 `react-native-url-polyfill`。 。 。 .

## 使用量

要执行检查, 您需要获取 **块列表对象** 财务报告和审定财务报表 **开花过滤器**。 。 。 . 在第一次获取后, 您应该不断更新这些对象 。 您可以在本地数据库中保存对象 (例如使用Chrome扩展中的本地存储).

我们建议每5分钟更新一次.

### 基本用途

```javascript
import {
  BlowfishLocalBlocklist,
  ApiConfig,
  BLOWFISH_API_BASE_URL,
} from "@blowfishxyz/blocklist";

const apiConfig: ApiConfig = {
  basePath: BLOWFISH_API_BASE_URL,
  // It's highly encouraged to use a proxy server to not expose your API key on the client (see: https://docs.blowfish.xyz/docs/wallet-integration-guide#optional-proxy-server).
  // When using a proxy server, replace basePath with your endpoint and set apiKey to `undefined`.
  apiKey: "you-api-key",
};
const blocklist = new BlowfishLocalBlocklist(apiConfig);

// 1. Fetch the blocklist and persist it in the storage
blocklist.fetchBlocklist();

// 2. Re-refetch the blocklist every 5 minutes
setInterval(() => blocklist.fetchBlocklist(), 1000 * 60 * 5);

// 3. Once you have a blocklist object and a bloom filter saved, you can execute lookups
const action = blocklist.scanDomain("https://scam-website.io");

if (action === Action.BLOCK) {
  // block the domain
}
```

你可以跳过 `apiKey` 并通过自定义 `basePath` 将查询引导到您的后端app或代理.

### Bloom 过滤器

屏蔽对象链接到开花过滤器. 然而,开花过滤器是一个700 KB 文件,所以您的应用程序只应该 纳西里时重新下载.

为了做到这一点,我们正在追踪开花滤波器的散列物,并在必要时重新抽取.

然后,我们保存开花滤波器本身 及其散列物到 `storage`。 。 。 .

我们不会比每24小时更频繁更新块状散列.

### 处理错误

依赖于 API a/或网络的函数可以返回 `null` 当遇到 I/O 错误时.

如果您想要跟踪错误, 您可以通过可选 `reportError` 回调到 `BlowfishLocalBlocklist` 建筑师.

它可以叫一个 `Error` 或以一弦为相.

## 指南

### 浏览器扩展

1.  安装必要的依赖 :

```bash
npm install @blowfishxyz/blocklist webextension-polyfill
```

2.  创建块列表模块 :

```typescript
// src/blocklist.ts
import {
  BlowfishLocalBlocklist,
  BlowfishBlocklistStorageKey,
  BlowfishBlocklistStorage,
  BLOWFISH_API_BASE_URL,
} from "@blowfishxyz/blocklist";

const storage: BlowfishBlocklistStorage = {
  async getItem<T>(key: BlowfishBlocklistStorageKey) {
    const storage = chrome.storage.local.get([key]);
    return storage[key] as T | undefined;
  },
  async setItem(key: BlowfishBlocklistStorageKey, data: unknown) {
    return chrome.storage.local.set({
      [key]: data,
    });
  },
};

export const blocklist = new BlowfishLocalBlocklist(
  { basePath: BLOWFISH_API_BASE_URL, apiKey: undefined },
  undefined,
  storage
);
export { Action } from "@blowfishxyz/blocklist";
```

3.  列表块列表更新 :

```typescript
// src/background.ts
import Browser from "webextension-polyfill";
import { blocklist } from "./blocklist";

Browser.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === "refetch-blocklist") {
    blocklist.fetchBlocklist();
  }
});

Browser.alarms.create("refetch-blocklist", {
  periodInMinutes: 5,
  delayInMinutes: 0,
});
```

4.  域扫描 :

```typescript
// src/content-script.ts
import Browser from "webextension-polyfill";
import { blocklist, Action } from "./blocklist";

blocklist.scanDomain(window.location.href).then((action) => {
  if (action === Action.BLOCK) {
    Browser.runtime.sendMessage({
      type: "block-domain",
      host: window.location.hostname,
      href: encodeURI(window.location.href),
    });
  }
});
```

5.  被屏蔽的域屏 :

```typescript
// src/block-screen.tsx
import { blocklist } from "./blocklist";

function proceedToBlockedDomainButtonClickHandler() {
  blocklist.allowDomainLocally(window.location.href);
}
```

### 原生反应

1.  安装必要的依赖 :

```bash
npm install @blowfishxyz/blocklist react-native-async-storage react-native-background-timer react-native-url-polyfill
```

2.  创建块列表模块 :

```typescript
// src/blocklist.ts
import {
  BlowfishLocalBlocklist,
  BlowfishBlocklistStorageKey,
  BlowfishBlocklistStorage,
  BLOWFISH_API_BASE_URL,
} from "@blowfishxyz/blocklist";
import AsyncStorage from "@react-native-async-storage/async-storage";

const storage: BlowfishBlocklistStorage = {
  async getItem<T>(key: BlowfishBlocklistStorageKey): Promise<T | undefined> {
    const data = await AsyncStorage.getItem(key);
    return data ? (JSON.parse(data) as T) : undefined;
  },
  async setItem(
    key: BlowfishBlocklistStorageKey,
    data: unknown
  ): Promise<void> {
    await AsyncStorage.setItem(key, JSON.stringify(data));
  },
};

export const blocklist = new BlowfishLocalBlocklist(
  { basePath: BLOWFISH_API_BASE_URL, apiKey: undefined },
  undefined,
  storage
);
export { Action } from "@blowfishxyz/blocklist";
```

3.  列表块列表更新 :

```typescript
// src/background.ts
import { blocklist } from "./blocklist";
import BackgroundTimer from "react-native-background-timer";

let intervalId;

const refetchBlocklist = () => {
  blocklist.fetchBlocklist();
};
export const startBlocklistRefetch = () => {
  intervalId = BackgroundTimer.setInterval(refetchBlocklist, 5 * 60 * 60);
};

export const stopBlocklistRefetch = () => {
  BackgroundTimer.clearInterval(intervalId);
};
```

4.  域扫描 :

```typescript
// src/domainScanner.ts
import { blocklist, Action } from "./blocklist";

const scanCurrentDomain = async (url: string) => {
  const action = await blocklist.scanDomain(url);
  if (action === Action.BLOCK) {
    // Handle domain blocking logic
    console.warn("Blocked domain:", url);
  }
};

export default scanCurrentDomain;
```

5.  被屏蔽的域屏 :

```typescript
// src/BlockScreen.tsx
import React from "react";
import { TouchableOpacity, Text } from "react-native";
import { blocklist } from "./blocklist";

function proceedToBlockedDomainHandler(url: string) {
  blocklist.allowDomainLocally(url);
}

const BlockScreen: React.FC<{ url: string }> = ({ url }) => {
  return (
    <TouchableOpacity onPress={() => proceedToBlockedDomainHandler(url)}>
      <Text>Proceed to Blocked Domain</Text>
    </TouchableOpacity>
  );
};

export default BlockScreen;
```

## API 参考

### `BlowfishLocalBlocklist`

### 构造参数

-   `apiConfig: ApiConfig`
    -   `basePath: string`: 域块列表的URL. 您可以用它将 API 请求传递给一个位于用户和 Blowfish API 之间的代理服务器.
    -   `apiKey: string | undefined`: Blowfish API的API密钥. 可能会 `undefined` 当使用代理时.
-   `blocklistConfig: BlocklistConfig`
    -   `priorityBlockLists: PriorityBlockListsEnum[] | undefined`: 如果在其中一个列表中显示, 总是块域, 即使它被允许在常规允许列表中列出( ex: `PHANTOM`, (中文(简体) ), `BLOWFISH`, (中文(简体) ), `BLOWFISH_AUTOMATED`, (中文(简体) ), `SOLFARE`, (中文(简体) ), `PHISHFORT`, (中文(简体) ), `SCAMSNIFFER`, (中文(简体) ), `METAMASK`(中文(简体) )
    -   `priorityAllowLists: PriorityAllowListsEnum[] | undefined`: 覆盖域名, 如果域名出现在其中的列表中, 即使它被列入常规的块列表中( ex: `BLOWFISH`, (中文(简体) ), `METAMASK`, (中文(简体) ), `DEFILLAMA`(中文(简体) )
    -   `blockLists: BlockListsEnum[] | undefined`: 覆盖域名, 如果域名出现在其中的列表中, 即使它被列入常规的块列表中( ex: `PHANTOM`, (中文(简体) ), `BLOWFISH`, (中文(简体) ), `BLOWFISH_AUTOMATED`, (中文(简体) ), `SOLFARE`, (中文(简体) ), `PHISHFORT`, (中文(简体) ), `SCAMSNIFFER`, (中文(简体) ), `METAMASK`(中文(简体) )
    -   `allowLists: AllowListsEnum[] | undefined`: 覆盖域名, 如果域名出现在其中的列表中, 即使它被列入常规的块列表中( ex: `BLOWFISH`, (中文(简体) ), `METAMASK`, (中文(简体) ), `DEFILLAMA`(中文(简体) )
    -   `bloomFilterTtl?: number`: 开花过滤器和相应的过滤器需要多长时间 `hash` 应保持静止。 默认24小时 最少24小时,最多14天. 在此期间,将增加新域 `recentlyAdded` 并删除 `recentlyRemoved` 字段.
-   `storage: BlowfishBlocklistStorage` 如果没有指定存储,我们使用内存存储。 大力鼓励您为您的环境提供合适的储存( Evironemt) [见指南](https://npmcn.com/package/%40blowfishxyz/blocklist/#readme-guides)) (中文(简体) ).
    -   `getItem<T>(key: BlowfishBlocklistStorageKey): Promise<T | undefined>`:从环境存储中逐项取出.
    -   `setItem(key: BlowfishBlocklistStorageKey, data: unknown)`: 按环境存储键设置项目.
-   `reportError: (error: unknown) => void`: 当结果出现时,库用于跟踪错误的回调函数 `null`. (可选)

### 方法

### `fetchBlocklist(): Promise<LocalBlocklist | undefined>`

获取块列表元数据并将其保存到存储中。 如果取取的块状散列与存储中的散列不同,则会将开花过滤器重新排入并保存到存储中.

如果块列表获取失败, 方法返回 `undefined` 并报告错误到 `reportError`。 。 。 .

### `scanDomain(url: string): Promise<Action>`

扫描所存储域块列表的域并返回要采取的行动( 要么 `BLOCK` 或者说 `NONE`) (中文(简体) ).

如果没有存储的块列表, 它会使用 `fetchBlocklist` 方法并返回所产生的动作.

如果获取失败, 方法返回动作 `NONE` 并报告错误到 `reportError`。 。 。 .

### `allowDomainLocally(url: string): Promise<Action>`

如果用户想通过明确的动作来继续到被封锁的域,域被添加到用户允许列表中(本地存储中).

这个 `scanDomain` 方法将返回 `NONE` 用于此域的动作,即使它在块列表中.

## 常见问题

### @blowfishxyz/blocklist 是什么？

获取并执行 Blowfish 块列表上的搜索

### 如何安装 @blowfishxyz/blocklist？

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

### @blowfishxyz/blocklist 支持 TypeScript 吗？

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

### @blowfishxyz/blocklist 支持 ESM 还是 CommonJS？

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

### @blowfishxyz/blocklist 可以商用吗？

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

### @blowfishxyz/blocklist 的下载量有多少？

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

### @blowfishxyz/blocklist 还在维护吗？

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