过滤

概述

过滤属性（'F'）允许你设置模板内数据过滤的类型。此属性提供了两种过滤选项：条件过滤（Conditional）和切片过滤（Slice filters）。你可以单独使用这些过滤选项，或结合使用来从表格中过滤数据。此属性可以从单个或多个表格中过滤数据，以生成报告。

GcExcel 仅支持在常规数据源上使用过滤属性，如 java.sql.ResultSet 或 ITableDataSource。

过滤属性

条件过滤器

条件过滤器使用运算符和 AND、OR、NOT 以及 LIKE 等的关键字来过滤数据。LIKE 关键字和比较运算符具有最高优先级，将首先被评估。对于其余的关键字，其优先级顺序为：NOT > AND > OR。此外，使用成对的括号可以自定义这些运算符和关键字评估的操作顺序。

值类型: 表达式

F/Filter = (field1 > 1 AND field2 = 2 OR field3 <> 3)

下表列出了条件过滤器（Conditional Filter）所支持的运算符和关键字：

示例 1：使用运算符进行过滤

{{order.oid(F = (order.count > 10))}}

下图展示了模板如何通过过滤出销售数量大于10的订单来生成报告。您还可以下载下面示例中使用的 Excel 模板布局。

FilterOperator.xlsx

示例 2：使用关键词进行过滤

{{order.oid(F = (order.cid ="C002" and order.pid = "W003"))}}

下面的图示展示了如何通过模板生成一份报告，该报告通过过滤筛选出客户ID为"C002"且产品ID为"W003"的所有订单。你也可以下载在下面示例中所使用的Excel模板布局。

FilterKeyWord.xlsx

示例3：多源报表

{{product.name(F=(product.pid = order.pid))}}

下面的图像展示了模板如何通过从不同的数据表中使用产品ID来筛选产品名称，从而生成一份报告。你也可以下载在下面示例中使用的Excel模板布局。

SimpleMultiDataSource.xlsx

示例4：复杂多源报表

下面的图像展示了模板如何通过从不同的数据表中使用客户ID和产品ID来筛选客户和产品名称，从而生成一份报告。你也可以下载在下面示例中使用的Excel模板布局。

ComplexMultiDataSource.xlsx

切片过滤器

切片过滤器（Slice Filter）通过选取数组中从给定起始索引到给定终止索引的数据来过滤数据，同时还可以定义一个步长，用来确定索引之间的间隔。

值类型：数组

F/Filter = [start:stop:step]

• start 指的是过滤开始的索引位置；

• stop 指的是过滤结束前的索引位置，不包括这个位置本身；

• step 定义了索引间的间隔，即每几个元素选择一个。

例如：使用切片过滤器

{{order.oid(F = [0:20:2])}}

下面的图像是关于模板如何生成报告的示例，该报告通过上述过滤规则筛选出前20个奇数位置的订单。你也可以下载在这个示例中使用的Excel模板布局。

SliceFilter.xlsx

示例：切片过滤反向操作

{{order.oid(F = [20:0:-2])}}

下面的图像展示了模板如何通过从索引20开始反向筛选最后二十个订单来生成报告。你也可以下载在下面示例中所使用的Excel模板布局。

SliceFilterReverseOperation.xlsx

组合过滤条件

你可以结合使用条件过滤器和切片过滤器来生成报告。

示例：组合过滤器

{{order.oid(F = (order.oid like "*1?")[0:5])}}

下面的图像展示了模板如何首先通过匹配表达式 "*1?" 来过滤订单ID，然后从过滤后的结果中选取前五条记录来生成报告。你也可以下载在下面示例中所使用的Excel模板布局。

CombinedFilter.xlsx

过滤空值

GcExcel Java 模板筛选功能支持 NULL 关键字，可根据字段值是否为空来筛选记录。

语法：

• 使用 = NULL 筛选字段值为空的记录。

  {{employee.name(F=(employee.department = NULL))}}

