企业官网建设流程全解析

PHPExcel 自动筛选（AutoFilter）功能完全指南：从概念到源码实现

【免费下载链接】PHPExcelARCHIVED项目地址: https://gitcode.com/gh_mirrors/ph/PHPExcel

导读

本篇指南以 PHPExcel 官方 Autofilters 系列文档为核心，系统讲解 Excel 自动筛选（AutoFilter）在 PHPExcel 中的概念模型、设置方式、五种筛选表达式类型及执行原理。读完本篇，你将掌握如何通过setAutoFilter()为工作表指定筛选区域、如何识别"启用未应用"与"已应用"两种筛选状态、如何编写简单/日期分组/自定义/动态/Top Ten 五类筛选规则，并理解底层showHideRows()逐行判定行显隐的实现机制，从而在自己的报表生成与数据处理脚本中直接落地这些能力。

一、什么是自动筛选

在 Excel 工作簿中，每个工作表只能包含一个自动筛选区域（autoFilter range）。自动筛选的作用是：只显示满足你指定条件的行，隐藏不希望显示的行。你可以同时依据多个列进行筛选，且筛选是**叠加（additive）**的——每增加一个列的筛选条件，都是基于当前筛选结果进一步缩小数据子集。

在 PHPExcel 中，这一概念由 Classes/PHPExcel/Worksheet/AutoFilter.php 中的PHPExcel_Worksheet_AutoFilter类实现。该类持有两个核心状态：

• $range：自动筛选作用的单元格区域字符串（如A1:E20）；
• $columns：各列上已定义的筛选规则集合（PHPExcel_Worksheet_AutoFilter_Column对象数组）。

标题行与数据行的边界

当一个自动筛选区域被设置后，区域中的第一行是标题行（heading row），它显示自动筛选的下拉图标，但不属于实际被筛选的数据；其后的所有行才是被筛选的数据行。因此，一个合法的自动筛选区域应当始终包含标题行以及一行或多行数据行。

单行数据几乎没有筛选意义，但 PHPExcel 并不会阻止你设置这样一个无意义的区域——是否避免这类错误，取决于开发者自己。

从源码看，setRange()只做两类校验（AutoFilter.php）：

if (strpos($pRange, ':') !== false) { $this->range = $pRange; } elseif (empty($pRange)) { $this->range = ''; } else { throw new PHPExcel_Exception('Autofilter must be set on a range of cells.'); }

即：区域必须是一个包含冒号（:）的单元格区间（如A1:E20），或者为空字符串（表示清除筛选）。传入非区间形式（如单个单元格A1）会直接抛出PHPExcel_Exception('Autofilter must be set on a range of cells.')。区域变更后，超出新区间范围的列规则也会被自动丢弃。

二、判断筛选状态：两个关键图标

在 Excel 界面中，通过列标题上的图标即可判断筛选状态：

下拉箭头：筛选已启用但未应用

列标题上显示下拉箭头，表示该列已启用筛选功能，但当前没有应用任何筛选条件。当鼠标悬停在该列标题上时，Excel 会显示提示气泡：该列第一行的单元格文本，以及消息 "(Showing All)"，表示当前显示全部数据。

漏斗按钮：筛选已应用

列标题上显示漏斗状筛选按钮，表示该列已应用了筛选条件。悬停时，提示气泡会显示实际应用的筛选描述，例如 "Equals a red cell color"（等于某个单元格颜色）或 "Larger than 150"（大于 150）。

在 PHPExcel 的对象模型中，"启用未应用"与"已应用"的差异体现在PHPExcel_Worksheet_AutoFilter_Column对象上：列对象默认存在（可通过getColumn()获取），而真正筛选生效的前提是列对象上设置了具体的规则（Rule）。关于列类型与规则的定义，可查看 Classes/PHPExcel/Worksheet/AutoFilter/Column.php。

三、设置自动筛选区域

设置一个自动筛选区域，只需一行代码（详见 02-Setting-an-Autofilter.md）：

