跳至内容 跳至搜索

Action View URL 帮助器

提供一组用于创建链接和获取依赖于路由子系统（参见 ActionDispatch::Routing）的 URL 的方法。这使您能够在视图和控制器中使用相同的链接格式。

命名空间
方法
B
C
L
M
P
S
包含的模块

常量

BUTTON_TAG_METHOD_VERBS = %w{patch put delete}
 

此帮助器可以包含在包含路由的 URL 帮助器（routes.url_helpers）的任何类中。这里提供的一些方法只在请求上下文（例如，link_to_unless_current）中工作，该上下文必须作为上下文上名为 request 的方法提供。
STRINGIFIED_COMMON_METHODS = { get: "get", delete: "delete", patch: "patch", post: "post", put: "put", }.freeze
 

实例公共方法

button_to(name = nil, options = nil, html_options = nil, &block)

生成一个包含单个按钮的表单，该按钮提交到由一组 options 创建的 URL。这是确保不会因搜索机器人或加速器触发导致数据更改的链接的最安全方法。

您可以使用 html_options 控制表单和按钮的行为。html_options 中的大多数值都将传递给按钮元素。例如，在 html_options 中传递 :class 选项将设置按钮元素的 class 属性。

表单元素的 class 属性可以通过在 html_options 中传递 :form_class 选项来设置。它默认设置为 "button_to" 以允许对表单及其子元素进行样式设置。

如果对象未持久化，则表单默认提交 POST 请求；反之，如果对象已持久化，则它将提交 PATCH 请求。若要指定不同的 HTTP 动词，请在 html_options 中使用 :method 选项。

如果从 button_to 生成的 HTML 按钮不适用于您的布局，您可以考虑使用 link_to 方法以及 data-turbo-method 属性，如 link_to 文档中所述。

选项

options 哈希接受与 url_for 相同的选项。若要生成没有 [action] 属性的 <form> 元素，请传递 false

<%= button_to "New", false %>
# => "<form method="post" class="button_to">
#      <button type="submit">New</button>
#      <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6"/>
#    </form>"

html_options 中的大多数值都将传递给按钮元素，但有一些特殊选项

  • :method - HTTP 动词的符号。支持的动词是 :post、:get、:delete、:patch 和 :put。默认情况下，它将是 :post。

  • :disabled - 如果设置为 true，它将生成一个禁用的按钮。

  • :data - 此选项可用于添加自定义数据属性。

  • :form - 此哈希将是表单属性

  • :form_class - 这控制放置提交按钮的表单的类

  • :params - 将作为表单中隐藏字段呈现的参数哈希。

示例

<%= button_to "New", action: "new" %>
# => "<form method="post" action="/controller/new" class="button_to">
#      <button type="submit">New</button>
#      <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6" autocomplete="off"/>
#    </form>"

<%= button_to "New", new_article_path %>
# => "<form method="post" action="/articles/new" class="button_to">
#      <button type="submit">New</button>
#      <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6" autocomplete="off"/>
#    </form>"

<%= button_to "New", new_article_path, params: { time: Time.now  } %>
# => "<form method="post" action="/articles/new" class="button_to">
#      <button type="submit">New</button>
#      <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6"/>
#      <input type="hidden" name="time" value="2021-04-08 14:06:09 -0500" autocomplete="off">
#    </form>"

<%= button_to [:make_happy, @user] do %>
  Make happy <strong><%= @user.name %></strong>
<% end %>
# => "<form method="post" action="/users/1/make_happy" class="button_to">
#      <button type="submit">
#        Make happy <strong><%= @user.name %></strong>
#      </button>
#      <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6"  autocomplete="off"/>
#    </form>"

<%= button_to "New", { action: "new" }, form_class: "new-thing" %>
# => "<form method="post" action="/controller/new" class="new-thing">
#      <button type="submit">New</button>
#      <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6"  autocomplete="off"/>
#    </form>"

<%= button_to "Create", { action: "create" }, form: { "data-type" => "json" } %>
# => "<form method="post" action="/images/create" class="button_to" data-type="json">
#      <button type="submit">Create</button>
#      <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6"  autocomplete="off"/>
#    </form>"

来源：显示 | 在 GitHub 上

