Action View 表单选项助手

返回 object 类中 method 的现有返回值集合的复选框标签。从对实例 object 调用 method 返回的值将被选中。如果调用 method 返回 nil，则不会进行任何选择。

:value_method 和 :text_method 参数是将在 collection 的每个成员上调用的方法。返回值分别用作每个复选框标签的 value 属性和内容。它们也可以是任何响应 call 的对象，例如 proc，它将被调用以获取 collection 的每个成员的值/文本。

此方法使用的示例对象结构

class Post < ActiveRecord::Base
  has_and_belongs_to_many :authors
end
class Author < ActiveRecord::Base
  has_and_belongs_to_many :posts
  def name_with_initial
    "#{first_name.first}. #{last_name}"
  end
end

示例用法（为 Post 实例 @post 选择关联的作者）

collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial)

如果 @post.author_ids 已经是 [1]，这将返回

<input id="post_author_ids_1" name="post[author_ids][]" type="checkbox" value="1" checked="checked" />
<label for="post_author_ids_1">D. Heinemeier Hansson</label>
<input id="post_author_ids_2" name="post[author_ids][]" type="checkbox" value="2" />
<label for="post_author_ids_2">D. Thomas</label>
<input id="post_author_ids_3" name="post[author_ids][]" type="checkbox" value="3" />
<label for="post_author_ids_3">M. Clark</label>
<input name="post[author_ids][]" type="hidden" value="" />

也可以通过向方法提供一个块来自定义元素的显示方式

collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial) do |b|
  b.label { b.check_box }
end

传递给块的参数是一种特殊的构建器，用于此集合，它能够为集合中的当前项目生成标签和复选框，并带有正确的文本和值。使用它，您可以更改标签和复选框的显示顺序，甚至将标签用作包装器，如上面的示例所示。

构建器方法 label 和 check_box 也接受额外的 HTML 选项

collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial) do |b|
  b.label(class: "check_box") { b.check_box(class: "check_box") }
end

还有三个特殊方法可用：object、text 和 value，它们分别是当前正在渲染的项目、其文本和值方法。您可以像这样使用它们

collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial) do |b|
   b.label(:"data-value" => b.value) { b.check_box + b.text }
end

注意

当复选框集合没有进行任何选择时，大多数 Web 浏览器不会发送任何值。

例如，如果我们有一个 User 模型，它具有 category_ids 字段，并且我们在更新操作中具有以下代码

@user.update(params[:user])

如果没有选择 category_ids，那么我们可以安全地假设此字段不会被更新。

这得益于辅助方法为每个复选框集合生成的隐藏字段。此隐藏字段被赋予与复选框相同的字段名称，并具有空值。

在极少数情况下，您不希望使用此隐藏字段，可以将 include_hidden: false 选项传递给辅助方法。

返回 object 类中 method 的现有返回值集合的单选按钮标签。调用 object 实例上的 method 返回的值将被选中。如果调用 method 返回 nil，则不进行任何选择。

:value_method 和 :text_method 参数是将在 collection 的每个成员上调用的方法。返回值分别用作每个单选按钮标签的 value 属性和内容。它们也可以是任何响应 call 的对象，例如 proc，它将被调用以获取 collection 中每个成员的值/文本。

此方法使用的示例对象结构

class Post < ActiveRecord::Base
  belongs_to :author
end

class Author < ActiveRecord::Base
  has_many :posts

  def name_with_initial
    "#{first_name.first}. #{last_name}"
  end
end

示例用法（为 Post 实例 @post 选择关联的作者）

collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial)

如果 @post.author_id 已经是 1，则将返回

<input id="post_author_id_1" name="post[author_id]" type="radio" value="1" checked="checked" />
<label for="post_author_id_1">D. Heinemeier Hansson</label>
<input id="post_author_id_2" name="post[author_id]" type="radio" value="2" />
<label for="post_author_id_2">D. Thomas</label>
<input id="post_author_id_3" name="post[author_id]" type="radio" value="3" />
<label for="post_author_id_3">M. Clark</label>

也可以通过向方法提供一个块来自定义元素的显示方式

collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial) do |b|
  b.label { b.radio_button }
end

传递给块的参数是一种特殊类型的构建器，用于此集合，它能够为集合中的当前项生成标签和单选按钮，并带有正确的文本和值。使用它，您可以更改标签和单选按钮的显示顺序，甚至可以使用标签作为包装器，如上面的示例所示。