$objPHPExcel->getActiveSheet()->setAutoFilter('A1:E20');

这为当前活动工作表设置了A1:E20区域的自动筛选。第一个工作表实例内部的调用链是：Worksheet::setAutoFilter($pRange)创建/更新一个PHPExcel_Worksheet_AutoFilter对象（该对象同时保存对其父级工作表的引用，见AutoFilter的__construct($pRange, $pSheet)与getParent()/setParent()），区域以字符串形式存储，列规则按需惰性创建。

如果希望把整个工作表作为自动筛选区域，可以结合calculateWorksheetDimension()动态计算已使用区域：

$objPHPExcel->getActiveSheet()->setAutoFilter( $objPHPExcel->getActiveSheet() ->calculateWorksheetDimension() );

注意：上述两种方式都只是启用了筛选功能，并不会真正应用任何筛选条件——即只产生"下拉箭头"状态，不会隐藏任何行。

获取与操作筛选对象

设置区域后，你可以通过以下 API 操作自动筛选（均在 Classes/PHPExcel/Worksheet/AutoFilter.php 中定义）：

其中getColumn('C')是编写筛选表达式前最常用的入口：

$autoFilter = $objPHPExcel->getActiveSheet()->getAutoFilter(); $columnFilter = $autoFilter->getColumn('C');

getColumn()内部会先调用testColumnInRange()做越界校验——如果C列不在当前筛选区域内，会抛出PHPExcel_Exception("Column is outside of current autofilter range.")。

四、筛选表达式的五种类型

PHPExcel 1.7.8 引入了真正创建、读取和写入筛选表达式的能力；最初仅支持 Excel2007 文件格式，后续版本逐步扩展到其他格式（详见 03-Autofilter-Expressions.md）。

要应用筛选表达式，首先需要定位要筛选的列（如上节的$columnFilter），然后在该列对象上设置筛选类型与规则。最常用的五种表达式类型：

1. Simple Filters（简单筛选）—— 从列的值列表中勾选要显示的值；
2. DateGroup Filters（日期分组筛选）—— 按年/月/日/时/分/秒的层级选择日期；
3. Custom Filters（自定义筛选）—— 使用运算符（如大于、小于、介于）与通配符组合条件；
4. Dynamic Filters（动态筛选）—— 基于当前日期或数据聚合（如"今天"、"高于平均值"）的动态条件；
5. Top Ten Filters（前 N 项筛选）—— 筛选数值最大/最小的若干项或若干百分比。

这些类型在同一列内是互斥的。虽然 PHPExcel 不会主动阻止你在同一列混用不同类型，但结果不可预测，开发者应当避免。

其他筛选表达式类型（例如按单元格颜色筛选）目前尚未支持。

上述五种类型对应PHPExcel_Worksheet_AutoFilter_Column类中的四种筛选类型常量（Column.php）：

4.1 简单筛选（Simple Filters）

在 MS Excel 中，简单筛选是该列所有值组成的下拉列表，用户通过勾选/取消复选框决定显示哪些值、隐藏哪些值。选中项的对应行被显示，未选中的值所在行被隐藏（详见 04-01-Autofilter-Expressions-Simple.md）。

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

• 简单筛选永远使用EQUAL（等于）比较；
• 多条简单筛选规则之间恒为 OR（或）连接；
• 规则数量不设上限。

匹配空白单元格：如果想筛选出空单元格，将值置为空字符串即可：

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

在底层，简单筛选的判定由AutoFilter::filterTestInSimpleDataSet()完成：空白/null单元格按blanks标志决定是否显示，非空单元格用in_array()判断是否命中勾选集合（AutoFilter.php）。

4.2 日期分组筛选（DateGroup Filters）

日期分组筛选提供针对日期值的层级下拉选择器：可以指定整个年份、某年中的某个月、乃至某月中的某一天（详见 04-02-Autofilter-Expressions-Dategroup.md）。

日期分组筛选仍然使用简单筛选的筛选类型：

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

关键点：

