0 追蹤者

類別 yii\data\Pagination

所有類別 | 屬性 | 方法 | 常數
繼承yii\data\Pagination » yii\base\BaseObject
實作yii\base\Configurable, yii\web\Linkable
自版本起可用2.0
原始碼 https://github.com/yiisoft/yii2/blob/master/framework/data/Pagination.php

Pagination 代表與資料項目的分頁相關的資訊。

當資料需要以多頁呈現時，可以使用分頁 (Pagination) 來呈現資訊，例如總項目計數、頁面大小、目前頁面等。這些資訊可以傳遞給頁碼器 (pagers) 以呈現分頁按鈕或連結。

以下範例展示如何建立分頁物件並將其提供給頁碼器。

控制器動作

public function actionIndex()
{
    $query = Article::find()->where(['status' => 1]);
    $countQuery = clone $query;
    $pages = new Pagination(['totalCount' => $countQuery->count()]);
    $models = $query->offset($pages->offset)
        ->limit($pages->limit)
        ->all();

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

視圖

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

// display pagination
echo LinkPager::widget([
    'pagination' => $pages,
]);

關於分頁的更多詳細資訊和使用方法，請參閱關於分頁的指南文章。

公共屬性

隱藏繼承的屬性

屬性 類型 描述 定義於
$defaultPageSize integer 預設的頁面大小。 yii\data\Pagination
$forcePageParam boolean 是否始終在 createUrl() 建立的 URL 中包含頁面參數。 yii\data\Pagination
$limit integer 資料的限制。 yii\data\Pagination
$offset integer 資料的偏移量。 yii\data\Pagination
$page integer 從零開始的目前頁碼。 yii\data\Pagination
$pageCount integer 頁數。 yii\data\Pagination
$pageParam string 儲存目前頁面索引的參數名稱。 yii\data\Pagination
$pageSize integer 每頁的項目數量。 yii\data\Pagination
$pageSizeLimit array|false 頁面大小限制。 yii\data\Pagination
$pageSizeParam string 儲存頁面大小的參數名稱。 yii\data\Pagination
$params array|null 應該用於取得目前頁碼和建立新分頁 URL 的參數 (名稱 => 值)。 yii\data\Pagination
$route string|null 用於顯示分頁內容的控制器動作路由。 yii\data\Pagination
$totalCount integer 項目總數。 yii\data\Pagination
$urlManager yii\web\UrlManager|null 用於建立分頁 URL 的 URL 管理器。 yii\data\Pagination
$validatePage boolean 是否檢查 $page 是否在有效範圍內。 yii\data\Pagination

公共方法

隱藏繼承的方法

方法 描述 定義於
__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
createUrl() 建立適用於具有指定頁碼的分頁的 URL。 yii\data\Pagination
getLimit() yii\data\Pagination
getLinks() 傳回一整組用於導航至第一頁、最後一頁、下一頁和上一頁的連結。 yii\data\Pagination
getOffset() yii\data\Pagination
getPage() 傳回從零開始的目前頁碼。 yii\data\Pagination
getPageCount() yii\data\Pagination
getPageSize() 傳回每頁的項目數量。 yii\data\Pagination
hasMethod() 傳回一個值，指示是否已定義方法。 yii\base\BaseObject
hasProperty() 傳回一個值，指示是否已定義屬性。 yii\base\BaseObject
init() 初始化物件。 yii\base\BaseObject
setPage() 設定目前頁碼。 yii\data\Pagination
setPageSize() yii\data\Pagination

保護方法

隱藏繼承的方法

方法 描述 定義於
getQueryParam() 傳回指定查詢參數的值。 yii\data\Pagination

常數

隱藏繼承的常數

常數 值 描述 定義於

屬性詳細資訊

隱藏繼承的屬性

$defaultPageSize 公共屬性

預設的頁面大小。當無法透過 $params 中的 $pageSizeParam 判斷頁面大小時，將傳回此屬性。

public integer $defaultPageSize = 20
$forcePageParam 公共屬性

是否始終在 createUrl() 建立的 URL 中包含頁面參數。如果為 false 且 $page 為 0，則頁面參數將不會放入 URL 中。

public boolean $forcePageParam = true
$limit 公共屬性

資料的限制。這可用於設定 SQL 陳述式的 LIMIT 值，以取得目前頁面的資料。請注意，如果頁面大小是無限的，將傳回值 -1。

public integer $limit = null
$offset 公共屬性

資料的偏移量。這可用於設定 SQL 陳述式的 OFFSET 值，以取得目前頁面的資料。

public integer $offset = null
$page 公共屬性

從零開始的目前頁碼。

public integer $page = null
$pageCount 公共屬性

頁數。

public integer $pageCount = null
$pageParam 公共屬性

儲存目前頁面索引的參數名稱。

另請參閱 $params。

public string $pageParam = 'page'
$pageSize 公共屬性

每頁的項目數量。如果小於 1，則表示頁面大小是無限的，因此單一頁面包含所有項目。

public integer $pageSize = null
$pageSizeLimit 公共屬性

頁面大小限制。第一個陣列元素定義最小頁面大小，第二個陣列元素定義最大頁面大小。如果為 false，則表示 $pageSize 應始終傳回 $defaultPageSize 的值。

public array|false $pageSizeLimit = [
    1,
    50,
]
$pageSizeParam 公共屬性

儲存頁面大小的參數名稱。

另請參閱 $params。

public string $pageSizeParam = 'per-page'
$params 公共屬性

應該用於取得目前頁碼和建立新分頁 URL 的參數 (名稱 => 值)。如果未設定，則將改為使用 $_GET 中的所有參數。

為了將雜湊 (hash) 新增至所有連結，請使用 array_merge($_GET, ['#' => 'my-hash'])。

由 $pageParam 索引的陣列元素被視為目前頁碼 (預設為 0)；而由 $pageSizeParam 索引的元素則被視為頁面大小 (預設為 $defaultPageSize)。

public array|null $params = null
$route 公共屬性

用於顯示分頁內容的控制器動作路由。如果未設定，則表示使用目前請求的路由。

public string|null $route = null
$totalCount 公共屬性

項目總數。

public integer $totalCount = 0
$urlManager 公共屬性

用於建立分頁 URL 的 URL 管理器。如果未設定，將使用 "urlManager" 應用程式元件。

public yii\web\UrlManager|null $urlManager = null
$validatePage 公共屬性

是否檢查 $page 是否在有效範圍內。當此屬性為 true 時，$page 的值將始終介於 0 和 ($pageCount-1) 之間。由於 $pageCount 依賴於 $totalCount 的正確值，而在某些情況下 (例如 MongoDB) 可能無法取得，因此您可能需要將此屬性設定為 false 以停用頁碼驗證。這樣做之後，$page 將傳回由 $params 中的 $pageParam 索引的值。

public boolean $validatePage = true

方法詳細資訊

隱藏繼承的方法

__call() 公共方法

定義於： yii\base\BaseObject::__call()

呼叫非類別方法的具名方法。

請勿直接呼叫此方法，因為它是一個 PHP 魔術方法，當呼叫未知方法時將會隱式呼叫它。

public mixed __call ( $name, $params )
$name string

方法名稱
$params array

方法參數
return mixed

方法傳回值
throws yii\base\UnknownMethodException

當呼叫未知方法時

 

                public function __call($name, $params)
{
    throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}
__construct() 公共方法

定義於： 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();
}
__get() 公共方法

