用途:在 Ruby on Rails 项目中实现表单的动态局部更新,避免整页刷新。典型场景包括:根据一个字段的选择更新另一个字段的选项、动态显示或隐藏条件字段、刷新表单局部内容、实现级联下拉或依赖字段。
主要能力:该模式由四部分组成——路由 concern(添加 turbo_fetch 端点)、控制器动作(准备数据并渲染 turbo streams)、Stimulus 控制器(前端触发 PATCH 请求)、Turbo Stream 视图(更新指定 DOM 元素)。Turbo Stream 支持 update、replace、append、prepend、remove 等操作。
使用方式:在 config/routes.rb 中定义 concern :turbo_fetch do patch :turbo_fetch, on: :collection end,并在资源上应用 resources :materials, concerns: %i[turbo_fetch],生成 PATCH /materials/turbo_fetch 路由。控制器中新增 turbo_fetch 动作,创建带参数的新实例(不保存数据库)并做授权。视图 app/views/[resource]/turbo_fetch.turbo_stream.slim 中用 turbo_stream.update、turbo_stream.replace 等更新目标元素。表单上挂载 Stimulus 控制器,使用 data-controller="turbo-fetch"、data-turbo-fetch-url-value、data-action="turbo-fetch#perform" 等属性;前端 turbo_fetch_controller.js 通过 @rails/request.js 的 patch 发起请求,responseKind 设为 turbo-stream。
常见模式:依赖下拉(触发字段带 data-action,目标字段有稳定唯一 ID,Turbo Stream 更新其集合)、条件字段区块(用 turbo_stream.replace 整体替换区块)、集合与成员路由(多数为 collection,嵌套子资源可用 on: :member)。
限制与注意:目标元素需有唯一稳定 ID;表单需用 simple_form_for 包住以保持表单上下文;授权应与 create/update 保持一致;turbo_fetch 动作只创建实例、绝不保存;一次响应可包含多个 turbo_stream 更新。排查时检查目标 ID 是否匹配、Stimulus 动作是否触发、路由是否存在、参数是否被许可。