• 关联数组的合法键为year、month、day、hour、minute、second；
• 与简单筛选一致：恒为 EQUAL 比较、多条规则间恒为 OR 连接、数量不限；
• 必须显式将规则类型设置为AUTOFILTER_RULETYPE_DATEGROUP，以区别于普通简单筛选。

底层判定由filterTestInDateGroupSet()完成：先把 Excel 序列日期值经PHPExcel_Shared_Date::ExcelToPHP()转成时间戳，再按"仅时间 / 仅日期 / 日期时间"三种情况，把YmdHis格式串与规则中各组件的拼接值做前缀匹配（AutoFilter.php）。

4.3 自定义筛选（Custom Filters）

自定义筛选允许使用"运算符 + 值"表达更复杂的条件，例如取值落在某个区间（如 -20 到 +20 之间），或使用通配符匹配文本（如以字母 U 开头）。自定义筛选最多两条规则，两条规则之间可用 AND 或 OR 连接（详见 04-03-Autofilter-Expressions-Custom.md）。

先设置筛选类型为自定义筛选：

$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"；
• ?匹配单个字符；
• 用波浪号~转义字面*或?，例如~*匹配字面星号；唯一需要额外转义的字符是~本身。

在源码实现中，非数值的规则值会先经preg_quote()转义正则保留字符，再通过$fromReplace/$toReplace两个替换数组把 Excel 通配符语法翻译成正则语法（\*→.*、\?→.、~~→~等），最后用preg_match('/^'.$rule['value'].'$/i', $cellValue)做大小写不敏感匹配（AutoFilter.php）。

"介于"区间示例——筛选数值在 -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 );

然后必须把两条规则的连接条件改为AND（默认是 OR）：

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

对应源码中列对象的join属性默认值为AUTOFILTER_COLUMN_JOIN_OR（Column.php），通过setJoin()/setAndOr()可切换为 AND。filterTestInCustomDataSet()中 AND 与 OR 的短路逻辑清晰可见：OR 连接一旦命中立即返回true，AND 连接则须全部规则通过（AutoFilter.php）。

自定义筛选合法的运算符常量（定义于PHPExcel_Worksheet_AutoFilter_Column_Rule类）：

4.4 动态筛选（Dynamic Filters）

动态筛选基于动态比较条件，比较值本身是变化的：要么与当前日期相关（如"今天"），要么基于单元格数据的聚合（如"高于平均值"）。同一列同一时刻只能应用一条动态筛选规则（详见 04-04-Autofilter-Expressions-Dynamic.md）。

设置筛选类型：

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

定义规则时不指定值（可传NULL），而通过setRule()的第三个参数指定动态筛选类别。例如筛选"年初至今"：

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

动态筛选类别完整清单（定义于PHPExcel_Worksheet_AutoFilter_Column_Rule类）：

从源码看，动态日期范围由dynamicFilterDateRange()计算：以DATENOW()为基准，按类别（周/月/季度/年）向前或向后推算起始值val与终止值maxVal，再转成两条自定义规则（>= val且< maxVal）交给filterTestInCustomDataSet()判定（AutoFilter.php）；而"高于/低于平均值"则直接构造=AVERAGE(列范围)公式交给计算引擎求值，再以大于/小于该平均值为条件筛选（AutoFilter.php）。

4.5 Top Ten 筛选（Top Ten Filters）

Top Ten 筛选与动态筛选类似，都基于对实际单元格数据的汇总计算；不同的是，Top Ten 允许你指定多个选择维度：

• 取最高（Top）还是最低（Bottom）值；
• 取多少项（数量）；
• 按百分比（percent）还是按条目数（value）计算。

与动态筛选一致，同一列同一时刻只能应用一条 Top Ten 规则（详见 04-05-Autofilter-Expressions-Topten.md）。

设置筛选类型（注意常量名是TOPTENFILTER）：

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

筛选前 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 by value）：

$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 Ten 相关常量（定义于PHPExcel_Worksheet_AutoFilter_Column_Rule类）：