• 使用 <> NULL 筛选字段值不为空的记录。

  {{employee.name(F=(employee.department <> NULL))}}

空值匹配规则

下表展示了 GcExcel Java 在模板筛选中对空值条件的判定规则：

在自定义实现ITableDataSource接口时，需确保getValue方法在缺失数据时返回 DBNull.Value 或原生 null。只有这两种值会被模板筛选引擎识别为空值。空字符串、字符串"null"、自定义占位对象等标记值，都无法被 = NULL 筛选条件匹配，该逻辑与 SQL 语义保持一致。

组合空值筛选条件

可通过逻辑运算符将空值筛选与其他筛选条件组合使用：

使用 NOT（以下两种表达式等效）：

• {{ds1.name(F=(NOT ds1.name = NULL))}}

• {{ds1.name(F=(ds1.name <> NULL))}}

使用 AND / OR：

• {{ds1.name(F=(ds1.name <> NULL AND ds1.age > 18))}}

• {{ds1.name(F=(ds1.name = NULL OR ds1.salary < 50000))}}

示例

下方截图演示了在模板中筛选空值的用法，你也可下载示例所用模板文件：

FilterNullKeywordTemplate.xlsx

你也可以查看演示示例，了解更多空值筛选相关用法。

使用正则表达式筛选值

GcExcel Java 模板筛选支持 REGEX 关键字，用于正则表达式匹配筛选。

语法

{{ds1.name(F=(ds1.name REGEX "pattern"))}}

正则匹配规则

• 非法的正则表达式规则会触发模板处理异常。

• 规则匹配使用 Java 原生正则引擎（java.util.regex），大小写匹配等所有正则行为均遵循平台默认规则。

• 建议仅对数据源中的字符串类型字段使用 REGEX 筛选；其他数据类型会通过 toString 方法转为字符串，不推荐这种用法。数值、日期类型建议使用对应比较运算符或日期时间函数处理。

组合正则筛选条件

REGEX 可与 NOT、AND、OR 以及括号组合使用，示例如下：

• {{ds1.name(F=(NOT ds1.name REGEX "pattern"))}}

• {{ds1.name(F=(ds1.name REGEX "^A" AND ds1.age > 18))}}

正则表达式语法与转义规则

• 正则表达式规则需遵循目标平台原生正则引擎支持的标准语法。

• 在源代码中将模板表达式作为字符串常量编写时，需遵循对应编程语言的字符串转义规则。例如匹配一个或多个数字的正则为 \d+。

• 直接在模板表达式中编写：{{product.pid(F=(product.name REGEX "\d+"))}}。

• 在源代码中编写时，需按规则转义反斜杠和引号："{{product.pid(F=(product.name REGEX \"\\d+\"))}}"。

• 为避免词法解析歧义，正则字符串内部的双引号需转义为 \"。若模板表达式嵌套在编程语言字符串中，还需遵循该语言的转义规则。例如在 C# 中，\" 需要写作 \\\"。

使用限制

Java 正则引擎存在部分功能限制，会影响正则表达式的使用：

• Java 正则仅支持固定长度后行断言，不支持可变长度后行断言（例如：(?<=a.*)b）。

• 不支持字符类减法语法，如 [a-z-[aeiou]]。

• Java 正则仅识别 (?<name>) 格式的命名捕获组。

• 不支持 (?(expr)yes|no) 格式的条件正则表达式规则。

示例

• 筛选名称以 Laptop 开头的商品：

  {{product.pid(F=(product.name REGEX "^Laptop"))}}

• 筛选库存单位匹配年份格式（2024）的商品：

  {{product.pid(F=(product.sku REGEX "2024-\d{3}"))}}

• 正则与其他条件组合筛选：

  {{product.pid(F=(product.name REGEX "^(Laptop|Phone)" AND NOT product.sku REGEX "2023"))}}

• 使用锚点进行整串匹配：

  {{product.pid(F=(product.name REGEX "^Laptop Pro 15$"))}}

