PHPExcel AutoFilter 自定义筛选(Custom Filter)表达式完全指南:通配符、区间过滤与 AND/OR 规则编排

原创2026-09-22 23:45:212,000 阅读
文章标签:后端数据处理

PHPExcel AutoFilter 自定义筛选(Custom Filter)表达式完全指南:通配符、区间过滤与 AND/OR 规则编排

本文是 PHPExcel AutoFilter 参考系列的进阶篇,聚焦于自定义筛选(Custom Filter)表达式:如何在 Excel 兼容的自动筛选中用运算符 + 值构建复杂条件,例如"以字母 U 开头"的文本通配匹配、"介于 -20 与 +20 之间"的数值区间过滤,以及如何通过 AND / OR 连接规则。读完本文,你将掌握 AUTOFILTER_FILTERTYPE_CUSTOMFILTER 类型的完整用法、* / ? / ~ 通配符语义、六种运算符的常量取值,并能结合实际源码理解规则在读写两端(Reader / Writer)的落地机制。

MS Excel 自定义自动筛选对话框:筛选以 U 开头的文本

MS Excel 自定义自动筛选规则设置与通配符提示

一、什么是自定义筛选:从单一条件到"运算符 + 值"

在 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 中找到对应实现:

  1. 规则类型 AUTOFILTER_RULETYPE_CUSTOMFILTER,值为 'customFilter'(Rule.php);
  2. 运算符 AUTOFILTER_COLUMN_RULE_EQUAL(详见第五节运算符表);
  3. 值 '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);

该示例同时印证了两点实践要点:

  1. 通配符模式必须走 customFilter:源码注释 "using a wildcard requires customFilter" 明确指出,只要规则值里出现 * / ? 通配符,列就必须是 CUSTOMFILTER 类型,标准筛选(FILTER)不支持通配匹配;
  2. 两条规则默认就是 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 类型;标准筛选不支持 * / ?。

易踩坑清单:

  1. 忘记设置列类型:仅 createRule() 而不设 CUSTOMFILTER,规则不会按自定义筛选语义生效;
  2. 区间忘改 AND:两条规则默认 OR 连接,>= -20 OR <= 20 会筛出几乎所有数值,务必显式 setJoin(AND);
  3. 通配符未转义:当业务数据本身含 * 时,不写 ~* 会导致匹配结果被通配符"污染";
  4. 超过 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 对照学习。

登录后查看全文
PHPExcel