PHPExcel 自动筛选之 DateGroup 日期分组筛选完全指南:规则构建、源码校验与 Excel2007 读写映射
PHPExcel 自动筛选之 DateGroup 日期分组筛选完全指南:规则构建、源码校验与 Excel2007 读写映射
DateGroup(日期分组)筛选是 PHPExcel 中针对日期列的高级筛选能力,它让开发者能用 year、month、day 等时间粒度精确筛选整年、整月乃至某个时刻的数据。本文以 PHPExcel 官方 AutoFilter 文档为骨架,结合 CRMEB 仓库 crmeb/vendor/phpoffice/phpexcel 目录下的完整源码,系统讲解 DateGroup 规则的构建方法、关联数组的底层校验逻辑,以及该规则在 Excel2007(.xlsx)读写层面的 XML 映射细节。
什么是 DateGroup 筛选
在 MS Excel 中,DateGroup 筛选会为日期列提供一组级联的下拉选择器:用户可以指定整个年份、某一年中的某个月份,或者某个月份中的某一天(甚至精确到时、分、秒)。它的行为与 Excel 中"日期筛选"菜单里按年、按月、按日折叠分组的效果一致。
与 PHPExcel 的另外几类筛选表达式(Simple、Custom、Dynamic、TopTen)不同,DateGroup 筛选仍然作为标准筛选(Standard Filter)类型应用。这意味着在列(Column)层面上,它的 filterType 依然是:
$columnFilter->setFilterType(
PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_FILTER
);
而区分 DateGroup 与普通简单筛选的关键,在于规则(Rule)层面的 ruleType:只有把规则类型显式设置为 AUTOFILTER_RULETYPE_DATEGROUP,该规则才会被识别为日期分组项。这一设计可以从 Rule.php 中定义的规则类型常量看出:
const AUTOFILTER_RULETYPE_FILTER = 'filter';
const AUTOFILTER_RULETYPE_DATEGROUP = 'dateGroupItem';
const AUTOFILTER_RULETYPE_CUSTOMFILTER = 'customFilter';
const AUTOFILTER_RULETYPE_DYNAMICFILTER = 'dynamicFilter';
const AUTOFILTER_RULETYPE_TOPTENFILTER = 'top10Filter';
dateGroupItem 正是 Excel2007 OOXML 中 filters 元素下日期分组子元素的标签名,在读写环节会被直接映射为同名的 XML 节点。
前置准备:定位要筛选的列
在构造任何筛选表达式之前,先通过工作表(Worksheet)的 AutoFilter 对象取得目标列。以下代码取自 PHPExcel 官方文档 03-Autofilter-Expressions.md:
$autoFilter = $objPHPExcel->getActiveSheet()->getAutoFilter();
$columnFilter = $autoFilter->getColumn('C');
返回的 PHPExcel_Worksheet_AutoFilter_Column 对象承载了该列的全部筛选状态。从源码看,该对象默认的 filterType 即 AUTOFILTER_FILTERTYPE_FILTER,多规则连接默认 join 为 AUTOFILTER_COLUMN_JOIN_OR(见 Column.php)。换用 getColumnByOffset($index) 可按列索引取列,Excel2007 读取器恢复筛选时正是这样做的。
构建一个 DateGroup 规则
创建 DateGroup 规则时,把被"勾选"的时间值作为一个关联数组传入 setRule()。数组中可用的键共有 6 个:
| 键 | 含义 | 典型取值 |
|---|---|---|
year |
年份 | 如 2012 |
month |
月份 | 如 1(1~12) |
day |
日 | 如 1(1~31) |
hour |
时 | 如 14(0~23) |
minute |
分 | 如 30(0~59) |
second |
秒 | 如 0(0~59) |
例如要筛选 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
);
关键点:
createRule()在列的规则集中追加一个新规则并返回该规则对象(见 Column.php);setRule()的第一个参数传操作符常量,对 DateGroup 而言总是AUTOFILTER_COLUMN_RULE_EQUAL;setRuleType()必须显式设置,否则规则仍会被当作普通 filter 处理;- 一个列上可以创建任意数量的 DateGroup 规则。
关联数组的底层校验与 grouping 自动推导
在 Rule.php 的 setValue() 中,对传入的关联数组有一套严格的校验逻辑:
- 只接受
year、month、day、hour、minute、second六个键,其余键会被静默移除; - 计算
grouping(分组粒度)为所有提供的键在$dateTimeGroups数组中索引的最大值,即取最小的时间单位。例如只传year和month,分组粒度推导为month; - 如果过滤后数组为空(没有任何合法键),抛出
PHPExcel_Exception('Invalid rule value for column AutoFilter Rule.')。
对应的 $dateTimeGroups 定义如下:
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';
此外,setRuleType() 会校验类型是否在 $ruleTypes 白名单内(Rule.php),非法类型同样抛出 PHPExcel_Exception。理解这一点有助于调试"类型写错但看起来没报错"的场景——实际上非法类型会直接中断。
语义约束:永远是 EQUALS,永远是 OR
与简单筛选(Simple Filter,见 04-01-Autofilter-Expressions-Simple.md)一致,DateGroup 筛选遵循两条硬性语义:
- 所有 DateGroup 规则的比较操作符固定为 EQUALS,
setRule()第一参数应传AUTOFILTER_COLUMN_RULE_EQUAL; - 同一列上的多个 DateGroup 规则之间总是按 OR 连接——即任一规则命中即显示该行。
这正符合 Excel 的行为:在日期列上勾选 2012 年 1 月和 2012 年 3 月,展示的是两个月数据的并集。列对象的默认 join 就是 OR(Column.php),且 DateGroup 属于标准筛选,不参与 CustomFilter 的 AND/OR 自定义连接。
另外注意:PHPExcel 文档提醒,同一列内不应混用不同类型的筛选表达式(Simple / DateGroup / Custom / Dynamic / TopTen 互斥)。库不会主动阻止混用,但结果不可预期。
源码纵深:DateGroup 在 Excel2007 读写层的映射
DateGroup 不是 PHPExcel 的虚构概念,而是对 OOXML 规范中 dateGroupItem 节点的直接实现。
写入(Writer)侧
在 Writer/Excel2007/Worksheet.php 中,写出筛选规则时对 AUTOFILTER_RULETYPE_DATEGROUP 做了专门处理:
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());
}
可以看到两个值得注意的实现细节:
- 关联数组中值为空字符串的时间单位不会被写出。例如规则只传了
year和month,生成的 XML 就只含这两个属性,而不是全部 6 个; dateTimeGrouping属性取自getGrouping(),即前面setValue()自动推导出的最小时间粒度。写入容器是<filters>下的<dateGroupItem>元素(通过$objWriter->startElement($rule->getRuleType())生成,因为ruleType的值正是dateGroupItem)。
生成后的典型 XML 结构大致为:
<filterColumn colId="3">
<filters>
<dateGroupItem year="2012" month="1" dateTimeGrouping="month"/>
</filters>
</filterColumn>
读取(Reader)侧
在 Reader/Excel2007.php 中,读取器遍历 $filters->dateGroupItem,把 XML 属性还原回关联数组,并显式传入 dateTimeGrouping 作为第三个参数:
foreach ($filters->dateGroupItem as $dateGroupItem) {
$column->createRule()->setRule(
null,
array(
'year' => (string) $dateGroupItem["year"],
'month' => (string) $dateGroupItem["month"],
'day' => (string) $dateGroupItem["day"],
'hour' => (string) $dateGroupItem["hour"],
'minute' => (string) $dateGroupItem["minute"],
'second' => (string) $dateGroupItem["second"],
),
(string) $dateGroupItem["dateTimeGrouping"]
)
->setRuleType(PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_DATEGROUP);
}
读取端把 6 个时间属性全部取出(不存在的属性在 SimpleXML 中会得到空字符串),并通过 setRule() 的第三个参数显式设置分组粒度。这样,用 PHPExcel 写入的 DateGroup 筛选可以被 PHPExcel 完整读回,实现"写入—读取—再写入"的往返无损。
完整实战:筛选当月最后一天的数据
仓库中的示例 10autofilter-selection-1.php 生成了 3 年 × 12 月 × 8 国家的逐日销售数据,其中 D 列(Date)就应用了 DateGroup 筛选——筛选出当前年份每个月的最后一天:
foreach($periods as $period) {
$endDate = date('t', mktime(0,0,0,$period,1,$currentYear));
$autoFilter->getColumn('D')
->setFilterType(PHPExcel_Worksheet_AutoFilter_Column::AUTOFILTER_FILTERTYPE_FILTER)
->createRule()
->setRule(
PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_COLUMN_RULE_EQUAL,
array(
'year' => $currentYear,
'month' => $period,
'day' => $endDate
)
)
->setRuleType(PHPExcel_Worksheet_AutoFilter_Column_Rule::AUTOFILTER_RULETYPE_DATEGROUP);
}
这段代码展示了两个实用手法:
- 动态计算日期分量:
date('t', ...)获取当月的最大天数,避免硬编码 31 等可能越界的值; - 批量创建多条 OR 规则:循环 12 个月,为每个月各建一条
year + month + day的 DateGroup 规则,最终在 Excel 中呈现为"当前年份每月最后一天"共 12 个日期的并集筛选。
运行该示例需要先引入 PHPExcel 自动加载(示例通过 require_once dirname(__FILE__) . '/../Classes/PHPExcel.php' 引入),并可用 PHPExcel_IOFactory::createWriter($objPHPExcel, 'Excel2007') 输出 .xlsx 验证效果。
实践要点与常见坑位
ruleType必须显式设置:漏掉setRuleType(AUTOFILTER_RULETYPE_DATEGROUP),规则会被当作普通filter值处理,Excel 中表现为单值相等而非日期分组。- 键名拼写敏感:
year/month/day/hour/minute/second之外的多余键会被setValue()直接丢弃;若全部键非法,将抛出异常。 - 粒度自动推导:不要手工猜测
dateTimeGrouping,PHPExcel 会按"提供的键中最精细的时间单位"自动推导;如需显式指定,可在setRule()第三个参数传入(读取端即如此还原)。 - 空值写出策略:写入 .xlsx 时,值为空字符串的时间分量不会出现在 XML 中,这保证最小粒度以上的冗余属性被省略。
- 多规则即 OR:同一日期列上多条 DateGroup 规则是并集关系,若想表达"同时满足年与月"的嵌套关系,应合并为一条规则中的多个键,而不是拆成多条规则。
- 与其他筛选类型互斥:不要在同一列混合 DateGroup 与 Custom/Dynamic/TopTen 筛选,PHPExcel 不阻止但结果不可预期。
通过以上 API 用法与源码细节,开发者可以在 PHPExcel 中完整复现 Excel 原生的日期分组筛选体验,并理解 dateGroupItem 在 OOXML 层面的完整生命周期。
