插件分享｜NocoBase 2.2.x 快捷筛选插件，兼容 V1 / V2 页面
大家好，分享一个用AI开发的 NocoBase 插件：快捷筛选（Quick Filter）。
在实际项目中，表格经常需要按状态、分类、业务类型等字段反复筛选。每次打开完整筛选面板、选择字段和条件，会多出不少操作。这个插件可以把常用筛选条件直接放到表格操作栏中，让用户通过下拉框、按钮、多选按钮或文本搜索框快速完成筛选。
插件同时支持 NocoBase V1 Schema 页面和 V2 FlowEngine 页面，目前面向 NocoBase 2.2.x，以 2.2.10 的接口进行开发和源码校验。
主要功能
1. 三种选项筛选样式
对于状态、分类、标签等具有固定选项的字段，可以选择以下显示方式：
- 下拉选择
- 单选按钮
- 多选按钮/复选框
选项型快捷筛选在选择后立即生效，并支持配置默认值、候选值范围、是否多选以及筛选运算符。
2. 文本框快速搜索
对于名称、编号、电话、邮箱、网址、备注等文本内容，可以将快捷筛选显示为搜索框。
文本搜索不会在输入每个字符时立即刷新数据，而是在以下操作后执行：
- 点击“搜索”按钮；
- 在输入框中按 Enter。
这样可以避免输入过程中连续发起请求。清空输入框后再次点击搜索或按 Enter，即可移除当前文本筛选。
文本筛选支持以下运算符：
- 包含；
- 不包含；
- 等于；
- 不等于。
3. 每个筛选对象可单独设置“独占一行”
在快捷筛选的配置窗口中，可以为每个对象单独勾选“独占一行”：
- 勾选：该快捷筛选独占一整行；
- 不勾选：与其他快捷筛选横向排列，空间不足时自动换行。
无论左侧配置多少个快捷筛选，右侧的刷新、新增、自定义操作等按钮都会保持在右侧，不会被挤到下一行。
4. 多个筛选条件可以组合使用
同一表格可以添加多个快捷筛选。插件会将它们与以下条件共同合并：
- 其他快捷筛选；
- NocoBase 原生普通筛选；
- 数据区块自身的数据范围。
清空某一个快捷筛选时，只会移除它自己的条件，不会影响其他已生效的筛选。
5. 同时兼容 V1 与 V2 页面
插件分别实现了 V1 和 V2 的适配层：
- V1 页面通过 Schema 初始化器和组件设置完成添加、配置、拖动和删除；
- V2 页面通过独立的 ActionModel 和 FlowEngine 筛选组工作。
两种页面的配置界面会根据字段类型自动区分“选项筛选”和“文本搜索”，不会把文本字段当成下拉选项使用。
【V1 页面配置】
【V2 页面配置】
支持的字段
选项型字段
| 字段接口 | 常见用途 |
|---|---|
select |
下拉单选 |
dictDataSingle |
字典单选 |
radioGroup |
单选框组 |
checkboxGroup |
复选框组 |
multipleSelect |
下拉多选 |
approvalStatus |
审批状态 |
文本型字段
| 字段接口 | 常见用途 |
|---|---|
input |
单行文本、名称、编号 |
textarea |
多行文本、备注 |
email |
邮箱 |
phone |
电话号码 |
url |
网址 |
兼容范围
| 项目 | 支持情况 |
|---|---|
| NocoBase | >=2.2.0 <2.3.0 |
| 开发与校验版本 | 2.2.10 |
| 页面引擎 | V1 Schema、V2 FlowEngine |
| Node.js | 22 及以上 |
| 新增业务数据表 | 不需要 |
| 许可证 | AGPL-3.0-only |
安装方法
方法一：使用发行包
普通用户建议前往 GitHub Releases 下载最新的 .tgz 发行包：
如果你的部署环境提供 NocoBase CLI，可以参考以下流程：
nb plugin import /你的路径/plugin-quick-filter-版本号.tgz
nb app restart
nb plugin enable @xiezuo/plugin-quick-filter
第一次安装时需要启用插件；后续升级通常重新导入新包并重启应用即可。不同部署方式请以 NocoBase 官方的第三方插件安装说明为准。
方法二：从源码编译
将仓库克隆到 NocoBase 项目的插件目录：
git clone https://github.com/charce526/plugin-quick-filter.git \
packages/plugins/@xiezuo/plugin-quick-filter
在 NocoBase 项目根目录安装依赖后，可以执行：
yarn build @xiezuo/plugin-quick-filter --tar
该命令会完成构建并生成 .tgz 包。随后按照上面的发行包方式导入目标应用。构建和打包流程也可以参考 NocoBase 官方的插件构建与打包文档。
如果 GitHub Releases 尚未发布与 main 分支对应的新版本，而你希望体验最新功能，请选择源码编译；希望安装更稳定、方便回退的版本，则建议使用 Releases 中的发行包。
使用方法
V1 页面
- 开启 UI 配置模式；
- 在表格操作栏点击“配置操作”；
- 选择“快捷筛选”；
- 选择目标字段并完成初始配置；
- 通过组件设置菜单继续配置标题、提示信息、默认值、运算符、候选值和“独占一行”。
V2 页面
- 开启 UI 配置模式；
- 在表格操作区点击“添加操作”；
- 展开“快捷筛选”并选择目标字段；
- 在快捷筛选设置中配置基本设置、显示设置以及值和运算符。
项目链接
- GitHub 仓库：GitHub - charce526/plugin-quick-filter: 一款NocoBase快捷筛选插件，为NocoBase数据表格操作栏提供可配置的选项快捷筛选与文本搜索，同时兼容 V1 Schema 页面与 V2 FlowEngine 页面。 · GitHub
- Releases：Releases · charce526/plugin-quick-filter · GitHub
- 问题反馈：Issues · charce526/plugin-quick-filter · GitHub
其他说明
插件完全由AI编写，感谢有巢数智公开分享「快速筛选」插件说明。AI基于该说明进行了最初的需求梳理，交互设计中参考并学习了该说明文档。