PHPExcel AutoFilter 表达式编程完全指南:Simple / DateGroup / Custom / Dynamic / TopTen 五种筛选规则实战

原创2026-09-22 19:58:581,885 阅读
文章标签:后端数据处理

PHPExcel AutoFilter 表达式编程完全指南:Simple / DateGroup / Custom / Dynamic / TopTen 五种筛选规则实战

导读

本指南基于 PHPExcel 官方 AutoFilter 参考文档(03-Autofilter-Expressions.md)及其五个分篇,系统讲解如何在 PHPExcel 中为自动筛选(AutoFilter)列创建、读取和写入筛选表达式。你将掌握列级筛选对象的获取方式、五种筛选类型(简单筛选、日期分组、自定义、动态、Top N)的完整常量与配置方法、通配符与转义规则,以及它们如何被序列化为 Excel2007 的 OOXML 结构,从而在实际项目中直接编写可运行的筛选代码。

概述:从 Excel 下拉筛选到 PHP 筛选表达式

在 MS Excel 中,AutoFilter 为数据区域的首行添加下拉箭头,用户可通过勾选来显示/隐藏行。PHPExcel 1.7.8 起提供了程序化创建、读取和写入筛选表达式的能力——最初仅支持 Excel2007(xlsx)格式文件,后续版本再扩展至其他格式。与之配套的还有 02-Setting-an-Autofilter.md(定义筛选范围)与 01-Autofilters.md(筛选基本概念)两篇姊妹文档。

先决条件:一个工作表内只能有一个 AutoFilter 范围;筛选是叠加式的——对多列分别施加的筛选会进一步缩小数据子集。因此,在写表达式之前,必须先把 AutoFilter 范围挂到工作表上,并取得目标列的筛选对象:

// 先设置 AutoFilter 范围(必须包含标题行与数据行)
$objPHPExcel->getActiveSheet()->setAutoFilter('A1:F100');

// 取得 AutoFilter,再取得某一列(此处为 C 列)的筛选对象
$autoFilter = $objPHPExcel->getActiveSheet()->getAutoFilter();
$columnFilter = $autoFilter->getColumn('C');

getColumn('C') 返回 PHPExcel_Worksheet_AutoFilter_Column 对象(见 AutoFilter.php):当列对象尚不存在时会自动创建并缓存,同时调用 testColumnInRange() 校验该列位于 AutoFilter 范围之内,越界会抛出 PHPExcel_Exception。之后所有筛选表达式都施加于该列对象上。

五种筛选类型与互斥原则

PHPExcel 支持以下五类筛选表达式:

  • Simple Filters(简单筛选)——等同于 Excel 下拉勾选列表;
  • DateGroup Filters(日期分组筛选)——按年/月/日等粒度筛选日期;
  • Custom Filters(自定义筛选)——运算符 + 通配符的复杂条件;
  • Dynamic Filters(动态筛选)——"今天""本年至今""高于平均值"等动态条件;
  • Top Ten Filters(Top N 筛选)——按数值或百分比取前/后 N 项。

重要约束:这五种类型在同一列内是互斥的,不要在同一列中混用不同筛选类型。PHPExcel 不会主动阻止你这样做,但结果不可预期。此外,单元格颜色筛选(colorFilter)、图标筛选(iconFilter)等类型当前尚未实现——这一点在 Column.php 的 $filterTypes 白名单注释中明确标注,传入白名单之外的 filterType 会抛出 PHPExcel_Exception: Invalid filter type for column AutoFilter.。

每种筛选类型在列对象上都有一个对应的过滤器类型常量(定义于 Column.php),在后续小节中会逐一使用:

常量(PHPExcel_Worksheet_AutoFilter_Column::) 值 说明
AUTOFILTER_FILTERTYPE_FILTER filters 标准筛选(Simple / DateGroup 共用)
AUTOFILTER_FILTERTYPE_CUSTOMFILTER customFilters 自定义筛选,最多 2 条规则,支持 And/Or
AUTOFILTER_FILTERTYPE_DYNAMICFILTER dynamicFilter 动态筛选,规则常量而数据可变(如 TODAY)
AUTOFILTER_FILTERTYPE_TOPTENFILTER top10 Top N 筛选

简单筛选(Simple Filters):勾选"选中值"

在 Excel 中,简单筛选是列内所有取值构成的勾选列表:勾选的行显示,未勾选的行隐藏。在 PHPExcel 中实现时,只需要为每个"要显示的值"创建一条筛选规则即可。

第一步,声明该列为标准筛选类型:

$columnFilter->setFilterType(
    PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_FILTER
);

第二步,为每个值创建一条规则。例如筛选出国家为 France 或 Germany 的行:

$columnFilter->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        'France'
    );

$columnFilter->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        'Germany'
    );