• 使用内联标识实现不区分大小写匹配：

  {{product.pid(F=(product.name REGEX "(?i)laptop"))}}

下方截图演示了模板筛选名称以 Laptop 开头商品并生成报表的效果，你也可下载示例模板：

FilterRegexTemplate.xlsx

你也可以查看演示示例，了解更多 REGEX 关键字筛选用法。

日期时间值筛选

模板筛选可通过 DATETIME 函数实现日期和时间的比较。可在模板条件筛选中使用该函数编写日期相关条件，无需在业务代码中对数据做预处理。

语法

DATETIME("dateTimeString")

参数说明

比较规则

• 模板引擎采用字面量值比对方式，直接按年、月、日、时、分、秒、毫秒等分量逐一比较，不做时区转换，比对逻辑固定且精准。

• 对于 DateTimeOffset、ZonedDateTime、OffsetDateTime 等带时区的数据源类型，比较时会忽略时区和偏移信息，仅使用本地日期时间分量。

• 仅传入时间的 DATETIME 常量（如 DATETIME("09:15:00")）与日期时间类型数据源比对时，仅对比时间分量。例如 2024-06-15 09:15:00 和 2024-06-16 09:15:00 均能匹配，而 2024-06-15 10:00:00 无法匹配。

• 仅传入日期的 DATETIME 常量（如 DATETIME("2024-06-15")）与日期时间类型数据源比对时，常量时间部分默认补为 00:00:00.000。仅 2024-06-15 00:00:00 这类值可匹配，2024-06-15 09:15:00 无法匹配。

运算符使用规则

所有比较运算符均执行标准值比对，无隐式区间匹配，等于运算符代表精确匹配。例如 = DATETIME("2024-06-15") 仅匹配精确为 2024-06-15 00:00:00.000 的数据源值。若要匹配当日所有记录，需使用区间写法：>= DATETIME("2024-06-15") AND < DATETIME("2024-06-16")。

支持的数据类型

模板引擎原生支持以下常用日期时间类型：

• System.DateTime

• System.DateTimeOffset

• System.DateOnly

• System.TimeOnly

• System.TimeSpan

不支持的自定义日期时间类型会触发模板处理异常。

与空值的交互规则

DATETIME 函数及日期时间比较逻辑不会与 NULL 关键字联动。对空值字段执行日期时间比较时，判定为不匹配（返回假）。如需筛选空日期值，直接使用 = NULL 或 <> NULL 即可。

示例

• 精确匹配日期时间：

  {{order.oid(F=(order.orderDate = DATETIME("2024-06-15 09:15:00")))}}

• 日期区间筛选——筛选 2024 年 6 月 15 日所有订单：

  {{order.oid(F=(order.orderDate >= DATETIME("2024-06-15") AND order.orderDate < DATETIME("2024-06-16")))}}

  {{order.oid(F=(order.orderDate >= DATETIME("2024-01-01") AND order.orderDate < DATETIME("2024-07-01")))}}

• ISO 8601 格式使用：

  {{order.oid(F=(order.orderDate >= DATETIME("2024-06-15T00:00:00")))}}

• Excel 兼容格式使用：

  {{order.oid(F=(order.orderDate >= DATETIME("06/15/2024")))}}

  {{order.oid(F=(order.orderDate >= DATETIME("Jun 15, 2024")))}}

• 仅筛选时间——上午 8 点及之后的订单：

  {{order.oid(F=(order.orderTime >= DATETIME("08:00")))}}

  {{order.oid(F=(order.orderTime >= DATETIME("09:00") AND order.orderTime < DATETIME("17:00")))}}

• 与其他条件组合筛选：

  {{order.oid(F=(order.orderDate >= DATETIME("2024-01-01") AND order.amount > 500))}}

下方截图演示了模板中日期时间筛选的使用效果，你可下载示例模板：

DateTimeFilterTemplate.xlsx

你也可以查看演示示例，了解更多日期时间值筛选用法。