# @dudousxd/nestjs-filter-client 中文文档

规范地址：https://npmcn.com/package/%40dudousxd/nestjs-filter-client/

版本：2\.0\.1
npm 元数据更新时间：2026-11-12T05:46:20.734Z
中文译文更新时间：2026-11-13T01:48:16.067Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dudousxd/nestjs-filter-client
原文对照：https://npmcn.com/package/%40dudousxd/nestjs-filter-client/?lang=original
项目主页：https://davidecarvalho.github.io/aviary/docs/filter
源码仓库：https://github.com/DavideCarvalho/nestjs-filter

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

- 包体积（解压后）：152 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：@tanstack/table-core \>=8\.0\.0
- 首次发布：2026-05-25T14:12:35.546Z
- 最新版本发布：2026-11-12T05:46:20.342Z
- 近 30 天下载量：2566（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

@dudousxd/nestjs- filter 的客户端查询构建器.

## 安装

```sh
npm install @dudousxd/nestjs-filter-client
```

也可以使用：`pnpm add @dudousxd/nestjs-filter-client`、`yarn add @dudousxd/nestjs-filter-client`、`bun add @dudousxd/nestjs-filter-client`

## README

# @dudousxd/nestjs-filter-客户端

客户端查询构建器 `@dudousxd/nestjs-filter`。零依赖性,在浏览器和节点.js中运行.

## 安装

```bash
npm install @dudousxd/nestjs-filter-client
```

## 使用量

```typescript
import { filterQuery } from '@dudousxd/nestjs-filter-client';

// Build a filter query
const query = filterQuery()
  .where('name', 'contains', 'fleet')
  .where('status', ['COMPLETED', 'FAILED'])
  .where('age', 'gte', 18)
  .build();
// → { where: [
//     { field: 'name', operator: 'contains', value: 'fleet' },
//     { field: 'status', operator: 'in', value: ['COMPLETED', 'FAILED'] },
//     { field: 'age', operator: 'gte', value: 18 },
//   ] }
```

### 方便方法

```typescript
filterQuery()
  .equals('status', 'active')
  .contains('name', 'fleet')
  .in('role', ['admin', 'editor'])
  .between('age', 18, 65)
  .gte('createdAt', '2026-01-01')
  .isNull('deletedAt')
  .set('page', 1)
  .set('size', 25)
  .build();
```

### 与OR/和

```typescript
filterQuery()
  .where('status', 'active')
  .or(q => q
    .where('name', 'contains', 'sync')
    .where('email', 'contains', 'sync')
  )
  .build();
```

### 查询字符串输出

```typescript
const qs = filterQuery()
  .where('name', 'contains', 'fleet')
  .where('status', ['COMPLETED', 'FAILED'])
  .toQueryString();
// → "name[contains]=fleet&status[]=COMPLETED&status[]=FAILED"
```

### 使用获取

```typescript
const qs = filterQuery()
  .contains('name', 'fleet')
  .gte('createdAt', '2026-01-01')
  .set('page', 1)
  .toQueryString();

const res = await fetch(`/api/users?${qs}`);
```

### 用作 POST 机体

```typescript
const body = filterQuery()
  .where('name', 'contains', 'fleet')
  .or(q => q
    .where('role', 'admin')
    .where('role', 'editor')
  )
  .build();

const res = await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(body),
});
```

## API 密码

