排序 ¶

在显示多行数据时，通常需要根据最终用户指定的某些列对数据进行排序。Yii 使用一个 yii\data\Sort 对象来表示有关排序方案的信息。特别是，

• attributes 指定了可以对数据进行排序的属性。属性可以像 模型属性 一样简单。它也可以通过组合多个模型属性或数据库列来组成复合属性。下面将详细介绍。
• attributeOrders 提供了每个属性当前请求的排序方向。
• orders 以底层列的形式提供排序方向。

要使用 yii\data\Sort，首先声明哪些属性可以排序。然后从 attributeOrders 或 orders 中检索当前请求的排序信息，并使用它们来自定义数据查询。例如，

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 和 name。

age 属性是一个简单属性，对应于 Article 活动记录类的 age 属性。它等效于以下声明

'age' => [
    'asc' => ['age' => SORT_ASC],
    'desc' => ['age' => SORT_DESC],
    'default' => SORT_ASC,
    'label' => Inflector::camel2words('age'),
]

name 属性是一个由 Article 的 first_name 和 last_name 定义的复合属性。它使用以下数组结构声明

• asc 和 desc 元素分别指定如何按升序和降序对属性进行排序。它们的值表示应按其排序的数据的实际列和方向。您可以指定一个或多个列来指示简单排序或复合排序。
• default 元素指定在最初请求时应按哪个方向对属性进行排序。它默认为升序，这意味着如果之前没有排序并且您请求按此属性排序，则数据将按此属性升序排序。
• label 元素指定在调用 yii\data\Sort::link() 创建排序链接时应使用哪个标签。如果未设置，则会调用 yii\helpers\Inflector::camel2words() 从属性名称生成标签。请注意，它不会进行 HTML 编码。

信息：您可以将orders 的值直接传递给数据库查询，以构建其 ORDER BY 子句。请勿使用attributeOrders，因为某些属性可能是复合的，数据库查询无法识别。

您可以调用yii\data\Sort::link() 生成一个超链接，最终用户可以点击该链接请求按指定属性对数据进行排序。您也可以调用yii\data\Sort::createUrl() 创建一个可排序的 URL。例如：

// specifies the route that the URL to be created should use
// If you do not specify this, the currently requested route will be used
$sort->route = 'article/index';

// display links leading to sort by name and age, respectively
echo $sort->link('name') . ' | ' . $sort->link('age');

// displays: /index.php?r=article%2Findex&sort=age
echo $sort->createUrl('age');

yii\data\Sort 检查 sort 查询参数以确定哪些属性正在被请求进行排序。当查询参数不存在时，您可以通过yii\data\Sort::$defaultOrder 指定默认排序。您还可以通过配置sortParam 属性来自定义查询参数的名称。