# @eliot-ragueneau/ngx-query-builder 中文文档

规范地址：https://npmcn.com/package/%40eliot-ragueneau/ngx-query-builder/

版本：20\.0\.2
npm 元数据更新时间：2025-07-01T15:28:09.503Z
中文译文更新时间：2026-11-14T04:49:05.015Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40eliot-ragueneau/ngx-query-builder
原文对照：https://npmcn.com/package/%40eliot-ragueneau/ngx-query-builder/?lang=original
项目主页：https://github.com/EliotRagueneau/ngx-query-builder
源码仓库：https://github.com/EliotRagueneau/ngx-query-builder

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

- 包体积（解压后）：266 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@angular/common ^20\.0\.0，@angular/core ^20\.0\.0
- 首次发布：2025-06-30T17:13:40.645Z
- 最新版本发布：2025-07-01T15:28:09.318Z
- 近 30 天下载量：2337（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 0 个）

## 中文简介

[![npm version](https://badge.fury.io/js/@eliot-ragueneau%2Fngx-query-builder.svg)](https://badge.fury.io/js/@eliot-ragueneau%2Fngx-query-builder) \[![npm downloads a month](https://img.shields.io/npm/dm/@eliot-ragueneau%2Fngx-query-builder.svg)(https://i) (中文(简体) )

## 安装

```sh
npm install @eliot-ragueneau/ngx-query-builder
```

也可以使用：`pnpm add @eliot-ragueneau/ngx-query-builder`、`yarn add @eliot-ragueneau/ngx-query-builder`、`bun add @eliot-ragueneau/ngx-query-builder`

## README

# ngx-query-建设器

[![npm version](https://badge.fury.io/js/@eliot-ragueneau%2Fngx-query-builder.svg)](https://badge.fury.io/js/@eliot-ragueneau%2Fngx-query-builder) [![npm downloads a month](https://img.shields.io/npm/dm/@eliot-ragueneau%2Fngx-query-builder.svg)](https://img.shields.io/npm/dm/@eliot-ragueneau%2Fngx-query-builder.svg) [![npm downloads a week](https://img.shields.io/npm/dt/@eliot-ragueneau%2Fngx-query-builder.svg)](https://img.shields.io/npm/dt/@eliot-ragueneau%2Fngx-query-builder.svg) [![Contribute with Gitpod](https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod&color=green)](https://gitpod.io/#https://github.com/EliotRagueneau/ngx-query-builder)

基于 jQuery QueryBuilder 的现代化Angular 4+查询构建器. 支持重定制Angular组件,并提供了处理自定义数据类型的灵活方法.

_**从( 从)[https://github.com/zebzhao/Angular-QueryBuilder 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/zebzhao/Angular-QueryBuilder)) 由于原作项目已停止更新,不支持最新的Angular版本,所以我将继续维护并支持Angular的最新版本.**_

# 开始

## 安装

-   角20,使用20.X.X
-   角19,使用19.X.X

`npm install @eliot-ragueneau/ngx-query-builder`

* * *

-   角9,使用0.6.0
-   角8,使用0.5.1
-   角6-7,使用0.4.2
-   角4-5,使用0.3.2

`npm install angular2-query-builder`

见 [https://github.com/zebzhao/Angular-QueryBuilder 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/zebzhao/Angular-QueryBuilder) 关于旧版本使用的更详细情况.

# 实例

## 基本用途

##### `app.module.ts`

```javascript
import {QueryBuilderModule} from "@eliot-ragueneau/ngx-query-builder";
import {AppComponent} from "./app.component"

@NgModule({
  imports: [...,
  QueryBuilderModule,
  IonicModule.forRoot(AppComponent) // (Optional) for IonicFramework 2+
]})
export class AppModule {
}
```

##### `app.component.html`

```html
...
<ngx-query-builder [(ngModel)]='query' [config]='config'></ngx-query-builder>
...
```

##### `app.component.ts`

```javascript
import {QueryBuilderConfig} from '@eliot-ragueneau/ngx-query-builder';

export class AppComponent {
  query = {
    condition: 'and',
    rules: [
      {field: 'age', operator: '<=', value: 'Bob'},
      {field: 'gender', operator: '>=', value: 'm'}
    ]
  };

  config: QueryBuilderConfig = {
    fields: {
      age: {name: 'Age', type: 'number'},
      gender: {
        name: 'Gender',
        type: 'category',
        options: [
          {name: 'Male', value: 'm'},
          {name: 'Female', value: 'f'}
        ]
      }
    }
  }
}
```

## 自定义输入组件

##### `app.component.html`

```html

<ngx-query-builder [(ngModel)]='query' [config]='config'>
  <ng-container *queryInput="let rule; type: 'date'">
    <custom-datepicker [(ngModel)]="rule.value"></custom-datepicker>
  </ng-container>
</ngx-query-builder>
```

##### `app.component.ts`

```javascript
query = {
  condition: 'and',
  rules: [
    {field: 'birthday', operator: '=', value: new Date()}
  ]
};

config: QueryBuilderConfig = {
  fields: {
    birthday: {
      name: 'Birthday',
      type: 'date',
      operators: ['=', '<=', '>'],
      defaultValue: () => new Date()
    }
  }
}
```

## 属性绑定快速引用

#### `ngx-query-builder`

| 名称 | 类型 | 需求 | 默认 | 说明 |
| :-- | :-- | :-- | :-- | :-- |
| `allowRuleset` | `boolean` | 可选 | `true` | 显示 `+ Ruleset` 按钮,如果 `true`。 。 。 . |
| `allowCollapse` | `boolean` | 可选 | `false` | 如果 `true`。 。 。 . |
| `classNames` | [`QueryBuilderClassNames`](https://npmcn.com/projects/ngx-query-builder/src/lib/models/query-builder.interfaces.ts#L48) | 可选 |  | 不同儿童元素的 CSS 类名 `query-builder` 组件. |
| `config` | [`QueryBuilderConfig`](https://npmcn.com/projects/ngx-query-builder/src/lib/models/query-builder.interfaces.ts#L85) | 需求 |  | 主组件的配置对象 . |
| `data` | [`Ruleset`](https://npmcn.com/projects/ngx-query-builder/src/lib/models/query-builder.interfaces.ts) | 可选 | {条件:"和",规则: \[\]} | (使用时) `ngModel` 或者说 `value` 改为. ) |
| `emptyMessage` | `string` | 可选 |  | 如果不允许为空规则显示信件. |
| `ngModel` | [`Ruleset`](https://npmcn.com/projects/ngx-query-builder/src/lib/models/query-builder.interfaces.ts) | 可选 | {条件:"和",规则: \[\]} | 存储组件状态的对象。 支持双向绑定. |
| `operatorMap` | `{ [key: string]: string[] }` | 可选 |  | 用于映射字段类型以列出运算符 . |
| `persistValueOnFieldChange` | `boolean` | 可选 | `false` | 若为 `true`,当一个字段更改为同类型的另一个字段,而该类型是:字符串、数字、时间、日期或布尔等,则坚持先前的值。 如果提供了配置. 计算 FellowChangeValue , 此选项将被忽略 . |
| `config.calculateFieldChangeValue` | `(currentField: Field, nextField: Field, currentValue: any) => any` | 可选 |  | 用于计算规则字段变化时的新值. |
| `value` | [`Ruleset`](https://npmcn.com/projects/ngx-query-builder/src/lib/models/query-builder.interfaces.ts) | 可选 | {条件:"和",规则: \[\]} | 存储组件状态的对象. |

## 结构指令

使用这些指令来用自定义组件来取代查询构建器的不同部分.

#### `queryArrowIcon`

用于替换查询构建器倒塌/ accordion 模式中使用的扩展箭头的指令.

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `RuleSet` | 当前包含儿童规则列表的规则集对象 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `querySwitchGroup`

用于替换开关控制,例如AND/OR条件。 通过使用此指令来覆盖默认组件,可以指定更多的自定义条件.

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `RuleSet` | 当前包含儿童规则列表的规则集对象 |
| `onChange` | `() => void` | 回调处理切换组组件的更改 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryButtonGroup`

用于替换添加的默认按钮组, 添加 Ruleset, 删除 Ruleset 按钮 .

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `RuleSet` | 当前包含儿童规则列表的规则集对象 |
| `parentValue` | `RuleSet` | 如果存在父节点的数据 |
| `addRule` | `() => void` | 处理新增规则的功能 |
| `addRuleSet` | `() => void` | 处理添加新规则集的函数 |
| `removeRuleSet` | `() => void` | 处理删除当前规则集的函数 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryRulesetAddRuleButton`

用于替换添加规则的默认按钮 .

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `RuleSet` | 当前包含儿童规则列表的规则集对象 |
| `addRule` | `() => void` | 处理新增规则的功能 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryRulesetAddRulesetButton`

用于替换添加规则的默认按钮 .

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `RuleSet` | 当前包含儿童规则列表的规则集对象 |
| `addRuleSet` | `() => void` | 处理添加新规则集的函数 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryRulesetRemoveButton`

用于替换删除规则的默认按钮 .

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `RuleSet` | 当前包含儿童规则列表的规则集对象 |
| `removeRuleSet` | `() => void` | 处理删除当前规则集的函数 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryEntity`

用于替换实体选择组件.

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `Rule` | 当前包含字段、值和运算符的规则对象 |
| `entities` | `Entity[]` | 构成部分实体清单,按 `config` |
| `onChange` | `(entityValue: string, rule: Rule) => void` | 回调处理实体组件的更改 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryField`

使用此指令来取代查询字段选择组件.

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `Rule` | 当前包含字段、值和运算符的规则对象 |
| `getFields` | `(entityName: string) => void` | 获取对应实体的字段列表 |
| `fields` | `Field[]` | 该组件的字段列表, 由 `config` |
| `onChange` | `(fieldValue: string, rule: Rule) => void` | 回调处理外地组件的更改 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryOperator`

用于替换查询运算符选择组件.

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `Rule` | 当前包含字段、值和运算符的规则对象 |
| `operators` | `string[]` | 字段运算符列表,由 `getOperators` |
| `onChange` | `() => void` | 回调处理操作员组件的更改 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryInput`

用于替换输入组件. 指定类型/queryInputType,以匹配特定的字段类型到输入模板.

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `Rule` | 当前包含字段、值和运算符的规则对象 |
| `field` | `Field` | 当前包含字段值和名称的字段对象 |
| `options` | `Option[]` | 字段选项列表,由 `getOptions` |
| `onChange` | `() => void` | 回调处理输入组件的更改 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryRuleRemoveButton`

替换默认指令删除单个规则按钮组件 .

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `Rule` | 当前包含字段、值和运算符的规则对象 |
| `removeRule` | `(rule: Rule) => void` | 处理删除规则的函数 |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

#### `queryEmptyWarning`

可用于自定义默认的空警告消息,也可以指定 `emptyMessage` 财产约束.

| 上下文名称 | 类型 | 说明 |
| :-- | :-- | :-- |
| `$implicit` | `RuleSet` | 当前包含儿童规则列表的规则集对象 |
| `message` | `string` | 传入的值 `emptyMessage` |
| `getDisabledState` | `() => boolean` | 获取或确定组件的已禁用状态 |

## 依赖关系

-   角 18 + 变相

# 发展

## 备忘

-   `pnpm watch`
-   `pnpm start`
-   http://localhost:4200 查看演示

### 演示预览

![demo](https://npmcn.com/projects/ngx-query-builder-demo/preview/1.png) ![demo](https://npmcn.com/projects/ngx-query-builder-demo/preview/2.png)

### 代码结构

-   BaseQuery 构建器( 逻辑容器 - 隐藏)
    -   查询构建组件( Root 组件 -) **导出**(中文(简体) )
    -   内部查询构建组件( 递归组件 - 隐藏)

## 构建

-   `pnpm build`

## 发布

```bash
cd dist/ngx-query-builder
npm publish --access public
```

## 用于其他地方项目

```bash
cd dist/ngx-query-builder
npm link

cd /path/to/other/project
npm link ngx-query-builder
```

就是这样.

## 常见问题

### @eliot-ragueneau/ngx-query-builder 是什么？

\[\(https://i\) \(中文\(简体\) \)

### 如何安装 @eliot-ragueneau/ngx-query-builder？

在项目目录运行 npm install @eliot-ragueneau/ngx-query-builder，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@angular/common（^20\.0\.0）、@angular/core（^20\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @eliot-ragueneau/ngx-query-builder 支持 TypeScript 吗？

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

### @eliot-ragueneau/ngx-query-builder 支持 ESM 还是 CommonJS？

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

### @eliot-ragueneau/ngx-query-builder 可以商用吗？

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

### @eliot-ragueneau/ngx-query-builder 的下载量有多少？

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

### @eliot-ragueneau/ngx-query-builder 还在维护吗？

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