ページネーション ¶

単一ページに表示するにはあまりに多くのデータがある場合、一般的な戦略はそれらを複数のページに表示し、各ページにはデータのほんのわずかを表示することです。この戦略はページネーションとして知られています。

Yiiはyii\data\Paginationオブジェクトを使用して、ページネーションスキームに関する情報を表します。特に

• 合計カウントはデータ項目の合計数を指定します。これは通常、単一のページに表示するために必要なデータ項目の数よりもはるかに大きいことに注意してください。
• ページサイズは各ページに含まれるデータ項目の数を指定します。デフォルト値は20です。
• 現在のページは現在のページ番号（ゼロベース）を示します。デフォルト値は0で、最初のページを意味します。

完全に指定されたyii\data\Paginationオブジェクトを使用すると、データを部分的に取得して表示できます。たとえば、データベースからデータを取得している場合は、ページネーションによって提供される対応する値を使用して、DBクエリにOFFSET句とLIMIT句を指定できます。例を以下に示します。

use yii\data\Pagination;

// build a DB query to get all articles with status = 1
$query = Article::find()->where(['status' => 1]);

// get the total number of articles (but do not fetch the article data yet)
$count = $query->count();

// create a pagination object with the total count
$pagination = new Pagination(['totalCount' => $count]);

// limit the query using the pagination and retrieve the articles
$articles = $query->offset($pagination->offset)
    ->limit($pagination->limit)
    ->all();

上記の例では、記事のどのページが返されますか？pageという名前のクエリパラメータが指定されているかどうかによって異なります。デフォルトでは、ページネーションは現在のページにpageパラメータの値を設定しようとします。パラメータが提供されない場合は、デフォルトで0になります。

ページネーションをサポートするUI要素を構築するために、Yiiはyii\widgets\LinkPagerウィジェットを提供します。このウィジェットは、ユーザーがデータのどのページを表示するかを示すページボタンのリストを表示します。ウィジェットはページネーションオブジェクトを取得して、現在のページと表示するページボタンの数を認識します。たとえば、

use yii\widgets\LinkPager;

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

UI要素を手動で構築したい場合は、yii\data\Pagination::createUrl()を使用して、異なるページにつながるURLを作成できます。このメソッドはページパラメータを必要とし、ページパラメータを含む適切にフォーマットされた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
$pagination->route = 'article/index';

// displays: /index.php?r=article%2Findex&page=100
echo $pagination->createUrl(100);

// displays: /index.php?r=article%2Findex&page=101
echo $pagination->createUrl(101);

ヒント: ページネーションオブジェクトを作成する際に、pageParamプロパティを設定することで、pageクエリパラメータの名前をカスタマイズできます。