stimulus-controllers

Stimulus コントローラー

概要

Stimulus コントローラーは、データ属性を介して HTML と連携するモジュール式の JavaScript 機能を提供します。新しいコントローラーを作成したら、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 でのコントローラー名にはケバブケースを使用します：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（スネークケース）
• クラス：export default class extends Controller
• 登録名："example"（ケバブケース）
• HTML：data-controller="example"（ケバブケース）
• 複数の単語：bulk_submit_controller.js → "bulk-submit"

主な概念

ターゲット

特定の DOM 要素を参照します。

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

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

値

型安全なデータ属性です。

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
}

アクション

イベントをメソッドに接続します。

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"

クラス

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. データ属性のスペル（ケバブケース）を確認します
5. テストで JavaScript が有効になっていることを確認します（:js タグ）

ターゲットが見つからない場合

• static targets のターゲット名が HTML と一致していることを確認します
• アクセスする前に hasXxxTarget を使って存在を確認します
• ターゲット要素がコントローラーのスコープ内にあることを確認します

関連スキル

• フロントエンドのパターン - HTML と CSS のパターン
• 動的フォーム - Stimulus コントローラーを必要としない動的なフォーム更新
• テストのパターン - JavaScript 機能のテスト