Pagy分页库快速入门指南-优快云博客

Pagy分页库快速入门指南

为什么选择Pagy？性能革命就在这里！

还在为Rails应用的分页性能问题头疼吗？传统的分页库如Kaminari和WillPaginate在处理大数据集时往往表现不佳，内存占用高，响应速度慢。Pagy（Pagination Gem for Ruby）以其卓越的性能和简洁的设计，正在成为Ruby社区的分页新标准。

读完本文，你将掌握：

Pagy的核心优势与性能对比
快速安装和基础配置方法
多种分页场景的实际应用
高级功能和自定义技巧
最佳实践和性能优化建议

🚀 Pagy性能优势一览

让我们先通过数据了解Pagy的惊人表现：

指标	Pagy	Kaminari	WillPaginate	优势倍数
执行速度(IPS)	6,500	160	150	~40x
内存占用(KB)	30	1,100	1,080	~36x
对象数量	450	16,000	15,800	~35x
效率比率	217	0.15	0.14	~1,410x

mermaid

快速开始：4步安装配置

步骤1：安装Pagy

# Gemfile中添加
gem 'pagy', '~> 9.4'

# 或者直接安装
gem install pagy

步骤2：基础配置

创建配置文件 config/initializers/pagy.rb：

# 冻结字符串字面量
# frozen_string_literal: true

# 设置分页默认值
Pagy::DEFAULT[:limit] = 20    # 每页显示20条记录
Pagy::DEFAULT[:size]  = 7     # 导航栏显示7个页码链接
Pagy::DEFAULT[:page_param] = :page  # 页码参数名

# 启用溢出处理（用户体验优化）
require 'pagy/extras/overflow'
Pagy::DEFAULT[:overflow] = :last_page

# 冻结配置防止意外修改
Pagy::DEFAULT.freeze

步骤3：后端集成

在控制器中引入后端模块：

# application_controller.rb
class ApplicationController < ActionController::Base
  include Pagy::Backend
  
  # 可选：全局异常处理
  rescue_from Pagy::OverflowError, with: :redirect_to_last_page
  
  private
  
  def redirect_to_last_page(exception)
    redirect_to url_for(page: exception.pagy.last), alert: "页码超出范围，已跳转到最后一页"
  end
end

步骤4：前端集成

在视图助手中引入前端模块：

# application_helper.rb
module ApplicationHelper
  include Pagy::Frontend
end

基础使用示例

基本分页场景

# 控制器中使用
class ProductsController < ApplicationController
  def index
    # 基本分页
    @pagy, @products = pagy(Product.all, items: 12)
    
    # 带条件查询的分页
    @pagy, @filtered_products = pagy(
      Product.where(category: params[:category]),
      items: params[:per_page] || 15
    )
  end
end

<!-- 视图中渲染分页导航 -->
<div class="products-container">
  <% @products.each do |product| %>
    <%= render product %>
  <% end %>
</div>

<!-- 分页导航 -->
<div class="pagination-container">
  <%== pagy_nav(@pagy) if @pagy.pages > 1 %>
  
  <!-- 分页信息显示 -->
  <div class="pagination-info">
    <%== pagy_info(@pagy) %>
  </div>
</div>

高级功能实战

1. 无限滚动（Infinite Scroll）

# 控制器
def index
  @pagy, @products = pagy(Product.all, items: 12)
  
  respond_to do |format|
    format.html
    format.turbo_stream if turbo_frame_request?
  end
end

<!-- 无限滚动容器 -->
<%= turbo_frame_tag "products", data: { 
  controller: "infinite-scroll",
  infinite_scroll_next_page_value: @pagy.next,
  infinite_scroll_url_value: products_path(page: @pagy.next)
} do %>
  <% @products.each do |product| %>
    <%= render product %>
  <% end %>
  
  <!-- 加载更多按钮 -->
  <% if @pagy.next %>
    <div data-infinite-scroll-target="loader">
      <button data-action="click->infinite-scroll#loadMore">
        加载更多
      </button>
    </div>
  <% end %>
<% end %>

2. 搜索分页集成

# 使用Ransack进行搜索分页
def search
  @q = Product.ransack(params[:q])
  @pagy, @products = pagy(@q.result(distinct: true), items: 16)
end

3. API分页（JSON响应）

# 启用元数据extra
require 'pagy/extras/metadata'

def api_index
  @pagy, @products = pagy(Product.all, items: params[:per_page] || 20)
  
  render json: {
    data: @products,
    meta: {
      pagination: pagy_metadata(@pagy)
    }
  }
end

自定义样式与主题

Bootstrap集成

# 配置文件中启用Bootstrap
require 'pagy/extras/bootstrap'

<!-- 使用Bootstrap样式的分页 -->
<%== pagy_bootstrap_nav(@pagy) %>

Tailwind CSS自定义

/* 自定义Tailwind分页样式 */
.pagy-nav {
  @apply flex justify-center space-x-2 mt-8;
}

.pagy-nav .page {
  @apply px-3 py-2 border border-gray-300 rounded-md text-sm font-medium;
}

.pagy-nav .page.active {
  @apply bg-blue-600 text-white border-blue-600;
}

.pagy-nav .page:hover:not(.active) {
  @apply bg-gray-50;
}

.pagy-nav .gap {
  @apply px-3 py-2 text-gray-500;
}

性能优化技巧

1. 使用Countless避免COUNT查询

# 对于大数据集，避免昂贵的COUNT查询
require 'pagy/extras/countless'

@pagy, @products = pagy_countless(Product.all, items: 20)

2. 键集分页（Keyset Pagination）

# 对于超大数据集的性能优化
require 'pagy/extras/keyset'

@pagy, @products = pagy(Product.order(created_at: :desc, id: :desc), 
                       items: 50, 
                       keyset: true)

3. 适当的分页策略

mermaid

常见问题解决方案

问题1：页码溢出处理

# 自动重定向到最后一页
Pagy::DEFAULT[:overflow] = :last_page

# 或者返回空页面
Pagy::DEFAULT[:overflow] = :empty_page

问题2：自定义每页显示数量

# 允许用户选择每页数量
def index
  per_page = [params[:per_page].to_i, 100].min.positive? ? params[:per_page].to_i : 20
  @pagy, @products = pagy(Product.all, items: per_page)
end

问题3：多语言支持

# 配置多语言
Pagy::I18n.load({ locale: 'zh-CN' }, { locale: 'en' })

# 或者在视图中动态设置
<%== pagy_info(@pagy, item_name: '产品'.pluralize(@pagy.count)) %>

最佳实践总结

性能优先：大数据集使用Countless或Keyset分页
用户体验：合理设置每页显示数量，提供页码跳转
移动端适配：使用响应式分页组件
API设计：提供丰富的元数据信息
错误处理：妥善处理页码溢出等边界情况

mermaid

进阶资源与扩展

Pagy提供了丰富的扩展功能，包括：

日历分页：按时间维度进行分页
弹性搜索集成：与Elasticsearch无缝集成
多种CSS框架支持：Bootstrap、Bulma、Tailwind等
JSON API标准：符合JSON API规范的分页响应

通过本指南，你应该已经掌握了Pagy的核心用法和最佳实践。Pagy以其卓越的性能、简洁的API和丰富的功能，无疑是Ruby分页领域的最佳选择。开始使用Pagy，让你的应用分页体验提升到一个新的水平！

记住：好的分页不仅仅是技术实现，更是用户体验的重要组成部分。选择合适的策略，让你的用户享受流畅的浏览体验。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考