PHPExcel AutoFilter 自定义筛选(Custom Filter)表达式完全指南:通配符、区间过滤与 AND/OR 规则编排
PHPExcel AutoFilter 自定义筛选(Custom Filter)表达式完全指南:通配符、区间过滤与 AND/OR 规则编排
本文是 PHPExcel AutoFilter 参考系列的进阶篇,聚焦于自定义筛选(Custom Filter)表达式:如何在 Excel 兼容的自动筛选中用运算符 + 值构建复杂条件,例如"以字母 U 开头"的文本通配匹配、"介于 -20 与 +20 之间"的数值区间过滤,以及如何通过 AND / OR 连接规则。读完本文,你将掌握 AUTOFILTER_FILTERTYPE_CUSTOMFILTER 类型的完整用法、* / ? / ~ 通配符语义、六种运算符的常量取值,并能结合实际源码理解规则在读写两端(Reader / Writer)的落地机制。
一、什么是自定义筛选:从单一条件到"运算符 + 值"
在 04-01-Autofilter-Expressions-Simple.md 中介绍的基础筛选(Filter)只能做等值匹配;而在 MS Excel 中,**自定义筛选(Custom filter)**允许我们使用"运算符 + 值"的组合来定义更复杂的条件。典型场景包括:
- 数值落在某个区间内,例如"介于 -20 和 +20 之间";
- 带通配符的文本匹配,例如"以字母 U 开头"。
为此,PHPExcel 在自动筛选列对象上提供了专门的筛选类型 AUTOFILTER_FILTERTYPE_CUSTOMFILTER。从 Column.php 的常量定义可以看到,一个列支持四类筛选类型:
| 筛选类型常量 | 值 | 说明 |
|---|---|---|
AUTOFILTER_FILTERTYPE_FILTER |
'filters' |
标准筛选(等值匹配) |
AUTOFILTER_FILTERTYPE_CUSTOMFILTER |
'customFilters' |
自定义筛选(运算符 + 值) |
AUTOFILTER_FILTERTYPE_DYNAMICFILTER |
'dynamicFilter' |
动态筛选(如"今天""本月",见 04-04) |
AUTOFILTER_FILTERTYPE_TOPTENFILTER |
'top10' |
Top N 筛选(见 04-05) |
关键限制:自定义筛选最多只能定义 2 条规则,且这两条规则之间只能用 AND 或 OR 连接。这一限制体现在源码注释中——Column.php 明确写着 "Supports no more than 2 rules, with an And/Or join criteria if more than 1 rule is defined"。
二、第一步:把列切换为 CUSTOMFILTER 类型
在编写任何规则之前,先要通过 setFilterType() 把目标列的筛选类型设置为 CUSTOMFILTER:
$columnFilter->setFilterType(
PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_CUSTOMFILTER
);
从源码看,setFilterType()(Column.php)会对传入值做白名单校验:只有 $filterTypes 数组中列出的四种类型是合法的,否则抛出 PHPExcel_Exception('Invalid filter type for column AutoFilter.')。因此建议始终使用类常量而非手写字符串。
一个完整的获取列对象的示例(参考 10autofilter-selection-1.php):
$autoFilter = $objPHPExcel->getActiveSheet()->getAutoFilter();
$columnFilter = $autoFilter->getColumn('C');
$columnFilter->setFilterType(
PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_CUSTOMFILTER
);
三、定义第一条规则:通配符文本匹配
设置好列类型后,就可以通过 createRule() 创建规则并链式调用 setRule() + setRuleType() 定义具体条件。下面的例子筛选出该列中所有以字母 U 开头的条目:
$columnFilter->createRule()
->setRule(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
'U*'
)
->setRuleType(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_CUSTOMFILTER
);
这段代码中出现了三个关键要素,均能在 Rule.php 中找到对应实现:
- 规则类型
AUTOFILTER_RULETYPE_CUSTOMFILTER,值为'customFilter'(Rule.php); - 运算符
AUTOFILTER_COLUMN_RULE_EQUAL(详见第五节运算符表); - 值
'U*',即带通配符的匹配模式。
通配符语义:*、? 与 ~ 转义
MS Excel 使用两个通配符字符,PHPExcel 与之完全兼容:
| 通配符 | 含义 | 示例 |
|---|---|---|
* |
匹配任意数量的字符(含 0 个) | 'U*' = 以 U 开头;'*U' = 以 U 结尾;'*U*' = 包含 U |
? |
匹配单个字符 | 'U??' = 以 U 开头且后面恰好还有两个字符 |
也就是说:
'U*'等价于"以 U 开头"(begins with);'*U'等价于"以 U 结尾"(ends with);'*U*'等价于"包含 U"(contains)。
显式匹配 * 或 ? 本身:用波浪号 ~ 转义
如果单元格值中本身含有 * 或 ?,需要显式匹配这些字符,则用波浪号 ~ 转义:
?~**:匹配"第二个字符是*、后面跟着任意数量字符"的值(?匹配第一个字符,~*把第二个字符固定为字面量*,末尾的*再匹配其余任意字符);- 唯一同样需要转义的就是
~本身,即匹配字面量波浪号时要写作~~。
这条规则与 Excel 的通配符约定一致,是构建"包含特殊字符的文本筛选"时最容易踩坑、也最值得记住的一点。
四、第二步:用两条规则构建"介于区间"条件
通配符之外,自定义筛选最常见的需求是数值区间。由于自定义筛选没有独立的 BETWEEN 运算符,区间条件需要拆成两条规则:一个下界(大于等于)加一个上界(小于等于)。下面的例子筛选数值满足 -20 <= x <= 20 的记录:
$columnFilter->createRule()
->setRule(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_GREATERTHANOREQUAL,
-20
)
->setRuleType(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_CUSTOMFILTER
);
$columnFilter->createRule()
->setRule(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_LESSTHANOREQUAL,
20
)
->setRuleType(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_CUSTOMFILTER
);
注意两条规则都要设置 setRuleType(CUSTOMFILTER)。此时列上已存在两条规则,默认的连接关系是 OR(详见下节),而区间语义要求同时满足两个条件,因此必须把连接符改为 AND。
调整规则的连接关系:AND / OR
$columnFilter->setAndOr(
PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_COLUMN_ANDOR_AND
);
这里需要对照当前仓库源码做一个澄清:在 Column.php 中,这一"多条规则连接方式"的实际常量与方法是:
| 文档中的写法 | 当前仓库源码中的对应物 |
|---|---|
AUTOFILTER_COLUMN_ANDOR_AND |
AUTOFILTER_COLUMN_JOIN_AND(值 'and') |
AUTOFILTER_COLUMN_ANDOR_OR |
AUTOFILTER_COLUMN_JOIN_OR(值 'or') |
setAndOr() |
setJoin()(Column.php) |
setJoin() 会先将参数 strtolower 再与 $ruleJoins 白名单比对,非法值抛出 PHPExcel_Exception('Invalid rule connection for column AutoFilter.')。同时需要注意 Join 的默认值是 OR(Column.php),这也是为什么区间筛选必须显式改为 AND 的原因。
规则集的管理方法
PHPExcel_Worksheet_AutoFilter_Column 还提供了完整的规则集管理 API(Column.php):
createRule():在规则集末尾新建一条规则并返回;addRule($pRule, $returnRule = true):追加一条已构造好的规则对象;deleteRule($pIndex):删除指定下标的规则,当规则数减少到 1 条时自动把 Join 重置回 OR;clearRules():清空全部规则,同时把 Join 重置回 OR;getRules()/getRule($pIndex):读取规则集。
这一"删到只剩一条就自动回退 OR"的行为,保证了单规则场景下 Join 设置不会产生歧义。
五、自定义筛选的合法运算符全集
自定义筛选(以及标准筛选)唯一合法的一组运算符定义在 Rule.php 中,注释明确列出其值对应 OOXML 规范 <xsd:enumeration> 枚举。完整列表如下:
| 运算符常量 | 值 |
|---|---|
AUTOFILTER_COLUMN_RULE_EQUAL |
'equal' |
AUTOFILTER_COLUMN_RULE_NOTEQUAL |
'notEqual' |
AUTOFILTER_COLUMN_RULE_GREATERTHAN |
'greaterThan' |
AUTOFILTER_COLUMN_RULE_GREATERTHANOREQUAL |
'greaterThanOrEqual' |
AUTOFILTER_COLUMN_RULE_LESSTHAN |
'lessThan' |
AUTOFILTER_COLUMN_RULE_LESSTHANOREQUAL |
'lessThanOrEqual' |
setOperator()(Rule.php)会对运算符做双重校验:空值回退为 EQUAL,非 $operators 白名单(或 TopTen 专用值)则抛出 PHPExcel_Exception('Invalid operator for column AutoFilter Rule.')。而 setRule()(Rule.php)本质是 setOperator() + setValue() 的组合封装,因此规则值既可以是字符串(含通配符模式),也可以按需传入其他类型(数值、布尔等)。
六、综合示例:双规则 OR 连接的文本匹配
自定义筛选并非只能用于区间。经典用法之一是"满足任一条件的多条文本规则",这正好用上 OR 连接。参考 10autofilter-selection-1.php 中的真实示例——筛选国家列中"以 u 开头 或 等于 japan"的记录:
// 规则一:以字母 u 开头(使用通配符 *,必须用 customFilter)
$autoFilter->getColumn('C')
->setFilterType(PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_CUSTOMFILTER)
->createRule()
->setRule(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
'u*'
)
->setRuleType(PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_CUSTOMFILTER);
// 规则二:等于 japan(默认 OR 连接,无需显式设置 Join)
$autoFilter->getColumn('C')
->createRule()
->setRule(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
'japan'
)
->setRuleType(PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_CUSTOMFILTER);
该示例同时印证了两点实践要点:
- 通配符模式必须走 customFilter:源码注释 "using a wildcard requires customFilter" 明确指出,只要规则值里出现
*/?通配符,列就必须是CUSTOMFILTER类型,标准筛选(FILTER)不支持通配匹配; - 两条规则默认就是 OR 连接,所以"满足其一"的场景无需调用
setJoin();只有"同时满足"(如区间)才需要显式改为 AND。
七、源码视角:Reader 如何还原 customFilter 规则
理解读写两端如何序列化自定义筛选,有助于排查"写出来的筛选被重新读取后行为不一致"的问题。以 Reader/Excel2007.php 为例,读取 xlsx 中的 customFilters 节点时,引擎按以下步骤还原:
// 检测到 <customFilters> 节点
if ($filterColumn->customFilters) {
$column->setFilterType(PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_CUSTOMFILTER);
$customFilters = $filterColumn->customFilters;
// 读取 and 属性:值为 1 时把 Join 设为 AND,否则保持默认 OR
if ((isset($customFilters["and"])) && ($customFilters["and"] == 1)) {
$column->setJoin(PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_COLUMN_JOIN_AND);
}
// 遍历每条 <customFilter>,取出 operator 和 val 属性构建规则
foreach ($customFilters->customFilter as $filterRule) {
$column->createRule()->setRule(
(string) $filterRule["operator"],
(string) $filterRule["val"]
)
->setRuleType(PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_CUSTOMFILTER);
}
}
可以看到:OOXML 中 customFilters 节点的 and="1" 属性直接映射到 AUTOFILTER_COLUMN_JOIN_AND,而每个子节点 customFilter 的 operator 与 val 属性则分别映射为规则的运算符与值——与我们在第三节、第四节用 PHP API 构建的对象模型一一对应。这意味着:在 PHPExcel 中定义的自定义筛选,写出为 xlsx 后,再用 PHPExcel 读回,规则语义可以无损还原。
八、小结与常见陷阱
自定义筛选是 PHPExcel AutoFilter 中表达能力最强的一类筛选,本文要点总结如下:
- 先
setFilterType(AUTOFILTER_FILTERTYPE_CUSTOMFILTER),再createRule()->setRule($operator, $value)->setRuleType(AUTOFILTER_RULETYPE_CUSTOMFILTER); - 最多 2 条规则,连接方式默认为 OR,区间等"同时满足"场景需显式设为 AND(源码中为
setJoin(AUTOFILTER_COLUMN_JOIN_AND)); - 通配符
*匹配任意数量字符、?匹配单个字符;字面量*/?/~需用~转义; - 六种运算符均定义在 Rule.php,非白名单值会直接抛异常;
- 通配符文本匹配只能使用 CUSTOMFILTER 类型;标准筛选不支持
*/?。
易踩坑清单:
- 忘记设置列类型:仅
createRule()而不设CUSTOMFILTER,规则不会按自定义筛选语义生效; - 区间忘改 AND:两条规则默认 OR 连接,
>= -20 OR <= 20会筛出几乎所有数值,务必显式setJoin(AND); - 通配符未转义:当业务数据本身含
*时,不写~*会导致匹配结果被通配符"污染"; - 超过 2 条规则:多规则需求请拆分为多个列筛选或在业务层预过滤。
自定义筛选与基础筛选、日期分组、动态筛选、Top N 共同构成了 PHPExcel AutoFilter 的完整表达式体系,可继续阅读 04-01-Autofilter-Expressions-Simple.md、04-02-Autofilter-Expressions-Dategroup.md、04-04-Autofilter-Expressions-Dynamic.md 与 04-05-Autofilter-Expressions-Topten.md 对照学习。

