Stimulus

JavaScriptオブジェクトをデータ属性経由でHTMLに接続するシンプルなJavaScriptフレームワーク。StimulusはHTMLをレンダリングしません。サーバーレンダリングされたHTMLに動作を追加します。

メンタルモデル: HTMLが真実のソース、JavaScriptコントローラーが要素に接続し、データ属性が配線となります。AssetMapperを使用すれば、ビルドステップは不要です。

クイックリファレンス

data-controller="name"              コントローラーを要素に接続
data-name-target="item"             要素をターゲットとしてマーク
data-action="event->name#method"    イベントをコントローラーメソッドにバインド
data-name-key-value="..."           型付きデータをコントローラーに渡す
data-name-key-class="..."           CSSクラス名を設定
data-name-other-outlet=".selector"  別のコントローラーインスタンスを参照

コントローラースケルトン

// assets/controllers/example_controller.js
import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
    static targets = ['input', 'output'];
    static values = { url: String, delay: { type: Number, default: 300 } };
    static classes = ['loading'];
    static outlets = ['other'];

    connect() {
        // コントローラーがDOMに接続されたときに呼ばれる
    }

    disconnect() {
        // コントローラーが切断されたときに呼ばれる -- ここでクリーンアップ
    }

    submit(event) {
        // アクションメソッド
    }
}

ファイル命名規則: hello_controller.jsはdata-controller="hello"にマップされます。サブディレクトリは--をセパレーターとして使用します: components/modal_controller.jsはdata-controller="components--modal"にマップされます。

HTMLの配線例

基本的なコントローラー

<div data-controller="hello">
    <input data-hello-target="name" type="text">
    <button data-action="click->hello#greet">Greet</button>
    <span data-hello-target="output"></span>
</div>

サーバーからの値(Twig)

値属性経由でサーバーデータをコントローラーに渡します。値は型付きで、自動的に解析されます。

<div data-controller="map"
     data-map-latitude-value="{{ place.lat }}"
     data-map-longitude-value="{{ place.lng }}"
     data-map-zoom-value="12">
</div>

使用可能な型: String、Number、Boolean、Array、Object。値が変更されると{name}ValueChanged()コールバックがトリガーされます。

アクション

形式はevent->controller#methodです。要素型ごとにデフォルトイベントが存在する(ボタンではclick、入力ではinput、フォームではsubmit)ため、イベントは省略可能です。

{# 明示的なイベント #}
<button data-action="click->hello#greet">Greet</button>

{# デフォルトイベント(ボタンではclick) #}
<button data-action="hello#greet">Greet</button>

{# 同じ要素に複数のアクション #}
<input type="text"
       data-action="focus->field#highlight blur->field#normalize input->field#validate">

{# デフォルト動作を防止 #}
<form data-action="submit->form#validate:prevent">

{# キーボードショートカット #}
<div data-action="keydown.esc@window->modal#close">
<input data-action="keydown.enter->modal#submit keydown.ctrl+s->modal#save">

{# グローバルイベント(window/document) #}
<div data-action="resize@window->sidebar#adjust click@document->sidebar#closeOutside">

CSSクラス

CSSクラス名を外部化してコントローラーを汎用にしましょう:

<button data-controller="button"
        data-button-loading-class="opacity-50 cursor-wait"
        data-button-active-class="bg-blue-600"
        data-action="click->button#submit">
    Submit
</button>

// コントローラー内
this.element.classList.add(...this.loadingClasses);

複数のコントローラー

1つの要素に複数のコントローラーを付与できます:

<div data-controller="dropdown tooltip"
     data-action="mouseenter->tooltip#show mouseleave->tooltip#hide">
    <button data-action="click->dropdown#toggle">Menu</button>
    <ul data-dropdown-target="menu" hidden>...</ul>
</div>

アウトレット(コントローラー間通信)

CSSセレクターで別のコントローラーインスタンスを参照します:

<div data-controller="player"
     data-player-playlist-outlet="#playlist">
    <button data-action="click->player#playNext">Next</button>
</div>

<ul id="playlist" data-controller="playlist">
    <li data-playlist-target="track">Song 1</li>
    <li data-playlist-target="track">Song 2</li>
</ul>

// プレイヤーコントローラー内
static outlets = ['playlist'];

playNext() {
    const tracks = this.playlistOutlet.trackTargets;
    // ...
}

遅延読み込み(重い依存関係)

要素がビューポートに表示されるときのみコントローラーJSを読み込みます。重い依存関係(チャートライブラリ、エディター、マップ)を持つコントローラーで使用します。

/* stimulusFetch: 'lazy' */
import { Controller } from '@hotwired/stimulus';
import Chart from 'chart.js';

export default class extends Controller {
    connect() {
        // Chart.jsはこの要素がビューポートに入るときだけ読み込まれる
    }
}

/* stimulusFetch: 'lazy' */コメントはファイルの最初の行である必要があります。

Symfony / Twig統合

生のデータ属性が推奨される方法です。どこでも動作し、読みやすく、特別なヘルパーは不要です。

{# 生のデータ属性(推奨) #}
<div data-controller="search"
     data-search-url-value="{{ path('api_search') }}">

Twigヘルパーは複雑なケースや属性をプログラムで生成する場合に使用できます:

{# Twigヘルパー #}
<div {{ stimulus_controller('search', { url: path('api_search') }) }}>

{# 複数のコントローラーをチェーン #}
<div {{ stimulus_controller('a')|stimulus_controller('b') }}>

{# ターゲットとアクションヘルパー #}
<input {{ stimulus_target('search', 'query') }}>
<button {{ stimulus_action('search', 'submit') }}>

主要な原則

HTMLが主導し、JSが応答します。 コントローラーはマークアップを作成しません。既存のHTMLに動作を追加します。コントローラー内でDOMを生成している場合、TwigComponentまたはLiveComponentがより適切かどうか検討してください。

1つのコントローラーは1つの関心事。 ドロップダウンコントローラーはドロップダウンを処理します。ツールチップコントローラーはツールチップを処理します。超大型コントローラーを作成するのではなく、同じ要素に複数のコントローラーを組み合わせます。

disconnect()でクリーンアップします。 connect()がイベントリスナー、タイマー、またはサードパーティライブラリインスタンスを追加する場合、disconnect()でそれらを削除する必要があります。Turboナビゲーションはページが変わるときにコントローラーを切断して再接続します。

生のデータ属性より値を使用します。 コントローラーが読み取るまたは監視する必要があるデータには、生のdata-*属性ではなくStimulus値(型付き、変更コールバック付き)を使用します。

参照

• 完全なAPI(ライフサイクル、ターゲット、値、アクション、クラス、アウトレット): references/api.md
• パターン(デバウンス、フェッチ、モーダル、フォーム等): references/patterns.md
• 落とし穴(一般的な間違い、デバッグ、Turbo互換性): references/gotchas.md