动态过滤

动态过滤定义

动态过滤（Dynamic Filter）是为某类对象预先定义的一组过滤条件，保存在 DynamicFilter 对象中。旧版本前端把它显示为列表页面上方的过滤页签，用户点击即可快速筛选数据。

当前版本的状态

• 当前前端不调用过滤器接口，列表页面上不会显示任何动态过滤器，也没有「保存为过滤器」的入口。已定义的过滤器（包括系统预置的消息中心「未读 / 跟踪 / 重要」等）暂时不会生效。
• 菜单 开发配置 > 表单 > 过滤器 当前打开后一直停留在加载状态：DynamicFilter 对象没有配置读写权限要求，对象数据接口（/domain/DynamicFilter）对所有用户（包括管理员）返回无权限。需要维护过滤器时，请通过 CSV 导入。
• 如果只是想让某个列表默认带上过滤条件，请使用表单 extInfo 中的 listForm.searchConditions，见 默认过滤条件，它使用与本页相同的条件格式。

过滤器的属性如下：

属性	说明
名称（name）	必填，租户内唯一，创建后不能修改
显示名称（label）	界面显示名称
图标（icon）	名称前显示的图标
显示顺序（displaySequence）	越小越靠前
描述（description）	鼠标悬停在名称上时显示的帮助信息
关联对象类型（objectType）	过滤器作用的对象类型
是否默认（isDefault）	是否为默认过滤器（旧版本前端进入列表页面时自动应用）
是否系统过滤器（isSystem）	系统预置的过滤器为 true，只能通过 CSV 设置
所有者（owner）	用户自定义过滤器的所有者，界面上不可编辑
过滤条件（conditions）	JSON 格式的过滤条件

CSV 导入时使用如下表头（与系统预置种子数据一致）：

name(*),label,displaySequence,conditions,objectType.shortName,isDefault,description,icon,isSystem

UnreadMessageFilter,未读,1,"{""isUnRead"": {""value"": true, ""columnKey"": ""isUnRead"", ""matchMode"": ""=""}}",Message,false,未读消息列表,InboxOutlined,true

过滤条件使用一段 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)
    "matchMode": "isOneOf",
    // 过滤的目标值: [FINDER, UPDATE]
    // Matching target value: [FINDER, UPDATE]
    "value": ["FINDER", "UPDATE"]  
  }
}

每个条件的 key 一般与 columnKey 相同；多个条件之间是「并且」的关系。对匹配模式、规则等的详细描述如下。

可用匹配模式

如下列出了可用的匹配模式，传入表中以外的值时，后端会报错 Unsupported match mode。startsWith、endsWith、contains、notContains 不区分大小写，其余模式区分大小写。

匹配模式	说明	适用数据类型
=	等于	除一对多、多对多关联的所有类型
!=	不等于	除一对多、多对多关联的所有类型
>	大于	数字、日期
<	小于	数字、日期
>=	大于等于	数字、日期
<=	小于等于	数字、日期
after	在 ... 之后，同 >	日期
before	在 ... 之前，同 <	日期
afterOrEqual	等于或在 ... 之后，同 >=	日期
beforeOrEqual	等于或在 ... 之前，同 <=	日期
isOneOf、containsAny	是列表中的某一个	除一对多、多对多关联的所有类型
isNotAnyOf、notContainsAny	不是列表中的任何一个	除一对多、多对多关联的所有类型
startsWith	以 ... 开头	文本
endsWith	以 ... 结尾	文本
contains	包含 ...	文本
notContains	不包含 ...	文本
isEmpty	为空（只匹配 NULL，不匹配空字符串）	除一对多、多对多关联的所有类型
isNotEmpty	不为空（非 NULL，空字符串也算不为空）	除一对多、多对多关联的所有类型

提示

旧版本的 hasRelated、hasNoRelated 1.0 起已不再支持。

不同字段类型匹配

关联关系的匹配

columnKey 支持用点号引用关联对象的字段，例如 customer.name 表示按关联客户的名称匹配，可以多级引用。

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");
}

其他类型字段的匹配

• boolean 字段的匹配值直接使用不带引号的 true 和 false
• 数字类型的匹配值直接使用不带引号的数字
• 如果匹配的值要求是数组，则使用 [] 将匹配值包含其中
• 日期时间的匹配值与下文时间占位符替换后的格式一致：yyyy-MM-dd HH:mm:ss（如 2021-08-23 07:57:49）

动态匹配条件

在过滤条件中，可以使用如下的占位符，返回给前端前会被替换为实际的值。表单和表单字段的 extInfo 中同样可以使用这些占位符（表单字段 extInfo 中的 ${currentUserGroups} 会被替换为空列表 []）。

占位符	替换结果
${currentHour}	当前小时零分零秒的时间
${currentDay}	当前日期零点的时间
${currentWeek}	当前星期的星期一零点
${currentMonth}	当前月的第一天零点
${currentQuarter}	当前季度第一天的零点
${currentYear}	当前年的一月一日零点
${currentUserGroups}	当前用户拥有的角色名称列表，格式为 ['ROLE_USER','ROLE_ADMIN']
${currentUsername}	当前登录用户的用户名，见下方说明
${currentUserId}	当前登录用户的 id，见下方说明

注意

• 当前版本在替换占位符时没有传入当前用户信息，${currentUsername}、${currentUserId} 会被替换为空字符串，暂时无法按当前用户过滤。
• 旧版本的 ${currentOrganization} 1.0 起已移除（平台只有租户，没有组织）。

提示

${currentUserGroups} 是一个列表，替换时连同两侧的引号一起替换为 ['ROLE_USER','ROLE_ADMIN'] 这样的数组，因此要配合 isOneOf 等列表匹配模式使用，并且在 JSON 中必须写成带引号的 "${currentUserGroups}"。下面的例子假设对象上有一个保存角色名称的文本字段 visibleRole，只显示该字段是当前用户所拥有角色之一的记录：

{
  "visibleRole": {
    "value": "${currentUserGroups}",
    "columnKey": "visibleRole",
    "matchMode": "isOneOf"
  }
}