この記事はGoogle翻訳の結果を編集したものです。

アプリケーションにStimulusをインストールするには[@hotwired/stimulus npm パッケージ](@hotwired/stimulus npm package)をJavaScriptバンドルに追加します。または<script type="module">タグでStimuls.jsをインポートします。

Stimulus for Rails の使用

Stimulus for Railsをインポートマップと一緒に使用している場合、統合によりapp/javascript/controllersからすべてのコントローラーファイルが自動的に読み込まれます。

コントローラーのファイル名は識別子にマップされます

コントローラーファイルに[identifier]_controller.jsという名前を付けます。ここでidentifierはHTML内の各コントローラーのdata-controller識別子に対応します。

Stimulus for Railsは通常、アンダースコアを使用してファイル名内の複数の単語を区切ります。コントローラーのファイル名の各アンダースコアはその識別子のダッシュに変換されます。

サブフォルダーを使用してコントローラーの名前を付けることもできます。名前空間化されたコントローラーファイルのパスの各スラッシュは、その識別子で2つのダッシュになります。

必要に応じてコントローラーのファイル名のどこにでもアンダースコアの代わりにダッシュを使用できます。Stimulusはそれらを同じように扱います。

コントローラーファイルの名前が...	その識別子は...
clipboard_controller.js	clipboard
date_picker_controller.js	date-picker
users/list_item_controller.js	users--list-item
local-time-controller.js	local-time

Webpackヘルパーの使用

WebpackをJavaScriptバンドラーとして使用している場合、@hotwired/stimulus-webpack-helpersパッケージを使用してStimulus for Railsと同じ形式の自動読み込み動作を取得できます。最初にパッケージを追加してから次のように使用します。

import { Application } from "@hotwired/stimulus"
import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"

window.Stimulus = Application.start()
const context = require.context("./controllers", true, /\.js$/)
Stimulus.load(definitionsFromContext(context))

他のビルドシステムの使用

Stimulusは他のビルドシステムでも動作しますが、コントローラーの自動読み込みはサポートされていません。代わりにコントローラーファイルを明示的に読み込んでアプリケーションインスタンスに登録する必要があります。

// src/application.js
import { Application } from "@hotwired/stimulus"

import HelloController from "./controllers/hello_controller"
import ClipboardController from "./controllers/clipboard_controller"

window.Stimulus = Application.start()
Stimulus.register("hello", HelloController)
Stimulus.register("clipboard", ClipboardController)

esbuildのようなビルダーでstimulus-railsを使用している場合、stimulus:manifest:updateRakeタスクと./bin/rails generate stimulus [controller]ジェネレーターを使用してapp/javascript/controllers/index.jsに配置されたコントローラーインデックスファイルを自動的に更新しておくことができます。

ビルドシステムなしで使う

ビルドシステムを使用したくない場合はStimulusを<script type="module">タグでロードできます。

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script type="module">
    import { Application, Controller } from "https://unpkg.com/@hotwired/stimulus/dist/stimulus.js"
    window.Stimulus = Application.start()

    Stimulus.register("hello", class extends Controller {
      static targets = [ "name" ]

      connect() {
      }
    })
  </script>
</head>
<body>
  <div data-controller="hello">
    <input data-hello-target="name" type="text">
    …
  </div>
</body>
</html>

属性のデフォルトのオーバーライド

Stimulusのdata-*属性がプロジェクト内の別のライブラリと競合する場合、Stimulusアプリケーションの作成時にオーバーライドできます。

data-controller
data-action
data-target

これらのコアStimulus属性はオーバーライドできます（schema.tsを参照）。

// src/application.js
import { Application, defaultSchema } from "@hotwired/stimulus"

const customSchema = {
  ...defaultSchema,
  actionAttribute: 'data-stimulus-action'
}

window.Stimulus = Application.start(document.documentElement, customSchema);

エラー処理

Stimulusからアプリケーションのコードへのすべての呼び出しはtry ... catchブロックでラップされます。

コードがエラーをスローするとStimulusによってキャッチされ、ブラウザーコンソールにログが記録されます。これにはコントローラー名、呼び出されているイベントまたはライフサイクル関数などの詳細が含まれます。window.onerrorを定義するエラー追跡システムを使用する場合、Stimulusはそれにエラーを渡します。

Application#handleErrorを定義することでStimulusがエラーを処理する方法をオーバーライドできます。

// src/application.js
import { Application } from "@hotwired/stimulus"
window.Stimulus = Application.start()

Stimulus.handleError = (error, message, detail) => {
  console.warn(message, detail)
  ErrorTrackingSystem.captureException(error)
}

デバッグ

Stimulusアプリケーションをwindow.Stimulusに割り当てた場合、コンソールからStimulus.debug = trueでデバッグモードをオンにできます。ソースコードでアプリケーションインスタンスを構成するときに、このフラグを設定することもできます。

ブラウザ対応

Stimulusはすべてのエバーグリーンで自己更新型のデスクトップおよびモバイルブラウザーをすぐにサポートします。Stimulus 3+はInternet Explorer 11をサポートしていません（ただし、@stimulus/polyfillsを使用してStimulus 2を使用することはできます）。

Stimulus 7: アプリケーションにStimulusをインストールする