Yii 2 排序实战:基于 yii\data\Sort 实现用户可控的数据排序

原创2026-09-22 18:33:591,921 阅读
文章标签:后端Web框架

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 是简单属性,直接对应 Article Active 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() 的规范化逻辑同时支持三种写法:

  1. 字符串 'age':自动生成同名列的升/降序定义;
  2. 数组但缺少 asc/desc:自动补齐基于属性名本身的升/降序定义,再与给定配置合并;
  3. 数组且包含 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)的处理流程如下:

  1. 若未显式配置 params,则从当前请求(yii\web\Request::getQueryParams())中读取参数;
  2. 解析 sortParam 指定的参数值,通过 parseSortParam()(默认按 separator 用 explode 拆分)得到属性名列表;
  3. 对每个属性名检查 - 前缀以确定方向,并校验该属性是否在 attributes 中声明过——未声明的属性会被静默忽略,这天然防止了任意列注入排序;
  4. 若参数不存在或解析结果为空,则回退到 defaultOrder(若已配置);
  5. 默认情况下(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),并附加两个实用特性:

  1. 方向 CSS 类:若该属性当前正按升序排序,链接的 class 会追加 asc;按降序排序则追加 desc。前端可据此给表头加箭头指示。
  2. 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&amp;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,都可以复用同一套机制。

相关实现与测试文件索引:

登录后查看全文
yii2