動作檢視輔助器 — Ruby on Rails 指南

1 Action View 提供的輔助工具概述

WIP：並非所有輔助工具都列於此處。如需完整清單，請參閱 API 文件

以下僅為 Action View 中可用輔助工具的簡要概述摘要。建議您檢閱 API 文件，其中更詳細地介紹所有輔助工具，但這應作為一個良好的起點。

1.1 AssetTagHelper

此模組提供用於產生 HTML 的方法，將檢視連結到資產，例如圖片、JavaScript 檔案、樣式表和饋送。

預設情況下，Rails 會在 public 資料夾中連結到目前主機上的這些資產，但你可以透過在應用程式設定中設定 config.asset_host，通常在 config/environments/production.rb 中，來引導 Rails 從專用資產伺服器連結到資產。例如，假設你的資產主機是 assets.example.com

config.asset_host = "assets.example.com"
image_tag("rails.png")
# => <img src="http://assets.example.com/images/rails.png" />

1.1.1 auto_discovery_link_tag

傳回瀏覽器和饋送閱讀器可使用來自動偵測 RSS、Atom 或 JSON 饋送的連結標籤。

auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", { title: "RSS Feed" })
# => <link rel="alternate" type="application/rss+xml" title="RSS Feed" href="http://www.example.com/feed.rss" />

1.1.2 image_path

計算 app/assets/images 目錄中圖片資產的路徑。將傳遞來自文件根目錄的完整路徑。由 image_tag 內部使用來建立圖片路徑。

image_path("edit.png") # => /assets/edit.png

如果 config.assets.digest 設為 true，指紋將會新增到檔名。

image_path("edit.png")
# => /assets/edit-2d1a2db63fc738690021fedb5a65b68e.png

1.1.3 image_url

計算 app/assets/images 目錄中圖片資產的 URL。這會在內部呼叫 image_path，並與你的目前主機或你的資產主機合併。

image_url("edit.png") # => http://www.example.com/assets/edit.png

1.1.4 image_tag

傳回來源的 HTML 圖片標籤。來源可以是完整路徑或存在於 app/assets/images 目錄中的檔案。

image_tag("icon.png") # => <img src="/assets/icon.png" />

1.1.5 javascript_include_tag

傳回每個提供的來源的 HTML script 標籤。你可以傳入存在於 app/assets/javascripts 目錄中 JavaScript 檔案的檔名（.js 副檔名為選用），以將其包含到目前頁面中，或者你可以傳入相對於文件根目錄的完整路徑。

javascript_include_tag "common"
# => <script src="/assets/common.js"></script>

1.1.6 javascript_path

計算 app/assets/javascripts 目錄中 JavaScript 資產的路徑。如果來源檔名沒有副檔名，將會附加 .js。將傳遞來自文件根目錄的完整路徑。由 javascript_include_tag 內部使用來建立腳本路徑。

javascript_path "common" # => /assets/common.js

1.1.7 javascript_url

計算 app/assets/javascripts 目錄中 JavaScript 資源的 URL。這會呼叫 javascript_path 內部函式，並與您目前的伺服器或資源伺服器合併。

javascript_url "common"
# => http://www.example.com/assets/common.js

1.1.8 picture_tag

傳回來源的 HTML picture 標籤。它支援傳遞字串、陣列或區塊。

picture_tag("icon.webp", "icon.png")

這會產生以下 HTML

<picture>
  <source srcset="/assets/icon.webp" type="image/webp" />
  <source srcset="/assets/icon.png" type="image/png" />
  <img src="/assets/icon.png" />
</picture>

1.1.9 preload_link_tag

傳回連結標籤，瀏覽器可以使用它來預載來源。來源可以是資源管線管理的資源路徑、完整路徑或 URI。

preload_link_tag "application.css"
# => <link rel="preload" href="/assets/application.css" as="style" type="text/css" />

1.1.10 stylesheet_link_tag

傳回樣式表連結標籤，作為引數指定的來源。如果您未指定副檔名，將自動附加 .css。

stylesheet_link_tag "application"
# => <link href="/assets/application.css" rel="stylesheet" />

1.1.11 stylesheet_path

計算 app/assets/stylesheets 目錄中樣式表資源的路徑。如果來源檔名沒有副檔名，將附加 .css。來自文件根目錄的完整路徑將傳遞。stylesheet_link_tag 內部使用它來建立樣式表路徑。

stylesheet_path "application" # => /assets/application.css

1.1.12 stylesheet_url

計算 app/assets/stylesheets 目錄中樣式表資源的 URL。這會呼叫 stylesheet_path 內部函式，並與您目前的伺服器或資源伺服器合併。

stylesheet_url "application"
# => http://www.example.com/assets/application.css

1.2 AtomFeedHelper

1.2.1 atom_feed

這個輔助程式讓建立 Atom 饋送變得容易。以下是完整的用法範例

config/routes.rb

resources :articles

app/controllers/articles_controller.rb

