類別 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,
]);
}
檢視
// display links leading to sort actions
echo $sort->link('name') . ' | ' . $sort->link('age');
foreach ($models as $model) {
// display $model here
}
在上方,我們宣告了兩個支援排序的 $attributes 屬性:name
和 age
。我們將排序資訊傳遞給 Article 查詢,以便查詢結果依照 Sort 物件指定的順序排序。在視圖中,我們顯示了兩個超連結,它們可以連結到依據對應屬性排序的頁面。
關於 Sort 的更多詳細資訊和使用方法,請參閱關於排序的指南文章。
公開屬性
屬性 | 類型 | 描述 | 定義於 |
---|---|---|---|
$attributeOrders | array (陣列) | 依屬性名稱索引的排序方向。 | yii\data\Sort |
$attributes | array (陣列) | 允許排序的屬性列表。 | yii\data\Sort |
$defaultOrder | array (陣列)|null | 當目前請求未指定任何排序時應使用的順序。 | yii\data\Sort |
$enableMultiSort | boolean (布林值) | 是否可以同時對多個屬性應用排序。 | yii\data\Sort |
$modelClass | string (字串)|null | 由 link() 方法使用的基於 yii\base\Model 的類別名稱,用於檢索屬性的標籤。 | yii\data\Sort |
$orders | array (陣列) | 欄位(鍵)及其對應的排序方向(值)。 | yii\data\Sort |
$params | array (陣列)|null | 應用於獲取當前排序方向和建立新的排序 URL 的參數(名稱 => 值)。 | yii\data\Sort |
$route | string (字串)|null | 用於顯示排序內容的控制器動作路由。 | yii\data\Sort |
$separator | string (字串) | 用於分隔需要排序的不同屬性的字元。 | yii\data\Sort |
$sortFlags | integer (整數) | 允許控制將傳遞給 ArrayHelper::multisort() 的第四個參數的值 | yii\data\Sort |
$sortParam | string (字串) | 指定要排序哪些屬性以及排序方向的參數名稱。 | yii\data\Sort |
$urlManager | yii\web\UrlManager|null | 用於建立排序 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 |
屬性詳細資訊
依屬性名稱索引的排序方向。排序方向可以是 SORT_ASC
代表升序,或 SORT_DESC
代表降序。請注意,此屬性的類型在 getter 和 setter 中有所不同。請參閱 getAttributeOrders() 和 setAttributeOrders() 以取得詳細資訊。
允許排序的屬性列表。其語法可以使用以下範例描述
[
'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
和 name
。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 specific feature
'desc' => '[[last_name]] DESC NULLS LAST',
]
name
屬性是一個複合屬性
name
鍵代表屬性名稱,它將出現在連結到排序動作的 URL 中。asc
和desc
元素指定如何依屬性以升序和降序排序。它們的值代表實際的欄位和資料應依其排序的方向。default
元素指定如果屬性目前未排序時應依哪個方向排序(預設值為升序)。label
元素指定在呼叫 link() 以建立排序連結時應使用的標籤。如果未設定,將呼叫 yii\helpers\Inflector::camel2words() 來取得標籤。請注意,它不會進行 HTML 編碼。
請注意,如果 Sort 物件已經建立,您只能使用完整格式來設定每個屬性。每個屬性都必須包含這些元素:asc
和 desc
。
當目前請求未指定任何排序時應使用的順序。陣列的鍵是屬性名稱,陣列的值是對應的排序方向。例如:
[
'name' => SORT_ASC,
'created_at' => SORT_DESC,
]
另請參閱 $attributeOrders。
是否可以同時對多個屬性應用排序。預設值為 false
,這表示每次資料只能依一個屬性排序。
由 link() 方法使用的基於 yii\base\Model 的類別名稱,用於檢索屬性的標籤。請參閱 link() 方法以取得詳細資訊。
欄位(鍵)及其對應的排序方向(值)。這可以傳遞給 yii\db\Query::orderBy() 以建構資料庫查詢。
應用於獲取當前排序方向和建立新的排序 URL 的參數(名稱 => 值)。如果未設定,則會改為使用 $_GET
。
為了將雜湊值新增到所有連結,請使用 array_merge($_GET, ['#' => 'my-hash'])
。
由 $sortParam 索引的陣列元素被視為目前的排序方向。如果該元素不存在,將使用預設順序。
另請參閱
允許控制將傳遞給 ArrayHelper::multisort() 的第四個參數的值
指定要排序哪些屬性以及排序方向的參數名稱。預設值為 sort
。
另請參閱 $params。
用於建立排序 URL 的 URL 管理器。如果未設定,將使用 urlManager
應用程式元件。
方法詳細資訊
public mixed __call ( $name, $params ) | ||
$name | string (字串) |
方法名稱 |
$params | array (陣列) |
$params |
傳回 | mixed |
方法傳回值 |
---|---|---|
拋出 | yii\base\UnknownMethodException |
當呼叫未知方法時 |
public function __call($name, $params)
{
throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}
定義於: yii\base\BaseObject::__construct()
建構子。
預設實作會執行兩件事
- 使用給定的組態
$config
初始化物件。 - 呼叫 init()。
如果子類別中覆寫了此方法,建議
- 建構子的最後一個參數是一個組態陣列,就像此處的
$config
一樣。 - 在建構子的結尾呼叫父類別實作。
public void __construct ( $config = [] ) | ||
$config | array (陣列) |
將用於初始化物件屬性的名稱-值對 |
public function __construct($config = [])
{
if (!empty($config)) {
Yii::configure($this, $config);
}
$this->init();
}
定義於: yii\base\BaseObject::__get()
傳回物件屬性的值。
請勿直接呼叫此方法,因為它是一個 PHP 魔術方法,當執行 $value = $object->property;
時,它會被隱式呼叫。
另請參閱 __set()。
public mixed __get ( $name ) | ||
$name | string (字串) |
$name |
傳回 | mixed |
屬性名稱 |
---|---|---|
拋出 | yii\base\UnknownPropertyException |
如果屬性未定義 |
拋出 | yii\base\InvalidCallException |
如果屬性為唯寫 |
public function __get($name)
{
$getter = 'get' . $name;
if (method_exists($this, $getter)) {
return $this->$getter();
} elseif (method_exists($this, 'set' . $name)) {
throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
}
throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
}
定義於: yii\base\BaseObject::__isset()
檢查屬性是否已設定,即已定義且非 null。
請勿直接呼叫此方法,因為它是一個 PHP 魔術方法,當執行 isset($object->property)
時,它會被隱式呼叫。
請注意,如果屬性未定義,將傳回 false。
public boolean (布林值) __isset ( $name ) | ||
$name | string (字串) |
$name |
傳回 | boolean (布林值) |
具名屬性或事件名稱 |
---|
public function __isset($name)
{
$getter = 'get' . $name;
if (method_exists($this, $getter)) {
return $this->$getter() !== null;
}
return false;
}
定義於: yii\base\BaseObject::__set()
設定物件屬性的值。
請勿直接呼叫此方法,因為它是一個 PHP 魔術方法,當執行 $object->property = $value;
時,它會被隱式呼叫。
另請參閱 __get()。
public void __set ( $name, $value ) | ||
$name | string (字串) |
$name |
$value | mixed |
屬性名稱 |
拋出 | yii\base\UnknownPropertyException |
如果屬性未定義 |
---|---|---|
拋出 | yii\base\InvalidCallException |
如果屬性為唯讀 |
public function __set($name, $value)
{
$setter = 'set' . $name;
if (method_exists($this, $setter)) {
$this->$setter($value);
} elseif (method_exists($this, 'get' . $name)) {
throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
} else {
throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
}
}
定義於: yii\base\BaseObject::__unset()
將物件屬性設定為 null。
請勿直接呼叫此方法,因為它是一個 PHP 魔術方法,當執行 unset($object->property)
時,它會被隱式呼叫。
請注意,如果屬性未定義,此方法將不會執行任何操作。如果屬性為唯讀,它將拋出例外。
public void __unset ( $name ) | ||
$name | string (字串) |
$name |
拋出 | yii\base\InvalidCallException |
如果屬性為唯讀。 |
---|
public function __unset($name)
{
$setter = 'set' . $name;
if (method_exists($this, $setter)) {
$this->$setter(null);
} elseif (method_exists($this, 'get' . $name)) {
throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
}
}
定義於: yii\base\BaseObject::canGetProperty()
傳回一個值,指示屬性是否可讀取。
如果屬性可讀取
- 類別具有與指定名稱關聯的 getter 方法(在這種情況下,屬性名稱不區分大小寫);
- 類別具有帶有指定名稱的成員變數(當
$checkVars
為 true 時);
另請參閱 canSetProperty()。
public boolean (布林值) canGetProperty ( $name, $checkVars = true ) | ||
$name | string (字串) |
$name |
$checkVars | boolean (布林值) |
是否將成員變數視為屬性 |
傳回 | boolean (布林值) |
屬性是否可讀取 |
---|
public function canGetProperty($name, $checkVars = true)
{
return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
}
定義於: yii\base\BaseObject::canSetProperty()
傳回一個值,指示屬性是否可設定。
如果屬性可寫入
- 類別具有與指定名稱關聯的 setter 方法(在這種情況下,屬性名稱不區分大小寫);
- 類別具有帶有指定名稱的成員變數(當
$checkVars
為 true 時);
另請參閱 canGetProperty()。
public boolean (布林值) canSetProperty ( $name, $checkVars = true ) | ||
$name | string (字串) |
$name |
$checkVars | boolean (布林值) |
是否將成員變數視為屬性 |
傳回 | boolean (布林值) |
屬性是否可寫入 |
---|
public function canSetProperty($name, $checkVars = true)
{
return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
}
::class
。
定義於: yii\base\BaseObject::className()
傳回此類別的完整命名空間名稱。
public static string (字串) className ( ) | ||
傳回 | string (字串) |
此類別的完整命名空間名稱。 |
---|
public static function className()
{
return get_called_class();
}
為指定的屬性建立排序變數。
新建立的排序變數可用於建立 URL,該 URL 將導向依指定屬性排序。
public string (字串) createSortParam ( $attribute ) | ||
$attribute | string (字串) |
屬性名稱 |
傳回 | string (字串) |
排序變數的值 |
---|---|---|
拋出 | yii\base\InvalidConfigException |
如果指定的屬性未在 $attributes 中定義 |
public function createSortParam($attribute)
{
if (!isset($this->attributes[$attribute])) {
throw new InvalidConfigException("Unknown attribute: $attribute");
}
$definition = $this->attributes[$attribute];
$directions = $this->getAttributeOrders();
if (isset($directions[$attribute])) {
if ($this->enableMultiSort) {
if ($directions[$attribute] === SORT_ASC) {
$direction = SORT_DESC;
} else {
$direction = null;
}
} else {
$direction = $directions[$attribute] === SORT_DESC ? SORT_ASC : SORT_DESC;
}
unset($directions[$attribute]);
} else {
$direction = isset($definition['default']) ? $definition['default'] : SORT_ASC;
}
if ($this->enableMultiSort) {
if ($direction !== null) {
$directions = array_merge([$attribute => $direction], $directions);
}
} else {
$directions = [$attribute => $direction];
}
$sorts = [];
foreach ($directions as $attribute => $direction) {
$sorts[] = $direction === SORT_DESC ? '-' . $attribute : $attribute;
}
return implode($this->separator, $sorts);
}
建立用於依指定屬性排序資料的 URL。
此方法將考慮由 $attributeOrders 給定的目前排序狀態。例如,如果目前頁面已經依指定屬性以升序排序資料,則建立的 URL 將導向依指定屬性以降序排序資料的頁面。
另請參閱
public string (字串) createUrl ( $attribute, $absolute = false ) | ||
$attribute | string (字串) |
屬性名稱 |
$absolute | boolean (布林值) |
是否建立絕對 URL。預設值為 |
傳回 | string (字串) |
用於排序的 URL。如果屬性無效,則為 False。 |
---|---|---|
拋出 | yii\base\InvalidConfigException |
yii\base\InvalidParamException |
public function createUrl($attribute, $absolute = false)
{
if (($params = $this->params) === null) {
$request = Yii::$app->getRequest();
$params = $request instanceof Request ? $request->getQueryParams() : [];
}
$params[$this->sortParam] = $this->createSortParam($attribute);
$params[0] = $this->route === null ? Yii::$app->controller->getRoute() : $this->route;
$urlManager = $this->urlManager === null ? Yii::$app->getUrlManager() : $this->urlManager;
if ($absolute) {
return $urlManager->createAbsoluteUrl($params);
}
return $urlManager->createUrl($params);
}
傳回目前請求中指定屬性的排序方向。
getAttributeOrder() 公開方法 | ||
$attribute | string (字串) |
屬性名稱 |
傳回 | public integer (整數)|null getAttributeOrder ( $attribute ) |
屬性的排序方向。可以是 |
---|
public function getAttributeOrder($attribute)
{
$orders = $this->getAttributeOrders();
return isset($orders[$attribute]) ? $orders[$attribute] : null;
}
傳回目前請求的排序資訊。
public array getAttributeOrders ( $recalculate = false ) | ||
$recalculate | boolean (布林值) |
是否重新計算排序方向 |
傳回 | array (陣列) |
排序方向以屬性名稱索引。排序方向可以是 |
---|
public function getAttributeOrders($recalculate = false)
{
if ($this->_attributeOrders === null || $recalculate) {
$this->_attributeOrders = [];
if (($params = $this->params) === null) {
$request = Yii::$app->getRequest();
$params = $request instanceof Request ? $request->getQueryParams() : [];
}
if (isset($params[$this->sortParam])) {
foreach ($this->parseSortParam($params[$this->sortParam]) as $attribute) {
$descending = false;
if (strncmp($attribute, '-', 1) === 0) {
$descending = true;
$attribute = substr($attribute, 1);
}
if (isset($this->attributes[$attribute])) {
$this->_attributeOrders[$attribute] = $descending ? SORT_DESC : SORT_ASC;
if (!$this->enableMultiSort) {
return $this->_attributeOrders;
}
}
}
return $this->_attributeOrders;
}
if (empty($this->_attributeOrders) && is_array($this->defaultOrder)) {
$this->_attributeOrders = $this->defaultOrder;
}
}
return $this->_attributeOrders;
}
傳回欄位及其對應的排序方向。
public array getOrders ( $recalculate = false ) | ||
$recalculate | boolean (布林值) |
是否重新計算排序方向 |
傳回 | array (陣列) |
欄位(鍵)及其對應的排序方向(值)。這可以傳遞給 yii\db\Query::orderBy() 以建構資料庫查詢。 |
---|
public function getOrders($recalculate = false)
{
$attributeOrders = $this->getAttributeOrders($recalculate);
$orders = [];
foreach ($attributeOrders as $attribute => $direction) {
$definition = $this->attributes[$attribute];
$columns = $definition[$direction === SORT_ASC ? 'asc' : 'desc'];
if (is_array($columns) || $columns instanceof \Traversable) {
foreach ($columns as $name => $dir) {
$orders[$name] = $dir;
}
} else {
$orders[] = $columns;
}
}
return $orders;
}
傳回一個值,指示排序定義是否支援依指定的屬性名稱進行排序。
public boolean hasAttribute ( $name ) | ||
$name | string (字串) |
屬性名稱 |
傳回 | boolean (布林值) |
排序定義是否支援依指定名稱的屬性進行排序。 |
---|
public function hasAttribute($name)
{
return isset($this->attributes[$name]);
}
定義於: yii\base\BaseObject::hasMethod()
傳回一個值,指示是否已定義方法。
預設實作是呼叫 php 函數 method_exists()
。當您實作了 php 魔術方法 __call()
時,您可以覆寫此方法。
public boolean hasMethod ( $name ) | ||
$name | string (字串) |
方法名稱 |
傳回 | boolean (布林值) |
方法是否已定義 |
---|
public function hasMethod($name)
{
return method_exists($this, $name);
}
定義於: yii\base\BaseObject::hasProperty()
傳回一個值,指示是否已定義屬性。
如果符合以下條件,則屬性已定義
- 類別具有與指定名稱相關聯的 getter 或 setter 方法 (在這種情況下,屬性名稱不區分大小寫);
- 類別具有帶有指定名稱的成員變數(當
$checkVars
為 true 時);
另請參閱
public boolean hasProperty ( $name, $checkVars = true ) | ||
$name | string (字串) |
$name |
$checkVars | boolean (布林值) |
是否將成員變數視為屬性 |
傳回 | boolean (布林值) |
屬性是否已定義 |
---|
public function hasProperty($name, $checkVars = true)
{
return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
}
正規化 $attributes 屬性。
public void init ( ) |
public function init()
{
$attributes = [];
foreach ($this->attributes as $name => $attribute) {
if (!is_array($attribute)) {
$attributes[$attribute] = [
'asc' => [$attribute => SORT_ASC],
'desc' => [$attribute => SORT_DESC],
];
} elseif (!isset($attribute['asc'], $attribute['desc'])) {
$attributes[$name] = array_merge([
'asc' => [$name => SORT_ASC],
'desc' => [$name => SORT_DESC],
], $attribute);
} else {
$attributes[$name] = $attribute;
}
}
$this->attributes = $attributes;
}
產生一個超連結,連結到排序動作以依指定的屬性排序。
根據排序方向,產生的超連結的 CSS 類別將附加 "asc" 或 "desc"。
public string link ( $attribute, $options = [] ) | ||
$attribute | string (字串) |
應該依其排序資料的屬性名稱。 |
$options | array (陣列) |
超連結標籤的其他 HTML 屬性。有一個特殊的屬性 |
傳回 | string (字串) |
產生的超連結 |
---|---|---|
拋出 | yii\base\InvalidConfigException |
yii\base\InvalidParamException |
public function link($attribute, $options = [])
{
if (($direction = $this->getAttributeOrder($attribute)) !== null) {
$class = $direction === SORT_DESC ? 'desc' : 'asc';
if (isset($options['class'])) {
$options['class'] .= ' ' . $class;
} else {
$options['class'] = $class;
}
}
$url = $this->createUrl($attribute);
$options['data-sort'] = $this->createSortParam($attribute);
if (isset($options['label'])) {
$label = $options['label'];
unset($options['label']);
} else {
if (isset($this->attributes[$attribute]['label'])) {
$label = $this->attributes[$attribute]['label'];
} elseif ($this->modelClass !== null) {
$modelClass = $this->modelClass;
/** @var \yii\base\Model $model */
$model = $modelClass::instance();
$label = $model->getAttributeLabel($attribute);
} else {
$label = Inflector::camel2words($attribute);
}
}
return Html::a($label, $url, $options);
}
將 $sortParam 的值解析為排序屬性陣列。
格式必須僅為屬性名稱 (用於遞增排序) 或以 -
為前綴的屬性名稱 (用於遞減排序)。
例如,以下傳回值將導致依 category
遞增排序,並依 created_at
遞減排序
[
'category',
'-created_at'
]
另請參閱
- $separator 用於屬性名稱分隔符號。
- $sortParam
protected array parseSortParam ( $param ) | ||
$param | string (字串) |
$sortParam 的值。 |
傳回 | array (陣列) |
有效的排序屬性。 |
---|
protected function parseSortParam($param)
{
return is_scalar($param) ? explode($this->separator, $param) : [];
}
設定目前的排序資訊。
public void setAttributeOrders ( $attributeOrders, $validate = true ) | ||
$attributeOrders | array (陣列)|null |
排序方向以屬性名稱索引。排序方向可以是 |
$validate | boolean (布林值) |
是否根據 $attributes 和 $enableMultiSort 驗證給定的屬性排序。如果啟用驗證,則會移除不正確的條目。 |
public function setAttributeOrders($attributeOrders, $validate = true)
{
if ($attributeOrders === null || !$validate) {
$this->_attributeOrders = $attributeOrders;
} else {
$this->_attributeOrders = [];
foreach ($attributeOrders as $attribute => $order) {
if (isset($this->attributes[$attribute])) {
$this->_attributeOrders[$attribute] = $order;
if (!$this->enableMultiSort) {
break;
}
}
}
}
}
註冊 或 登入 以發表評論。