构建器方法 label 和 radio_button 也接受额外的 HTML 选项

collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial) do |b|
  b.label(class: "radio_button") { b.radio_button(class: "radio_button") }
end

还有三个特殊方法可用：object、text 和 value，它们分别是当前正在渲染的项目、其文本和值方法。您可以像这样使用它们

collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial) do |b|
   b.label(:"data-value" => b.value) { b.radio_button + b.text }
end

注意

HTML 规范指出，当单选按钮集合中没有选中任何选项时，Web 浏览器不会向服务器发送任何值。不幸的是，这会导致一个问题：如果 User 模型具有 category_id 字段，并且在表单中没有选择任何类别，则不会发送 category_id 参数。因此，任何类似于强参数的习惯用法，例如

params.require(:user).permit(...)

将引发错误，因为不会存在 {user: ...}。

为了防止这种情况，助手会在每个单选按钮集合之前生成一个辅助隐藏字段。隐藏字段具有与单选按钮相同的名称和空白值。

如果您不希望助手生成此隐藏字段，您可以指定 include_hidden: false 选项。

返回用于 object 类中 method 的现有返回值集合的 <select> 和 <option> 标签。在实例 object 上调用 method 返回的值将被选中。如果调用 method 返回 nil，则在 options 哈希中不包含 :prompt 或 :include_blank 时，不会进行任何选择。

:value_method 和 :text_method 参数是将在 collection 的每个成员上调用的方法。返回值分别用作每个 <option> 标签的 value 属性和内容。它们也可以是任何响应 call 的对象，例如 proc，它将被调用以获取 collection 的每个成员的值/文本。

此方法使用的示例对象结构

class Post < ActiveRecord::Base
  belongs_to :author
end

class Author < ActiveRecord::Base
  has_many :posts

  def name_with_initial
    "#{first_name.first}. #{last_name}"
  end
end

示例用法（为 Post 实例 @post 选择关联的作者）

collection_select(:post, :author_id, Author.all, :id, :name_with_initial, prompt: true)

如果 @post.author_id 已经是 1，则将返回

<select name="post[author_id]" id="post_author_id">
  <option value="">Please select</option>
  <option value="1" selected="selected">D. Heinemeier Hansson</option>
  <option value="2">D. Thomas</option>
  <option value="3">M. Clark</option>
</select>

返回用于 object 类中 method 的现有返回值集合的 <select>、<optgroup> 和 <option> 标签。在实例 object 上调用 method 返回的值将被选中。如果调用 method 返回 nil，则在 options 哈希中不包含 :prompt 或 :include_blank 时，不会进行任何选择。

参数

• object - 用于选择标签的类的实例

• method - 对应于选择标签的 object 的属性

• collection - 表示 <optgroup> 标签的对象数组。

• group_method - 当在 collection 的成员上调用时，返回表示 <option> 标签的子对象数组的方法的名称。它也可以是任何响应 call 的对象，例如 proc，它将被调用以获取 collection 的每个成员的值。

• group_label_method - 当在 collection 的成员上调用时，返回用作其 <optgroup> 标签的 label 属性的字符串的方法的名称。它也可以是任何响应 call 的对象，例如 proc，它将被调用以获取 collection 的每个成员的标签。

• option_key_method - 当在 collection 成员的子对象上调用时，返回用作其 <option> 标签的 value 属性的值的方法的名称。

• option_value_method - 当在collection成员的子对象上调用时，返回一个值的名称，该值将用作其<option>标签的内容。

此方法使用的示例对象结构

# attributes: id, name
class Continent < ActiveRecord::Base
  has_many :countries
end

# attributes: id, name, continent_id
class Country < ActiveRecord::Base
  belongs_to :continent
end

# attributes: id, name, country_id
class City < ActiveRecord::Base
  belongs_to :country
end

示例用法

grouped_collection_select(:city, :country_id, @continents, :countries, :name, :id, :name)

可能的输出

<select name="city[country_id]" id="city_country_id">
  <optgroup label="Africa">
    <option value="1">South Africa</option>
    <option value="3">Somalia</option>
  </optgroup>
  <optgroup label="Europe">
    <option value="7" selected="selected">Denmark</option>
    <option value="2">Ireland</option>
  </optgroup>
</select>

返回一个<option>标签字符串，类似于options_for_select，但用<optgroup>标签将其包装起来

