Action View URL 幫手
提供一組建立連結和取得 URL 的方法,這些方法取決於路由子系統(請參閱 ActionDispatch::Routing
)。這讓您可以在檢視和控制器中使用相同的格式來建立連結。
- #
- B
- C
- L
- M
- P
- S
常數
BUTTON_TAG_METHOD_VERBS | = | %w{patch put delete} |
此幫手可以包含在任何包含路由 URL 幫手的類別中(routes.url_helpers)。這裡提供的一些方法只會在請求的內容中運作(例如 |
||
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 屬性可透過在 html_options
中傳遞 :form_class
選項來設定。預設為 "button_to"
,以允許對表單及其子項進行樣式設定。
表單預設會提交 POST 請求。你可以透過 html_options
中的 :method
選項指定不同的 HTTP 動詞。
如果由 button_to
產生的 HTML 按鈕不適用於你的版面配置,你可以考慮使用 link_to
方法,並加上 data-turbo-method
屬性,如 link_to
文件中所述。
選項
options
hash 接受與 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
- 此 hash 將會是表單屬性 -
:form_class
- 此選項控制提交按鈕將置入其中的表單類別 -
:params
- 要在表單中作為隱藏欄位呈現的參數 hash。
範例
<%= 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>"
已棄用:Rails UJS 屬性
在 Rails 7 之前,Rails 預設會附帶一個名為 @rails/ujs
的 JavaScript 函式庫。在 Rails 7 之後,此函式庫不再預設開啟。此函式庫與下列選項整合
-
:remote
- 如果設為 true,將允許@rails/ujs
控制提交行為。預設情況下,此行為為 Ajax 提交。
@rails/ujs
也與下列 :data
選項整合
-
confirm: "question?"
- 此選項將允許@rails/ujs
提示指定的疑問(在此情況下,產生的文字將會是question?
)。如果使用者接受,按鈕將正常處理,否則不會執行任何動作。 -
:disable_with
- 提交表單時,此參數的值將用作提交按鈕停用版本的數值。
Rails UJS 範例
<%= button_to "Create", { action: "create" }, remote: true, form: { "data-type" => "json" } %>
# => "<form method="post" action="/images/create" class="button_to" data-remote="true" data-type="json">
# <button type="submit">Create</button>
# <input name="authenticity_token" type="hidden" value="10f2163b45388899ad4d5ae948988266befcb6c3d1b2451cf657a0c293d605a6" autocomplete="off"/>
# </form>"
來源:顯示 | 在 GitHub 上
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 609 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::DEFAULT_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::DEFAULT_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
link_to(name = nil, options = nil, html_options = nil, &block) 連結
使用由 options
集合建立的 URL,建立具有給定 name
的錨點元素。請參閱 url_for
文件中的有效選項。也可以傳遞字串,而不是選項雜湊,它會產生一個錨點元素,使用字串值作為連結的 href。使用 :back
符號,而不是選項雜湊,將會產生一個連結到參考者的連結(如果沒有參考者,將會使用 JavaScript 返回連結)。如果傳遞 nil
作為 name,連結本身的值將會變成 name。
簽章
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>
Turbo
Rails
7 預設啟用 Turbo。Turbo 提供下列 :data
選項
-
turbo_method: HTTP 動詞符號
- 使用指定的 HTTP 動詞執行 Turbo 連結拜訪。建議在執行非GET
要求時使用表單。僅在無法使用表單時使用data-turbo-method
。 -
turbo_confirm: "question?"
- 使用指定的值新增確認對話框至連結。
範例
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.org/", data: { turbo_confirm: "Are you sure?" }
# => <a href="https://rubyonrails.org/" data-turbo-confirm="Are you sure?">Visit Other Site</a>
已棄用:Rails UJS 屬性
在 Rails 7 之前,Rails 預設會附帶一個名為 @rails/ujs
的 JavaScript 函式庫。在 Rails 7 之後,此函式庫不再預設開啟。此函式庫與下列選項整合
-
method: HTTP 動詞符號
- 此修飾詞將動態建立 HTML 表單,並立即使用指定的 HTTP 動詞提交表單以進行處理。對於讓連結在危險動作中執行 POST 操作(例如刪除記錄,搜尋機器人在爬取您的網站時可能會追蹤)很有用。支援的動詞為:post
、:delete
、:patch
和:put
。請注意,如果使用者停用 JavaScript,要求將改為使用 GET。如果使用href: '#'
且使用者停用 JavaScript,則按一下連結不會產生任何作用。如果您依賴 POST 行為,您應該使用要求物件的方法post?
、delete?
、patch?
或put?
在控制器動作中檢查此行為。 -
remote: true
- 這將允許@rails/ujs
對有問題的 URL 提出 Ajax 要求,而不是追蹤連結。
@rails/ujs
也與下列 :data
選項整合
-
confirm: "question?"
- 這將允許@rails/ujs
提示指定的疑問(在本例中,結果文字將為question?
)。如果使用者接受,連結將正常處理,否則不會採取任何動作。 -
:disable_with
- 此參數的值將用作連結停用版本的標題。
Rails UJS 範例
link_to "Remove Profile", profile_path(@profile), method: :delete
# => <a href="/profiles/1" rel="nofollow" data-method="delete">Remove Profile</a>
link_to "Visit Other Site", "http://www.rubyonrails.org/", data: { confirm: "Are you sure?" }
# => <a href="http://www.rubyonrails.org/" data-confirm="Are you sure?">Visit Other Site</a>
來源:顯示 | 在 GitHub 上
# File actionview/lib/action_view/helpers/url_helper.rb, line 234 def link_to(name = nil, options = nil, html_options = nil, &block) html_options, options, name = options, name, block if block_given? options ||= {} html_options = convert_options_to_data_attributes(options, html_options) url = url_target(name, options) html_options["href"] ||= url content_tag("a", name || url, html_options, &block) end
link_to_if(condition, name, options = {}, html_options = {}, &block) 連結
如果 condition
為 true,則使用由 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 上
# File actionview/lib/action_view/helpers/url_helper.rb, line 498 def link_to_if(condition, name, options = {}, html_options = {}, &block) if condition link_to(name, options, html_options) else if block_given? block.arity <= 1 ? capture(name, &block) : capture(name, options, html_options, &block) else ERB::Util.html_escape(name) end end end
link_to_unless(condition, name, options = {}, html_options = {}, &block) 連結
使用由 options
組合建立的 URL 建立具有給定 name
的連結標籤,除非 condition
為 true,否則僅傳回名稱。若要設定預設行為(例如,顯示登入連結,而非僅顯示純文字連結文字),您可以傳遞一個區塊,該區塊接受 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 上
# File actionview/lib/action_view/helpers/url_helper.rb, line 475 def link_to_unless(condition, name, options = {}, html_options = {}, &block) link_to_if !condition, name, options, html_options, &block end
link_to_unless_current(name, options = {}, html_options = {}, &block) 連結
使用由 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 上
# File actionview/lib/action_view/helpers/url_helper.rb, line 451 def link_to_unless_current(name, options = {}, html_options = {}, &block) link_to_unless current_page?(options), name, options, html_options, &block end
mail_to(email_address, name = nil, html_options = {}, &block) 連結
建立一個 mailto 連結標籤,連結到指定的 email_address
,該地址也會用作連結的名稱,除非指定了 name
。連結的其他 HTML 屬性可以傳遞在 html_options
中。
mail_to
有多種方法可以透過傳遞特殊金鑰給 html_options
來自訂電子郵件本身。
選項
-
:subject
- 預設電子郵件的主旨列。 -
:body
- 預設電子郵件的內文。 -
:cc
- 在電子郵件中加入副本給其他收件者。 -
:bcc
- 在電子郵件中隱藏抄送其他收件人。 -
: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 548 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) 連結
建立一個 TEL錨點連結標籤,連結到指定的phone_number
。當點擊連結時,會開啟預設的撥打電話應用程式,並預先填入電話號碼。
如果未指定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>
如果連結目標難以放入 name 參數中,也可以使用區塊。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 743 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) 連結
建立一個 SMS 錨點連結標籤,連結到指定的phone_number
。當點擊連結時,會開啟預設的 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>
如果連結目標難以放入 name 參數中,也可以使用區塊。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 692 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