Yii 2 排序实战:基于 yii\data\Sort 实现用户可控的数据排序
Yii 2 排序实战:基于 yii\data\Sort 实现用户可控的数据排序
本文以 Yii 2 框架的官方指南 docs/guide-ru/output-sorting.md 为核心,深入讲解如何利用 yii\data\Sort 对象为列表数据提供用户可控的排序能力:从声明可排序属性、处理简单属性与复合属性,到生成排序链接、集成数据提供者与数据小部件。读完本文,你将能够为 Active Record 查询、SQL 查询乃至内存数组完整落地"点击表头排序"的实战方案,并理解其底层实现原理。
1. 排序问题的本质:为什么需要 Sort 对象
在展示多行数据(如文章列表、商品列表)时,几乎总是需要让用户按某些列进行排序。手工实现通常要处理三件事:解析请求参数、校验哪些列允许排序、把排序指令翻译成数据库的 ORDER BY。Yii 2 用 yii\data\Sort 这个类统一封装了上述逻辑,它本质上是一个"排序方案描述器",承担三个核心职责:
- 声明:通过
attributes声明哪些属性(列)允许被排序; - 解析:读取当前请求(默认是 query 参数
sort),解析出每个属性当前的排序方向; - 输出:把排序方向转换为数据库可识别的低层列与方向映射,并生成用户可点击的排序链接。
对应地,framework/data/Sort.php 中定义了三组核心成员,理解它们是掌握排序功能的第一步:
| 成员 | 含义 | 典型值 |
|---|---|---|
Sort::$attributes |
允许排序的属性列表。属性可以对应模型的简单属性,也可以是组合多个模型属性或数据库列的复合属性 | ['age', 'name' => ['asc' => [...], 'desc' => [...]]] |
Sort::$attributeOrders |
当前请求下按属性名索引的排序方向 | ['age' => SORT_ASC, 'name' => SORT_DESC] |
Sort::$orders |
当前请求下按低层列名索引的排序方向,可直接喂给数据库查询的 ORDER BY |
['first_name' => SORT_DESC, 'last_name' => SORT_DESC] |
从源码结构看(见 framework/data/Sort.php),orders 是 attributeOrders 的"展开版":getOrders() 会遍历每个已排序属性,把属性定义中 asc/desc 对应的真实列逐一展开成列名到方向的映射。因此 orders 永远以真实数据库列为键,而 attributeOrders 以逻辑属性名为键,二者不能混用。
2. 最小可用示例:声明属性并驱动查询
Sort 的基本用法分三步:声明可排序属性 → 从对象取当前排序方向 → 注入数据查询。官方指南给出的完整示例(原文见 docs/guide-ru/output-sorting.md)如下:
use yii\data\Sort;
$sort = new Sort([
'attributes' => [
'age',
'name' => [
'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
'default' => SORT_DESC,
'label' => 'Name',
],
],
]);
$articles = Article::find()
->where(['status' => 1])
->orderBy($sort->orders)
->all();
这里为 Sort 声明了两个可排序属性:
age是简单属性,直接对应ArticleActive Record 类的age属性;name是复合属性,它并不存在于模型中,而是由first_name与last_name两个真实列组合而成。
->orderBy($sort->orders) 这一行是关键:orders 返回的是"列名 => 排序方向"的映射,可以直接传给查询构建器生成 ORDER BY 子句。当用户请求按 name 降序排列时,实际生成的 SQL 相当于 ORDER BY first_name DESC, last_name DESC。
注意(官方指南 Info 提示):构造数据库查询的
ORDER BY时,必须使用$sort->orders而非$sort->attributeOrders。因为某些属性可能是复合属性(如上面的name),attributeOrders里的键是逻辑属性名name,数据库查询无法识别;而orders已经展开为真实列名。
2.1 简单属性背后的完整声明
age 这种简单写法是 Yii 提供的语法糖。在源码 framework/data/Sort.php 的 init() 方法中,简单字符串形式的属性会被自动展开成如下等价声明:
'age' => [
'asc' => ['age' => SORT_ASC],
'desc' => ['age' => SORT_DESC],
'default' => SORT_ASC,
'label' => Inflector::camel2words('age'),
]
也就是说,每个属性最终都会拥有四要素:asc(升序时的列与方向)、desc(降序时的列与方向)、default(首次请求时的默认方向)、label(排序链接的显示文本)。init() 的规范化逻辑同时支持三种写法:
- 字符串
'age':自动生成同名列的升/降序定义; - 数组但缺少
asc/desc:自动补齐基于属性名本身的升/降序定义,再与给定配置合并; - 数组且包含
asc/desc:完整使用自定义定义(如复合属性)。
提示:如果
Sort对象已创建(例如后续再修改属性),则每个属性必须使用包含asc和desc的完整格式进行配置(见 framework/data/Sort.php 的注释说明)。
3. 复合属性详解:asc / desc / default / label
当排序规则无法用单一列表达时,就需要复合属性。官方指南以 name 为例拆解了声明结构中的四个配置项:
asc与desc:分别指定按该属性升序、降序排序时的真实列与方向。值可以是单个列(简单排序),也可以是多个列的映射(复合排序)。上面示例中name升序等价于ORDER BY first_name ASC, last_name ASC。default:指定属性被首次请求排序时的方向。默认是升序——即该属性此前未参与排序、用户第一次点击其排序链接时,数据按升序排列。示例中'default' => SORT_DESC表示第一次点击name链接时按降序排列。label:调用Sort::link()生成排序链接时使用的显示文本。不设置时,框架会调用yii\helpers\Inflector::camel2words()从属性名自动生成(例如created_at会变为 "Created At")。注意:label不会进行 HTML 转义,如果需要输出包含特殊字符的标签,需自行处理。
3.1 高级用法:直接排序表达式(2.0.12+)
从 Yii 2.0.12 起(见 framework/data/Sort.php),asc/desc 的值除了列映射数组外,还可以是直接排序表达式字符串,用于表达数据库特定功能:
'name' => [
'asc' => '[[last_name]] ASC NULLS FIRST', // PostgreSQL 特定语法
'desc' => '[[last_name]] DESC NULLS LAST',
]
当 asc/desc 是字符串而非数组时,getOrders() 会把它作为完整的排序表达式原样放进 orders 数组(见 framework/data/Sort.php)。这一特性在 tests/framework/data/SortTest.php 的 testGetExpressionOrders 测试中有明确验证:请求 -name(降序)时,getOrders() 返回 ['[[last_name]] DESC NULLS LAST']。这为需要自定义 NULLS FIRST/LAST、函数表达式等场景提供了出口。
4. 解析请求:sort 参数的格式与处理流程
Sort 通过读取 query 参数(默认名为 sort)来判断用户请求了哪些排序。参数值的格式约定为:
- 升序:直接写属性名,如
sort=age; - 降序:属性名前加
-前缀,如sort=-age; - 多属性:用逗号分隔(分隔符可通过
$sort->separator配置,默认,),如sort=age,-name表示age升序、name降序。
源码 getAttributeOrders()(见 framework/data/Sort.php)的处理流程如下:
- 若未显式配置
params,则从当前请求(yii\web\Request::getQueryParams())中读取参数; - 解析
sortParam指定的参数值,通过parseSortParam()(默认按separator用explode拆分)得到属性名列表; - 对每个属性名检查
-前缀以确定方向,并校验该属性是否在attributes中声明过——未声明的属性会被静默忽略,这天然防止了任意列注入排序; - 若参数不存在或解析结果为空,则回退到
defaultOrder(若已配置); - 默认情况下(
enableMultiSort = false)只取第一个有效属性,命中后立即返回。
parseSortParam() 是 protected 方法,允许子类重写以支持自定义参数格式——测试 tests/framework/data/SortTest.php 中的 CustomSort 就演示了如何解析 [['field' => 'age', 'dir' => 'asc'], ...] 这种结构化参数。
4.1 默认排序与参数名定制
当请求中没有 sort 参数时,可以通过 defaultOrder 指定默认排序。该属性是"属性名 => 方向"的映射:
$sort = new Sort([
'attributes' => [...],
'defaultOrder' => [
'name' => SORT_ASC,
'created_at' => SORT_DESC,
],
]);
defaultOrder 的值直接作为 attributeOrders 使用(见 framework/data/Sort.php),因此同样适用于复合属性,并且同样要经过 getOrders() 展开为真实列后传给查询。
如果想改变 query 参数名(例如避免与其他系统参数冲突,或数据提供者同页存在多个排序场景),配置 sortParam 即可:
$sort = new Sort([
'attributes' => [...],
'sortParam' => 'order', // 此时读取 ?order=age 而非 ?sort=age
]);
sortParam 默认值为 'sort'(见 framework/data/Sort.php)。
5. 生成排序链接:link() 与 createUrl()
5.1 createUrl():纯 URL 生成
createUrl($attribute, $absolute = false) 生成一个指向"按指定属性排序"的 URL(见 framework/data/Sort.php)。它的核心逻辑:
- 保留当前请求的其他 query 参数(基于
params,默认$_GET),只替换sortParam的值; - 路由默认取当前控制器路由,可通过
$sort->route显式指定; - 内部调用
createSortParam($attribute)计算新的排序参数值:若该属性当前是升序,则生成降序参数(点击后切换方向);若是降序,则切换回升序;若从未排序,则采用default定义的方向。
官方指南示例:
// 指定生成 URL 使用的路由;不指定时使用当前请求路由
$sort->route = 'article/index';
// 分别生成按 name、按 age 排序的链接
echo $sort->link('name') . ' | ' . $sort->link('age');
// 输出:/index.php?r=article%2Findex&sort=age
echo $sort->createUrl('age');
5.2 link():带状态的超链接
link($attribute, $options = <a href="https://link.gitcode.com/i/643c58a7ce822b207af3c7a1bd0c9f32" target="_blank">]) 在 createUrl() 基础上生成完整 <a> 标签(见 [framework/data/Sort.php),并附加两个实用特性:
- 方向 CSS 类:若该属性当前正按升序排序,链接的
class会追加asc;按降序排序则追加desc。前端可据此给表头加箭头指示。 data-sort属性:链接会携带data-sort属性,值为新的排序参数,便于前端 JavaScript 拦截与 AJAX 化处理。
link() 的标签文本解析顺序为:$options<a href="https://link.gitcode.com/i/d33bd0777b72d21fef8ec358d22ae71c" target="_blank">'label'] 显式指定 → 属性定义中的 label → modelClass(2.0.49+ 支持,见 [framework/data/Sort.php)对应的模型 getAttributeLabel() → Inflector::camel2words($attribute) 自动生成。同样的,标签不会被 HTML 编码。
测试 tests/framework/data/SortTest.php 验证了 link() 在多种方向组合下的输出,例如升序时输出:
<a class="asc" href="/index.php?r=site%2Findex&sort=-age" data-sort="-age">Age</a>
6. 多属性同时排序:enableMultiSort
默认情况下 enableMultiSort = false,意味着同一时刻只能按一个属性排序——用户点击新的排序链接会重置之前的排序。若需要支持"按住修饰键同时按多列排序"的场景,可开启多属性排序:
$sort = new Sort([
'attributes' => [...],
'enableMultiSort' => true,
]);
开启后,createSortParam() 的行为变为:若属性当前是升序,新的参数把它切换为降序并保持其他属性;若当前是降序,则把该属性从排序中移除(见 framework/data/Sort.php)。测试 tests/framework/data/SortTest.php 覆盖了这类交互,例如请求 sort=age,-name 时点击 name 会生成 sort=age(移除 name),点击 age 会生成 sort=-age,-name(切换 age 方向并保持 name)。
此外,getAttributeOrders($recalculate) 与 getOrders($recalculate) 支持传 true 强制重算,这在同一请求内修改 params 后需要重新解析时很有用(测试 tests/framework/data/SortTest.php 正是这样验证 enableMultiSort 开关效果的)。从 2.0.33 起还提供 sortFlags 属性,用于控制传给 ArrayHelper::multisort() 的排序标志(如 SORT_NUMERIC、SORT_STRING),对内存数组排序场景有实际意义。
7. 与数据提供者和数据小部件的集成
单独使用 Sort 对象驱动查询是基础用法;更常见的做法是把它配置进数据提供者,由 GridView、ListView 等数据小部件自动渲染排序链接。
7.1 通过数据提供者使用
yii\data\BaseDataProvider 的 sort 属性接受三种值:配置数组(自动创建 yii\data\Sort 实例)、Sort 实例、或 false(禁用排序)。见 framework/data/BaseDataProvider.php。以下为官方指南 docs/guide/output-data-providers.md 中的完整示例:
use yii\data\ActiveDataProvider;
$provider = new ActiveDataProvider([
'query' => Post::find(),
'pagination' => [
'pageSize' => 10,
],
'sort' => [
'defaultOrder' => [
'created_at' => SORT_DESC,
'title' => SORT_ASC,
],
],
]);
ActiveDataProvider 会读取 sort 配置生成 Sort 对象,并自动把 $sort->orders 注入查询的 ORDER BY(SqlDataProvider 则相应调整 SQL 的 ORDER BY 子句;ArrayDataProvider 在内存中调用 ArrayHelper::multisort() 完成排序)。
注意(官方指南 Note):如果查询本身已指定
orderBy,用户通过sort配置发来的新排序指令会追加到现有orderBy之后,而不是覆盖它;而分页请求会覆盖已有的limit/offset。
与数据提供者集成时还有一个细节:当数据提供者设置了 id(同页存在多个数据提供者时自动生成 dp-1、dp-2 等),BaseDataProvider::setSort() 会把 sortParam 自动改为 dp-1-sort 这种带前缀的参数名,避免同页多个排序控件互相冲突(见 framework/data/BaseDataProvider.php)。
7.2 通过 LinkSorter 小部件渲染
若不想手写 link() 循环,可以使用 yii\widgets\LinkSorter 小部件(见 framework/widgets/LinkSorter.php),它会为 Sort::attributes 中声明的每个属性自动生成一个排序链接,并输出为 <ul> 列表:
use yii\widgets\LinkSorter;
echo LinkSorter::widget([
'sort' => $sort,
// 'attributes' => ['age', 'name'], // 可选:只渲染部分属性
// 'options' => ['class' => 'sorter'], // 容器 HTML 属性
]);
LinkSorter 的 attributes 属性可限制渲染哪些排序链接;options 默认给容器加上 sorter CSS 类;linkOptions(2.0.6+)用于向 Sort::link() 传递链接的额外 HTML 属性。该小部件的 init() 要求 sort 属性必须设置,否则抛出 InvalidConfigException。GridView 小部件内部同样通过 renderSorter() 复用 LinkSorter 渲染表头排序链接(见 framework/grid/GridView.php 中 {sorter} 相关说明)。
8. 完整实战:文章列表按年龄与姓名排序
综合上述知识点,一个完整的"控制器 + 视图"落地示例(基于官方指南 docs/guide-ru/output-sorting.md 示例扩展)如下。
控制器动作:
use yii\data\Sort;
public function actionIndex()
{
$sort = new Sort([
'attributes' => [
'age',
'name' => [
'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
'default' => SORT_DESC,
'label' => 'Name',
],
],
'defaultOrder' => ['name' => SORT_ASC],
]);
$articles = Article::find()
->where(['status' => 1])
->orderBy($sort->orders)
->all();
return $this->render('index', [
'articles' => $articles,
'sort' => $sort,
]);
}
视图模板:
<?php
// 显示排序链接
echo $sort->link('name') . ' | ' . $sort->link('age');
foreach ($articles as $article) {
// 展示文章数据
}
此时访问列表页:
- 不带任何参数:按
defaultOrder(name升序,即first_name ASC, last_name ASC)排序; - 访问
?sort=age:按age升序排列,name链接的class变为asc(若再点击则切换为降序); - 访问
?sort=-name:按first_name DESC, last_name DESC排列; - 访问
?sort=foo:foo未声明,被静默忽略,回退到默认排序。
9. 小结与进一步阅读
yii\data\Sort 是 Yii 2 数据层中处理排序的标准组件,其设计把"声明允许排序的属性"与"解析当前排序请求"彻底解耦:声明层用 attributes 白名单控制可排序范围(天然防御任意列注入),解析层用 - 前缀 + 逗号分隔的紧凑参数格式承载方向与多属性信息,输出层通过 orders 把逻辑属性翻译成数据库真实列。无论是手写查询、配合 ActiveDataProvider/SqlDataProvider/ArrayDataProvider,还是直接使用 GridView、LinkSorter,都可以复用同一套机制。
相关实现与测试文件索引:
- 核心类实现:framework/data/Sort.php
- 数据提供者集成:framework/data/BaseDataProvider.php
- 排序链接小部件:framework/widgets/LinkSorter.php
- 单元测试(覆盖参数解析、URL 生成、多属性排序、表达式排序):tests/framework/data/SortTest.php
- 官方指南配套主题:数据提供者、分页、数据小部件、模型属性说明