跳到內容 跳到搜尋

宣告一個列舉屬性,其中值對應到資料庫中的整數,但可以用名稱查詢。範例

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ]
end

# conversation.update! status: 0
conversation.active!
conversation.active? # => true
conversation.status  # => "active"

# conversation.update! status: 1
conversation.archived!
conversation.archived? # => true
conversation.status    # => "archived"

# conversation.status = 1
conversation.status = "archived"

conversation.status = nil
conversation.status.nil? # => true
conversation.status      # => nil

也會提供根據列舉欄位允許值建立的範圍。使用上述範例

Conversation.active
Conversation.not_active
Conversation.archived
Conversation.not_archived

當然,如果範圍不符合您的需求,您也可以直接查詢它們

Conversation.where(status: [:active, :archived])
Conversation.where.not(status: :active)

可以透過將 :scopes 設定為 false 來停用範圍定義。

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ], scopes: false
end

您可以透過設定 :default 來設定預設列舉值,例如

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ], default: :active
end

conversation = Conversation.new
conversation.status # => "active"

可以用雜湊明確對應屬性和資料庫整數之間的關聯

class Conversation < ActiveRecord::Base
  enum :status, active: 0, archived: 1
end

最後,也可以使用字串欄位來儲存列舉值。請注意,這可能會導致資料庫查詢速度變慢

class Conversation < ActiveRecord::Base
  enum :status, active: "active", archived: "archived"
end

請注意,當使用陣列時,從值到資料庫整數的隱式對應會根據值在陣列中出現的順序而衍生。在範例中,:active 對應到 0,因為它是第一個元素,而 :archived 對應到 1。一般來說,第 i 個元素對應到資料庫中的 i-1

因此,一旦將值新增到列舉陣列中,就必須維持它在陣列中的位置,而且只能將新值新增到陣列的尾端。若要移除未使用的值,應使用明確的雜湊語法。

在罕見的情況下,您可能需要直接存取對應關係。對應關係會透過類別方法公開,其使用複數屬性名稱,並在 ActiveSupport::HashWithIndifferentAccess 中傳回對應關係

Conversation.statuses[:active]    # => 0
Conversation.statuses["archived"] # => 1

當您需要知道列舉的序數值時,請使用該類別方法。例如,您可以在手動建立 SQL 字串時使用它

Conversation.where("status <> ?", Conversation.statuses[:archived])

當您需要使用相同值定義多個列舉時,可以使用 :prefix:suffix 選項。如果傳遞的值為 true,則方法會加上列舉名稱的前綴/後綴。也可以提供自訂值

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ], suffix: true
  enum :comments_status, [ :active, :inactive ], prefix: :comments
end

使用上述範例,驚嘆號和謂詞方法以及相關範圍現在會適當地加上前綴和/或後綴

conversation.active_status!
conversation.archived_status? # => false

conversation.comments_inactive!
conversation.comments_active? # => false

如果您想停用模型上的自動產生方法,您可以將 :instance_methods 選項設定為 false

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ], instance_methods: false
end

如果您希望在儲存之前驗證列舉值,請使用選項 :validate

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ], validate: true
end

conversation = Conversation.new

conversation.status = :unknown
conversation.valid? # => false

conversation.status = nil
conversation.valid? # => false

conversation.status = :active
conversation.valid? # => true

也可以傳遞其他驗證選項

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ], validate: { allow_nil: true }
end

conversation = Conversation.new

conversation.status = :unknown
conversation.valid? # => false

conversation.status = nil
conversation.valid? # => true

conversation.status = :active
conversation.valid? # => true

否則會引發 ArgumentError

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ]
end

conversation = Conversation.new

conversation.status = :unknown # 'unknown' is not a valid status (ArgumentError)
方法
E

實例公開方法

enum(name = nil, values = nil, **options)

# File activerecord/lib/active_record/enum.rb, line 216
def enum(name = nil, values = nil, **options)
  if name
    values, options = options, {} unless values
    return _enum(name, values, **options)
  end

  definitions = options.slice!(:_prefix, :_suffix, :_scopes, :_default, :_instance_methods)
  options.transform_keys! { |key| :"#{key[1..-1]}" }

  definitions.each { |name, values| _enum(name, values, **options) }
end