Ernie/Ransack 项目入门：简单模式使用指南

Ernie/Ransack 项目入门：简单模式使用指南

ransack 项目地址: https://gitcode.com/gh_mirrors/ran/ransack

什么是 Ransack 的简单模式

Ransack 是一个功能强大的 Ruby 搜索库，它提供了两种工作模式：简单模式和高级模式。简单模式适用于不需要复杂布尔逻辑的搜索和过滤场景，能够满足大多数基础查询需求。

控制器中的基本配置

在控制器中使用 Ransack 非常简单，只需要几行代码就能实现强大的搜索功能：

def index
  @q = Person.ransack(params[:q])
  @people = @q.result(distinct: true)
end

如果你需要对关联表进行排序并实现分页，可以这样写：

def index
  @q = Person.ransack(params[:q])
  @people = @q.result.includes(:articles).page(params[:page])
end

重要安全提示：默认情况下，Ransack 允许对模型的所有列进行搜索和排序。在生产环境中，你应该通过授权机制来限制可搜索的字段。

搜索参数配置

默认搜索参数键名

Ransack 默认使用 :q 作为搜索参数的键名。你可以通过初始化文件修改这个默认值：

Ransack.configure do |c|
  c.search_key = :query  # 将默认键名改为 :query
end

字符串搜索处理

从 2.4.0 版本开始，Ransack 默认会去除查询字符串两端的空白字符。你可以通过配置关闭这一行为：

Ransack.configure do |c|
  c.strip_whitespace = false  # 禁用自动去除空白字符
end

视图中的搜索表单

Ransack 提供了两个主要的视图辅助方法：search_form_for 和 sort_link。

搜索表单构建

使用 search_form_for 可以轻松创建搜索表单：

<%= search_form_for @q do |f| %>
  <%= f.label :name_cont %>
  <%= f.search_field :name_cont %>
  
  <%= f.label :articles_title_start %>
  <%= f.search_field :articles_title_start %>
  
  <%= f.submit %>
<% end %>

搜索字段的命名规则为：属性名[_or_属性名]..._谓词

其中 cont (包含) 和 start (以...开头) 是 Ransack 提供的众多搜索谓词中的两个。

可排序表头链接

sort_link 辅助方法可以创建可点击排序的表头：

<%= sort_link(@q, :name) %>

你可以自定义链接文本和默认排序方向：

<%= sort_link(@q, :name, '姓氏', default_order: :desc) %>

对于复杂的排序需求，比如基于 SQL 函数结果的排序，你可以在模型中定义相应的作用域：

class Person < ActiveRecord::Base
  scope :sort_by_reverse_name_asc, -> { order("REVERSE(name) ASC") }
  scope :sort_by_reverse_name_desc, -> { order("REVERSE(name) DESC") }
end

然后在视图中使用：

<%= sort_link(@q, :reverse_name) %>

高级配置选项

排序指示箭头定制

你可以全局定制排序链接中的箭头图标：

Ransack.configure do |c|
  c.custom_arrows = {
    up_arrow: '<i class="custom-up-arrow-icon"></i>',
    down_arrow: 'U+02193',
    default_arrow: '<i class="default-arrow-icon"></i>'
  }
end

PostgreSQL 特定配置

对于 PostgreSQL 数据库，你可以配置 NULL 值的排序行为：

Ransack.configure do |c|
  c.postgres_fields_sort_option = :nulls_first  # 或 :nulls_last
end

如果需要强制 NULL 值始终在最前或最后：

Ransack.configure do |c|
  c.postgres_fields_sort_option = :nulls_always_first  # 或 :nulls_always_last
end

不区分大小写的排序

在 PostgreSQL 中实现所有字符串列的不区分大小写排序：

module RansackObject
  def self.included(base)
    base.columns.each do |column|
      if column.type == :string
        base.ransacker column.name.to_sym, type: :string do
          Arel.sql("lower(#{base.table_name}.#{column.name})")
        end
      end
    end
  end
end

class UserWithManyAttributes < ActiveRecord::Base
  include RansackObject
end

性能提示：使用此方法时，建议添加函数索引以提高查询性能。

通过以上配置和使用方法，你可以轻松地在项目中实现强大的搜索和排序功能，而无需编写复杂的查询逻辑。Ransack 的简单模式已经能够满足大多数常见的搜索需求，让开发者能够更专注于业务逻辑的实现。

ransack 项目地址: https://gitcode.com/gh_mirrors/ran/ransack