PHPExcel AutoFilter 表达式编程完全指南:Simple / DateGroup / Custom / Dynamic / TopTen 五种筛选规则实战
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:
- 写入
<autoFilter ref="A1:F100"/>声明筛选范围; - 遍历每个含规则的列,写入
<filterColumn colId="n">; - 根据
getFilterType()输出容器元素:filters、customFilters、dynamicFilter或top10,连接为 AND 时附加and="1"属性; - 逐条序列化规则:空值 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 的序列化路径,以及官方示例与单元测试中的验证细节。
如需继续深入,可参阅同目录下的其余文档:
- 01-Autofilters.md——AutoFilter 基础概念与图标语义;
- 02-Setting-an-Autofilter.md——筛选范围的设置与校验;
- 05-Executing-Autofilters.md——AutoFilter 的求值/执行机制;
- 06-Autofilter-Sorting.md——筛选结果的排序支持。
源码层面可重点阅读 AutoFilter.php(范围与列管理)、Column.php(筛选类型/连接/规则集)、Rule.php(全部常量与规则校验),以及 Writer/Excel2007/Worksheet.php 的 writeAutoFilter() 方法;官方示例 10autofilter-selection-1.php 提供了可直接运行的综合用例。