分页 ¶

当要显示的数据太多以至于无法在一页中显示时，一种常见的策略是将它们分成多页显示，并且每页只显示一小部分数据。这种策略称为分页。

Yii 使用 yii\data\Pagination 对象来表示分页方案的信息。特别是，

• 总数据量 指定了数据的总数量。请注意，这通常远大于在一页中需要显示的数据量。
• 每页数据量 指定每页包含多少数据项。默认值为 20。
• 当前页 给出当前页码（从 0 开始）。默认值为 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。该方法需要一个 page 参数，并将创建一个包含 page 参数的格式正确的 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 查询参数的名称。