本文详解如何在 magento 2 自定义模块页面（如客户报价列表页）中正确集成原生分页器，涵盖 collection 分页配置、block 中 _preparelayout() 的关键改造、pager 实例化与模板调用，附可直接复用的代码示例及常见避坑提示。
本文详解如何在 magento 2 自定义模块页面（如客户报价列表页）中正确集成原生分页器，涵盖 collection 分页配置、block 中 _preparelayout() 的关键改造、pager 实例化与模板调用，附可直接复用的代码示例及常见避坑提示。
在 Magento 2 中为自定义页面（例如客户专属的报价单列表页）添加分页功能，不能仅依赖前端 HTML 或简单循环渲染——必须结合框架的 Collection 分页机制与 Magento\Theme\Block\Html\Pager 组件协同工作。核心在于：分页逻辑由 Collection 承载，UI 渲染由 Pager Block 控制，二者需在 Block 层完成绑定与初始化。
以下是一个经过生产环境验证的完整实现方案，适用于基于 EAV 或 Flat 表的自定义 Collection（如 Quote 模型集合）：
✅ 正确实现步骤
1. 在 Block 类中重写 getSavedQuotes() 方法（含分页参数解析）
该方法负责构建并配置分页后的 Collection，需主动读取 URL 参数 p（当前页码）和 limit（每页条数），并调用 setPageSize() 和 setCurPage()：
public function getSavedQuotes()
{
$page = (int) $this->getRequest()->getParam('p', 1);
$pageSize = (int) $this->getRequest()->getParam('limit', 10);
$collection = $this->_quoteMainFactory->create()->getCollection()
->addFieldToFilter('is_deleted', 0)
->addFieldToFilter('status', 1)
->addFieldToFilter('customer_id', $this->customerSession->getCustomer()->getId());
$collection->setPageSize($pageSize);
$collection->setCurPage($page);
return $collection;
}⚠️ 注意：务必使用 (int) 强制类型转换，防止恶意参数注入；setCurPage() 必须在 setPageSize() 之后调用，否则分页计算将失效。
2. 在 _prepareLayout() 中创建并挂载 Pager Block
这是最关键的一步——必须在布局准备阶段手动实例化 Pager，并将其设为子 Block，同时显式调用 $collection->load() 触发分页查询：
protected function _prepareLayout()
{
parent::_prepareLayout();
$this->pageConfig->getTitle()->set(__('My Quotes'));
$quotesCollection = $this->getSavedQuotes();
if ($quotesCollection && $quotesCollection->getSize()) {
$pager = $this->getLayout()->createBlock(\Magento\Theme\Block\Html\Pager::class)
->setAvailableLimit([10 => 10, 20 => 20, 30 => 30])
->setShowPerPage(true) // 设为 true 才显示“每页显示”下拉框
->setCollection($quotesCollection);
$this->setChild('pager', $pager);
$quotesCollection->load(); // ? 必须调用！否则 Pager 无法获取总记录数
}
return $this;
}? 提示：setShowPerPage(true) 启用每页数量切换；若设为 false，则仅显示页码导航。setAvailableLimit() 定义用户可选的 pageSize 值。
3. 在 Block 中暴露 getPagerHtml() 方法供模板调用
public function getPagerHtml()
{
return $this->getChildHtml('pager');
}4. 在对应 .phtml 模板中渲染分页器
在你的报价列表模板（如 quote/list.phtml）底部添加：
<?php echo $block->getPagerHtml(); ?>
此时，URL 将自动支持如下分页参数：
- ?p=2 → 第 2 页
- ?limit=20&p=1 → 每页 20 条，第 1 页
系统会自动生成带样式的页码导航、跳转控件及总数统计。
? 常见错误排查
- ❌ 忘记调用 $collection->load() → Pager 显示 “0 items”，无分页控件；
- ❌ setCurPage() 在 setPageSize() 前调用 → 分页错乱，数据重复或缺失；
- ❌ Collection 未设置 addFieldToFilter() 等条件就传入 Pager → 分页作用于全表，性能崩溃；
- ❌ 模板中未调用 getPagerHtml() 或拼写错误 → 分页器完全不显示；
- ❌ 使用了 addAttributeToFilter()（EAV 专用）但模型非 EAV → 报错，应统一用 addFieldToFilter()。
✅ 最佳实践建议
- 对高频访问的分页页码，可在 Collection 上启用缓存（$collection->setIsLoaded(false)->load() 配合 Cache Tag）；
- 如需自定义 Pager 样式，可继承 \Magento\Theme\Block\Html\Pager 并重写 getPagerHtml()；
- 建议在 getSavedQuotes() 中加入 ->setOrder('created_at', 'DESC') 确保排序一致性。
通过以上四步，即可在任意 Magento 2 自定义页面中稳定、高效地集成原生分页功能，无需第三方扩展，完全兼容官方升级路径。
