Yii 2 数据排序完全指南:掌握 yii\data\Sort 从属性声明到排序链接的完整实现
Yii 2 数据排序完全指南:掌握 yii\data\Sort 从属性声明到排序链接的完整实现
在 Yii 2 框架中,当需要向终端用户展示多行数据并允许其按指定列排序时,yii\data\Sort 对象承担了排序方案的建模与实现工作。本指南以官方指南文档(docs/guide-pt-BR/output-sorting.md)为核心骨架,结合框架源码(framework/data/Sort.php)与单元测试(tests/framework/data/SortTest.php)深入展开,帮助你从属性声明、排序信息提取、查询接入,到排序链接生成与数据提供器集成,完整掌握 Yii 2 的排序能力。
理解 Sort 对象:排序方案的三要素
Yii 2 使用一个 yii\data\Sort 对象来表示"排序方案"(sorting schema)的全部信息。该对象有三个核心概念:
attributes(yii\data\Sort::$attributes):声明数据允许按照哪些属性(attribute)进行排序。一个属性既可以是简单的模型属性,也可以是由多个模型属性或数据库列组合而成的复合属性。attributeOrders(yii\data\Sort::$attributeOrders):以属性名为索引,给出当前请求为每个属性指定的排序方向(升序SORT_ASC或降序SORT_DESC)。orders(yii\data\Sort::$orders):以底层数据库列(key)及其排序方向(value)表示的排序指令,可以直接喂给数据库查询构造ORDER BY子句。
从源码层面看,这三者之间存在明确的转换关系:getAttributeOrders() 负责从查询参数解析出"按属性名索引"的排序方向,而 getOrders() 再把属性级的排序方向映射为"按数据库列索引"的排序指令。二者的区别正是文档中反复强调的:属性名并不总是等同于列名,复合属性的一个逻辑属性可以对应多个真实列。
声明可排序属性:简单属性与复合属性
使用 Sort 的第一步是声明允许排序的属性。以下示例声明了两个属性 age 和 name:
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',
],
],
]);
简单属性:age
age 是一个简单属性,直接对应 Article Active Record 类的 age 属性。上面的简写形式等价于如下完整声明:
'age' => [
'asc' => ['age' => SORT_ASC],
'desc' => ['age' => SORT_DESC],
'default' => SORT_ASC,
'label' => Inflector::camel2words('age'),
]
简单属性之所以可以简写,是因为 Sort::init() 会在对象初始化时对 attributes 做规范化:当某项不是数组时,自动为其补齐 asc、desc 的默认映射(列名即属性名,方向分别为 SORT_ASC 与 SORT_DESC);当某项是数组但缺少 asc/desc 键时,同样会按属性名自动补全。从源码可以看到,完整格式下每个属性必须包含 asc 和 desc 两个元素。
复合属性:name
name 是一个复合属性,由 Article 的 first_name 和 last_name 两个列共同定义。声明结构中的元素含义如下:
asc/desc:分别指定按该属性升序、降序排序时的实际列与方向。值可以是一列(简单排序)也可以是多列(复合排序)。以name为例,升序时按first_name ASC, last_name ASC排序,降序时按first_name DESC, last_name DESC排序。default:指定首次请求按该属性排序时的默认方向。默认值为升序(SORT_ASC)——如果此前尚未按该属性排序过,用户点击排序链接后将按升序排列。label:调用Sort::link()生成排序链接时使用的标签文本。若未设置,会调用yii\helpers\Inflector::camel2words()从属性名生成可读标签。注意:该标签不会被 HTML 编码,如果需要包含特殊字符,应自行做好转义。
提示:从 Yii 2.0.12 起(见 Sort.php 源码注释),
asc/desc还可以直接写成排序表达式字符串,例如针对 PostgreSQL 的'asc' => '[[last_name]] ASC NULLS FIRST',从而支持NULLS FIRST/LAST等数据库特性。
将排序信息接入数据查询
声明好属性后,需要把当前请求的排序信息应用到数据查询上。官方推荐的做法是读取 orders 属性并传给查询的 orderBy():
$articles = Article::find()
->where(['status' => 1])
->orderBy($sort->orders)
->all();
重要提示(Info):可以放心地把
Sort::$orders的值直接喂给数据库查询来构建ORDER BY子句,但不要使用attributeOrders——因为部分属性可能是复合属性(如name对应first_name、last_name两列),数据库查询无法识别这种复合逻辑属性名。
这一设计在源码中得到印证:getOrders() 遍历 getAttributeOrders() 的结果,针对每个属性从 attributes 定义中取出对应方向的列映射(asc 或 desc),再逐列展开为 列名 => 方向 的最终数组;若定义值是标量表达式字符串则原样追加到结果中(Sort::getOrders())。
生成排序链接与排序 URL
Sort 提供了两个用于生成前端交互元素的方法:
link($attribute, $options = []):生成一个排序超链接,用户点击后即请求按指定属性排序。createUrl($attribute, $absolute = false):生成一个可排序的 URL;当第二个参数为true时生成绝对 URL。
官方示例:
// 指定生成 URL 时使用的路由
// 如果不指定,将使用当前请求的路由
$sort->route = 'article/index';
// 分别显示按 name 和 age 排序的链接
echo $sort->link('name') . ' | ' . $sort->link('age');
// 输出形如:/index.php?r=article/index&sort=age
echo $sort->createUrl('age');
结合源码可以更深入地理解这两个方法的行为(Sort::link()、Sort::createUrl()、Sort::createSortParam()):
link()会先通过getAttributeOrder()判断当前是否已按该属性排序:若已排序,会在生成的<a>标签上附加 CSS 类asc或desc(用于高亮当前排序状态);同时还会为链接附加data-sort属性,其值为排序参数(如data-sort="age")。标签文本的取值优先级为:$options['label']>attributes中定义的label>modelClass模型属性标签 >Inflector::camel2words()生成。createUrl()会保留当前请求的其他查询参数(params),仅替换sort参数,并将params[0]设置为路由($sort->route或当前路由),最终通过urlManager(默认为应用组件urlManager)生成 URL。createSortParam()实现"点击切换方向"的交互逻辑:若当前已按该属性升序排序,则生成降序参数;若当前已是降序,则生成空参数(取消排序);若尚未排序,则使用default方向(默认升序)。
单元测试 tests/framework/data/SortTest.php 中的 testCreateSortParam 与 testCreateUrl 精确验证了这些行为,例如:当前 sort=age 时 createSortParam('age') 返回 -age;当前 sort=-age 时返回空字符串;testCreateUrl 验证生成 URL 为 /index.php?r=site%2Findex&sort=-age%2C-name。
排序参数的解析规则与查询参数定制
Sort 通过检查查询参数 sort(默认名称)来确定用户请求按哪些属性排序。参数格式为:
- 属性名本身(如
age)表示按该属性升序; - 以
-前缀的属性名(如-age)表示按该属性降序; - 多个属性用逗号分隔(如
age,-name)表示多属性排序,这需要开启enableMultiSort。
源码中 getAttributeOrders() 会通过 parseSortParam() 按 separator(默认为 ,)拆分参数值,识别 - 前缀并映射为 SORT_DESC,且只接受已在 attributes 中声明的属性(Sort::getAttributeOrders())。从源码可以推断,非标量参数值会被安全地忽略,避免注入风险。
常用的可配置属性包括:
| 属性 | 默认值 | 作用 |
|---|---|---|
sortParam |
'sort' |
查询参数名,可改为其他名称以避免冲突 |
defaultOrder |
null |
查询参数缺失时使用的默认排序,格式为 ['属性名' => SORT_ASC/SORT_DESC] |
enableMultiSort |
false |
是否允许多属性同时排序;为 false 时每次只按一个属性排序(解析到第一个有效属性即返回) |
separator |
',' |
多属性排序参数的分隔字符 |
route |
null |
生成 URL 使用的路由,null 表示使用当前路由 |
params |
null |
获取/生成排序参数所用的请求参数,null 时使用 $_GET |
urlManager |
null |
生成 URL 所用的 URL 管理器,null 时使用 urlManager 应用组件 |
sortFlags |
SORT_REGULAR |
2.0.33 起,传递给 ArrayHelper::multisort() 的排序标志 |
modelClass |
null |
2.0.49 起,link() 获取属性标签所用的 Model 类 |
例如,指定默认排序并更换参数名:
$sort = new Sort([
'attributes' => ['created_at', 'title'],
'defaultOrder' => ['created_at' => SORT_DESC],
'sortParam' => 'order',
]);
testGetAttributeOrders(tests/framework/data/SortTest.php)验证了:开启 enableMultiSort 时 sort=age,-name 得到 ['age' => SORT_ASC, 'name' => SORT_DESC];关闭多排序后仅保留第一个属性 age。
与数据提供器(Data Provider)的集成
在实际项目中,排序几乎总是与分页、数据展示组件配合使用,因此 Yii 2 提供了开箱即用的数据提供器集成方案。在配置 ActiveDataProvider、SqlDataProvider 或 ArrayDataProvider 时,直接通过 sort 配置项传入 Sort 的配置数组即可(详见 output-data-providers.md):
$dataProvider = new ActiveDataProvider([
'query' => Article::find()->where(['status' => 1]),
'sort' => [
'attributes' => ['age', 'name'],
'defaultOrder' => ['age' => SORT_DESC],
],
]);
此时排序的接入是全自动的:从 ActiveDataProvider::prepareModels() 可以看到,数据提供器在准备模型数据时会调用 $sort->getOrders() 并通过 $query->addOrderBy() 追加到查询上。
数据提供器还会主动补全排序信息(ActiveDataProvider::setSort()):若 sort->attributes 为空,会自动把模型类的所有 attributes() 声明为可排序属性;同时把 sort->modelClass 设为查询对应的模型类,使 link() 能够利用模型属性标签。从源码结构可以推断,SqlDataProvider 与 ArrayDataProvider 也遵循相同的 sort 配置约定,分别作用于 SQL 查询结果与大数组。
使用 LinkSorter 组件渲染排序链接
除了手动调用 link(),Yii 2 还提供了 yii\widgets\LinkSorter 小组件,为 Sort 中声明的每个属性批量渲染一个排序链接,并输出为 <ul> 列表。常用配置:
use yii\widgets\LinkSorter;
echo LinkSorter::widget([
'sort' => $sort,
'attributes' => ['name', 'age'], // 不设置则使用 sort->attributes 的全部键
'options' => ['class' => 'sorter'], // 容器 ul 的 HTML 属性
'linkOptions' => ['class' => 'btn'], // 传递给 Sort::link() 的链接 HTML 属性
]);
从 LinkSorter 源码可以看到,渲染逻辑就是遍历属性列表依次调用 $sort->link($name, $this->linkOptions),最后用 Html::ul() 输出(encode => false)。LinkSorter 还经常作为 ListView 布局的一部分(如 'layout' => '{sorter}')与数据提供器配合使用,tests/framework/widgets/LinkSorterTest.php 验证了通过 ActiveDataProvider 配置的排序属性会被渲染为带有 data-sort 属性的排序链接。
完整实战示例:控制器 + 视图
将以上内容整合为一个完整的列表页排序示例:
// ArticleController.php
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' => ['age' => SORT_DESC],
'route' => 'article/index',
]);
$articles = Article::find()
->where(['status' => 1])
->orderBy($sort->orders)
->all();
return $this->render('index', [
'articles' => $articles,
'sort' => $sort,
]);
}
// views/article/index.php
<?= \yii\widgets\LinkSorter::widget(['sort' => $sort]) ?>
<table>
<tr>
<th><?= $sort->link('name') ?></th>
<th><?= $sort->link('age') ?></th>
</tr>
<?php foreach ($articles as $article): ?>
<tr>
<td><?= Html::encode($article->first_name . ' ' . $article->last_name) ?></td>
<td><?= Html::encode($article->age) ?></td>
</tr>
<?php endforeach; ?>
</table>
小结
yii\data\Sort 是 Yii 2 排序能力的核心:通过 attributes 声明排序维度(简单或复合),通过 attributeOrders/orders 两个视角读取当前排序状态,通过 link()/createUrl() 生成用户交互入口,并通过 defaultOrder、sortParam、enableMultiSort 等属性满足多样化的排序需求。实际开发中,配合 ActiveDataProvider 等数据提供器即可零成本获得"排序 + 分页 + 数据展示"的完整闭环。相关英文原版指南位于 docs/guide/output-sorting.md,核心实现与测试可分别参阅 framework/data/Sort.php 与 tests/framework/data/SortTest.php。