PHPExcel AutoFilter 日期分组筛选(DateGroup Filter)完整指南:按年、月、日、时分秒精确筛选日期列
PHPExcel AutoFilter 日期分组筛选(DateGroup Filter)完整指南:按年、月、日、时分秒精确筛选日期列
导读
本篇文章以 PHPExcel AutoFilter Reference 文档中的 DateGroup Filters 章节为核心,系统讲解如何在 PHPExcel 中对日期列创建"日期分组筛选"(DateGroup Filter)——即像 MS Excel 那样,通过下拉筛选器按整个年份、年内某个月份、或某月中的某一天来精确筛选数据。读完本文,你将掌握 DateGroup 筛选规则的完整 API 调用方式、关联数组的六个时间粒度键(year / month / day / hour / minute / second)的使用规则、其与普通 Standard Filter 的差异,以及底层的匹配与写出实现原理,能够直接在你的业务代码中落地可运行的日期筛选方案。
一、DateGroup 筛选是什么
在 MS Excel 中,DateGroup 筛选(日期分组筛选)为日期列提供了一组层级化的下拉筛选器:你可以先选年份,再在年份内选月份,还可以进一步细化到某月中的某一天,甚至小时、分钟、秒级粒度。
在 PHPExcel 中,DateGroup 筛选本质上仍是一种 Standard Filter(标准筛选)类型,而非独立的筛选类型。也就是说,这一列在 filterType 层面使用的是与简单值筛选相同的 AUTOFILTER_FILTERTYPE_FILTER,二者的区别完全体现在**规则(Rule)**的细节上——DateGroup 规则把"日期分组值"以关联数组的形式传给规则,并显式声明规则类型为 AUTOFILTER_RULETYPE_DATEGROUP。
$columnFilter->setFilterType(
PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_FILTER
);
二、前置准备:定位要筛选的列
在创建任何筛选表达式之前,需要先从工作表的 AutoFilter 对象中取出目标列。根据 Autofilter Expressions 总览,获取某一列的筛选器对象的标准写法如下:
$autoFilter = $objPHPExcel->getActiveSheet()->getAutoFilter();
$columnFilter = $autoFilter->getColumn('C');
getColumn() 返回一个 PHPExcel_Worksheet_AutoFilter_Column 对象,之后的所有规则都挂载在这个对象上。需要注意的是:AutoFilter 表达式类型(Simple / DateGroup / Custom / Dynamic / Top Ten)在同一列内是互斥的,不应该在同一列混合多种类型,否则结果不可预测(PHPExcel 不会主动阻止你,但行为无保证)。
同时请确认该工作表已设置 AutoFilter 区域。最简单的做法是让 AutoFilter 覆盖整个工作表的已使用区域(参见 Setting an AutoFilter area on a worksheet):
$objPHPExcel->getActiveSheet()->setAutoFilter(
$objPHPExcel->getActiveSheet()->calculateWorksheetDimension()
);
AutoFilter 区域的第一行永远是表头行(显示下拉箭头、不属于被筛选数据),其余行才是筛选数据,因此区域至少应包含表头行 + 一行数据。
三、创建 DateGroup 筛选规则
3.1 最小示例:按"年 + 月"筛选
假设我们想筛选出 2012 年 1 月的所有数据。在 PHPExcel 中,需要创建一个 DateGroup 规则,并把"被勾选"的日期分组值以关联数组形式传入 setRule():
$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
);
关键点:
createRule()在列对象内部追加一条新规则并返回该规则对象(见 Column.php 中createRule()的实现:$this->ruleset[] = new PHPExcel_Worksheet_AutoFilter_Column_Rule($this);)。setRule()的第一个参数是操作符,DateGroup 规则固定使用AUTOFILTER_COLUMN_RULE_EQUAL(等于)。setRuleType()必须显式声明为AUTOFILTER_RULETYPE_DATEGROUP,用来与普通标准筛选区分开。
3.2 关联数组的六个键
DateGroup 规则值关联数组支持以下六个键,粒度从粗到细:
| 键名 | 含义 | 示例值 | 对应的源码常量 |
|---|---|---|---|
year |
年份 | 2012 |
AUTOFILTER_RULETYPE_DATEGROUP_YEAR |
month |
月份(1–12) | 1 |
AUTOFILTER_RULETYPE_DATEGROUP_MONTH |
day |
日(1–31) | 15 |
AUTOFILTER_RULETYPE_DATEGROUP_DAY |
hour |
小时(0–23) | 9 |
AUTOFILTER_RULETYPE_DATEGROUP_HOUR |
minute |
分钟(0–59) | 30 |
AUTOFILTER_RULETYPE_DATEGROUP_MINUTE |
second |
秒(0–59) | 0 |
AUTOFILTER_RULETYPE_DATEGROUP_SECOND |
这六个常量定义在 Rule.php 中:
const AUTOFILTER_RULETYPE_DATEGROUP_YEAR = 'year';
const AUTOFILTER_RULETYPE_DATEGROUP_MONTH = 'month';
const AUTOFILTER_RULETYPE_DATEGROUP_DAY = 'day';
const AUTOFILTER_RULETYPE_DATEGROUP_HOUR = 'hour';
const AUTOFILTER_RULETYPE_DATEGROUP_MINUTE = 'minute';
const AUTOFILTER_RULETYPE_DATEGROUP_SECOND = 'second';
粒度规则(重要):DateGroup 的匹配是前缀式包含的。你可以在关联数组中只提供其中一部分键——提供 year 就匹配整年;提供 year + month 就匹配该年内的那个月;提供 year + month + day 就精确匹配某一天。时间部分(hour/minute/second)同理,可以单独与日期组合。
源码验证:setValue() 在处理数组时会逐一校验键是否属于上述六个合法键,非法键会被剔除;同时会根据传入键中最细的粒度自动推断出该规则的 grouping(分组粒度)并写入 $this->setGrouping(...)(参见 Rule.php)。若数组经校验后为空,会抛出 PHPExcel_Exception('Invalid rule value for column AutoFilter Rule.')。
3.3 匹配语义与规则数量
- DateGroup 筛选永远是 EQUALS(等于)匹配,与简单标准筛选一致,不存在大于/小于等比较操作。
- 多条 DateGroup 规则之间永远按 OR(或)连接:即任一规则命中即显示该行。你可以为一个列创建任意数量的 DateGroup 规则(参见原文档以及 Column.php 中
createRule()可反复调用)。
例如,同时筛选 2012 年 1 月和 2012 年 3 月两个月的数据:
// 规则 1: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
);
// 规则 2:2012 年 3 月
$columnFilter->createRule()
->setRule(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
array('year' => 2012, 'month' => 3)
)
->setRuleType(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_DATEGROUP
);
四、为什么必须显式指定 RuleType
原文档特别强调:必须通过 setRuleType(AUTOFILTER_RULETYPE_DATEGROUP) 显式区分 DateGroup 规则与普通标准筛选。这一区分在"执行筛选"和"写出文件"两个环节都至关重要:
- 在执行筛选(
showHideRows())时,AutoFilter.php 会根据$rule->getRuleType()判断:若是普通AUTOFILTER_RULETYPE_FILTER,走filterTestInSimpleDataSet(按值精确匹配);若是 DateGroup 规则,则把关联数组拆分为date(Ymd)、time(His)、dateTime(YmdHis)三组前缀串,交由filterTestInDateGroupSet做前缀匹配。 - 在写出 Excel2007 文件时,Writer/Excel2007/Worksheet.php 会为 DateGroup 规则生成
<dateGroupItem>子元素,把关联数组的每个键写成 XML 属性,并额外写出由setValue()推断出的dateTimeGrouping属性:
if ($rule->getRuleType() === PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_DATEGROUP) {
// Date Group filters
foreach ($rule->getValue() as $key => $value) {
if ($value > '') {
$objWriter->writeAttribute($key, $value);
}
}
$objWriter->writeAttribute('dateTimeGrouping', $rule->getGrouping());
}
也就是说,dateTimeGrouping 值(即 year / month / day / hour / minute / second 中最细的那个粒度)是 PHPExcel 根据你传入的关联数组自动计算的——这正是为什么你只需要在 setRule() 中传 year/month/day 等键、而无需手工设置分组粒度的原因。
五、让筛选真正生效:执行与遍历可见行
与简单筛选一样,PHPExcel 不会在设置或修改筛选表达式时自动执行筛选,只有在文件保存时才会把规则写入文件。如果需要在脚本内立即得到筛选结果,需手动调用 showHideRows()(参见 Executing an AutoFilter):
$autoFilter = $objPHPExcel->getActiveSheet()->getAutoFilter();
$autoFilter->showHideRows();
showHideRows() 的实现要点(见 AutoFilter.php):
- 表头行(区域起始行)始终设为可见;
- 为每个带规则的列构建"行匹配测试"(DateGroup 对应
filterTestInDateGroupSet); - 逐行取
getCalculatedValue()执行测试,多列条件之间为 AND 连接,任一列不匹配即隐藏该行; - 通过
getRowDimension($row)->setVisible($result)设置行的显隐标志。
之后若要只遍历被筛选出的行,需要配合行的可见性判断,而不是简单遍历区域内的所有行:
foreach ($objPHPExcel->getActiveSheet()->getRowIterator() as $row) {
if ($objPHPExcel->getActiveSheet()
->getRowDimension($row->getRowIndex())->getVisible()) {
// 仅处理可见(匹配筛选条件)的行
echo ' Row number - ' , $row->getRowIndex() , ' ';
echo $objPHPExcel->getActiveSheet()
->getCell('C'.$row->getRowIndex())
->getValue(), EOL;
}
}
六、DateGroup 匹配的底层原理
filterTestInDateGroupSet()(定义于 AutoFilter.php)展示了 DateGroup 匹配的核心逻辑:
- 空值/null 单元格的显隐由"是否勾选空白"(
blanks标志)决定; - 数值型单元格先通过
PHPExcel_Shared_Date::ExcelToPHP()把 Excel 序列号日期转换为 PHP 时间戳,再格式化为:- 纯时间部分(值 < 1)→
His(如093000); - 纯日期部分(值为整数)→
Ymd(如20120115); - 日期 + 时间 →
YmdHis(如20120115093000);
- 纯时间部分(值 < 1)→
- 用
substr($dtVal, 0, strlen($dateValue)) == $dateValue做前缀匹配:只要单元格日期串的开头与规则中按粒度拼接出的前缀(如2012、201201)一致,即视为命中。
这也解释了为什么粒度是"越细越精确":规则中只给 year 时前缀是 4 位年份,年内任何日期都命中;加上 month 后前缀变为 6 位,只有该月的日期命中;若再给 day,前缀扩展到 8 位,则精确到具体某一天。
七、完整可运行示例
把以上内容串起来,一个完整的"按日期分组筛选并输出 Excel2007 文件"的脚本骨架如下(参考 Examples/10autofilter.php 的结构):
require_once dirname(__FILE__) . '/Classes/PHPExcel.php';
$objPHPExcel = new PHPExcel();
$objPHPExcel->getActiveSheet()->setCellValue('A1', 'Year')
->setCellValue('B1', 'Date');
// ... 填充数据(B 列为日期,如 2012-01-05 的 Excel 序列号或日期字符串)...
// 1. 设置 AutoFilter 区域(覆盖整个已使用区域)
$objPHPExcel->getActiveSheet()->setAutoFilter(
$objPHPExcel->getActiveSheet()->calculateWorksheetDimension()
);
// 2. 取出要筛选的列(假设日期在 B 列)
$autoFilter = $objPHPExcel->getActiveSheet()->getAutoFilter();
$columnFilter = $autoFilter->getColumn('B');
// 3. 指定为标准筛选类型(DateGroup 基于 Standard Filter)
$columnFilter->setFilterType(
PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_FILTER
);
// 4. 创建 DateGroup 规则:筛选 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
);
// 5.(可选)立即在脚本内执行筛选
$autoFilter->showHideRows();
// 6. 写出 Excel2007 文件
$objWriter = PHPExcel_IOFactory::createWriter($objPHPExcel, 'Excel2007');
$objWriter->save('dategroup-filter-example.xlsx');
说明:日期分组筛选表达式的创建、读取与写出最初仅支持 Excel2007(xlsx) 格式(参见 Autofilter Expressions 总览),在依赖
.xls等旧格式时请自行验证对应 Writer 的支持情况。
八、小结与注意事项
| 要点 | 说明 |
|---|---|
| 筛选类型 | DateGroup 使用 AUTOFILTER_FILTERTYPE_FILTER(Standard Filter) |
| 规则类型 | 必须显式设置 AUTOFILTER_RULETYPE_DATEGROUP |
| 规则值 | 关联数组,键为 year/month/day/hour/minute/second,按需提供 |
| 匹配方式 | 恒为 EQUALS,按粒度前缀匹配 |
| 多规则关系 | 多条规则之间恒为 OR 连接,可创建任意条数 |
| 执行时机 | 设置规则不会自动筛选,需调用 showHideRows() 或保存文件 |
| 同列互斥 | 不同表达式类型(Simple / DateGroup / Custom / Dynamic / Top Ten)不可混用在同一列 |
掌握 DateGroup 筛选后,你可以像 Excel 一样按"某年、某年某月、乃至具体某一天"灵活筛选日期列,并依托 showHideRows() 在脚本内即时获得筛选后的可见行集合,为报表生成、数据抽取等业务场景提供准确可控的日期筛选能力。