# File actionview/lib/action_view/helpers/url_helper.rb, line 296
def button_to(name = nil, options = nil, html_options = nil, &block)
  html_options, options = options, name if block_given?
  html_options ||= {}
  html_options = html_options.stringify_keys

  url =
    case options
    when FalseClass then nil
    else url_for(options)
    end

  remote = html_options.delete("remote")
  params = html_options.delete("params")

  authenticity_token = html_options.delete("authenticity_token")

  method     = (html_options.delete("method").presence || method_for_options(options)).to_s
  method_tag = BUTTON_TAG_METHOD_VERBS.include?(method) ? method_tag(method) : "".html_safe

  form_method  = method == "get" ? "get" : "post"
  form_options = html_options.delete("form") || {}
  form_options[:class] ||= html_options.delete("form_class") || "button_to"
  form_options[:method] = form_method
  form_options[:action] = url
  form_options[:'data-remote'] = true if remote

  request_token_tag = if form_method == "post"
    request_method = method.empty? ? "post" : method
    token_tag(authenticity_token, form_options: { action: url, method: request_method })
  else
    ""
  end

  html_options = convert_options_to_data_attributes(options, html_options)
  html_options["type"] = "submit"

  button = if block_given?
    content_tag("button", html_options, &block)
  elsif button_to_generates_button_tag
    content_tag("button", name || url, html_options, &block)
  else
    html_options["value"] = name || url
    tag("input", html_options)
  end

  inner_tags = method_tag.safe_concat(button).safe_concat(request_token_tag)
  if params
    to_form_params(params).each do |param|
      inner_tags.safe_concat tag(:input, type: "hidden", name: param[:name], value: param[:value],
                                 autocomplete: "off")
    end
  end
  html = content_tag("form", inner_tags, form_options)
  prevent_content_exfiltration(html)
end

current_page?(options = nil, check_parameters: false, **options_as_kwargs)

如果当前请求 URI 是由给定的 options 生成的，则为 True。

示例

假设我们位于 http://www.example.com/shop/checkout?order=desc&page=1 操作中。

current_page?(action: 'process')
# => false

current_page?(action: 'checkout')
# => true

current_page?(controller: 'library', action: 'checkout')
# => false

current_page?(controller: 'shop', action: 'checkout')
# => true

current_page?(controller: 'shop', action: 'checkout', order: 'asc')
# => false

current_page?(controller: 'shop', action: 'checkout', order: 'desc', page: '1')
# => true

current_page?(controller: 'shop', action: 'checkout', order: 'desc', page: '2')
# => false

current_page?('http://www.example.com/shop/checkout')
# => true

current_page?('http://www.example.com/shop/checkout', check_parameters: true)
# => false

current_page?('/shop/checkout')
# => true

current_page?('http://www.example.com/shop/checkout?order=desc&page=1')
# => true

假设我们位于 http://www.example.com/products 操作中，在产品无效的情况下，使用 POST 方法。

current_page?(controller: 'product', action: 'index')
# => false

我们也可以传递符号参数而不是字符串。

来源：显示 | 在 GitHub 上

