# 动态过滤

# 动态过滤定义

动态过滤(Dynamic Filter)是显示在列表页面中，用于用户快速的对列表附加过滤条件的客制化。

其显示效果如下图：

Dynamic Filter Display Effect

通过菜单 System Configuration > Forms > Filters 维护动态过滤的定义，其创建和编辑表单如下：

相关字段说明如下：

字段	描述
Organization	所属组织，只能是允许客制化的组织
Name	名称，在组织内唯一，创建后不允许修改
Label	界面显示名称
Icon	界面显示时，名称前显示的小图标
Display sequence	界面显示的顺序，越小越靠前
Description	界面上鼠标放到名称上时候显示的帮助信息
Object type	关联的 Domain 类型
Enable for roles	限制哪些用户可以看到该动态 filter, 如果希望所有用户均可用，设置为 ROLE_USER
Is default	是否为默认 filter, 默认 filter 是用户进入列表页面，系统自动应用的 filter
Conditions	过滤的条件定义

Condition 的定义使用一段 JSON 格式来描述匹配规则，采用如下的格式：

// 下面的动态过滤条件的说明：
// 1. 状态字段等于 SUCCESS
// 2. type 是 FINDER, UPDATE 中的一个
// Below is the description of the dynamic filter conditions:
// 1. The status field is equal to SUCCESS
// 2. type is one of FINDER, UPDATE
{
  // key 是列名称： status 
  // key is the column name: status 
  "status": {  
    // 过滤的目标列
    // The target column to filter
    "columnKey": "status", 
    // 匹配规则：等于
    // Match rule: equal
    "matchMode": "=",      
    // 匹配的目标值： SUCCESS
    // Matching target value: SUCCESS
    "value": "SUCCESS",   
  },
  "type": { // key 是列名称: type
    // 过滤的目标列, 与上一行的 key 相同
    // The target column to filter, same as the key in the previous line
    "columnKey": "type",           
    // 过滤的匹配规则：isOneOf (是其中某一个)
    // Filter matching rule: isOneOf (is one of them)
    // 过滤的目标值: [FINDER, UPDATE]
    // Matching target value: [FINDER, UPDATE]
    "value": ["FINDER", "UPDATE"]  
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

对匹配的相关模式，规则等的详细描述如下。

# 可用匹配模式

如下列出了可用的匹配模式

匹配模式	说明	适用数据类型
=	等于	除一对多，多对多关联的所有类型
!=	不等于	除一对多，多对多关联的所有类型
>	大于	数字
<	小于	数字
>=	大于等于	数字
<=	小于等于	数字
after	日期，在 ... 之后	日期
before	日期，在 ... 之前	日期
afterOrEqual	日期，等于 ... 或在 ... 之后	日期
beforeOrEqual	日期，等于 ... 或在 ... 之前	日期
isOneOf	是其中的某一个	除一对多，多对多关联的所有类型
isNotAnyOf	不是列表中的任一个	除一对多，多对多关联的所有类型
endsWith	以 ... 结尾	字符
startsWith	以 ... 开头	字符
contains	包含 ...	字符
notContains	不包含 ...	字符
hasNoRelated	该字段不包含关联数据	一对多关联
hasRelated	该字段包含关联数据	一对多关联
isNotEmpty	不为空	除一对多，多对多关联的所有类型
isEmpty	为空	除一对多，多对多关联的所有类型

# 不同字段类型匹配

# 关联关系的匹配

一对多关联关系支持 hasRelated 和 hasNoRelated 的匹配，分别表示关联多端是否有关联对象。
一对一关联关系支持 =, !=, isOneOf, isNotAnyOf, isNotEmpty, isEmpty 类型的匹配。

# Enum 字段的匹配

Enum 字段的匹配值使用 Enum 定义的 name 进行匹配, 比如如下的 Enum 定义，使用 ONLY_LABEL_FIELD, EXCLUDE_ARRAY_COLUMNS, ALL_COLUMNS 这三个值进行匹配

enum FetchType {
  ONLY_LABEL_FIELD("Fetch label field"),
  EXCLUDE_ARRAY_COLUMNS("Fetch columns not of type array"),
  ALL_COLUMNS("Fetch all columns");
}

1
2
3
4
5

# 其他类型字段的匹配

boolean 字段的匹配值直接使用不带引号的 true 和 false
数字类型的匹配值直接使用不带引号的数字
如果匹配的值要求是数组，则使用 [] 将匹配值包含其中
日期时间的匹配请使用如下格式: yyyy-MM-dd HH:mm:ss (2021-08-23 07:57:49)
不带时间的日期匹配请使用如下格式： yyyy-MM-dd

提示

Dynamic Filter 的 conditions 字段格式与页面往后台发送的搜索请求中的搜索条件的格式一致。

开发时，可以先使用界面上的搜索功能，设定正确的搜索条件，然后监控页面往后台发送的 POST 搜索请求中的请求数据 body，使用该请求数据作为预定义的 Dynamic Filter 的 conditions 字段值。

# 动态匹配条件

在 Dynamic Filter 的匹配条件中，可以使用如下的动态匹配条件

占位符	匹配条件说明
`${currentUsername}`	当前登陆用户的用户名
`${currentOrganization}`	当前登陆用户的所属组织名称
`${currentHour}`	当前小时零分的时间
`${currentDay}`	当前日期零点的时间
`${currentWeek}`	当前星期的星期一的零点
`${currentMonth}`	当前月的第一天零点
`${currentQuarter}`	当前季度第一天的零点
`${currentYear}`	当前年的一月一日零点
`${currentUserGroups}`	当前用户所属的所有用户组名称列表

提示

当前用户所属用户组是一个列表，在格式化为过滤条件的时候，会被格式化为 ['groups', 'group2'] 的格式，因此需要将其作为一个列表进行条件匹配。如下是一个使用 isOneOf 规则进行匹配的例子:

"{
  "conditions": {
    "directFavoriteGroups.name": {
      "value": "${currentUserGroups}",
      "columnKey": "directFavoriteGroups.name",
      "matchMode": "isOneOf"
    }
  }
}"

1
2
3
4
5
6
7
8
9

# 用户自定义动态过滤器

用户可以将当前的搜索条件保存为动态过滤器。保存后，它将显示在动态过滤器列表中，用户只需一键点击即可筛选数据。

要创建自定义动态过滤器：

在列表页面设置所需的搜索条件。
点击"Create dynamic filter"按钮。
在弹出的对话框中，输入过滤器名称和描述（可选）。
如果希望此过滤器在进入页面时自动应用，勾选"Is Default"选项。
点击"Save"保存新的动态过滤器。

保存后，新的动态过滤器将出现在页面顶部的过滤器列表中。用户可以通过点击相应的过滤器名称来快速应用它。

这种自定义动态过滤器功能使用户能够快速访问常用的搜索条件，提高工作效率。

← 📃 基础表单 🎛️ 动态字段 →