Guides.rubyonrails.org

Chapters

1. 概览：各组件之间的协作
2. 创建响应
   • 渲染视图
   • 使用 render 方法
   • 使用 redirect_to 方法
   • 使用 head 构建只返回报头的响应
3. 布局结构
   • 静态资源标签帮助方法
   • 理解 yield
   • 使用 content_for 方法
   • 使用局部视图
   • 使用嵌套布局

1 概览：各组件之间的协作

本文关注 MVC 架构中控制器和视图之间的交互。你可能已经知道，控制器的作用是处理请求，但经常会把繁重的操作交给模型完成。返回响应时，控制器会把一些操作交给视图完成。本文要说明的就是控制器交给视图的操作是怎么完成的。

总的来说，这个过程涉及到响应中要发送什么内容，以及调用哪个方法创建响应。如果响应是个完整的视图，Rails 还要做些额外工作，把视图套入布局，有时还要渲染局部视图。后文会详细介绍整个过程。

2 创建响应

从控制器的角度来看，创建 HTTP 响应有三种方法：

• 调用 render 方法，向浏览器发送一个完整的响应；
• 调用 redirect_to 方法，向浏览器发送一个 HTTP 重定向状态码；
• 调用 head 方法，向浏览器发送只含报头的响应；

2.1 渲染视图

你可能已经听说过 Rails 的开发原则之一是“多约定，少配置”。默认渲染视图的处理就是这一原则的完美体现。默认情况下，Rails 中的控制器会渲染路由对应的视图。例如，有如下的 BooksController 代码：

class BooksController < ApplicationController
end

在路由文件中有如下定义：

resources :books

而且有个名为 app/views/books/index.html.erb 的视图文件：

<h1>Books are coming soon!</h1>

那么，访问 /books 时，Rails 会自动渲染视图 app/views/books/index.html.erb，网页中会看到显示有“Books are coming soon!”。

网页中显示这些文字没什么用，所以后续你可能会创建一个 Book 模型，然后在 BooksController 中添加 index 动作：

class BooksController < ApplicationController
  def index
    @books = Book.all
  end
end

注意，基于“多约定，少配置”原则，在 index 动作末尾并没有指定要渲染视图，Rails 会自动在控制器的视图文件夹中寻找 action_name.html.erb 模板，然后渲染。在这个例子中，Rails 渲染的是 app/views/books/index.html.erb 文件。

如果要在视图中显示书籍的属性，可以使用 ERB 模板：

<h1>Listing Books</h1>

<table>
  <tr>
    <th>Title</th>
    <th>Summary</th>
    <th></th>
    <th></th>
    <th></th>
  </tr>

<% @books.each do |book| %>
  <tr>
    <td><%= book.title %></td>
    <td><%= book.content %></td>
    <td><%= link_to "Show", book %></td>
    <td><%= link_to "Edit", edit_book_path(book) %></td>
    <td><%= link_to "Remove", book, method: :delete, data: { confirm: "Are you sure?" } %></td>
  </tr>
<% end %>
</table>

<br>

<%= link_to "New book", new_book_path %>

2.2 使用 render 方法

大多数情况下，ActionController::Base#render 方法都能满足需求，而且还有多种定制方式，可以渲染 Rails 模板的默认视图、指定的模板、文件、行间代码或者什么也不渲染。渲染的内容格式可以是文本，JSON 或 XML。而且还可以设置响应的内容类型和 HTTP 状态码。

2.2.1 什么都不渲染

或许 render 方法最简单的用法是什么也不渲染：

render nothing: true

如果使用 cURL 查看请求，会得到一些输出：