语义要点:

  • 简单筛选始终是 EQUALS(等于) 匹配,多条规则之间恒为 OR 连接;
  • 规则数量没有上限,可任意添加;
  • 调用链中 createRule() 返回规则对象,setRule() 返回规则对象本身以便继续链式调用——createRule() 的实现见 Column.php,它向规则集尾部追加一个新的 PHPExcel_Worksheet_AutoFilter_Column_Rule 实例并返回。

匹配空白单元格(Matching Blanks)

要筛选出空单元格,使用 EQUAL 运算符并传入空字符串:

$columnFilter->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        ''
    );

写入 Excel2007 时,这条规则会被序列化为带 blank="1" 属性的标准 filter 规则——见 Writer/Excel2007/Worksheet.php 中的专门分支。运行示例可参考 10autofilter-selection-1.php,它把 E 列(Sales Value)的空值行筛选出来。

日期分组筛选(DateGroup Filters):按年/月/日粒度过滤日期

Excel 的 DateGroup 筛选器允许按整个年份、某年中的某月、某月中的某日(甚至小时/分钟/秒)逐级下钻选择日期。PHPExcel 中它仍然以标准筛选类型(AUTOFILTER_FILTERTYPE_FILTER)施加:

$columnFilter->setFilterType(
    PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_FILTER
);

与简单筛选不同,日期分组的筛选值是一个关联数组,键为 year、month、day、hour、minute、second。例如筛选 2012 年 1 月:

$columnFilter->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        array(
            'year'  => 2012,
            'month' => 1
        )
    )
    ->setRuleType(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_DATEGROUP
    );

关键点:与普通标准筛选不同,这里必须显式把规则类型设置为 AUTOFILTER_RULETYPE_DATEGROUP,否则无法与简单筛选区分。其常量值定义于 Rule.php。

关联数组的合法键由 PHPExcel_Worksheet_AutoFilter_Column_Rule 类中的日期分组常量定义(Rule.php):

键 常量 说明
year AUTOFILTER_RULETYPE_DATEGROUP_YEAR 年
month AUTOFILTER_RULETYPE_DATEGROUP_MONTH 月
day AUTOFILTER_RULETYPE_DATEGROUP_DAY 日
hour AUTOFILTER_RULETYPE_DATEGROUP_HOUR 时
minute AUTOFILTER_RULETYPE_DATEGROUP_MINUTE 分
second AUTOFILTER_RULETYPE_DATEGROUP_SECOND 秒

底层机制:setRule() 最终调用 Rule::setValue()(Rule.php),它会逐一校验数组键是否属于上述六键白名单,剔除非法键,并以"出现的最细粒度"自动推算分组层级存入 grouping 属性(例如只传 year+month 时 grouping 即为 month)。因此你通常无需手工设置 grouping。写入 OOXML 时,这些键被展开为 <dateGroupItem year="2012" month="1" dateTimeGrouping="month"/> 元素(见 Writer/Excel2007/Worksheet.php)。

与标准筛选一致:日期分组规则恒为 EQUALS 匹配、多规则恒为 OR 连接,且规则数量不限。实际用例见 10autofilter-selection-1.php——它为 D 列(Date)循环创建 12 条日期分组规则,筛选出当前年份每个月最后一天。

自定义筛选(Custom Filters):运算符 + 通配符

自定义筛选允许使用运算符和值组合出更复杂的条件,典型场景是区间筛选(如 -20 到 +20)或文本通配符(如以字母 U 开头)。自定义筛选最多只能有 2 条规则,规则间用 AND 或 OR 连接。

首先把筛选类型改为自定义:

$columnFilter->setFilterType(
    PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_CUSTOMFILTER
);

文本通配符:以 U 开头的所有条目

$columnFilter->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        'U*'
    )
    ->setRuleType(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_CUSTOMFILTER
    );

通配符语义(与 MS Excel 一致):

  • * 匹配任意多个字符:U* = 以 U 开头;*U = 以 U 结尾;*U* = 包含 U;
  • ? 匹配单个字符;
  • 转义:要匹配字面量 * 或 ?,用波浪号 ~ 转义。例如 ?~** 表示"第二个字符是字面 *,其后跟任意字符"。唯一需要转义的另一个字符是 ~ 本身。

区间筛选:-20 到 +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
    );

由于"两条规则均须满足"才是区间,必须把列上默认的 OR 连接改为 AND:

$columnFilter->setAndOr(
    PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_COLUMN_ANDOR_AND
);

注意:该文档使用的 setAndOr() 在较新实现中对应 setJoin()(PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_COLUMN_JOIN_AND / AUTOFILTER_COLUMN_JOIN_OR,值分别为 'and'/'or',见 Column.php)。列对象默认连接为 OR(AUTOFILTER_COLUMN_JOIN_OR);调用 deleteRule() 将规则数删减到 1 时,连接会自动重置回 OR(Column.php)。单元测试 ColumnTest.php 验证了默认连接值与 AND 切换行为。

