Class yii\data\Sort

继承yii\data\Sort » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/data/Sort.php

Sort 表示与排序有关的信息.

当需要根据一个或多个属性对数据进行排序时, 我们可以使用 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',
            ],
        ],
    ]);

    $models = Article::find()
        ->where(['status' => 1])
        ->orderBy($sort->orders)
        ->all();

    return $this->render('index', [
         'models' => $models,
         'sort' => $sort,
    ]);
}

View:

// 显示导致排序动作的链接
echo $sort->link('name') . ' | ' . $sort->link('age');

foreach ($models as $model) {
    // display $model here
}

在上面, 我们声明了两个支持排序的 属性: nameage.

我们将排序信息传递给 Article 查询, 以便按 Sort 对象指定的顺序对查询结果进行排序.

在该视图中, 我们显示了两个超链接, 这些超链接可以跳转到带有按响应属性排序的数据的页面.

有关 Sort 的更多详细信息和使用信息, 请参阅 权威指南 - 显示数据 - 排序(Sorting).

公共属性

隐藏继承的属性

属性类型描述定义在
$attributeOrders array 按属性名称索引的排序方向. 排序方向可以是升序SORT_ASC或降序SORT_DESC. 请注意, 该属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getAttributeOrders()setAttributeOrders(). yii\data\Sort
$attributes array 允许排序的属性列表. yii\data\Sort
$defaultOrder array 当前请求未指定任何排序时应该使用的排序. yii\data\Sort
$enableMultiSort boolean 排序是否可以同时应用于多个属性 默认为false, 这意味着每次只能按一个属性对数据进行排序. yii\data\Sort
$orders array 列(键)及其对应的排序方向(值). 可以将其传递给 yii\db\Query::orderBy() 以构造 DB 查询. 该属性是只读的. yii\data\Sort
$params array 用于获取当前排序方向并创建新的排序 URL 的参数(name => value), . yii\data\Sort
$route string 用于显示排序后的内容的控制器动作的路由. yii\data\Sort
$separator string 用于分隔需要排序的不同属性的字符. yii\data\Sort
$sortFlags integer 允许控制将传递给 ArrayHelper::multisort() 的第四个参数的值. yii\data\Sort
$sortParam string 参数的名称, 指定要在哪个方向上对哪些属性进行排序. yii\data\Sort
$urlManager yii\web\UrlManager 用于创建排序 URL 的 URL 管理器. yii\data\Sort

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的已命名方法. yii\base\BaseObject
__construct() 构造函数. yii\base\BaseObject
__get() 返回对象属性的值. yii\base\BaseObject
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\BaseObject
__set() 设置对象属性的值. yii\base\BaseObject
__unset() 将对象属性设置为null. yii\base\BaseObject
canGetProperty() 返回一个值, 指示属性是否可读. yii\base\BaseObject
canSetProperty() 返回一个值, 指示属性是否可写. yii\base\BaseObject
className() 返回此类的完全限定名称. yii\base\BaseObject
createSortParam() 为指定的属性创建排序变量. yii\data\Sort
createUrl() 创建一个URL, 用于根据指定的属性对数据进行排序. yii\data\Sort
getAttributeOrder() 返回当前请求中指定属性的排序方向. yii\data\Sort
getAttributeOrders() 返回当前请求的排序信息. yii\data\Sort
getOrders() 返回列及其对应的排序方向. yii\data\Sort
hasAttribute() 返回一个值, 该值指示排序定义是否支持按指定属性进行排序. yii\data\Sort
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\BaseObject
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\BaseObject
init() 标准化 $attributes 属性. yii\data\Sort
link() 生成一个超链接, 该超链接链接到排序操作以按指定的属性进行排序. yii\data\Sort
setAttributeOrders() 设置当前的排序信息. yii\data\Sort

受保护的方法

隐藏继承的方法

方法描述定义在
parseSortParam() $sortParam 的值解析为排序属性数组. yii\data\Sort

属性详情

$attributeOrders public 属性

按属性名称索引的排序方向. 排序方向可以是升序SORT_ASC或降序SORT_DESC. 请注意, 该属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getAttributeOrders()setAttributeOrders().

public array $attributeOrders null
$attributes public 属性

允许排序的属性列表. 它的语法可以用下面的例子来描述:

[
    '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',
    ],
]

在上面, 声明了两个属性: agename. age属性是一个简单的属性, 它等效于以下内容:

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

自 2.0.12 起, 特定的排序方向也可以指定为直接排序表达式, 如下所示:

'name' => [
    'asc' => '[[last_name]] ASC NULLS FIRST', // PostgreSQL 的特定功能
    'desc' => '[[last_name]] DESC NULLS LAST',
]

name属性是一个复合属性:

  • name键表示属性名称, 该名称将出现在导致排序操作的 URL 中.
  • ascdesc元素分别指定如何按属性升序和降序对属性进行排序. 它们的值代表实际的列和数据所依据的方向.
  • default元素指定如果属性当前未排序(默认值是升序), 则应按哪个方向排序.
  • label元素指定调用 link() 创建排序链接时应使用的标签. 如果未设置, 则将调用 yii\helpers\Inflector::camel2words() 来获取标签. 请注意, 它不会被 HTML 编码.

Note: 如果已经创建了 Sort 对象, 则只能使用完整格式来配置每个属性. 每个属性必须包含以下元素: ascdesc.

public array $attributes = []
$defaultOrder public 属性

