企业官网建设流程全解析

hotwire-rails 是 Ruby on Rails 生态中用于聚合 Hotwire 两大核心组件 Turbo 与 Stimulus 的 gem，让你无需编写大量 JavaScript，就能让传统 Rails 应用拥有接近单页应用（SPA）的流畅体验。本文面向新手，完整讲解 Turbo Frames、Turbo Streams 与 Stimulus 控制器的安装与用法。

1分钟看懂 hotwire-rails 是干什么的 🎯

Hotwire 的理念是“HTML over the wire”（HTML 走网线）：服务器发送 HTML 片段，浏览器做最小化局部更新。它由两部分组成：

• Turbo（由turbo-rails提供）：接管页面跳转、表单提交，实现局部刷新
• Stimulus（由stimulus-rails提供）：轻量的 JavaScript 框架，用数据属性把行为挂到 HTML 元素上

hotwire-rails本身的作用是“打包”这两个 gem：入口文件 lib/hotwire-rails.rb 会同时引入turbo-rails与stimulus-rails，hotwire-rails.gemspec 中声明了这三项依赖（外加rails >= 6.0.0）。

⚠️ 注意：官方认为“聚合依赖”价值有限，该 gem 已标记Deprecated（见 README.md）。新项目建议直接引入turbo-rails和stimulus-rails，功能完全一致，本文用法同样适用。

快速安装：3 步跑通 Hotwire

第 1 步：声明依赖

在 Gemfile 中加入：

gem "hotwire-rails"

第 2 步：安装 gem

bundle install

第 3 步：执行安装命令

rails generate hotwire:install

该任务定义在 lib/tasks/hotwire_tasks.rake 中，内部串联了stimulus:install与turbo:install，会自动完成 JS 资源、视图 helper 等全部引入。若使用较新的独立安装方式，则分别运行rails generate turbo:install和rails generate stimulus:install即可。

Turbo Frames：局部刷新，页面不再整页重载

Turbo Frame 允许把页面的一部分包进<turbo-frame>容器，导航或刷新时只重载 frame 内的内容。

1. 在视图中用 frame 包裹局部内容

<%= turbo_frame_tag "cart" do %> <%= render "partials/cart" %> <% end %>

2. 服务器只返回该 frame 对应的片段

当请求指向#cart时，Rails 只需返回对应局部模板的 HTML，Turbo 会自动替换到正确位置。

典型使用场景：

• 侧边栏购物车：只有购物车区域刷新，页面状态（滚动位置、焦点）完整保留
• 分页列表：翻页只更新列表区域
• 同页多端适配：移动端与桌面端加载不同局部内容

核心优势：一行 JavaScript 都不用写。

Turbo Streams：服务器推送“补丁”，页面实时更新 💡

Turbo Streams 相当于 HTML 的“远程补丁”：服务器返回一系列turbo-stream指令，浏览器执行后精准更新对应元素。支持 5 种操作：

1. 控制器中返回 stream 响应

def publish @article = Article.find(params[:id]) @article.publish! render turbo_stream: [ turbo_stream.append("articles", partial: "articles/article", locals: { article: @article }) ] end

2. 用 ActionCable 实时广播给所有用户

def show @article = Article.find(params[:id]) stream_from @article end

只要某个用户触发了turbo_stream渲染，所有订阅了同一频道、打开同一页面的用户都会收到并应用这块“补丁”——这正是实时评论区、实时排行榜的实现原理。

Stimulus：给 HTML 加上“刚刚好”的 JavaScript

Stimulus 用数据属性把行为绑定到元素上，避免庞大的app.js。

1. 生成控制器

rails generate stimulus:controller hello

2. 控制器代码（自动生成于app/javascript/controllers/hello_controller.js）：

import { Controller } from "@hotwired/stimulus" export default class extends Controller { connect() { console.log(this.element.dataset.name) } }

3. 在 HTML 中声明

<div>赞分享