# File actionview/lib/action_view/helpers/url_helper.rb, line 548
def current_page?(options = nil, check_parameters: false, **options_as_kwargs)
  unless request
    raise "You cannot use helpers that need to determine the current " \
          "page unless your view context provides a Request object " \
          "in a #request method"
  end

  return false unless request.get? || request.head?

  options ||= options_as_kwargs
  check_parameters ||= options.is_a?(Hash) && options.delete(:check_parameters)
  url_string = URI::RFC2396_PARSER.unescape(url_for(options)).force_encoding(Encoding::BINARY)

  # We ignore any extra parameters in the request_uri if the
  # submitted URL doesn't have any either. This lets the function
  # work with things like ?order=asc
  # the behavior can be disabled with check_parameters: true
  request_uri = url_string.index("?") || check_parameters ? request.fullpath : request.path
  request_uri = URI::RFC2396_PARSER.unescape(request_uri).force_encoding(Encoding::BINARY)

  if %r{^\w+://}.match?(url_string)
    request_uri = +"#{request.protocol}#{request.host_with_port}#{request_uri}"
  end

  remove_trailing_slash!(url_string)
  remove_trailing_slash!(request_uri)

  url_string == request_uri
end

使用由一组 options 创建的 URL 创建给定 name 的锚元素。请参阅 url_for 文档中的有效选项。也可以传递字符串而不是选项哈希，这将生成一个锚元素，该元素使用字符串的值作为链接的 href。使用 :back 符号而不是选项哈希将生成一个指向引荐来源的链接（如果不存在引荐来源，则将使用 JavaScript 返回链接来代替）。如果传递 nil 作为名称，则链接本身的值将成为名称。

link_to(body, url, html_options = {})
  # url is a String; you can use URL helpers like
  # posts_path

link_to(body, url_options = {}, html_options = {})
  # url_options, except :method, is passed to url_for

link_to(options = {}, html_options = {}) do
  # name
end

link_to(url, html_options = {}) do
  # name
end

link_to(active_record_model)

  • :data - 此选项可用于添加自定义数据属性。

由于它依赖于 url_for，因此 link_to 支持旧式控制器/操作/id 参数和较新的 RESTful 路由。当前的 Rails 样式尽可能地支持 RESTful 路由，因此请将您的应用程序建立在资源之上并使用

link_to "Profile", profile_path(@profile)
# => <a href="/profiles/1">Profile</a>

或者更简洁的

link_to "Profile", @profile
# => <a href="/profiles/1">Profile</a>

替换旧的更冗长、非面向资源的

link_to "Profile", controller: "profiles", action: "show", id: @profile
# => <a href="/profiles/show/1">Profile</a>

同样，

link_to "Profiles", profiles_path
# => <a href="/profiles">Profiles</a>

比以下方法更好

link_to "Profiles", controller: "profiles"
# => <a href="/profiles">Profiles</a>

当 name 为 nil 时，会显示 href

link_to nil, "http://example.com"
# => <a href="http://www.example.com">http://www.example.com</a>

更简洁，当 name 是一个定义了 to_s 方法的 Active Record 模型，该方法返回一个默认值或模型实例属性时

link_to @profile
# => <a href="http://www.example.com/profiles/1">Eileen</a>

如果您的链接目标难以放入 name 参数中，您也可以使用块。 ERB 示例

<%= link_to(@profile) do %>
  <strong><%= @profile.name %></strong> -- <span>Check it out!</span>
<% end %>
# => <a href="/profiles/1">
       <strong>David</strong> -- <span>Check it out!</span>
     </a>

用于 CSS 的类和 id 很容易生成

link_to "Articles", articles_path, id: "news", class: "article"
# => <a href="/articles" class="article" id="news">Articles</a>

使用旧式参数样式时要小心，因为需要额外的文字哈希

link_to "Articles", { controller: "articles" }, id: "news", class: "article"
# => <a href="/articles" class="article" id="news">Articles</a>

省略哈希将生成错误的链接

link_to "WRONG!", controller: "articles", id: "news", class: "article"
# => <a href="/articles/index/news?class=article">WRONG!</a>

link_to 还可以生成带有锚点或查询字符串的链接

link_to "Comment wall", profile_path(@profile, anchor: "wall")
# => <a href="/profiles/1#wall">Comment wall</a>

link_to "Ruby on Rails search", controller: "searches", query: "ruby on rails"
# => <a href="/searches?query=ruby+on+rails">Ruby on Rails search</a>

link_to "Nonsense search", searches_path(foo: "bar", baz: "quux")
# => <a href="/searches?foo=bar&baz=quux">Nonsense search</a>

您可以设置任何链接属性，例如 target、rel、type

link_to "External link", "http://www.rubyonrails.org/", target: "_blank", rel: "nofollow"
# => <a href="http://www.rubyonrails.org/" target="_blank" rel="nofollow">External link</a>

Rails 7 默认情况下启用 Turbo。Turbo 提供以下 :data 选项

  • turbo_method: HTTP 动词的符号 - 使用给定的 HTTP 动词执行 Turbo 链接访问。建议在执行非 GET 请求时使用表单。仅在表单不可用时使用 data-turbo-method。

  • turbo_confirm: "question?" - 使用给定的值在链接中添加确认对话框。

有关上述选项的更多信息，请查阅 Turbo 手册。

link_to "Delete profile", @profile, data: { turbo_method: :delete }
# => <a href="/profiles/1" data-turbo-method="delete">Delete profile</a>

link_to "Visit Other Site", "https://rubyonrails.net.cn/", data: { turbo_confirm: "Are you sure?" }
# => <a href="https://rubyonrails.net.cn/" data-turbo-confirm="Are you sure?">Visit Other Site</a>

来源：显示 | 在 GitHub 上

如果 condition 为真，则使用由一组 options 创建的 URL 创建给定 name 的链接标签，否则只返回名称。若要专门化默认行为，您可以传递一个接受名称或 link_to_if 的完整参数列表的块。

<%= link_to_if(@current_user.nil?, "Login", { controller: "sessions", action: "new" }) %>
# If the user isn't logged in...
# => <a href="/sessions/new/">Login</a>

<%=
   link_to_if(@current_user.nil?, "Login", { controller: "sessions", action: "new" }) do
     link_to(@current_user.login, { controller: "accounts", action: "show", id: @current_user })
   end
%>
# If the user isn't logged in...
# => <a href="/sessions/new/">Login</a>
# If they are logged in...
# => <a href="/accounts/show/3">my_username</a>

来源：显示 | 在 GitHub 上

除非 condition 为真，否则使用由一组 options 创建的 URL 创建给定 name 的链接标签，在这种情况下，只返回名称。若要专门化默认行为（例如，显示登录链接而不是纯文本链接文本），您可以传递一个接受名称或 link_to_unless 的完整参数列表的块。

<%= link_to_unless(@current_user.nil?, "Reply", { action: "reply" }) %>
# If the user is logged in...
# => <a href="/controller/reply/">Reply</a>

<%=
   link_to_unless(@current_user.nil?, "Reply", { action: "reply" }) do |name|
     link_to(name, { controller: "accounts", action: "signup" })
   end
%>
# If the user is logged in...
# => <a href="/controller/reply/">Reply</a>
# If not...
# => <a href="/accounts/signup">Reply</a>

来源：显示 | 在 GitHub 上

使用由一组 options 创建的 URL 创建给定 name 的链接标签，除非当前请求 URI 与链接相同，在这种情况下，只返回名称（或者如果存在，则执行给定的块）。您可以给 link_to_unless_current 一个块，它将专门化默认行为（例如，显示“从这里开始”链接而不是链接的文本）。

假设您有一个导航菜单…

<ul id="navbar">
  <li><%= link_to_unless_current("Home", { action: "index" }) %></li>
  <li><%= link_to_unless_current("About Us", { action: "about" }) %></li>
</ul>

如果在“关于”操作中，它将渲染…

<ul id="navbar">
  <li><a href="/controller/index">Home</a></li>
  <li>About Us</li>
</ul>

…但是如果在“索引”操作中，它将渲染

<ul id="navbar">
  <li>Home</li>
  <li><a href="/controller/about">About Us</a></li>
</ul>

如果当前操作是给定的操作，则将评估传递给 link_to_unless_current 的隐式块。因此，如果我们有一个评论页面并且想要渲染“返回”链接而不是指向评论页面的链接，我们可以这样做…

<%=
    link_to_unless_current("Comment", { controller: "comments", action: "new" }) do
       link_to("Go back", { controller: "posts", action: "index" })
    end
 %>

来源：显示 | 在 GitHub 上

mail_to(email_address, name = nil, html_options = {}, &block)

创建指向指定 email_address 的 mailto 链接标签，该标签也被用作链接的名称，除非指定了 name。链接的附加 HTML 属性可以传递给 html_options。

mail_to 有几种方法可以通过将特殊键传递给 html_options 来自定义电子邮件本身。

选项

  • :subject - 预设电子邮件的主题行。

  • :body - 预设电子邮件的正文。

  • :cc - 在电子邮件中抄送其他收件人。

  • :bcc - 在电子邮件中密送其他收件人。

  • :reply_to - 预设电子邮件的 Reply-To 字段。

混淆

在 Rails 4.0 之前，mail_to 提供了对地址进行编码的选项，以阻碍电子邮件收集器。要利用这些选项，请安装 actionview-encoded_mail_to gem。

示例

mail_to "[email protected]"
# => <a href="mailto:[email protected]">[email protected]</a>

mail_to "[email protected]", "My email"
# => <a href="mailto:[email protected]">My email</a>

mail_to "[email protected]", cc: "[email protected]",
         subject: "This is an example email"
# => <a href="mailto:[email protected][email protected]&subject=This%20is%20an%20example%20email">[email protected]</a>

如果您的链接目标难以放入 name 参数中，您也可以使用块。 ERB 示例

<%= mail_to "[email protected]" do %>
  <strong>Email me:</strong> <span>[email protected]</span>
<% end %>
# => <a href="mailto:[email protected]">
       <strong>Email me:</strong> <span>[email protected]</span>
     </a>

来源：显示 | 在 GitHub 上

# File actionview/lib/action_view/helpers/url_helper.rb, line 487
def mail_to(email_address, name = nil, html_options = {}, &block)
  html_options, name = name, nil if name.is_a?(Hash)
  html_options = (html_options || {}).stringify_keys

  extras = %w{ cc bcc body subject reply_to }.map! { |item|
    option = html_options.delete(item).presence || next
    "#{item.dasherize}=#{ERB::Util.url_encode(option)}"
  }.compact
  extras = extras.empty? ? "" : "?" + extras.join("&")

  encoded_email_address = ERB::Util.url_encode(email_address).gsub("%40", "@")
  html_options["href"] = "mailto:#{encoded_email_address}#{extras}"

  content_tag("a", name || email_address, html_options, &block)
end

phone_to(phone_number, name = nil, html_options = {}, &block)

创建一个指向指定 phone_number 的 TEL 锚点链接标签。当单击链接时，将打开默认的拨打电话应用程序，并预先填充电话号码。

如果未指定 name，则 phone_number 将用作链接的名称。

支持 country_code 选项，该选项会在链接的电话号码前加上加号和给定的国家/地区代码。例如，country_code: "01" 将在链接的电话号码前加上 +01。

可以通过 html_options 传递链接的其他 HTML 属性。

选项

  • :country_code - 在电话号码前加上国家/地区代码

示例

phone_to "1234567890"
# => <a href="tel:1234567890">1234567890</a>

phone_to "1234567890", "Phone me"
# => <a href="tel:1234567890">Phone me</a>

phone_to "1234567890", country_code: "01"
# => <a href="tel:+011234567890">1234567890</a>

如果链接目标难以放入名称参数，也可以使用块。ERB 示例

<%= phone_to "1234567890" do %>
  <strong>Phone me:</strong>
<% end %>
# => <a href="tel:1234567890">
       <strong>Phone me:</strong>
     </a>

来源：显示 | 在 GitHub 上

# File actionview/lib/action_view/helpers/url_helper.rb, line 669
def phone_to(phone_number, name = nil, html_options = {}, &block)
  html_options, name = name, nil if name.is_a?(Hash)
  html_options = (html_options || {}).stringify_keys

  country_code = html_options.delete("country_code").presence
  country_code = country_code.nil? ? "" : "+#{ERB::Util.url_encode(country_code)}"

  encoded_phone_number = ERB::Util.url_encode(phone_number)
  html_options["href"] = "tel:#{country_code}#{encoded_phone_number}"

  content_tag("a", name || phone_number, html_options, &block)
end

sms_to(phone_number, name = nil, html_options = {}, &block)

创建一个指向指定 phone_number 的 SMS 锚点链接标签。当单击链接时，将打开默认的 SMS 消息应用程序，准备发送消息到链接的电话号码。如果指定了 body 选项，则消息的内容将预设为 body。

如果未指定 name，则 phone_number 将用作链接的名称。

支持 country_code 选项，该选项会在链接的电话号码前加上加号和给定的国家/地区代码。例如，country_code: "01" 将在链接的电话号码前加上 +01。

可以通过 html_options 传递链接的其他 HTML 属性。

选项

  • :country_code - 在电话号码前加上国家/地区代码。

  • :body - 预设消息的主体。

示例

sms_to "5155555785"
# => <a href="sms:5155555785;">5155555785</a>

sms_to "5155555785", country_code: "01"
# => <a href="sms:+015155555785;">5155555785</a>

sms_to "5155555785", "Text me"
# => <a href="sms:5155555785;">Text me</a>

sms_to "5155555785", body: "I have a question about your product."
# => <a href="sms:5155555785;?body=I%20have%20a%20question%20about%20your%20product">5155555785</a>

如果链接目标难以放入名称参数，也可以使用块。ERB 示例

<%= sms_to "5155555785" do %>
  <strong>Text me:</strong>
<% end %>
# => <a href="sms:5155555785;">
       <strong>Text me:</strong>
     </a>

来源：显示 | 在 GitHub 上

# File actionview/lib/action_view/helpers/url_helper.rb, line 618
def sms_to(phone_number, name = nil, html_options = {}, &block)
  html_options, name = name, nil if name.is_a?(Hash)
  html_options = (html_options || {}).stringify_keys

  country_code = html_options.delete("country_code").presence
  country_code = country_code ? "+#{ERB::Util.url_encode(country_code)}" : ""

  body = html_options.delete("body").presence
  body = body ? "?&body=#{ERB::Util.url_encode(body)}" : ""

  encoded_phone_number = ERB::Util.url_encode(phone_number)
  html_options["href"] = "sms:#{country_code}#{encoded_phone_number};#{body}"

  content_tag("a", name || phone_number, html_options, &block)
end