当前请求未指定任何排序时应该使用的排序.

数组键是属性名称, 数组值是相应的排序方向. 例如:

[
    'name' => SORT_ASC,
    'created_at' => SORT_DESC,
]

参见 $attributeOrders.

public array $defaultOrder null
$enableMultiSort public 属性

排序是否可以同时应用于多个属性

默认为false, 这意味着每次只能按一个属性对数据进行排序.

public boolean $enableMultiSort false
$orders public 属性

列(键)及其对应的排序方向(值). 可以将其传递给 yii\db\Query::orderBy() 以构造 DB 查询. 该属性是只读的.

public array $orders null
$params public 属性

用于获取当前排序方向并创建新的排序 URL 的参数(name => value), .

如果未设置, 则使用$_GET.

为了给所有链接添加散列, 请使用array_merge($_GET, ['#' => 'my-hash']).

$sortParam 索引的数组元素被认为是当前的排序方向. 如果该元素不存在, 则将使用 默认排序.

参见:

public array $params null
$route public 属性

用于显示排序后的内容的控制器动作的路由.

如果未设置, 则表示使用当前请求的路由.

public string $route null
$separator public 属性

用于分隔需要排序的不同属性的字符.

public string $separator ','
$sortFlags public 属性 (可用自版本: 2.0.33)

允许控制将传递给 ArrayHelper::multisort() 的第四个参数的值.

public integer $sortFlags SORT_REGULAR
$sortParam public 属性

参数的名称, 指定要在哪个方向上对哪些属性进行排序. 默认为sort.

参见 $params.

public string $sortParam 'sort'
$urlManager public 属性

用于创建排序 URL 的 URL 管理器.

如果未设置, 将使用应用程序urlManager组件.

方法详情

createSortParam() public 方法

为指定的属性创建排序变量.

新创建的排序变量可用于创建一个 URL, 该 URL 将导致按指定的属性进行排序.

public string createSortParam ( $attribute )
$attribute string

属性名称.

return string

排序变量的值.

throws yii\base\InvalidConfigException

如果 $attributes 中未定义指定的属性.

createUrl() public 方法

创建一个URL, 用于根据指定的属性对数据进行排序.

该方法将考虑由 $attributeOrders 给出的当前排序状态. 例如, 如果当前页面已经按指定属性按升序对数据进行排序, 则创建的 URL 将导致页面按照指定的属性的降序对数据进行排序.

参见:

public string createUrl ( $attribute, $absolute false )
$attribute string

属性名称.

$absolute boolean

是否创建一个绝对 URL. 默认为false.

return string

排序的 URL. 如果属性无效, 则为false.

throws yii\base\InvalidConfigException

如果属性是未知的.

getAttributeOrder() public 方法

返回当前请求中指定属性的排序方向.

public integer|null getAttributeOrder ( $attribute )
$attribute string

属性名称.

return integer|null

属性的排序方向. 可以是升序SORT_ASC或降序SORT_DESC. 如果属性无效或不需要排序, 则返回null.

getAttributeOrders() public 方法

返回当前请求的排序信息.

public array getAttributeOrders ( $recalculate false )
$recalculate boolean

是否重新计算排序方向.

return array

按属性名称索引的排序方向. 排序方向可以是升序SORT_ASC或降序SORT_DESC.

getOrders() public 方法

返回列及其对应的排序方向.

public array getOrders ( $recalculate false )
$recalculate boolean

是否重新计算排序方向.

return array

列(键)及其对应的排序方向(值). 可以将其传递给 yii\db\Query::orderBy() 以构造 DB 查询.

hasAttribute() public 方法

返回一个值, 该值指示排序定义是否支持按指定属性进行排序.

public boolean hasAttribute ( $name )
$name string

属性名称.

return boolean

Whether 排序定义是否支持按指定属性进行排序.

init() public 方法

标准化 $attributes 属性.

public void init ( )
link() public 方法

生成一个超链接, 该超链接链接到排序操作以按指定的属性进行排序.

根据排序方向, 生成的超链接的 CSS 类将附加ascdesc.

public string link ( $attribute, $options = [] )
$attribute string

数据排序所依据的属性名称.

$options array

超链接标记的其它 HTML 属性. 有一个特殊的属性label, 它将被用作超链接的标签. 如果未设置, 将使用 $attributes 中定义的标签. 如果未定义标签, 则将调用 yii\helpers\Inflector::camel2words() 来获取标签.

Note: 它不会被 HTML 编码.

return string

生成的超链接.

throws yii\base\InvalidConfigException

如果属性是未知的.

parseSortParam() protected 方法 (可用自版本: 2.0.12)

$sortParam 的值解析为排序属性数组.

格式必须是仅用于升序的属性名称, 或者是带有-前缀的降序的属性名称.

例如, 下面的返回值将按category进行升序排序, 并按created_at进行降序排序:

[
    'category',
    '-created_at'
]

参见:

protected array parseSortParam ( $param )
$param string

$sortParam 的值.

return array

有效的排序属性.

setAttributeOrders() public 方法 (可用自版本: 2.0.10)

设置当前的排序信息.

public void setAttributeOrders ( $attributeOrders, $validate true )
$attributeOrders array|null

按属性名称索引的排序方向. 排序方向可以是升序SORT_ASC或降序SORT_DESC.

$validate boolean

是否针对 $attributes$enableMultiSort 验证给定的属性排序. 如果启用验证, 则将删除不正确的条目.