grouped_options = [
 ['North America',
   [['United States','US'],'Canada']],
 ['Europe',
   ['Denmark','Germany','France']]
]
grouped_options_for_select(grouped_options)

grouped_options = {
  'North America' => [['United States','US'], 'Canada'],
  'Europe' => ['Denmark','Germany','France']
}
grouped_options_for_select(grouped_options)

可能的输出

<optgroup label="North America">
  <option value="US">United States</option>
  <option value="Canada">Canada</option>
</optgroup>
<optgroup label="Europe">
  <option value="Denmark">Denmark</option>
  <option value="Germany">Germany</option>
  <option value="France">France</option>
</optgroup>

参数

• grouped_options - 接受嵌套的字符串数组或哈希。第一个值用作<optgroup>标签，而第二个值必须是选项数组。第二个值可以是文本-值对的嵌套数组。有关更多信息，请参见options_for_select。

  Ex. ["North America",[["United States","US"],["Canada","CA"]]]
  

  可以提供一个可选的第三个值作为optgroup的 HTML 属性。

  Ex. ["North America",[["United States","US"],["Canada","CA"]], { disabled: "disabled" }]
  

• selected_key - 一个与<option>标签的value属性相等的 value，该标签将具有selected属性。注意：此值可能与多个选项匹配，因为您可能在多个组中具有相同的选项。然后，每个选项都将获得selected="selected"。

选项

• :prompt - 设置为 true 或提示字符串。当选择元素还没有值时，这会在前面添加一个具有通用提示的选项 - “请选择” - 或给定的提示字符串。

• :divider - 选项组的分割符。

  grouped_options = [
    [['United States','US'], 'Canada'],
    ['Denmark','Germany','France']
  ]
  grouped_options_for_select(grouped_options, nil, divider: '---------')
  

  可能的输出

  <optgroup label="---------">
    <option value="US">United States</option>
    <option value="Canada">Canada</option>
  </optgroup>
  <optgroup label="---------">
    <option value="Denmark">Denmark</option>
    <option value="Germany">Germany</option>
    <option value="France">France</option>
  </optgroup>
  

注意：只返回<optgroup>和<option>标签，因此您仍然需要将输出包装在适当的<select>标签中。

返回一个<option>标签字符串，类似于options_from_collection_for_select，但根据参数的对象关系将其分组到<optgroup>标签中。

参数

• collection - 表示 <optgroup> 标签的对象数组。

• group_method - 当在collection的成员上调用时，返回一个表示<option>标签的子对象数组的名称。

• group_label_method - 当在collection的成员上调用时，返回一个字符串的名称，该字符串将用作其<optgroup>标签的label属性。

• option_key_method - 当在 collection 成员的子对象上调用时，返回用作其 <option> 标签的 value 属性的值的方法的名称。

• option_value_method - 当在collection成员的子对象上调用时，返回一个值的名称，该值将用作其<option>标签的内容。

• selected_key - 等于其中一个<option>标签的value属性的值，该标签将设置selected属性。对应于对option_key_method的调用之一的返回值。如果为nil，则不进行选择。如果要指定禁用值，也可以是哈希。

此方法使用的示例对象结构

class Continent < ActiveRecord::Base
  has_many :countries
  # attribs: id, name
end

class Country < ActiveRecord::Base
  belongs_to :continent
  # attribs: id, name, continent_id
end

示例用法

option_groups_from_collection_for_select(@continents, :countries, :name, :id, :name, 3)

可能的输出

<optgroup label="Africa">
  <option value="1">Egypt</option>
  <option value="4">Rwanda</option>
  ...
</optgroup>
<optgroup label="Asia">
  <option value="3" selected="selected">China</option>
  <option value="12">India</option>
  <option value="5">Japan</option>
  ...
</optgroup>

注意：只返回<optgroup>和<option>标签，因此您仍然需要将输出包装在适当的<select>标签中。

接受一个容器（哈希、数组、可枚举、您的类型）并返回一个选项标签字符串。给定一个容器，其中元素响应 first 和 last（例如，一个包含两个元素的数组），则“lasts”用作选项值，“firsts”用作选项文本。哈希会自动转换为这种形式，因此键变为“firsts”，值变为 lasts。如果指定了selected，则匹配的“last”或元素将获得选定的选项标签。当使用多选时，selected也可以是将被选中的值的数组。

options_for_select([["Dollar", "$"], ["Kroner", "DKK"]])
# => <option value="$">Dollar</option>
# => <option value="DKK">Kroner</option>

