Yii 2 数据排序完全指南:掌握 yii\data\Sort 从属性声明到排序链接的完整实现

原创2026-09-22 20:38:091,887 阅读
文章标签:后端Web框架

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。

登录后查看全文
yii2