分页插件Kaminari
http://www.xingishere.com/blogs/kaminari_gem
Rails 2.x 中最常用的分页插件是 will_paginate ,这个相信大家都耳熟能详
不过到 Rails 3 以后,我发现一个更好选择,那就是 Kaminari
我选择它,主要是看中其直观灵活的界面定制功能,它不像 will_paginate 那样需要配置一大堆参数,而是采用 view 文件来进行配置,非常好用
安装
很简单,在 Gemfile 增加一行即可
gem 'kaminari', '~> 0.13.0'
常用法
ActiveRecord
装了插件以后,你可以在 model 对象上使用 .page() 和 .per() 这两个方法,就像 .where() 一样
- 每页10个,取第2页数据
User.page(2).per(10)
- 配合查询条件语句,取第三页数据,默认每页为25个
User.where(status: 1).includes(:topics).page(3)
- 如果传给 .page() 方法的参数是 nil,则默认为1
User.page(params[:page])
View
在页面上,要显示分页的话,用它提供的 helper 方法即可
<%= paginate @users %>
这样会生成类似 « First ‹ Prev … 2 3 4 5 6 7 8 9 10 … Next › Last » 的 html
参数配置
全局参数配置
执行以下命令,会在 config\initializers 下生成一个配置文件 kaminari_config.rb
rails g kaminari:config
这个配置文件控制着 kaminari 的全局设置,有以下参数可以进行自定义
- default_per_page 缺省情况下的每页个数,默认为25
- page_method_name 分页方法的名称,如果你怕冲突(比如想很蛋疼地同时使用 will_paginate),可以修改它
- param_name 分页参数的参数名,默认为 param
- window / outer_window / left / right 这四个参数都与分页显示有关系,特别是在总页数比较多的时候,该如何显示
Model 配置
如果统一的 per_page 全局设置不能满足你的要求,你希望针对每一种 model 设置不同的 per_page ,那么可以这样
class User < ActiveRecord::Base paginates_per 50 end
这样就省去你在每个 controller 中各自使用 .per() 方法了
I18N 语言
默认情况下, kaminari 生成的分页组件是这个样子
如果你想简单地修改其中的文字的话,可以通过修改相应的 locales 语言文件来实现比如我的配置如下
views:
pagination:
first: 首页
last: 末页
previous: 上一页
next: 下一页
truncate: ...
分页界面定制
修改默认界面
为了自定义分页的显示样式,首先要生成一些模板文件,执行以下命令
rails g kaminari:views default
这样会创建 app/views/kaminari/ 文件夹,里面的文件就是分页显示所需的 view ,你可以修改它们
- _paginator.html.erb 这是总的入口文件,可以通过修改它来调整显示的整体结构
比如我不需要“首页”,”末页“这两个链接,那么我就在这个文件里面将对应的代码删除 - _page.html.erb 对应页码链接
- _first_page.html.erb / _last_page.html.erb 对应“首页”和“末页”的链接
- _prev_page.html.erb / _next_page.html.erb 对应“上一页”和“下一页”的链接
- _gap.html.erb 空隙的显示,默认是中间的省略号(…)
注意文件不要改名,否则入口文件会找不到对应的子文件,不过如果你入口文件中将某个部分的代码删除的话,那么相应的子文件也可以删掉
对数组分页
上面所述的都是对ActiveRecord分页,实际工作中经常出现需求对数组分页,kaminari是实现了这个功能的
Kaminari.paginate_array(a, total_count: 100).page(params[:page]).per(10)
其中total_count是数据总数
theme 功能
以上的方法可以用于修改默认的分页界面,不过如果系统比较复杂,在不同的地方需要显示不同的分页界面该怎么办?强大的 kaminari 还提供了 theme 的功能,而且实现很简单,你只需要在 app/views/kaminari/ 下再新建子文件夹即可
例如我在 app/views/kaminari 下新建了一个叫做 tiny 的子文件夹,并将外面的文件都拷贝进去然后在 view 中这样写即可
<%= paginate @blogs, theme: tiny %>
这时候 kaminari 就会根据 tiny 子文件夹下的 view 来渲染分页界面了
资源
这是 Klog 项目中所自定义的两个分页界面,分别用于前台和后台,供参考