自定义筛选合法运算符一览

运算符常量同样定义在 PHPExcel_Worksheet_AutoFilter_Column_Rule 类中(Rule.php),共六种:

运算符常量 值
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() 会校验运算符是否落入上述白名单(TopTen 专用值除外),非法值抛出 PHPExcel_Exception(Rule.php)。在 Excel2007 写入器中,非 EQUAL 运算符会被写成 operator="greaterThanOrEqual" 之类的属性(Writer/Excel2007/Worksheet.php),写入时两个自定义规则会被包裹在 customFilters 容器内。

动态筛选(Dynamic Filters):随日期与数据变化的条件

动态筛选的比较条件是可变的:基准值要么随时间变化(如 today),要么是数据本身的聚合(如 aboveAverage 高于平均值)。同一列一次只能应用一条动态筛选规则。

设置筛选类型:

$columnFilter->setFilterType(
    PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_DYNAMICFILTER
);

定义规则时不需要提供值(传 NULL),但要指定动态筛选的类别,并同时把规则类型设为 DYNAMICFILTER:

$columnFilter->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        NULL,
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_DYNAMIC_YEARTODATE
    )
    ->setRuleType(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_DYNAMICFILTER
    );

这里 setRule() 的第三个参数就是"分组/类别"参数:setRule() 只在用户显式传入该参数时才覆盖 setValue() 自动推算的分组值(Rule.php)。

动态筛选类别完整清单

全部常量定义于 PHPExcel_Worksheet_AutoFilter_Column_Rule 类(Rule.php),setGrouping() 会对其校验:

常量(AUTOFILTER_RULETYPE_DYNAMIC_*) 值 语义
YESTERDAY yesterday 昨天
TODAY today 今天
TOMORROW tomorrow 明天
YEARTODATE yearToDate 本年至今
THISYEAR thisYear 今年
THISQUARTER thisQuarter 本季度
THISMONTH thisMonth 本月
THISWEEK thisWeek 本周
LASTYEAR lastYear 去年
LASTQUARTER lastQuarter 上季度
LASTMONTH lastMonth 上月
LASTWEEK lastWeek 上周
NEXTYEAR nextYear 明年
NEXTQUARTER nextQuarter 下季度
NEXTMONTH nextMonth 下月
NEXTWEEK nextWeek 下周
MONTH_1 ~ MONTH_12(别名 JANUARY ~ DECEMBER) M1 ~ M12 指定月份
QUARTER_1 ~ QUARTER_4 Q1 ~ Q4 指定季度
ABOVEAVERAGE aboveAverage 高于平均值
BELOWAVERAGE belowAverage 低于平均值

注意:月份常量同时提供了编号形式(MONTH_1…MONTH_12)与英文名别名(JANUARY…DECEMBER),二者指向相同值 M1…M12,可互换使用。

写入细节:动态规则在 OOXML 中序列化为 <dynamicFilter type="yearToDate"/>,若列对象上设置了 val / maxVal 属性也会一并写入(Writer/Excel2007/Worksheet.php)。由于规则值本身是 NULL,配合列上的 val/maxVal 属性即可表达 Excel 中"动态日期区间"这类带上下界的动态条件。

Top Ten 筛选(Top N Filters):按数值或百分比取前/后 N 项

Top N 筛选与动态筛选类似,都基于单元格数据的聚合统计;区别在于 Top N 允许按多个维度自定义:取最大值(top)还是最小值(bottom)、取多少项、按条数(byValue)还是按百分比(byPercent)。与动态筛选一样,同一列一次只能应用一条 Top N 规则。

筛选类型为 TOPTENFILTER:

$columnFilter->setFilterType(
    PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_TOPTENFILTER
);

示例一:列内 Top 5%(前 5% 的数值)

$columnFilter->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_TOPTEN_PERCENT,
        5,
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_TOPTEN_TOP
    )
    ->setRuleType(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_TOPTENFILTER
    );

示例二:列内最小 2 条(bottom 2 values)

$columnFilter->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_TOPTEN_BY_VALUE,
        2,
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_TOPTEN_BOTTOM
    )
    ->setRuleType(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_TOPTENFILTER
    );

Top N 参数常量

setRule() 的参数依次为:统计口径(byValue/byPercent)、数量 N、方向(top/bottom)。两组常量定义于 Rule.php:

常量(AUTOFILTER_COLUMN_RULE_TOPTEN_*) 值 说明
BY_VALUE byValue 按条数取值
PERCENT byPercent 按百分比取值
常量(AUTOFILTER_COLUMN_RULE_TOPTEN_*) 值 说明
TOP top 前(最大值)
BOTTOM bottom 后(最小值)