定義於： yii\base\BaseObject::__get()

傳回物件屬性的值。

請勿直接呼叫此方法，因為它是一個 PHP 魔術方法，當執行 $value = $object->property; 時將會隱式呼叫它。

另請參閱 __set()。

public mixed __get ( $name )
$name string

屬性名稱
return mixed

屬性值
throws yii\base\UnknownPropertyException

如果屬性未定義
throws 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);
}
__isset() 公共方法

定義於： yii\base\BaseObject::__isset()

檢查屬性是否已設定，即已定義且非 null。

請勿直接呼叫此方法，因為它是一個 PHP 魔術方法，當執行 isset($object->property) 時將會隱式呼叫它。

請注意，如果屬性未定義，將傳回 false。

另請參閱 https://php.dev.org.tw/manual/en/function.isset.php。

public boolean __isset ( $name )
$name string

屬性名稱或事件名稱
return boolean

具名屬性是否已設定 (非 null)。

 

                public function __isset($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        return $this->$getter() !== null;
    }
    return false;
}
__set() 公共方法

定義於： yii\base\BaseObject::__set()

設定物件屬性的值。

請勿直接呼叫此方法，因為它是一個 PHP 魔術方法，當執行 $object->property = $value; 時將會隱式呼叫它。

另請參閱 __get()。

public void __set ( $name, $value )
$name string

屬性名稱或事件名稱
$value mixed

屬性值
throws yii\base\UnknownPropertyException

如果屬性未定義
throws 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);
    }
}
__unset() 公共方法

定義於： yii\base\BaseObject::__unset()

將物件屬性設定為 null。

請勿直接呼叫此方法，因為它是一個 PHP 魔術方法，當執行 unset($object->property) 時將會隱式呼叫它。

請注意，如果屬性未定義，此方法將不執行任何操作。如果屬性為唯讀，它將擲回例外。