def index
  @articles = Article.all

  respond_to do |format|
    format.html
    format.atom
  end
end

app/views/articles/index.atom.builder

atom_feed do |feed|
  feed.title("Articles Index")
  feed.updated(@articles.first.created_at)

  @articles.each do |article|
    feed.entry(article) do |entry|
      entry.title(article.title)
      entry.content(article.body, type: 'html')

      entry.author do |author|
        author.name(article.author_name)
      end
    end
  end
end

1.3 BenchmarkHelper

1.3.1 benchmark

讓您測量範本中區塊的執行時間，並將結果記錄到日誌。將這個區塊包覆在昂貴的操作或可能的瓶頸周圍，以取得操作的時間讀數。

<% benchmark "Process data files" do %>
  <%= expensive_files_operation %>
<% end %>

這會在日誌中新增類似「處理資料檔案 (0.34523)」的內容，然後您可以在最佳化程式碼時使用它來比較時間。

1.4 CacheHelper

1.4.1 cache

快取整個動作或頁面片段的方法，而非快取整個動作或頁面。此技術可快取選單、新聞主題清單、靜態 HTML 片段等片段。此方法會取得包含您想快取內容的區塊。請參閱 AbstractController::Caching::Fragments 以取得更多資訊。

<% cache do %>
  <%= render "application/footer" %>
<% end %>

1.5 CaptureHelper

1.5.1 capture

capture 方法讓您能將範本的一部分擷取到變數中。您可以在範本或配置中的任何位置使用此變數。

<% @greeting = capture do %>
  <p>Welcome! The date and time is <%= Time.now %></p>
<% end %>

擷取的變數可以在其他任何位置使用。

<html>
  <head>
    <title>Welcome!</title>
  </head>
  <body>
    <%= @greeting %>
  </body>
</html>

1.5.2 content_for

呼叫 content_for 會將標記區塊儲存在識別碼中以供後續使用。您可以透過將識別碼傳遞為 yield 的引數，在其他範本或配置中後續呼叫儲存的內容。

例如，假設我們有一個標準應用程式配置，但也有需要特定 JavaScript 的特殊頁面，而網站的其他部分不需要這個 JavaScript。我們可以使用 content_for 在特殊頁面上包含這個 JavaScript，而不會讓網站的其他部分變肥大。

app/views/layouts/application.html.erb

<html>
  <head>
    <title>Welcome!</title>
    <%= yield :special_script %>
  </head>
  <body>
    <p>Welcome! The date and time is <%= Time.now %></p>
  </body>
</html>

app/views/articles/special.html.erb

<p>This is a special page.</p>

<% content_for :special_script do %>
  <script>alert('Hello!')</script>
<% end %>

1.6 DateHelper

1.6.1 distance_of_time_in_words

回報兩個時間或日期物件或整數之間的時間距離近似值（以秒為單位）。如果您想要更詳細的近似值，請將 include_seconds 設為 true。

distance_of_time_in_words(Time.now, Time.now + 15.seconds)
# => less than a minute
distance_of_time_in_words(Time.now, Time.now + 15.seconds, include_seconds: true)
# => less than 20 seconds

1.6.2 time_ago_in_words

與 distance_of_time_in_words 類似，但 to_time 固定為 Time.now。

time_ago_in_words(3.minutes.from_now) # => 3 minutes

1.7 DebugHelper

傳回一個 pre 標籤，其中包含 YAML 轉儲的物件。這會建立一個非常容易閱讀的方式來檢查物件。

my_hash = { 'first' => 1, 'second' => 'two', 'third' => [1, 2, 3] }
debug(my_hash)

<pre class='debug_dump'>---
first: 1
second: two
third:
- 1
- 2
- 3
</pre>

1.8 FormHelper

表單幫手旨在讓使用模型變得比僅使用標準 HTML 元素容易許多，方法是提供一組用於根據模型建立表單的方法。此幫手會產生表單的 HTML，並為每種輸入類型（例如文字、密碼、選取等）提供一個方法。當提交表單（即當使用者按下提交按鈕或透過 JavaScript 呼叫 form.submit）時，表單輸入會綑綁到 params 物件中，並傳回控制器。

您可以在 Action View 表單幫手指南中深入了解表單幫手。

1.9 JavaScriptHelper

提供在檢視中使用 JavaScript 的功能。

1.9.1 escape_javascript

針對 JavaScript 區段跳脫載入傳回和單引號及雙引號。

1.9.2 javascript_tag

傳回一個 JavaScript 標籤，將提供的程式碼包裝起來。

javascript_tag "alert('All is good')"

<script>
//<![CDATA[
alert('All is good')
//]]>
</script>

1.10 NumberHelper

提供將數字轉換為格式化字串的方法。提供電話號碼、貨幣、百分比、精確度、位置表示法和檔案大小的方法。

1.10.1 number_to_currency

將數字格式化為貨幣字串（例如 $13.65）。

number_to_currency(1234567890.50) # => $1,234,567,890.50

