Magento 2 自定义页面添加分页功能的完整实现教程

本文详解如何在 magento 2 自定义模块页面（如客户报价列表页）中正确集成原生分页器，涵盖 Collection 分页配置、block 中 _preparelayout() 的关键改造、pager 实例化与模板调用，附可直接复用的代码示例及常见避坑提示。

本文详解如何在 magento 2 自定义模块页面（如客户报价列表页）中正确集成原生分页器，涵盖 collection 分页配置、block 中 _preparelayout() 的关键改造、pager 实例化与模板调用，附可直接复用的代码示例及常见避坑提示。

在 Magento 2 中为自定义页面（例如客户专属的报价单列表页）添加分页功能，不能仅依赖前端 HTML 或简单循环渲染——必须结合框架的 Collection 分页机制与 MagentoThemeBlockHtmlPager 组件协同工作。核心在于：分页逻辑由 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(MagentoThemeBlockHtmlPager::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 样式，可继承 MagentoThemeBlockHtmlPager 并重写 getPagerHtml()；
• 建议在 getSavedQuotes() 中加入 ->setOrder(‘created_at’, ‘DESC’) 确保排序一致性。

通过以上四步，即可在任意 Magento 2 自定义页面中稳定、高效地集成原生分页功能，无需第三方扩展，完全兼容官方升级路径。