Rails 7中Turbo Stream仅渲染局部视图问题排查与修复求助

在Rails 7应用中使用turbo-rails时遇到以下问题：

• 已安装最新版turbo-rails
• 页面包含一个包裹在表单内的筛选下拉框，下方用局部视图展示用户数据
• 提交筛选表单后，页面仅显示符合条件的局部视图，其余内容全部消失
• Chrome开发者工具显示请求头为：

  text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
  

需要改用Turbo Stream实现页面多元素更新，想知道问题原因及修复方法。

相关代码如下：

表单HTML #

<div class="users">
    <div class="filters">
        <%= form_with url: '/users/load', method: :get, data: { turbo_frame: :form_response } do |form| %>
            <%= render partial: "shared/select", locals: {
                placeholder: 'Gender', 
                width: '90px', 
                options: @genders,
                classes: 'filter',
                name: 'gender',
            } %>
            <%= form.submit %>
        <% end %>
    </div>

    <%= turbo_frame_tag :form_response do %>
        <%= render partial: "users/user_list", locals: {
            users: @users
        } %>
    <% end %>
</div>

路由配置 #

get '/users' => "users#index"
get '/users/load' => "users#load"

控制器代码 #

class UsersController < ApplicationController

    before_action :require_user

    USERS_PER_PAGE = 15

    def index
        @genders = ["Male", "Female"]
        @users = User
                            .limit(USERS_PER_PAGE)
                            .order(:creation_date).reverse_order
    end

    def load
        @users = User
                            .limit(USERS_PER_PAGE)
                            .order(:creation_date).reverse_order
                            
        if params[:gender]
            @users = @users.where(gender: params[:gender])
        end

        respond_to do |format|
            format.html { render partial: 'users/user_list', locals: { users: @users } }
        end
    end
end

1. Turbo Frame匹配失败：表单指定了data: { turbo_frame: :form_response }，期望响应内容包裹在turbo_frame_tag :form_response中，但控制器load方法仅返回了user_list局部视图，没有包含对应的Turbo Frame标签。Turbo无法找到目标Frame时，会直接用响应内容替换整个页面。
2. 未启用Turbo Stream响应：当前控制器只处理了format.html，没有返回Turbo Stream格式的响应，无法实现多元素更新的需求。

方案一：修复Turbo Frame模式（单元素更新） #

修改load方法，让响应内容包裹在目标Turbo Frame中：

def load
    @users = User.limit(USERS_PER_PAGE).order(creation_date: :desc)
    @users = @users.where(gender: params[:gender]) if params[:gender]

    respond_to do |format|
        format.html do
            render turbo_frame_tag(:form_response) do
                render partial: 'users/user_list', locals: { users: @users }
            end
        end
    end
end

这样Turbo会找到页面中的:form_response Frame，仅更新该区域内容，不会替换整个页面。

方案二：改用Turbo Stream实现多元素更新 #

如果需要同时更新页面多个元素，按以下步骤修改：

1. 修改表单，移除data-turbo-frame，明确指定Turbo Stream请求 #

<%= form_with url: '/users/load', method: :get, data: { turbo_stream: true } do |form| %>
  <!-- 原有下拉框和提交按钮不变 -->
<% end %>

2. 更新控制器，添加format.turbo_stream响应 #

def load
    @users = User.limit(USERS_PER_PAGE).order(creation_date: :desc)
    @users = @users.where(gender: params[:gender]) if params[:gender]

    respond_to do |format|
        format.html { redirect_to users_path, notice: "Filter applied" }
        format.turbo_stream
    end
end

3. 创建Turbo Stream视图文件 #

在app/views/users/目录下创建load.turbo_stream.erb：

<%# 更新用户列表区域 %>
<%= turbo_stream.replace :form_response do %>
    <%= render partial: "users/user_list", locals: { users: @users } %>
<% end %>

<%# 示例：同时更新筛选状态提示（需页面存在id="filter_status"的元素） %>
<%= turbo_stream.update :filter_status do %>
    <p>当前筛选：<%= params[:gender] || "全部性别" %></p>
<% end %>

• 确保turbo-rails已正确集成：检查application.js是否包含import "@hotwired/turbo-rails"
• GET请求使用Turbo Stream时，添加data-turbo-stream: true可避免Turbo默认按HTML请求处理

内容的提问来源于stack exchange，提问作者A. Vreeswijk