| 方法 | 说明 |
| --- | --- |
| `where(field, value)` | 等于过滤器( 阵列自动检测为 `in`(中文(简体) ) |
| `where(field, operator, value)` | 带有明确运算符的过滤器 |
| `equals(field, value)` | 等号的快手 |
| `contains(field, value)` | 包含的快手 |
| `in(field, values)` | 输入时的快手 |
| `between(field, low, high)` | 介于两者之间的简称 |
| `gt` 编号 : `gte` 编号 : `lt` 编号 : `lte` | 比较快手 |
| `isNull` 编号 : `isNotNull` | 无法检查简称 |
| `isEmpty` 编号 : `isNotEmpty` | 空检查快取 |
| `startsWith` 编号 : `endsWith` | 字符串匹配的简称 |
| `or(callback)` | OR组 |
| `and(callback)` | 和组 |
| `set(key, value)` | 添加额外的密钥( 如页面, 大小) |
| `build()` | 回返 `FilterQueryResult` 对象 |
| `toQueryString()` | 返回 URL 查询字符串 |
| `toFlatObject()` | 返回自动字段的平面对象 |

## 类型

| 类型 | 这是什么 |
| --- | --- |
| `FilterQueryResult` | 什麽 `build()` 返回: 整个信封, 包含 |
| `UnpagedFilterQuery` | 同一个信封 **无** `paginate` —— 说 `FilterQueryResult` 扩展它 |
| `ColumnFilter` | 一个前提: `field` + 键 `operator` (+ 数) `value`(中文(简体) ) |
| `ColumnFilterGroup` | 纯布尔组 : `{ OR: [...] }` 编号 : `{ AND: [...] }`,没有字段,没有操作员 |
| `ColumnFilterClause` | `ColumnFilter | ColumnFilterGroup` - 哪个条目 `filter.where` 也许 |

### `UnpagedFilterQuery` —— 查询减去页面

导出将呼叫窗口交给服务器( CSV 导出, 报告), a 只计数请求、预选键或缓存密钥都想要显示的查询 _哪个行_ 不用说 _哪个切片_这是 `UnpagedFilterQuery`数字 :

```typescript
import type { UnpagedFilterQuery } from '@dudousxd/nestjs-filter-client';

function exportBody(query: UnpagedFilterQuery) {
  return JSON.stringify(query); // the server decides how much it streams
}

const { paginate, ...unpaged } = filterQuery().contains('name', 'fleet').page(0, 25).build();
exportBody(unpaged);
```

执行 **没有** 访问范围 `Omit<FilterQueryResult, 'paginate'>` 换句话说. `FilterQueryResult` 携带 `[key: string]: unknown` 这样 `set()` 额外生存,和 `Omit` 重建类型 从 `keyof` 对于索引签名类型来说 `string | number`。奥米 因此崩溃 `{ [x: string]: unknown }`: 每一个被命名的密钥都不见了, 每个类型 已接受,没有编译错误可告诉你. `UnpagedFilterQuery` 被宣布为 基础 `FilterQueryResult` 延伸,所以两者不能漂移.

### `ColumnFilterClause` - 上游条款和仅属于集团的条款

条款要么是上游条款,要么是只构成其他条款的集团。 两者都是 在电线上有效(服务器的验证器有明显的组-节点分支),所以两者都 输入 :

```typescript
import type { ColumnFilterClause } from '@dudousxd/nestjs-filter-client';

const where: ColumnFilterClause[] = [
  { field: 'status', operator: 'equals', value: 'active' },   // predicate
  { OR: [                                                      // group — no field, no operator
    { field: 'name', operator: 'contains', value: 'sync' },
    { field: 'email', operator: 'contains', value: 'sync' },
  ] },
];
```

`ColumnFilter` 本身没有变化 **需求** `field` 财务报告和审定财务报表 `operator`数字 : 团体是工会的单独成员,而不是放松,所以 `{ field: 'status', value: 'active' }` ——其操作员被遗忘的上游—— 仍然是编译错误.

## 许可证

麻省理工学院

## 常见问题

### @dudousxd/nestjs-filter-client 是什么？

@dudousxd/nestjs- filter 的客户端查询构建器\.

### 如何安装 @dudousxd/nestjs-filter-client？

在项目目录运行 npm install @dudousxd/nestjs-filter-client，或使用 pnpm add / yarn add / bun add。

### @dudousxd/nestjs-filter-client 支持 TypeScript 吗？

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

### @dudousxd/nestjs-filter-client 支持 ESM 还是 CommonJS？

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

### @dudousxd/nestjs-filter-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dudousxd/nestjs-filter-client 可以商用吗？

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

### @dudousxd/nestjs-filter-client 的下载量有多少？

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

### @dudousxd/nestjs-filter-client 还在维护吗？

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