options_for_select([ "VISA", "MasterCard" ], "MasterCard")
# => <option value="VISA">VISA</option>
# => <option selected="selected" value="MasterCard">MasterCard</option>

options_for_select({ "Basic" => "$20", "Plus" => "$40" }, "$40")
# => <option value="$20">Basic</option>
# => <option value="$40" selected="selected">Plus</option>

options_for_select([ "VISA", "MasterCard", "Discover" ], ["VISA", "Discover"])
# => <option selected="selected" value="VISA">VISA</option>
# => <option value="MasterCard">MasterCard</option>
# => <option selected="selected" value="Discover">Discover</option>

您可以选择将 HTML 属性作为数组的最后一个元素提供。

options_for_select([ "Denmark", ["USA", { class: 'bold' }], "Sweden" ], ["USA", "Sweden"])
# => <option value="Denmark">Denmark</option>
# => <option value="USA" class="bold" selected="selected">USA</option>
# => <option value="Sweden" selected="selected">Sweden</option>

options_for_select([["Dollar", "$", { class: "bold" }], ["Kroner", "DKK", { onclick: "alert('HI');" }]])
# => <option value="$" class="bold">Dollar</option>
# => <option value="DKK" onclick="alert('HI');">Kroner</option>

如果您希望指定禁用的选项标签，请将selected设置为哈希，其中:disabled是将被禁用的值或值的数组。在这种情况下，您可以使用:selected来指定选定的选项标签。

options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], disabled: "Super Platinum")
# => <option value="Free">Free</option>
# => <option value="Basic">Basic</option>
# => <option value="Advanced">Advanced</option>
# => <option value="Super Platinum" disabled="disabled">Super Platinum</option>

options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], disabled: ["Advanced", "Super Platinum"])
# => <option value="Free">Free</option>
# => <option value="Basic">Basic</option>
# => <option value="Advanced" disabled="disabled">Advanced</option>
# => <option value="Super Platinum" disabled="disabled">Super Platinum</option>

options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], selected: "Free", disabled: "Super Platinum")
# => <option value="Free" selected="selected">Free</option>
# => <option value="Basic">Basic</option>
# => <option value="Advanced">Advanced</option>
# => <option value="Super Platinum" disabled="disabled">Super Platinum</option>

注意：只返回选项标签，您必须将此调用包装在常规 HTML select 标签中。

返回一个选项标签字符串，这些标签是通过迭代collection并为选项值分配对value_method的调用的结果，以及为选项文本分配text_method的结果而编译的。

options_from_collection_for_select(@people, 'id', 'name')
# => <option value="#{person.id}">#{person.name}</option>

这通常在 select_tag 中使用，例如以下示例

select_tag 'person', options_from_collection_for_select(@people, 'id', 'name')

如果selected指定为值或值的数组，则在value_method上返回匹配的元素将是选定的选项标签。

如果selected指定为 Proc，则对匿名函数返回 true 的集合成员是选定的值。

selected 也可以是一个哈希，指定所需的 :selected 和/或 :disabled 值。

请确保在指定选中或禁用的选项时，使用与 value_method 相同的类。否则会导致意外的结果。例如

options_from_collection_for_select(@people, 'id', 'name', '1')

不会选择 id 为 1 的人，因为 1（一个 Integer）与 '1'（一个字符串）不同。

options_from_collection_for_select(@people, 'id', 'name', 1)

应该会产生预期的结果。

为提供的对象和方法创建一个选择标签和一系列包含的选项标签。如果对象可用，则将选择对象当前持有的选项。

choices 参数有两种可能的格式，对应于其他帮助程序的输出。

• 一个扁平集合（参见 options_for_select）。

• 一个嵌套集合（参见 grouped_options_for_select）。

示例：@post.person_id => 2

select :post, :person_id, Person.all.collect { |p| [ p.name, p.id ] }, { include_blank: true })

将变成

<select name="post[person_id]" id="post_person_id">
  <option value="" label=" "></option>
  <option value="1">David</option>
  <option value="2" selected="selected">Eileen</option>
  <option value="3">Rafael</option>
</select>

这可以用来以标准方式提供一组默认选项：在渲染创建表单之前，一个新的模型实例被分配默认选项并绑定到 @model_name。通常这个模型不会保存到数据库中。相反，当收到创建请求时，会创建一个第二个模型对象。这允许用户多次提交表单页面，并获得创建多个记录的预期结果。此外，这允许使用单个部分来生成编辑和创建表单的表单输入。