另請參閱 https://php.dev.org.tw/manual/en/function.unset.php。

public void __unset ( $name )
$name string

屬性名稱
throws 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);
    }
}
canGetProperty() 公共方法

定義於： yii\base\BaseObject::canGetProperty()

傳回一個值，指示是否可以讀取屬性。

如果符合以下條件，屬性是可讀取的

  • 類別具有與指定名稱關聯的 getter 方法 (在這種情況下，屬性名稱不區分大小寫)；
  • 類別具有具有指定名稱的成員變數 (當 $checkVars 為 true 時)；

另請參閱 canSetProperty()。

public boolean canGetProperty ( $name, $checkVars = true )
$name string

屬性名稱
$checkVars boolean

是否將成員變數視為屬性
return boolean

屬性是否可讀取

 

                public function canGetProperty($name, $checkVars = true)
{
    return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
}
canSetProperty() public method

定義於： yii\base\BaseObject::canSetProperty()

傳回一個值，指示是否可以設定屬性。

屬性可寫入的條件為

  • 類別具有與指定名稱相關聯的 setter 方法 (在此情況下，屬性名稱不區分大小寫)；
  • 類別具有具有指定名稱的成員變數 (當 $checkVars 為 true 時)；

另請參閱 canGetProperty()。

public boolean canSetProperty ( $name, $checkVars = true )
$name string

屬性名稱
$checkVars boolean

是否將成員變數視為屬性
return boolean

屬性是否可寫入

 

                public function canSetProperty($name, $checkVars = true)
{
    return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
}
className() public static method
自 2.0.14 版本起已過時。在 PHP >=5.5 版本，請改用 ::class。

定義於： yii\base\BaseObject::className()

傳回此類別的完整限定名稱。

public static string className ( )
return string

此類別的完整限定名稱。

 

                public static function className()
{
    return get_called_class();
}
createUrl() public method

建立適用於具有指定頁碼的分頁的 URL。

當分頁器建立用於執行分頁的 URL 時，主要會呼叫此方法。

另請參閱

public string createUrl ( $page, $pageSize = null, $absolute = false )
$page integer

URL 應指向的從零開始的頁碼。
$pageSize integer|null

每頁的項目數。如果未設定，將使用 $pageSize 的值。
$absolute boolean

是否建立絕對 URL。預設為 false。
return string

建立的 URL

 

                public function createUrl($page, $pageSize = null, $absolute = false)
{
    $page = (int) $page;
    $pageSize = (int) $pageSize;
    if (($params = $this->params) === null) {
        $request = Yii::$app->getRequest();
        $params = $request instanceof Request ? $request->getQueryParams() : [];
    }
    if ($page > 0 || $page == 0 && $this->forcePageParam) {
        $params[$this->pageParam] = $page + 1;
    } else {
        unset($params[$this->pageParam]);
    }
    if ($pageSize <= 0) {
        $pageSize = $this->getPageSize();
    }
    if ($pageSize != $this->defaultPageSize) {
        $params[$this->pageSizeParam] = $pageSize;
    } else {
        unset($params[$this->pageSizeParam]);
    }
    $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);
}
getLimit() public method

public integer getLimit ( )
return integer

資料的限制。這可用於設定 SQL 陳述式的 LIMIT 值，以取得目前頁面的資料。請注意，如果頁面大小是無限的，將傳回值 -1。

 

                public function getLimit()
{
    $pageSize = $this->getPageSize();
    return $pageSize < 1 ? -1 : $pageSize;
}
getLinks() public method

傳回一整組用於導航至第一頁、最後一頁、下一頁和上一頁的連結。

public array getLinks ( $absolute = false )
$absolute boolean

產生的 URL 是否應為絕對網址。
return array

用於導航目的的連結。陣列鍵指定連結的目的 (例如 LINK_FIRST)，而陣列值是相應的 URL。

getOffset() public method

public integer getOffset ( )
return integer

資料的偏移量。這可用於設定 SQL 陳述式的 OFFSET 值，以取得目前頁面的資料。

 

                public function getOffset()
{
    $pageSize = $this->getPageSize();
    return $pageSize < 1 ? 0 : $this->getPage() * $pageSize;
}
getPage() public method

傳回從零開始的目前頁碼。

public integer getPage ( $recalculate = false )
$recalculate boolean

是否根據頁面大小和項目計數重新計算當前頁面。
return integer

從零開始的目前頁碼。

 

                public function getPage($recalculate = false)
{
    if ($this->_page === null || $recalculate) {
        $page = (int) $this->getQueryParam($this->pageParam, 1) - 1;
        $this->setPage($page, true);
    }
    return $this->_page;
}
getPageCount() public method

public integer getPageCount ( )
return integer

