Stimulus for Rails 使用教程

Stimulus for Rails 使用教程

1. 项目介绍

Stimulus for Rails 是一个用于在 Ruby on Rails 应用中集成 Stimulus 框架的工具。Stimulus 是一个轻量级的 JavaScript 框架，旨在为服务器渲染的 HTML 添加交互性。通过 Stimulus for Rails，开发者可以轻松地在 Rails 应用中使用 Stimulus，无论是通过 import-mapped 还是 JavaScript-bundled 的方式。

2. 项目快速启动

安装

首先，确保你的 Rails 应用已经安装了 stimulus-rails gem。如果你使用的是 Rails 7+，这个 gem 会自动配置，除非你在生成应用时使用了 --skip-hotwire 选项。

对于 Rails 6 及以下版本，你可以手动安装：

# Gemfile
gem 'stimulus-rails'

然后运行：

$ bundle install
$ rails stimulus:install

配置

根据你的项目设置，选择使用 import map 或 JavaScript bundler。

使用 Import Map

创建 app/javascript/controllers/index.js 并加载你的控制器：

import { application } from "controllers/application"
import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"

eagerLoadControllersFrom("controllers", application)

创建 app/javascript/controllers/application.js：

import { Application } from "@hotwired/stimulus"

const application = Application.start()

// 配置 Stimulus 开发体验
application.debug = process.env.NODE_ENV === "development"

使用 JavaScript Bundler

如果你使用的是 Node-capable Rails（如通过 jsbundling-rails），Stimulus 会自动包含在 bundle 中。

创建控制器

在 app/javascript/controllers/ 目录下创建你的 Stimulus 控制器，例如 hello_controller.js：

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    this.element.textContent = "Hello, Stimulus!"
  }
}

在 HTML 中使用

在你的 Rails 视图中使用 Stimulus 控制器：

<div data-controller="hello">
  <h1>Hello, Stimulus!</h1>
</div>

3. 应用案例和最佳实践

应用案例

Stimulus 特别适合用于增强现有的服务器渲染应用。例如，Basecamp 使用 Stimulus 来为其应用添加交互性，而不需要完全重写为单页应用（SPA）。

最佳实践

1. 保持简单：Stimulus 的设计理念是保持简单和轻量，避免过度复杂的 JavaScript 逻辑。
2. 模块化：将不同的交互功能拆分为多个 Stimulus 控制器，保持代码的可维护性。
3. 与 Rails 集成：充分利用 Rails 的生态系统，如 Turbo 和 StimulusReflex，来增强用户体验。

4. 典型生态项目

Turbo

Turbo 是 Hotwire 的核心组件之一，与 Stimulus 一起使用可以构建快速、响应式的 Web 应用。Turbo 提供了页面导航、表单提交等功能，而 Stimulus 则负责处理页面上的交互逻辑。

StimulusReflex

StimulusReflex 是一个扩展，允许你在 Stimulus 控制器中直接调用 Rails 的 ActionCable，实现实时更新和双向通信。

通过这些工具，你可以构建出功能强大且易于维护的 Rails 应用。