# @dirupt/adonis-lucid-filter 中文文档 规范地址：https://npmcn.com/package/%40dirupt/adonis-lucid-filter/ 版本：6\.0\.3 npm 元数据更新时间：2026-07-10T14:51:23.466Z 中文译文更新时间：2026-11-12T11:16:39.302Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dirupt/adonis-lucid-filter 原文对照：https://npmcn.com/package/%40dirupt/adonis-lucid-filter/?lang=original 项目主页：https://github.com/dirupt-agency/adonis-lucid-filter#readme 源码仓库：https://github.com/dirupt-agency/adonis-lucid-filter ## 关键信息（来自 npm 元数据） - 包体积（解压后）：61.4 kB，37 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=24\.0\.0 - 运行依赖：1 个 - peer 依赖：@adonisjs/core ^7\.0\.0，@adonisjs/lucid ^22\.0\.0，lodash ^4\.17\.21 - 首次发布：2026-03-06T20:58:56.158Z - 最新版本发布：2026-07-10T14:51:23.113Z - 近 30 天下载量：9456（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：4（近 12 个月 4 个） ## 中文简介 用于过滤 AdonisJS Lucid ORM( 与 AdonisJS v7 支持的叉子) 的添加 ## 安装 ```sh npm install @dirupt/adonis-lucid-filter ``` 也可以使用：`pnpm add @dirupt/adonis-lucid-filter`、`yarn add @dirupt/adonis-lucid-filter`、`bun add @dirupt/adonis-lucid-filter` ## README # @ dirupt/adonis-lucid-filter (英语) > 叉子为 [adonis-lucid-过滤器](https://github.com/lookinlab/adonis-lucid-filter) 拥有 AdonisJS v7 支持 [![npm-image](https://img.shields.io/npm/v/@dirupt/adonis-lucid-filter?logo=npm&style=for-the-badge)](https://www.npmjs.com/package/@dirupt/adonis-lucid-filter) [![ci-image](https://img.shields.io/github/actions/workflow/status/dirupt-agency/adonis-lucid-filter/ci.yml?branch=master&style=for-the-badge&logo=github&label=CI)](https://github.com/dirupt-agency/adonis-lucid-filter/actions/workflows/ci.yml) [![license-image](https://img.shields.io/npm/l/@dirupt/adonis-lucid-filter?style=for-the-badge&color=blueviolet)](https://github.com/dirupt-agency/adonis-lucid-filter/blob/master/LICENSE.md) [![typescript-image](https://img.shields.io/npm/types/@dirupt/adonis-lucid-filter?color=294E80&label=%20&logo=typescript&style=for-the-badge)](https://github.com/dirupt) 这个加通增加了过滤Lucid Models的功能. > 灵感来自 [朗诵片](https://github.com/Tucker-Eric/EloquentFilter) 原著作者: [看安东](https://github.com/lookinlab) ## 贷项 这个包是叉子 [`adonis-lucid-filter`](https://github.com/lookinlab/adonis-lucid-filter) 以 [寻找Lab](https://github.com/lookinlab),更新为 AdonisJS v7 兼容性。 原执行的功劳全部归原作者. ## 版本数 | @ dirupt/adonis-lucid-filter (英语) | @ adonisjs/ lucid (英语) | 阿多尼斯·贾克 | | --- | --- | --- | | ^6. \*. \* 翻译: | ^22.\* (中文(简体) ) | ưμ㼯a | 对于 AdonisJS v6 ,使用原始软件包: [`adonis-lucid-filter@^5`](https://github.com/lookinlab/adonis-lucid-filter) ## 从 `adonis-lucid-filter` 如果你是从上游来的 `adonis-lucid-filter` 软件包,迁移是直接的: ```bash pnpm remove adonis-lucid-filter pnpm add @dirupt/adonis-lucid-filter ``` 然后更新代码库的进口: ```diff - import { BaseModelFilter, Filterable } from 'adonis-lucid-filter' + import { BaseModelFilter, Filterable } from '@dirupt/adonis-lucid-filter' ``` 并更新你的 `adonisrc.ts`数字 : ```diff providers: [ - () => import('adonis-lucid-filter/provider'), + () => import('@dirupt/adonis-lucid-filter/provider'), ], commands: [ - () => import('adonis-lucid-filter/commands') + () => import('@dirupt/adonis-lucid-filter/commands') ] ``` > 不同时安装两个软件包, 它们会扩展相同的 `ModelQueryBuilder` 并且会发生冲突. ## 导言 示例,我们希望返回一个被多个参数过滤的用户列表. 当我们导航到: `/users?name=Tony&lastName=&companyId=2&industry=5` `request.all()` 或者说 `request.qs()` 将返回 : ```json { "name": "Tony", "lastName": "", "companyId": 2, "industry": 5 } ``` 为了过滤所有这些参数,我们需要做一些诸如: ```ts import type { HttpContext } from '@adonisjs/core/http' import User from '#models/user' export default class UsersController { async index({ request }: HttpContext): Promise { const { companyId, lastName, name, industry } = request.qs() const query = User.query().where('company_id', +companyId) if (lastName) { query.where('last_name', 'LIKE', `%${lastName}%`) } if (name) { query.where(function () { this.where('first_name', 'LIKE', `%${name}%`) .orWhere('last_name', 'LIKE', `%${name}%`) }) } return query.exec() } } ``` 要用 Lucid 过滤器过滤同样的输入 : ```ts import type { HttpContext } from '@adonisjs/core/http' import User from '#models/user' export default class UsersController { async index({ request }: HttpContext): Promise { return User.filter(request.qs()).exec() } } ``` ## 安装 > 需要节点.js 24+和类型脚本 `strict: true` 对于过滤器输入的完整类型推论. ```bash pnpm add @dirupt/adonis-lucid-filter ``` 安装后调用 `configure`数字 : ```bash node ace configure @dirupt/adonis-lucid-filter ``` ## 使用量 请在内部注册提供者和命令 `adonisrc.ts` 文档. ```ts providers: [ // ... () => import('@dirupt/adonis-lucid-filter/provider'), ], commands: [ // ... () => import('@dirupt/adonis-lucid-filter/commands') ] ``` ### 生成过滤器 您可以使用以下 A 命令创建模型过滤器: ```bash node ace make:filter user ``` 何处 `user` 您正在创建过滤器的 Lucid 模型 。 这将创建 `app/models/filters/user_filter.ts` ### 定义过滤逻辑 根据骆驼大小写输入键传递到 `filter()` 方法. - 空字符串被忽略 - `setup()` 将调用,不论输入 - `_id` 从输入的末尾删除以定义方法这样过滤 `user_id` 将使用 `user()` 方法 - 没有相应过滤方法的输入被忽略 - 键的值注入到方法中 - 所有值都可通过 `this.$input` 属性 - 所有查询构建方法都可以在 `this.$query` 在模型过滤类中的对象. 确定下列输入的方法: ```json { "companyId": 5, "name": "Tony", "mobilePhone": "888555" } ``` 您将使用下列方法: ```ts import { BaseModelFilter } from '@dirupt/adonis-lucid-filter' import type { ModelQueryBuilderContract } from '@adonisjs/lucid/types/model' import User from '#models/user' export default class UserFilter extends BaseModelFilter { declare $query: ModelQueryBuilderContract static blacklist: string[] = ['secretMethod'] company(id: number) { this.$query.where('company_id', id) } name(name: string) { this.$query.where((builder) => { builder .where('first_name', 'LIKE', `%${name}%`) .orWhere('last_name', 'LIKE', `%${name}%`) }) } mobilePhone(phone: string) { this.$query.where('mobile_phone', 'LIKE', `${phone}%`) } secretMethod(secretParameter: any) { this.$query.where('some_column', true) } } ``` #### 黑名单 表格中定义的任何方法 `blacklist` 数组将不会被过滤器调用 。 这些方法通常用于内部过滤逻辑. 这个 `whitelistMethod()` 方法可用于动态白名单方法. 示例 ```ts setup($query) { this.whitelistMethod('secretMethod') this.$query.where('is_admin', true) } ``` > `setup()` 可能不会同步 #### 静态属性 ```ts export default class UserFilter extends BaseModelFilter { // Blacklisted methods static blacklist: string[] = [] // Dropped `_id` from the end of the input static dropId: boolean = true // Convert input keys to camelCase method names static camelCase: boolean = true } ``` ### 将过滤器应用到模型 ```ts import UserFilter from '#models/filters/user_filter' import { compose } from '@adonisjs/core/helpers' import { Filterable } from '@dirupt/adonis-lucid-filter' export default class User extends compose(BaseModel, Filterable) { static $filter = () => UserFilter // ...columns and props } ``` 这让你可以访问 `filter()` 接受输入对象的方法 : ```ts import type { HttpContext } from '@adonisjs/core/http' import User from '#models/user' export default class UsersController { async index({ request }: HttpContext): Promise { return User.filter(request.qs()).exec() } // or with paginate method async index({ request }: HttpContext): Promise> { const { page = 1, ...input } = request.qs() return User.filter(input).paginate(page, 15) } } ``` ### 动态过滤器 您可以通过传递过滤器来动态地定义过滤器,以作为过滤器()方法的第二个参数. ```ts import type { HttpContext } from '@adonisjs/core/http' import AdminFilter from '#models/filters/admin_filter' import UserFilter from '#models/filters/user_filter' export default class UsersController { async index({ request, auth }: HttpContext): Promise { const filter = auth.user.isAdmin() ? AdminFilter : UserFilter return User.filter(request.qs(), filter).exec() } } ``` ### 过滤关系 用于过滤您可能使用的模型关系 `.query().filter()` 范围 `filtration`数字 : ```ts import type { HttpContext } from '@adonisjs/core/http' import User from '#models/user' export default class UserPostsController { async index({ params, request }: HttpContext): Promise { const user: User = await User.findOrFail(params.user_id) return user.related('posts').query() .apply(scopes => scopes.filtration(request.qs())) .exec() // or return user.related('posts').query().filter(request.qs()).exec() } } ``` > 关系模型必须有 `Filterable` 混合和 `$filter` 必须定义 ### 类型安全输入 包会暴露一个 `InputObject<>` 帮助推断直接从过滤类接受输入密钥 。 两者 `snake_case`, (中文(简体) ), `camelCase` 财务报告和审定财务报表 `_id` 可识别的变体: ```ts import type { InputObject } from '@dirupt/adonis-lucid-filter/types/filter' import type UserFilter from '#models/filters/user_filter' type UserFilterInput = InputObject // → { company?: number; companyId?: number; company_id?: number; // name?: string; mobilePhone?: string; mobile_phone?: string; ... } // Useful to type request payloads or DTOs: async index({ request }: HttpContext) { const input = request.qs() as UserFilterInput return User.filter(input).exec() } ``` 您的 IDE 将根据您所声明的方法自动完成合法密钥 `UserFilter`。 。 。 . ## 许可证 [麻省理工学院](https://npmcn.com/package/%40dirupt/adonis-lucid-filter/LICENSE.md) ## 常见问题 ### @dirupt/adonis-lucid-filter 是什么？ 用于过滤 AdonisJS Lucid ORM\( 与 AdonisJS v7 支持的叉子\) 的添加 ### 如何安装 @dirupt/adonis-lucid-filter？ 在项目目录运行 npm install @dirupt/adonis-lucid-filter，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@adonisjs/core（^7\.0\.0）、@adonisjs/lucid（^22\.0\.0）、lodash（^4\.17\.21）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @dirupt/adonis-lucid-filter 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @dirupt/adonis-lucid-filter 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @dirupt/adonis-lucid-filter 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @dirupt/adonis-lucid-filter 可以商用吗？ @dirupt/adonis-lucid-filter 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @dirupt/adonis-lucid-filter 的下载量有多少？ 根据 npm 官方下载统计，@dirupt/adonis-lucid-filter 在 2026/10/13 – 2026/11/11 这 30 天内被下载 9,456 次，日均约 315 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @dirupt/adonis-lucid-filter 还在维护吗？ 最新版本 6\.0\.3 发布于 2026/07/10（4 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/03/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。