PHPExcel AutoFilter 日期分组筛选(DateGroup Filter)完整指南:按年、月、日、时分秒精确筛选日期列

原创2026-09-22 21:47:261,614 阅读
文章标签:后端数据处理

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 AutoFilter 日期分组筛选下拉效果

在 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
    );

关键点:

  1. createRule() 在列对象内部追加一条新规则并返回该规则对象(见 Column.php 中 createRule() 的实现:$this->ruleset[] = new PHPExcel_Worksheet_AutoFilter_Column_Rule($this);)。
  2. setRule() 的第一个参数是操作符,DateGroup 规则固定使用 AUTOFILTER_COLUMN_RULE_EQUAL(等于)。
  3. 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):

  1. 表头行(区域起始行)始终设为可见;
  2. 为每个带规则的列构建"行匹配测试"(DateGroup 对应 filterTestInDateGroupSet);
  3. 逐行取 getCalculatedValue() 执行测试,多列条件之间为 AND 连接,任一列不匹配即隐藏该行;
  4. 通过 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 匹配的核心逻辑:

  1. 空值/null 单元格的显隐由"是否勾选空白"(blanks 标志)决定;
  2. 数值型单元格先通过 PHPExcel_Shared_Date::ExcelToPHP() 把 Excel 序列号日期转换为 PHP 时间戳,再格式化为:
    • 纯时间部分(值 < 1)→ His(如 093000);
    • 纯日期部分(值为整数)→ Ymd(如 20120115);
    • 日期 + 时间 → YmdHis(如 20120115093000);
  3. 用 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() 在脚本内即时获得筛选后的可见行集合,为报表生成、数据抽取等业务场景提供准确可控的日期筛选能力。

登录后查看全文
PHPExcel