$ curl -i 127.0.0.1:3000/books
HTTP/1.1 200 OK
Connection: close
Date: Sun, 24 Jan 2010 09:25:18 GMT
Transfer-Encoding: chunked
Content-Type: */*; charset=utf-8
X-Runtime: 0.014297
Set-Cookie: _blog_session=...snip...; path=/; HttpOnly
Cache-Control: no-cache

$

可以看到，响应的主体是空的（Cache-Control 之后没有数据），但请求本身是成功的，因为 Rails 把响应码设为了“200 OK”。调用 render 方法时可以设置 :status 选项修改状态码。这种用法可在 Ajax 请求中使用，因为此时只需告知浏览器请求已经完成。

2.2.2 渲染动作的视图

如果想渲染同个控制器中的其他模板，可以把视图的名字传递给 render 方法：

def update
  @book = Book.find(params[:id])
  if @book.update(book_params)
    redirect_to(@book)
  else
    render "edit"
  end
end

如果更新失败，会渲染同个控制器中的 edit.html.erb 模板。

如果不想用字符串，还可使用 Symbol 指定要渲染的动作：

def update
  @book = Book.find(params[:id])
  if @book.update(book_params)
    redirect_to(@book)
  else
    render :edit
  end
end

2.2.3 渲染其他控制器中的动作模板

如果想渲染其他控制器中的模板该怎么做呢？还是使用 render 方法，指定模板的完整路径即可。例如，如果控制器 AdminProductsController 在 app/controllers/admin 文件夹中，可使用下面的方式渲染 app/views/products 文件夹中的模板：

render "products/show"

因为参数中有个斜线，所以 Rails 知道这个视图属于另一个控制器。如果想让代码的意图更明显，可以使用 :template 选项（Rails 2.2 及先前版本必须这么做）：

render template: "products/show"

2.2.4 渲染任意文件

render 方法还可渲染程序之外的视图（或许多个程序共用一套视图）：

render "/u/apps/warehouse_app/current/app/views/products/show"

因为参数以斜线开头，所以 Rails 将其视为一个文件。如果想让代码的意图更明显，可以使用 :file 选项（Rails 2.2+ 必须这么做）

render file: "/u/apps/warehouse_app/current/app/views/products/show"

:file 选项的值是文件系统中的绝对路径。当然，你要对使用的文件拥有相应权限。

2.2.5 小结

上述三种渲染方式的作用其实是一样的。在 BooksController 控制器的 update 动作中，如果更新失败后想渲染 views/books 文件夹中的 edit.html.erb 模板，下面这些用法都能达到这个目的：

render :edit
render action: :edit
render "edit"
render "edit.html.erb"
render action: "edit"
render action: "edit.html.erb"
render "books/edit"
render "books/edit.html.erb"
render template: "books/edit"
render template: "books/edit.html.erb"
render "/path/to/rails/app/views/books/edit"
render "/path/to/rails/app/views/books/edit.html.erb"
render file: "/path/to/rails/app/views/books/edit"
render file: "/path/to/rails/app/views/books/edit.html.erb"

你可以根据自己的喜好决定使用哪种方式，总的原则是，使用符合代码意图的最简单方式。

2.2.6 使用 render 方法的 :inline 选项

如果使用 :inline 选项指定了 ERB 代码，render 方法就不会渲染视图。如下所示的用法完全可行：

render inline: "<% products.each do |p| %><p><%= p.name %></p><% end %>"

默认情况下，行间渲染使用 ERB 模板。你可以使用 :type 选项指定使用其他处理程序：

render inline: "xml.p {'Horrid coding practice!'}", type: :builder

2.2.7 渲染文本

调用 render 方法时指定 :plain 选项，可以把没有标记语言的纯文本发给浏览器：

render plain: "OK"

2.2.8 渲染 HTML

调用 render 方法时指定 :html 选项，可以把 HTML 字符串发给浏览器：

render html: "<strong>Not Found</strong>".html_safe

2.2.9 渲染 JSON

JSON 是一种 JavaScript 数据格式，很多 Ajax 库都用这种格式。Rails 内建支持把对象转换成 JSON，经渲染后再发送给浏览器。

render json: @product

2.2.10 渲染 XML

Rails 也内建支持把对象转换成 XML，经渲染后再发回给调用者：

render xml: @product

2.2.11 渲染普通的 JavaScript

Rails 能渲染普通的 JavaScript：

render js: "alert('Hello Rails');"

这种方法会把 MIME 设为 text/javascript，再把指定的字符串发给浏览器。

2.2.12 渲染原始的主体

调用 render 方法时使用 :body 选项，可以不设置内容类型，把原始的内容发送给浏览器：

render body: "raw"

2.2.13 render 方法的选项

render 方法一般可接受四个选项：

• :content_type
• :layout
• :location
• :status

2.2.13.1 :content_type 选项

默认情况下，Rails 渲染得到的结果内容类型为 text/html；如果使用 :json 选项，内容类型为 application/json；如果使用 :xml 选项，内容类型为 application/xml。如果需要修改内容类型，可使用 :content_type 选项

render file: filename, content_type: "application/rss"

2.2.13.2 :layout 选项

render 方法的大多数选项渲染得到的结果都会作为当前布局的一部分显示。后文会详细介绍布局。

:layout 选项告知 Rails，在当前动作中使用指定的文件作为布局：

render layout: "special_layout"

也可以告知 Rails 不使用布局：

render layout: false

2.2.13.3 :location 选项

:location 选项可以设置 HTTP Location 报头：

render xml: photo, location: photo_url(photo)

2.2.13.4 :status 选项

Rails 会自动为生成的响应附加正确的 HTTP 状态码（大多数情况下是 200 OK）。使用 :status 选项可以修改状态码：

render status: 500
render status: :forbidden

Rails 能理解数字状态码和对应的符号，如下所示：

2.2.14 查找布局

查找布局时，Rails 首先查看 app/views/layouts 文件夹中是否有和控制器同名的文件。例如，渲染 PhotosController 控制器中的动作会使用 app/views/layouts/photos.html.erb（或 app/views/layouts/photos.builder）。如果没找到针对控制器的布局，Rails 会使用 app/views/layouts/application.html.erb 或 app/views/layouts/application.builder。如果没有 .erb 布局，Rails 会使用 .builder 布局（如果文件存在）。Rails 还提供了多种方法用来指定单个控制器和动作使用的布局。

2.2.14.1 指定控制器所用布局

在控制器中使用 layout 方法，可以改写默认使用的布局约定。例如：

class ProductsController < ApplicationController
  layout "inventory"
  #...
end

这么声明之后，ProductsController 渲染的所有视图都将使用 app/views/layouts/inventory.html.erb 文件作为布局。

要想指定整个程序使用的布局，可以在 ApplicationController 类中使用 layout 方法：

class ApplicationController < ActionController::Base
  layout "main"
  #...
end

这么声明之后，整个程序的视图都会使用 app/views/layouts/main.html.erb 文件作为布局。

2.2.14.2 运行时选择布局

可以使用一个 Symbol，在处理请求时选择布局：

class ProductsController < ApplicationController
  layout :products_layout

  def show
    @product = Product.find(params[:id])
  end

  private
    def products_layout
      @current_user.special? ? "special" : "products"
    end

end

如果当前用户是特殊用户，会使用一个特殊布局渲染产品视图。

还可使用行间方法，例如 Proc，决定使用哪个布局。如果使用 Proc，其代码块可以访问 controller 实例，这样就能根据当前请求决定使用哪个布局：

class ProductsController < ApplicationController
  layout Proc.new { |controller| controller.request.xhr? ? "popup" : "application" }
end

2.2.14.3 条件布局

在控制器中指定布局时可以使用 :only 和 :except 选项。这两个选项的值可以是一个方法名或者一个方法名数组，这些方法都是控制器中的动作：

class ProductsController < ApplicationController
  layout "product", except: [:index, :rss]
end

这么声明后，除了 rss 和 index 动作之外，其他动作都使用 product 布局渲染视图。

2.2.14.4 布局继承

布局声明按层级顺序向下顺延，专用布局比通用布局优先级高。例如：

• application_controller.rb

class ApplicationController < ActionController::Base
  layout "main"
end

• posts_controller.rb

class PostsController < ApplicationController
end

• special_posts_controller.rb

class SpecialPostsController < PostsController
  layout "special"
end

• old_posts_controller.rb

class OldPostsController < SpecialPostsController
  layout false

  def show
    @post = Post.find(params[:id])
  end

  def index
    @old_posts = Post.older
    render layout: "old"
  end
  # ...
end

在这个程序中：

• 一般情况下，视图使用 main 布局渲染；
• PostsController#index 使用 main 布局；
• SpecialPostsController#index 使用 special 布局；
• OldPostsController#show 不用布局；
• OldPostsController#index 使用 old 布局；

2.2.15 避免双重渲染错误

大多数 Rails 开发者迟早都会看到一个错误消息：Can only render or redirect once per action（动作只能渲染或重定向一次）。这个提示很烦人，也很容易修正。出现这个错误的原因是，没有理解 render 的工作原理。

例如，下面的代码会导致这个错误：

def show
  @book = Book.find(params[:id])
  if @book.special?
    render action: "special_show"
  end
  render action: "regular_show"
end

如果 @book.special? 的结果是 true，Rails 开始渲染，把 @book 变量导入 special_show 视图中。但是，show 动作并不会就此停止运行，当 Rails 运行到动作的末尾时，会渲染 regular_show 视图，导致错误出现。解决的办法很简单，确保在一次代码运行路线中只调用一次 render 或 redirect_to 方法。有一个语句可以提供帮助，那就是 and return。下面的代码对上述代码做了修改：

def show
  @book = Book.find(params[:id])
  if @book.special?
    render action: "special_show" and return
  end
  render action: "regular_show"
end

千万别用 && return 代替 and return，因为 Ruby 语言操作符优先级的关系，&& return 根本不起作用。

注意，ActionController 能检测到是否显式调用了 render 方法，所以下面这段代码不会出错：

def show
  @book = Book.find(params[:id])
  if @book.special?
    render action: "special_show"
  end
end

如果 @book.special? 的结果是 true，会渲染 special_show 视图，否则就渲染默认的 show 模板。

2.3 使用 redirect_to 方法

响应 HTTP 请求的另一种方法是使用 redirect_to。如前所述，render 告诉 Rails 构建响应时使用哪个视图（以及其他静态资源）。redirect_to 做的事情则完全不同：告诉浏览器向另一个地址发起新请求。例如，在程序中的任何地方使用下面的代码都可以重定向到 photos 控制器的 index 动作：

redirect_to photos_url

redirect_to 方法的参数与 link_to 和 url_for 一样。有个特殊的重定向，返回到前一个页面：

redirect_to :back

2.3.1 设置不同的重定向状态码

调用 redirect_to 方法时，Rails 会把 HTTP 状态码设为 302，即临时重定向。如果想使用其他的状态码，例如 301（永久重定向），可以设置 :status 选项：

redirect_to photos_path, status: 301

和 render 方法的 :status 选项一样，redirect_to 方法的 :status 选项同样可使用数字状态码或符号。

2.3.2 render 和 redirect_to 的区别

有些经验不足的开发者会认为 redirect_to 方法是一种 goto 命令，把代码从一处转到别处。这么理解是不对的。执行到 redirect_to 方法时，代码会停止运行，等待浏览器发起新请求。你需要告诉浏览器下一个请求是什么，并返回 302 状态码。

下面通过实例说明。

def index
  @books = Book.all
end

def show
  @book = Book.find_by(id: params[:id])
  if @book.nil?
    render action: "index"
  end
end

在这段代码中，如果 @book 变量的值为 nil 很可能会出问题。记住，render :action 不会执行目标动作中的任何代码，因此不会创建 index 视图所需的 @books 变量。修正方法之一是不渲染，使用重定向：

def index
  @books = Book.all
end

def show
  @book = Book.find_by(id: params[:id])
  if @book.nil?
    redirect_to action: :index
  end
end

这样修改之后，浏览器会向 index 动作发起新请求，执行 index 方法中的代码，一切都能正常运行。

这种方法有个缺点，增加了浏览器的工作量。浏览器通过 /books/1 向 show 动作发起请求，控制器做了查询，但没有找到对应的图书，所以返回 302 重定向响应，告诉浏览器访问 /books/。浏览器收到指令后，向控制器的 index 动作发起新请求，控制器从数据库中取出所有图书，渲染 index 模板，将其返回浏览器，在屏幕上显示所有图书。

在小型程序中，额外增加的时间不是个问题。如果响应时间很重要，这个问题就值得关注了。下面举个虚拟的例子演示如何解决这个问题：

def index
  @books = Book.all
end

def show
  @book = Book.find_by(id: params[:id])
  if @book.nil?
    @books = Book.all
    flash.now[:alert] = "Your book was not found"
    render "index"
  end
end

在这段代码中，如果指定 ID 的图书不存在，会从模型中取出所有图书，赋值给 @books 实例变量，然后直接渲染 index.html.erb 模板，并显示一个 Flash 消息，告知用户出了什么问题。

2.4 使用 head 构建只返回报头的响应

head 方法可以只把报头发送给浏览器。还可使用意图更明确的 render :nothing 达到同样的目的。head 方法的参数是 HTTP 状态码的符号形式（参见前文表格），选项是一个 Hash，指定报头名和对应的值。例如，可以只返回报错的报头：

head :bad_request

生成的报头如下：

HTTP/1.1 400 Bad Request
Connection: close
Date: Sun, 24 Jan 2010 12:15:53 GMT
Transfer-Encoding: chunked
Content-Type: text/html; charset=utf-8
X-Runtime: 0.013483
Set-Cookie: _blog_session=...snip...; path=/; HttpOnly
Cache-Control: no-cache

或者使用其他 HTTP 报头提供其他信息：

head :created, location: photo_path(@photo)

生成的报头如下：

HTTP/1.1 201 Created
Connection: close
Date: Sun, 24 Jan 2010 12:16:44 GMT
Transfer-Encoding: chunked
Location: /photos/1
Content-Type: text/html; charset=utf-8
X-Runtime: 0.083496
Set-Cookie: _blog_session=...snip...; path=/; HttpOnly
Cache-Control: no-cache

3 布局结构

Rails 渲染响应的视图时，会把视图和当前模板结合起来。查找当前模板的方法前文已经介绍过。在布局中可以使用三种工具把各部分合在一起组成完整的响应：

• 静态资源标签
• yield 和 content_for
• 局部视图

3.1 静态资源标签帮助方法

静态资源帮助方法用来生成链接到 Feed、JavaScript、样式表、图片、视频和音频的 HTML 代码。Rails 提供了六个静态资源标签帮助方法：

• auto_discovery_link_tag
• javascript_include_tag
• stylesheet_link_tag
• image_tag
• video_tag
• audio_tag

这六个帮助方法可以在布局或视图中使用，不过 auto_discovery_link_tag、javascript_include_tag 和 stylesheet_link_tag 最常出现在布局的 <head> 中。

3.1.1 使用 auto_discovery_link_tag 链接到 Feed

auto_discovery_link_tag 帮助方法生成的 HTML，大多数浏览器和 Feed 阅读器都能用来自动识别 RSS 或 Atom Feed。auto_discovery_link_tag 接受的参数包括链接的类型（:rss 或 :atom），传递给 url_for 的 Hash 选项，以及该标签使用的 Hash 选项：

<%= auto_discovery_link_tag(:rss, {action: "feed"},
  {title: "RSS Feed"}) %>

auto_discovery_link_tag 的标签选项有三个：

• :rel：指定链接 rel 属性的值，默认值为 "alternate"；
• :type：指定 MIME 类型，不过 Rails 会自动生成正确的 MIME 类型；
• :title：指定链接的标题，默认值是 :type 参数值的全大写形式，例如 "ATOM" 或 "RSS"；

3.1.2 使用 javascript_include_tag 链接 JavaScript 文件

javascript_include_tag 帮助方法为指定的每个资源生成 HTML script 标签。

如果启用了 Asset Pipeline，这个帮助方法生成的链接指向 /assets/javascripts/ 而不是 Rails 旧版中使用的 public/javascripts。链接的地址由 Asset Pipeline 伺服。

Rails 程序或引擎中的 JavaScript 文件可存放在三个位置：app/assets，lib/assets 或 vendor/assets。详细说明参见 Asset Pipeline 中的“静态资源的组织方式”一节。

文件的地址可使用相对文档根目录的完整路径，或者是 URL。例如，如果想链接到 app/assets、lib/assets 或 vendor/assets 文件夹中名为 javascripts 的子文件夹中的文件，可以这么做：

<%= javascript_include_tag "main" %>

Rails 生成的 script 标签如下：

<script src='/assets/main.js'></script>

对这个静态资源的请求由 Sprockets gem 伺服。

同时引入 app/assets/javascripts/main.js 和 app/assets/javascripts/columns.js 可以这么做：

<%= javascript_include_tag "main", "columns" %>

引入 app/assets/javascripts/main.js 和 app/assets/javascripts/photos/columns.js：

<%= javascript_include_tag "main", "/photos/columns" %>

引入 http://example.com/main.js：

<%= javascript_include_tag "http://example.com/main.js" %>

3.1.3 使用 stylesheet_link_tag 链接 CSS 文件

stylesheet_link_tag 帮助方法为指定的每个资源生成 HTML <link> 标签。

如果启用了 Asset Pipeline，这个帮助方法生成的链接指向 /assets/stylesheets/，由 Sprockets gem 伺服。样式表文件可以存放在三个位置：app/assets，lib/assets 或 vendor/assets。

文件的地址可使用相对文档根目录的完整路径，或者是 URL。例如，如果想链接到 app/assets、lib/assets 或 vendor/assets 文件夹中名为 stylesheets 的子文件夹中的文件，可以这么做：

<%= stylesheet_link_tag "main" %>

引入 app/assets/stylesheets/main.css 和 app/assets/stylesheets/columns.css：

<%= stylesheet_link_tag "main", "columns" %>

引入 app/assets/stylesheets/main.css 和 app/assets/stylesheets/photos/columns.css：

<%= stylesheet_link_tag "main", "photos/columns" %>

引入 http://example.com/main.css：

<%= stylesheet_link_tag "http://example.com/main.css" %>

默认情况下，stylesheet_link_tag 创建的链接属性为 media="screen" rel="stylesheet"。指定相应的选项（:media，:rel）可以重写默认值：

<%= stylesheet_link_tag "main_print", media: "print" %>

3.1.4 使用 image_tag 链接图片

image_tag 帮助方法为指定的文件生成 HTML <img /> 标签。默认情况下，文件存放在 public/images 文件夹中。

<%= image_tag "header.png" %>

可以指定图片的路径：

<%= image_tag "icons/delete.gif" %>

可以使用 Hash 指定额外的 HTML 属性：

<%= image_tag "icons/delete.gif", {height: 45} %>

可以指定一个Alt属性，在关闭图片的浏览器中显示。如果没指定Alt属性，Rails 会使用图片的文件名，去掉扩展名，并把首字母变成大写。例如，下面两个标签会生成相同的代码：

<%= image_tag "home.gif" %>
<%= image_tag "home.gif", alt: "Home" %>

还可指定图片的大小，格式为“{width}x{height}”：

<%= image_tag "home.gif", size: "50x20" %>

除了上述特殊的选项外，还可在最后一个参数中指定标准的 HTML 属性，例如 :class、:id 或 :name：

<%= image_tag "home.gif", alt: "Go Home",
                          id: "HomeImage",
                          class: "nav_bar" %>

3.1.5 使用 video_tag 链接视频

video_tag 帮助方法为指定的文件生成 HTML5 <video> 标签。默认情况下，视频文件存放在 public/videos 文件夹中。

<%= video_tag "movie.ogg" %>

生成的代码如下：

<video src="/videos/movie.ogg" />

和 image_tag 类似，视频的地址可以使用绝对路径，或者相对 public/videos 文件夹的路径。而且也可以指定 size: "#{width}x#{height}" 选项。video_tag 还可指定其他 HTML 属性，例如 id、class 等。

video_tag 方法还可使用 HTML Hash 选项指定所有 <video> 标签的属性，包括：

• poster: "image_name.png"：指定视频播放前在视频的位置显示的图片；
• autoplay: true：页面加载后开始播放视频；
• loop: true：视频播完后再次播放；
• controls: true：为用户提供浏览器对视频的控制支持，用于和视频交互；
• autobuffer: true：页面加载时预先加载视频文件；

把数组传递给 video_tag 方法可以指定多个视频：

<%= video_tag ["trailer.ogg", "movie.ogg"] %>

生成的代码如下：

<video><source src="trailer.ogg" /><source src="movie.ogg" /></video>

3.1.6 使用 audio_tag 链接音频

audio_tag 帮助方法为指定的文件生成 HTML5 <audio> 标签。默认情况下，音频文件存放在 public/audio 文件夹中。

<%= audio_tag "music.mp3" %>

还可指定音频文件的路径：

<%= audio_tag "music/first_song.mp3" %>

还可使用 Hash 指定其他属性，例如 :id、:class 等。

和 video_tag 类似，audio_tag 也有特殊的选项：

• autoplay: true：页面加载后开始播放音频；
• controls: true：为用户提供浏览器对音频的控制支持，用于和音频交互；
• autobuffer: true：页面加载时预先加载音频文件；

3.2 理解 yield

在布局中，yield 标明一个区域，渲染的视图会插入这里。最简单的情况是只有一个 yield，此时渲染的整个视图都会插入这个区域：

<html>
  <head>
  </head>
  <body>
  <%= yield %>
  </body>
</html>

布局中可以标明多个区域：

<html>
  <head>
  <%= yield :head %>
  </head>
  <body>
  <%= yield %>
  </body>
</html>

视图的主体会插入未命名的 yield 区域。要想在具名 yield 区域插入内容，得使用 content_for 方法。

3.3 使用 content_for 方法

content_for 方法在布局的具名 yield 区域插入内容。例如，下面的视图会在前一节的布局中插入内容：

<% content_for :head do %>
  <title>A simple page</title>
<% end %>

<p>Hello, Rails!</p>

套入布局后生成的 HTML 如下：

<html>
  <head>
  <title>A simple page</title>
  </head>
  <body>
  <p>Hello, Rails!</p>
  </body>
</html>

如果布局不同的区域需要不同的内容，例如侧边栏和底部，就可以使用 content_for 方法。content_for 方法还可用来在通用布局中引入特定页面使用的 JavaScript 文件或 CSS 文件。

3.4 使用局部视图

局部视图可以把渲染过程分为多个管理方便的片段，把响应的某个特殊部分移入单独的文件。

3.4.1 具名局部视图

在视图中渲染局部视图可以使用 render 方法：

<%= render "menu" %>

渲染这个视图时，会渲染名为 _menu.html.erb 的文件。注意文件名开头的下划线：局部视图的文件名开头有个下划线，用于和普通视图区分开，不过引用时无需加入下划线。即便从其他文件夹中引入局部视图，规则也是一样：

<%= render "shared/menu" %>

这行代码会引入 app/views/shared/_menu.html.erb 这个局部视图。

3.4.2 使用局部视图简化视图

局部视图的一种用法是作为“子程序”（subroutine），把细节提取出来，以便更好地理解整个视图的作用。例如，有如下的视图：

<%= render "shared/ad_banner" %>

<h1>Products</h1>

<p>Here are a few of our fine products:</p>
...

<%= render "shared/footer" %>

这里，局部视图 _ad_banner.html.erb 和 _footer.html.erb 可以包含程序多个页面共用的内容。在编写某个页面的视图时，无需关心这些局部视图中的详细内容。

3.4.3 局部布局

和视图可以使用布局一样，局部视图也可使用自己的布局文件。例如，可以这样调用局部视图：

<%= render partial: "link_area", layout: "graybar" %>

这行代码会使用 _graybar.html.erb 布局渲染局部视图 _link_area.html.erb。注意，局部布局的名字也以下划线开头，和局部视图保存在同个文件夹中（不在 layouts 文件夹中）。

还要注意，指定其他选项时，例如 :layout，必须明确地使用 :partial 选项。

3.4.4 传递本地变量

本地变量可以传入局部视图，这么做可以把局部视图变得更强大、更灵活。例如，可以使用这种方法去除新建和编辑页面的重复代码，但仍然保有不同的内容：

<h1>New zone</h1>
<%= render partial: "form", locals: {zone: @zone} %>

<h1>Editing zone</h1>
<%= render partial: "form", locals: {zone: @zone} %>

<%= form_for(zone) do |f| %>
  <p>
    <b>Zone name</b><br>
    <%= f.text_field :name %>
  </p>
  <p>
    <%= f.submit %>
  </p>
<% end %>

虽然两个视图使用同一个局部视图，但 Action View 的 submit 帮助方法为 new 动作生成的提交按钮名为“Create Zone”，为 edit 动作生成的提交按钮名为“Update Zone”。

每个局部视图中都有个和局部视图同名的本地变量（去掉前面的下划线）。通过 object 选项可以把对象传给这个变量：

<%= render partial: "customer", object: @new_customer %>

在 customer 局部视图中，变量 customer 的值为父级视图中的 @new_customer。

如果要在局部视图中渲染模型实例，可以使用简写句法：

<%= render @customer %>

假设实例变量 @customer 的值为 Customer 模型的实例，上述代码会渲染 _customer.html.erb，其中本地变量 customer 的值为父级视图中 @customer 实例变量的值。

3.4.5 渲染集合

渲染集合时使用局部视图特别方便。通过 :collection 选项把集合传给局部视图时，会把集合中每个元素套入局部视图渲染：

<h1>Products</h1>
<%= render partial: "product", collection: @products %>

<p>Product Name: <%= product.name %></p>

传入复数形式的集合时，在局部视图中可以使用和局部视图同名的变量引用集合中的成员。在上面的代码中，局部视图是 _product，在其中可以使用 product 引用渲染的实例。

渲染集合还有个简写形式。假设 @products 是 product 实例集合，在 index.html.erb 中可以直接写成下面的形式，得到的结果是一样的：

<h1>Products</h1>
<%= render @products %>

Rails 根据集合中各元素的模型名决定使用哪个局部视图。其实，集合中的元素可以来自不同的模型，Rails 会选择正确的局部视图进行渲染。

<h1>Contacts</h1>
<%= render [customer1, employee1, customer2, employee2] %>

<p>Customer: <%= customer.name %></p>

<p>Employee: <%= employee.name %></p>

在上面几段代码中，Rails 会根据集合中各成员所属的模型选择正确的局部视图。

如果集合为空，render 方法会返回 nil，所以最好提供替代文本。

<h1>Products</h1>
<%= render(@products) || "There are no products available." %>

3.4.6 本地变量

要在局部视图中自定义本地变量的名字，调用局部视图时可通过 :as 选项指定：

<%= render partial: "product", collection: @products, as: :item %>

这样修改之后，在局部视图中可以使用本地变量 item 访问 @products 集合中的实例。

使用 locals: {} 选项可以把任意本地变量传入局部视图：

<%= render partial: "product", collection: @products,
           as: :item, locals: {title: "Products Page"} %>

在局部视图中可以使用本地变量 title，其值为 "Products Page"。

在使用主局部视图渲染两个实例中间还可使用 :spacer_template 选项指定第二个局部视图。

3.4.7 间隔模板

<%= render partial: @products, spacer_template: "product_ruler" %>

Rails 会在两次渲染 _product 局部视图之间渲染 _product_ruler 局部视图（不传入任何数据）。

3.4.8 集合局部视图的布局

渲染集合时也可使用 :layout 选项。

<%= render partial: "product", collection: @products, layout: "special_layout" %>

使用局部视图渲染集合中的各元素时会套用指定的模板。和局部视图一样，当前渲染的对象以及 object_counter 变量也可在布局中使用。

3.5 使用嵌套布局

在程序中有时需要使用不同于常规布局的布局渲染特定的控制器。此时无需复制主视图进行编辑，可以使用嵌套布局（有时也叫子模板）。下面举个例子。

假设 ApplicationController 布局如下：

<html>
<head>
  <title><%= @page_title or "Page Title" %></title>
  <%= stylesheet_link_tag "layout" %>
  <style><%= yield :stylesheets %></style>
</head>
<body>
  <div id="top_menu">Top menu items here</div>
  <div id="menu">Menu items here</div>
  <div id="content"><%= content_for?(:content) ? yield(:content) : yield %></div>
</body>
</html>

在 NewsController 的页面中，想隐藏顶部目录，在右侧添加一个目录：

<% content_for :stylesheets do %>
  #top_menu {display: none}
  #right_menu {float: right; background-color: yellow; color: black}
<% end %>
<% content_for :content do %>
  <div id="right_menu">Right menu items here</div>
  <%= content_for?(:news_content) ? yield(:news_content) : yield %>
<% end %>
<%= render template: "layouts/application" %>

就这么简单。News 控制器的视图会使用 news.html.erb 布局，隐藏了顶部目录，在 <div id="content"> 中添加一个右侧目录。

使用子模板方式实现这种效果有很多方法。注意，布局的嵌套层级没有限制。使用 render template: 'layouts/news' 可以指定使用一个新布局。如果确定，可以不为 News 控制器创建子模板，直接把 content_for?(:news_content) ? yield(:news_content) : yield 替换成 yield 即可。

反馈

欢迎帮忙改善指南质量。

如发现任何错误，欢迎修正。开始贡献前，可先行阅读贡献指南：文档。

翻译如有错误，深感抱歉，欢迎 Fork 修正，或至此处回报。

文章可能有未完成或过时的内容。请先检查 Edge Guides 来确定问题在 master 是否已经修掉了。再上 master 补上缺少的文件。内容参考 Ruby on Rails 指南准则来了解行文风格。

最后，任何关于 Ruby on Rails 文档的讨论，欢迎到 rubyonrails-docs 邮件群组。