stimulus-controllers

Stimulus 控制器

概述

Stimulus 控制器提供模块化 JavaScript 功能，并通过数据属性与 HTML 相连。创建新控制器后，必须在 index.js 文件中注册。

创建新控制器

1. 创建控制器文件

在 app/javascript/controllers/ 中创建新的控制器：

// app/javascript/controllers/example_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["element"]
  static values = { name: String }

  connect() {
    // Called when controller is connected to DOM
  }

  disconnect() {
    // Called when controller is disconnected from DOM
  }

  // Action methods
  handleClick(event) {
    event.preventDefault()
    // Your logic here
  }
}

2. 注册控制器

重要：创建新控制器后，运行：

bin/rails stimulus:manifest:update

此命令会自动更新 app/javascript/controllers/index.js，以注册你的控制器。

手动注册（如有需要）：

import ExampleController from "./example_controller"
application.register("example", ExampleController)

HTML 中的控制器名称使用 kebab-case：data-controller="example"

3. 在 HTML 中使用

将控制器连接到 HTML 元素：

.container data-controller="example" data-example-name-value="test"
  button data-action="click->example#handleClick" Click Me
  div data-example-target="element" Target Element

命名约定

• 文件：example_controller.js（snake_case）
• 类：export default class extends Controller
• 注册名称："example"（kebab-case）
• HTML：data-controller="example"（kebab-case）
• 多词名称：bulk_submit_controller.js → "bulk-submit"

核心概念

Targets

引用特定的 DOM 元素：

static targets = ["input", "output"]

// Access in methods:
this.inputTarget        // First matching element
this.inputTargets       // All matching elements
this.hasInputTarget     // Boolean check

Values

类型安全的数据属性：

static values = {
  url: String,
  count: Number,
  active: Boolean,
  items: Array,
  config: Object
}

// Access in methods:
this.urlValue
this.countValue

// Watch for changes:
urlValueChanged(newUrl, oldUrl) {
  // Called when value changes
}

Actions

将事件连接到方法：

data-action="click->example#save"


data-action="click->example#save submit->example#submit"


data-action="example:refresh->example#reload"


data-action="submit->example#save:prevent"

Classes

管理 CSS 类：

static classes = ["active", "hidden"]

// Use in methods:
this.element.classList.add(this.activeClass)
this.element.classList.remove(this.hiddenClass)

常见模式

表单验证

export default class extends Controller {
  static targets = ["form", "submit"]

  validate() {
    const isValid = this.formTarget.checkValidity()
    this.submitTarget.disabled = !isValid
  }
}

切换可见性

export default class extends Controller {
  static targets = ["content"]
  static classes = ["hidden"]

  toggle() {
    this.contentTarget.classList.toggle(this.hiddenClass)
  }
}

AJAX 更新

export default class extends Controller {
  static values = { url: String }

  async refresh() {
    const response = await fetch(this.urlValue)
    const html = await response.text()
    this.element.innerHTML = html
  }
}

测试

在系统规格测试中测试 Stimulus 控制器：

it 'handles interaction', :js do
  visit page_path

  click_button 'Toggle'

  expect(page).to have_css('[data-controller="example"]')
end

故障排查

控制器无法工作？

1. 确认控制器已在 index.js 中注册
2. 运行 bin/rails stimulus:manifest:update
3. 检查浏览器控制台中的错误
4. 确认数据属性拼写正确（kebab-case）
5. 确保测试已启用 JavaScript（:js 标签）

找不到 Targets？

• 检查 static targets 中的 target 名称是否与 HTML 一致
• 访问前使用 hasXxxTarget 确认其存在
• 确保 target 元素位于控制器的作用范围内

相关技能

• frontend-patterns - HTML 和 CSS 模式
• dynamic-forms - 动态表单更新，无需 Stimulus 控制器
• testing-patterns - JavaScript 功能测试