# @ballistix\.digital/odata-query-builder 中文文档

规范地址：https://npmcn.com/package/%40ballistix.digital/odata-query-builder/

版本：0\.12\.0
npm 元数据更新时间：2026-10-23T14:29:32.469Z
中文译文更新时间：2026-11-07T21:56:44.010Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ballistix.digital/odata-query-builder
原文对照：https://npmcn.com/package/%40ballistix.digital/odata-query-builder/?lang=original
项目主页：https://github.com/layeredprints/odata-query-builder#readme
源码仓库：https://github.com/layeredprints/odata-query-builder

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

- 包体积（解压后）：128 kB，86 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-22T12:37:02.419Z
- 最新版本发布：2026-10-23T14:29:32.296Z
- 近 30 天下载量：2323（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

为方言@ballistix.digital/typeorm-extensions服务的打字,流利的OData v4查询字符串构建器.

## 安装

```sh
npm install @ballistix.digital/odata-query-builder
```

也可以使用：`pnpm add @ballistix.digital/odata-query-builder`、`yarn add @ballistix.digital/odata-query-builder`、`bun add @ballistix.digital/odata-query-builder`

## README

# @ballistix. digital/odata-query-buildinger (中文(简体) )

OData v4 查询字符串的打入流畅的构建器 `@ballistix.digital/typeorm-extensions` 服务.

它建立了一个 **查询字符串**它不获取,它不知道 `_embedded` 编号 : `_page` 反应信封。 它已经 **零运行时间依赖关系**。 。 。 .

完整的文献资料 [`docs/`](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/index.md)(单位:千美元) [指南](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/guide/index.md) 用于使用软件包的开发者,以及 [维护者页面](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/maintainer/index.md) 对于一个改变它的开发者.

## 安装

```sh
npm i @ballistix.digital/odata-query-builder
```

它需要节点20或更新,以及TypeScript 5.9, 6.0或 7.0.

## 示例

```ts
import { odataQuery } from '@ballistix.digital/odata-query-builder';

enum ProjectStatusEnum {
  DRAFT = 'draft',
  ACTIVE = 'active',
  ARCHIVED = 'archived',
}

// ProjectDto is your own DTO type. Getting started shows its shape.
const query = odataQuery<ProjectDto>()
  .filter((v, o) =>
    o.and(
      v.archived.isFalse(),
      v.status.in([ProjectStatusEnum.DRAFT, ProjectStatusEnum.ACTIVE]),
      v.children.any((a) => a.priority.ge(2)),
    ),
  )
  .select('id', 'name', 'status')
  .expand.parent((p) => p.select('name').expand.owner((u) => u.select('fullName')))
  .orderBy('name', 'desc')
  .top(25)
  .count()
  .toQueryString();
// $filter=archived eq false and status in ('draft','active') and children/any(a:a/priority ge 2)&$select=id,name,status&$expand=parent($select=name;$expand=owner($select=fullName))&$orderby=name desc&$top=25&$count=true
```

[开始](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/guide/getting-started.md#the-one-assumption-_embedded) 打印 `ProjectDto` 形状.

## 是什么使它输入

范围a `filter()` 接收的回调仅取自 DTO 类型 :

-   自己的平面柱成为由柱子本身类型所打入的表达式,所以 a. enum 列取 enum 成员,而数字列拒绝字符串;
-   (单位:千美元) `_embedded` 至一关系成为嵌入范围,与 `/`· ;
-   (单位:千美元) `_embedded` 和很多关系成为了羊肉的命名空间,所以 `any` 财务报告和审定财务报表 `all` 唯一能够达到的东西——这是服务器接受的;
-   原始数组列( e)`text[]`变成一个羊肉的命名空间 键.

`expand.<relation>` 确切列出关系 `_embedded` 声明 有一个 没有代码生成, 没有 `$metadata` 文档,没有配置: DTO 公约是 `_embedded`,图书馆也假设.

## 属性读取从来不是一种方法

`v.year` 运行时模糊: `year()` 函数,或称列 `year`因此,读取一个属性永远不会解决一个函数。 更多信息 从它开始,它是一个路径段, 它叫它,它是一个函数。 两个角色 在一个表达式中工作:

```ts
v.year.eq(v.date.asDate().year());
// year eq year(date)
```

## 逃跑

`toQueryString()` 已经是 URL 安全 . **别** 运行 `encodeURIComponent` 结束 转弯 `%25` 输入 `%2525`。 。 。 . [逃跑规则](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/guide/sending-the-query.md#the-escape-rules) 列出什么 每个字面字符都变成.

使用 `toParams()` 当呼叫者有自己的序列器时(`URLSearchParams`, (中文(简体) ), ky:它把原始值拿回去 这样连载器自己的编码是唯一的 一个申请.

## 文档

-   [开始](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/guide/getting-started.md) - 安装、安装 `_embedded` 假设,第一个查询.
-   [查询](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/guide/querying.md) 每一个动词 `expand` 命名空间、 过滤扩展和 `odataItem`。 。 。 .
-   [过滤](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/guide/filtering.md) - 操作员、功能、羊肉、日期、, `cast` 以及配器.
-   [发送查询](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/guide/sending-the-query.md) —— 说 `toQueryString()` 或者说 `toParams()`和逃跑规则.
-   [错误](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/guide/errors.md) ——建设者抛出什么来,如何抓住.
-   [烹饪本](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/guide/cookbook.md) - 十二个调用形状与他们的弦.

## 捐款

要运行测试 寻找你的方式 在源头,阅读 [公约](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/maintainer/conventions.md#run-the-repository-locally) 财务报告和审定财务报表 [测试](https://npmcn.com/package/%40ballistix.digital/odata-query-builder/docs/maintainer/testing.md#the-five-tiers)。 。 。 .

## 常见问题

### @ballistix\.digital/odata-query-builder 是什么？

为方言@ballistix\.digital/typeorm-extensions服务的打字,流利的OData v4查询字符串构建器\.

### 如何安装 @ballistix\.digital/odata-query-builder？

在项目目录运行 npm install @ballistix\.digital/odata-query-builder，或使用 pnpm add / yarn add / bun add。

### @ballistix\.digital/odata-query-builder 支持 TypeScript 吗？

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

### @ballistix\.digital/odata-query-builder 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @ballistix\.digital/odata-query-builder 需要什么版本的 Node\.js？

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

### @ballistix\.digital/odata-query-builder 可以商用吗？

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

### @ballistix\.digital/odata-query-builder 的下载量有多少？

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

### @ballistix\.digital/odata-query-builder 还在维护吗？

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