頁數

 

                public function getPageCount()
{
    $pageSize = $this->getPageSize();
    if ($pageSize < 1) {
        return $this->totalCount > 0 ? 1 : 0;
    }
    $totalCount = $this->totalCount < 0 ? 0 : (int) $this->totalCount;
    return (int) (($totalCount + $pageSize - 1) / $pageSize);
}
getPageSize() public method

傳回每頁的項目數量。

預設情況下，此方法會嘗試透過 $params 中的 $pageSizeParam 來判斷頁面大小。如果無法透過此方式判斷頁面大小，則會傳回 $defaultPageSize。

另請參閱 $pageSizeLimit。

public integer getPageSize ( )
return integer

每頁的項目數量。如果小於 1，則表示頁面大小是無限的，因此單一頁面包含所有項目。

 

                public function getPageSize()
{
    if ($this->_pageSize === null) {
        if (empty($this->pageSizeLimit) || !isset($this->pageSizeLimit[0], $this->pageSizeLimit[1])) {
            $pageSize = $this->defaultPageSize;
            $this->setPageSize($pageSize);
        } else {
            $pageSize = (int) $this->getQueryParam($this->pageSizeParam, $this->defaultPageSize);
            $this->setPageSize($pageSize, true);
        }
    }
    return $this->_pageSize;
}
getQueryParam() protected method

傳回指定查詢參數的值。

此方法從 $params 傳回具名參數值。如果該值不存在，則傳回 Null。

protected string|null getQueryParam ( $name, $defaultValue = null )
$name string

參數名稱
$defaultValue string|null

當指定的參數在 $params 中不存在時，要傳回的值。
return string|null

參數值

 

                protected function getQueryParam($name, $defaultValue = null)
{
    if (($params = $this->params) === null) {
        $request = Yii::$app->getRequest();
        $params = $request instanceof Request ? $request->getQueryParams() : [];
    }
    return isset($params[$name]) && is_scalar($params[$name]) ? $params[$name] : $defaultValue;
}
hasMethod() public method

定義於： yii\base\BaseObject::hasMethod()

傳回一個值，指示是否已定義方法。

預設實作是對 php 函數 method_exists() 的呼叫。當您實作 php 魔術方法 __call() 時，可以覆寫此方法。

public boolean hasMethod ( $name )
$name string

方法名稱
return boolean

方法是否已定義

 

                public function hasMethod($name)
{
    return method_exists($this, $name);
}
hasProperty() public method

定義於： yii\base\BaseObject::hasProperty()

傳回一個值，指示是否已定義屬性。

屬性被定義的條件為

  • 類別具有與指定名稱相關聯的 getter 或 setter 方法 (在此情況下，屬性名稱不區分大小寫)；
  • 類別具有具有指定名稱的成員變數 (當 $checkVars 為 true 時)；

另請參閱

public boolean hasProperty ( $name, $checkVars = true )
$name string

屬性名稱
$checkVars boolean

是否將成員變數視為屬性
return boolean

屬性是否已定義

 

                public function hasProperty($name, $checkVars = true)
{
    return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
}
init() public method

定義於： yii\base\BaseObject::init()

初始化物件。

在物件以給定組態初始化之後，會在建構函式的結尾調用此方法。

public void init ( )

                public function init()
{
}
setPage() public method

設定目前頁碼。

public void setPage ( $value, $validatePage = false )
$value integer

目前頁面的從零開始的索引。
$validatePage boolean

是否驗證頁碼。請注意，為了驗證頁碼，$validatePage 和此參數都必須為 true。

 

                public function setPage($value, $validatePage = false)
{
    if ($value === null) {
        $this->_page = null;
    } else {
        $value = (int) $value;
        if ($validatePage && $this->validatePage) {
            $pageCount = $this->getPageCount();
            if ($value >= $pageCount) {
                $value = $pageCount - 1;
            }
        }
        if ($value < 0) {
            $value = 0;
        }
        $this->_page = $value;
    }
}
setPageSize() public method

public void setPageSize ( $value, $validatePageSize = false )
$value integer

每頁的項目數量。
$validatePageSize boolean

是否驗證頁面大小。

 

                public function setPageSize($value, $validatePageSize = false)
{
    if ($value === null) {
        $this->_pageSize = null;
    } else {
        $value = (int) $value;
        if ($validatePageSize && isset($this->pageSizeLimit[0], $this->pageSizeLimit[1])) {
            if ($value < $this->pageSizeLimit[0]) {
                $value = $this->pageSizeLimit[0];
            } elseif ($value > $this->pageSizeLimit[1]) {
                $value = $this->pageSizeLimit[1];
            }
        }
        $this->_pageSize = $value;
    }
}