默认情况下，post.person_id 是选定的选项。指定 selected: value 以使用不同的选择，或 selected: nil 以使所有选项未选中。类似地，您可以通过指定 :disabled 选项来指定要在选项标签中禁用的值。这可以是一个值或一个要禁用的值的数组。

可以将一个块传递给select来定制选项标签的渲染方式。这在选项标签具有复杂属性时非常有用。

select(report, :campaign_ids) do
  available_campaigns.each do |c|
    tag.option(c.name, value: c.id, data: { tags: c.tags.to_json })
  end
end

注意

HTML 规范指出，当将multiple参数传递给 select 并且所有选项都被取消选中时，Web 浏览器不会向服务器发送任何值。不幸的是，这会导致一个问题：如果一个User模型具有多个roles并且具有role_ids访问器，并且在编辑用户角色的表单中，用户从role_ids多选框中取消选中所有角色，则不会发送role_ids参数。因此，任何类似于以下的批量赋值习惯用法

@user.update(params[:user])

将不会更新角色。

为了防止这种情况，助手会在每个多选框之前生成一个辅助隐藏字段。隐藏字段具有与多选框相同的名称和空值。

注意：客户端要么只发送隐藏字段（表示未选中的多选框），要么发送两个字段。这意味着结果数组始终包含一个空字符串。

如果您不希望助手生成此隐藏字段，您可以指定 include_hidden: false 选项。

返回一个选项标签字符串，用于表示世界上几乎所有时区。提供一个ActiveSupport::TimeZone名称作为selected，使其被标记为选中的选项标签。您还可以提供一个ActiveSupport::TimeZone对象的数组作为priority_zones，以便它们在（长）列表的其余部分之前列出。（您可以使用ActiveSupport::TimeZone.us_zones作为获取美国时区列表的便利方法，或者使用Regexp来选择您选择的时区）

selected参数必须是nil，或者是一个命名ActiveSupport::TimeZone的字符串。

默认情况下，model是ActiveSupport::TimeZone常量（可以在 Active Record 中作为值对象获得）。model参数必须响应all并返回一个表示时区的对象数组；每个对象必须响应name。如果给定一个Regexp，它将尝试使用match?方法匹配时区。

注意：只返回选项标签，您必须将此调用包装在常规 HTML select 标签中。

返回给定对象和方法的 select 和 option 标签，使用 time_zone_options_for_select 生成选项标签列表。

除了上面记录的 :include_blank 选项之外，此方法还支持 :model 选项，该选项默认为 ActiveSupport::TimeZone。用户可以使用它来指定不同的时区模型对象。（有关更多信息，请参阅 time_zone_options_for_select。）

您还可以提供一个 ActiveSupport::TimeZone 对象数组作为 priority_zones，以便它们将列在其余（较长）列表的上面。您可以使用 ActiveSupport::TimeZone.us_zones 获取美国时区列表，ActiveSupport::TimeZone.country_zones(country_code) 获取另一个国家/地区的时区，或使用 Regexp 选择您选择的时区。

最后，此方法支持 :default 选项，该选项在对象的时区为 nil 时选择默认的 ActiveSupport::TimeZone。

time_zone_select(:user, :time_zone, nil, include_blank: true)

time_zone_select(:user, :time_zone, nil, default: "Pacific Time (US & Canada)")

time_zone_select(:user, :time_zone, ActiveSupport::TimeZone.us_zones, default: "Pacific Time (US & Canada)")

time_zone_select(:user, :time_zone, [ ActiveSupport::TimeZone["Alaska"], ActiveSupport::TimeZone["Hawaii"] ])

time_zone_select(:user, :time_zone, /Australia/)

time_zone_select(:user, :time_zone, ActiveSupport::TimeZone.all.sort, model: ActiveSupport::TimeZone)

返回一周中每一天的选项标签字符串。

选项

• :index_as_value - 默认为 false，设置为 true 以使用 I18n.translate("date.day_names") 中的索引作为值。默认情况下，星期日始终为 0。

• :day_format - 用于星期几选项的数组的 I18n 键。默认为 :day_names，设置为 :abbr_day_names 以获取缩写。

• :beginning_of_week - 默认为 Date.beginning_of_week。

注意：只返回选项标签，您必须将此调用包装在常规 HTML select 标签中。

返回给定对象和方法的 select 和 option 标签，使用 weekday_options_for_select 生成选项标签列表。