1.10.2 number_to_human

漂亮列印（格式化和近似）數字，讓使用者更容易閱讀；對於可能會變得非常大的數字很有用。

number_to_human(1234)    # => 1.23 Thousand
number_to_human(1234567) # => 1.23 Million

1.10.3 number_to_human_size

將大小中的位元組格式化為更易於理解的表示方式；對於向使用者報告檔案大小很有用。

number_to_human_size(1234)    # => 1.21 KB
number_to_human_size(1234567) # => 1.18 MB

1.10.4 number_to_percentage

將數字格式化為百分比字串。

number_to_percentage(100, precision: 0) # => 100%

1.10.5 number_to_phone

將數字格式化為電話號碼（預設為美國）。

number_to_phone(1235551234) # => 123-555-1234

1.10.6 number_with_delimiter

使用分隔符號將數字格式化為群組的千位數。

number_with_delimiter(12345678) # => 12,345,678

1.10.7 number_with_precision

使用指定的 precision 層級格式化數字，預設為 3。

number_with_precision(111.2345)               # => 111.235
number_with_precision(111.2345, precision: 2) # => 111.23

1.11 SanitizeHelper

SanitizeHelper 模組提供一組用於清除文字中不需要的 HTML 元素的方法。

1.11.1 sanitize

這個 sanitize 輔助工具將 HTML 編碼所有標籤，並移除所有未特別允許的屬性。

sanitize @article.body

如果傳遞了 :attributes 或 :tags 選項，則僅允許指定的屬性和標籤，其他都不允許。

sanitize @article.body, tags: %w(table tr td), attributes: %w(id class style)

若要變更多重使用的預設值，例如將表格標籤新增至預設值

class Application < Rails::Application
  config.action_view.sanitized_allowed_tags = 'table', 'tr', 'td'
end

1.11.2 sanitize_css(style)

清除一區塊的 CSS 程式碼。

1.11.3 strip_links(html)

從文字中移除所有連結標籤，僅保留連結文字。

strip_links('<a href="https://rubyonrails.org">Ruby on Rails</a>')
# => Ruby on Rails

strip_links('emails to <a href="mailto:[email protected]">[email protected]</a>.')
# => emails to [email protected].

strip_links('Blog: <a href="http://myblog.com/">Visit</a>.')
# => Blog: Visit.

1.11.4 strip_tags(html)

從 html 中移除所有 HTML 標籤，包括註解。此功能由 rails-html-sanitizer 這個 gem 提供。

strip_tags("Strip <i>these</i> tags!")
# => Strip these tags!

strip_tags("<b>Bold</b> no more!  <a href='more.html'>See more</a>")
# => Bold no more!  See more

注意：輸出可能仍包含未跳脫的「<」、「>」、「&」字元，並混淆瀏覽器。

1.12 UrlHelper

提供建立連結和取得 URL 的方法，這些方法取決於路由子系統。

1.12.1 url_for

傳回提供之 options 設定的 URL。

1.12.1.1 範例

url_for @profile
# => /profiles/1

url_for [ @hotel, @booking, page: 2, line: 3 ]
# => /hotels/1/bookings/1?line=3&page=2

url_for @post # given a composite primary key [:blog_id, :id]
# => /posts/1_2

1.12.2 link_to

連結到從 url_for 衍生的 URL，在底層主要用於建立 RESTful 資源連結，在此範例中，簡化為將模型傳遞給 link_to 的情況。

範例

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

link_to "Book", @book # given a composite primary key [:author_id, :id]
# => <a href="/books/2_1">Book</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>

請參閱 API 文件，以取得更多資訊

1.12.3 button_to

產生一個表單，提交至傳遞的 URL。表單有一個提交按鈕，其值為 name。

1.12.3.1 範例

<%= button_to "Sign in", sign_in_path %>

大約會輸出類似

<form method="post" action="/sessions" class="button_to">
  <input type="submit" value="Sign in" />
</form>

請參閱 API 文件，以取得更多資訊

1.13 CsrfHelper

傳回 meta 標籤「csrf-param」和「csrf-token」，分別包含跨網站請求偽造防護參數和令牌的名稱。

<%= csrf_meta_tags %>

一般表單會產生隱藏欄位，因此不會使用這些標籤。更多詳細資料可以在 Rails 安全指南中找到。

意見回饋

我們鼓勵您協助提升本指南的品質。

如果您發現任何錯字或事實錯誤，請協助我們修正。首先，您可以閱讀我們的文件貢獻區段。

您也可能會發現不完整或過時的內容。請務必為 main 新增任何遺漏的文件。請先查看 Edge Guides，確認問題是否已在 main 分支中修正。查看 Ruby on Rails 指南指南，了解風格和慣例。

如果您發現需要修正的地方，但無法自行修補，請開啟問題。

最後，我們非常歡迎在官方 Ruby on Rails 論壇中針對 Ruby on Rails 文件進行任何討論。

Action View 輔助工具

章節

意見回饋