底层实现中，calculateTopTenValue()会把该列数据区（不含标题行）读入数组、过滤空值，再按 Top 降序 / Bottom 升序排序，取出前 N 个值中的临界值；百分比模式先换算为行数（floor($ruleValue * ($dataRowCount / 100))），并强制收敛到 1~500 之间（AutoFilter.php），最终以>= 临界值或<= 临界值的形式执行。

五、执行筛选：showHideRows() 的工作原理

MS Excel 中应用自动筛选时，会基于所选条件为筛选区域内的每一行设置隐藏/显示标志，只展示匹配条件的行。PHPExcel不会在你设置或修改筛选表达式时自动执行等效操作，而只在文件保存时按需触发。

手动执行筛选

若要在脚本中立即执行筛选，需要手动调用showHideRows()：

$autoFilter = $objPHPExcel->getActiveSheet()->getAutoFilter(); $autoFilter->showHideRows();

该方法会把区域内所有匹配条件的行设为可见，隐藏其余行（AutoFilter.php）。其执行流程可分为四步：

1. 标题行恒可见：区域首行（标题行）始终setVisible(true)；
2. 构建每列的测试函数：遍历$columns，按列筛选类型（简单/日期分组/自定义/动态/Top Ten）把规则编译为一个"测试方法 + 参数"结构（如filterTestInSimpleDataSet、filterTestInDateGroupSet、filterTestInCustomDataSet、filterTestInPeriodDateSet）；
3. 逐行执行测试：从标题行下一行开始，逐行取出各列单元格的计算值（getCalculatedValue()），调用对应的测试方法并做 AND 合取——任一列不匹配立即短路跳出，避免多余计算；
4. 设置行显隐：根据判定结果调用getRowDimension($row)->setVisible($result)更新行维度。

注意步骤 3 使用的是getCalculatedValue()，即公式单元格会先被计算引擎求值，再进行筛选比较。

遍历并显示已筛选的行

需要强调的是：直接循环遍历筛选区域的行，仍会访问到所有行，无论它是否匹配筛选条件。要只处理被筛选出来的行，需要逐行检查行维度的可见性标志：

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(), ' '; echo $objPHPExcel->getActiveSheet() ->getCell( 'D'.$row->getRowIndex() )->getFormattedValue(), ' '; echo EOL; } }

这段代码先通过getRowIterator()遍历工作表所有行，再用getRowDimension()->getVisible()过滤出可见行，最后输出 C 列原始值与 D 列格式化值。

六、进一步阅读

本系列文档的其他篇目可继续深入：

• 02-Setting-an-Autofilter.md：设置自动筛选区域的完整说明；
• 03-Autofilter-Expressions.md：筛选表达式类型的总览与互斥性说明；
• 04-01-Autofilter-Expressions-Simple.md：简单筛选与空白单元格匹配；
• 04-02-Autofilter-Expressions-Dategroup.md：日期分组筛选；
• 04-03-Autofilter-Expressions-Custom.md：自定义筛选与通配符；
• 04-04-Autofilter-Expressions-Dynamic.md：动态筛选类别清单；
• 04-05-Autofilter-Expressions-Topten.md：Top Ten 筛选；
• 05-Executing-Autofilters.md：手动执行筛选与遍历可见行；
• 06-Autofilter-Sorting.md：筛选与排序配合使用。

核心源码与测试参考：

• Classes/PHPExcel/Worksheet/AutoFilter.php：自动筛选核心类（区域、列规则、showHideRows()）；
• Classes/PHPExcel/Worksheet/AutoFilter/Column.php：筛选列对象与四种筛选类型常量；
• Classes/PHPExcel/Worksheet/AutoFilter/Column/Rule.php：筛选规则对象与运算符、动态类别、Top Ten 常量；
• unitTests/Classes/PHPExcel/Worksheet/AutoFilterTest.php：自动筛选相关单元测试，可作为行为验证参考。

【免费下载链接】PHPExcelARCHIVED项目地址: https://gitcode.com/gh_mirrors/ph/PHPExcel