写入细节:Top N 规则在 OOXML 中被序列化为 <top10 val="5" percent="1" top="1"/>,其中 percent 属性由运算符是否为 TOPTEN_PERCENT 决定,top 属性由分组值是否为 TOPTEN_TOP 决定(Writer/Excel2007/Worksheet.php)。

从对象模型到 OOXML:表达式如何落盘

PHPExcel_Worksheet_AutoFilter_Column 与 PHPExcel_Worksheet_AutoFilter_Column_Rule 共同构成了 AutoFilter 表达式的对象模型:列对象持有 filterType(筛选类型)、join(多规则连接)与 ruleset(规则数组);规则对象持有 ruleType、operator、value、grouping 四个属性。

写 Excel2007 时,Writer/Excel2007/Worksheet.php 的 writeAutoFilter() 按如下流程生成 XML:

  1. 写入 <autoFilter ref="A1:F100"/> 声明筛选范围;
  2. 遍历每个含规则的列,写入 <filterColumn colId="n">;
  3. 根据 getFilterType() 输出容器元素:filters、customFilters、dynamicFilter 或 top10,连接为 AND 时附加 and="1" 属性;
  4. 逐条序列化规则:空值 EQUAL 规则 → blank="1";动态规则 → type/val/maxVal;Top N → val/percent/top;其余(filter/dateGroupItem/customFilter)→ 规则元素 + operator/val/日期分组键等属性。

这套双向映射意味着:你用上述 PHP API 构建的筛选表达式,既能写进 xlsx 文件,也能从已有的 xlsx 文件中读取回来(读入端同样以列 + 规则对象呈现)。

组合示例:真实项目中的综合用法

以下把五种筛选类型放到一个脚本里,演示多列叠加筛选的完整写法(结构参照官方示例 10autofilter-selection-1.php,该示例为每月的每天、每个国家生成数据行后设置筛选):

$objPHPExcel->getActiveSheet()->setAutoFilter('A1:F1000');
$autoFilter = $objPHPExcel->getActiveSheet()->getAutoFilter();

// C 列(国家):自定义筛选——以 U 开头,或等于 Japan(OR 连接,默认)
$colC = $autoFilter->getColumn('C');
$colC->setFilterType(
    PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_CUSTOMFILTER
);
$colC->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        'U*'
    )
    ->setRuleType(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_CUSTOMFILTER
    );
$colC->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        'Japan'
    )
    ->setRuleType(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_CUSTOMFILTER
    );

// D 列(日期):日期分组——当前年 1 月的所有记录
$colD = $autoFilter->getColumn('D');
$colD->setFilterType(
    PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_FILTER
);
$colD->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        array('year' => date('Y'), 'month' => 1)
    )
    ->setRuleType(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_DATEGROUP
    );

// E 列(销售额):筛选空白单元格
$autoFilter->getColumn('E')
    ->setFilterType(
        PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_FILTER
    )
    ->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
        ''
    );

// F 列(支出):Top 10% 最大支出
$autoFilter->getColumn('F')
    ->setFilterType(
        PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_TOPTENFILTER
    )
    ->createRule()
    ->setRule(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_TOPTEN_PERCENT,
        10,
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_TOPTEN_TOP
    )
    ->setRuleType(
        PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_TOPTENFILTER
    );

// 写入 Excel2007(xlsx)文件
$objWriter = PHPExcel_IOFactory::createWriter($objPHPExcel, 'Excel2007');
$objWriter->save('autofilter-demo.xlsx');

需要强调的是:筛选是叠加式的,多列条件同时生效会逐级缩小结果集;同时务必遵守"单列内只使用一种筛选类型"的互斥原则,以免产生不可预期的行为。

总结与扩展阅读

本文完整覆盖了 PHPExcel AutoFilter 表达式的全部五种类型:简单筛选(EQUALS + OR、匹配空白)、日期分组(六键关联数组 + 自动分组推算)、自定义筛选(六种运算符、*/? 通配符与 ~ 转义、最多 2 条规则 + AND/OR 连接)、动态筛选(20+ 类别,规则常量值可变)、Top N 筛选(byValue/byPercent × top/bottom)。并进一步揭示了从 Column/Rule 对象模型到 Excel2007 OOXML 的序列化路径,以及官方示例与单元测试中的验证细节。

如需继续深入,可参阅同目录下的其余文档:

源码层面可重点阅读 AutoFilter.php(范围与列管理)、Column.php(筛选类型/连接/规则集)、Rule.php(全部常量与规则校验),以及 Writer/Excel2007/Worksheet.php 的 writeAutoFilter() 方法;官方示例 10autofilter-selection-1.php 提供了可直接运行的综合用例。

登录后查看全文
PHPExcel