Yii框架内置了完善的分页组件，能够便捷地实现数据列表的分页功能，无需开发者手动处理复杂的分页逻辑，大幅降低开发成本。
Yii分页组件核心原理
Yii的分页功能主要依赖CPagination类实现，该类会自动计算总数据量、当前页码、每页显示条数等核心参数，同时提供分页链接的生成方法，开发者只需要结合数据查询组件即可完成分页流程。
核心参数说明
| 参数名 | 作用 | 默认值 |
|---|---|---|
| itemCount | 总数据条数 | 0 |
| pageSize | 每页显示的数据条数 | 10 |
| currentPage | 当前页码（从0开始计数） | 0 |
基础分页实现步骤
第一步：控制器中配置分页参数
首先需要在控制器中查询总数据量，初始化分页组件并设置相关参数，之后根据分页参数获取当前页的数据。
<?php
class ArticleController extends CController {
public function actionList() {
// 1. 查询总文章数量
$totalCount = Article::model()->count();
// 2. 初始化分页组件
$pages = new CPagination($totalCount);
// 3. 设置每页显示10条数据
$pages->pageSize = 10;
// 4. 根据分页参数查询当前页数据
$criteria = new CDbCriteria();
$criteria->offset = $pages->offset;
$criteria->limit = $pages->limit;
$articleList = Article::model()->findAll($criteria);
// 5. 渲染视图，传递数据和分页对象
$this->render('list', array(
'articleList' => $articleList,
'pages' => $pages
));
}
}
?>
第二步：视图中渲染分页链接
在视图文件中，使用CLinkPager组件渲染分页导航栏，该组件会自动根据分页参数生成对应的页码链接。
<?php
// 循环展示当前页的文章数据
foreach ($articleList as $article) {
echo '<div class="article-item">';
echo '<h3>' . CHtml::encode($article->title) . '</h3>';
echo '<p>' . CHtml::encode($article->summary) . '</p>';
echo '</div>';
}
// 渲染分页导航栏
$this->widget('CLinkPager', array(
'pages' => $pages,
// 设置分页样式类
'cssFile' => false,
'htmlOptions' => array('class' => 'pagination')
));
?>
分页功能进阶调整
自定义每页显示数量
如果需要让用户自定义每页显示的数量，可以在请求中传递pageSize参数，在控制器中动态设置分页的pageSize属性。
<?php
// 获取用户传递的每页显示数量，默认10条
$pageSize = Yii::app()->request->getParam('pageSize', 10);
$pages->pageSize = intval($pageSize);
?>
处理分页链接的URL规则
如果需要自定义分页链接的URL格式，可以设置分页组件的route和params属性，适配项目的URL路由规则。
<?php
$pages->route = 'article/list';
// 追加额外的URL参数
$pages->params = array_merge($_GET, array('type' => 'news'));
?>
常见问题说明
- 分页组件的currentPage默认从0开始计数，前端传递页码时如果需要从1开始，需要做对应的转换处理
- 如果数据查询使用了复杂的条件，需要确保总数据量的查询条件和当前页数据的查询条件一致，避免分页数据不准确
- 分页组件的offset和limit属性会自动根据当前页码和每页数量计算，无需手动计算偏移量
通过以上步骤，就可以在Yii框架中完整实现数据列表的分页功能，开发者可以根据项目的实际需求调整分页的参数和样式，满足不同的业务场景。
Yii框架分页功能数据列表分页CPagination分页组件修改时间：2026-06-15 15:36:57