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

:::note
この記事は[Google翻訳](https://translate.google.co.jp/)の結果を編集したものです。
:::

https://stimulus.hotwired.dev/handbook/installing

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

# Stimulus for Rails の使用

[Stimulus for Rails](https://github.com/hotwired/stimulus-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](https://www.npmjs.com/package/@hotwired/stimulus-webpack-helpers)パッケージを使用してStimulus for Railsと同じ形式の自動読み込み動作を取得できます。最初にパッケージを追加してから次のように使用します。

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

```javascript
// 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:update`Rakeタスクと`./bin/rails generate stimulus [controller]`ジェネレーターを使用して`app/javascript/controllers/index.js`に配置されたコントローラーインデックスファイルを自動的に更新しておくことができます。

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

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

```html
<!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`を参照）。

```javascript
// 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がエラーを処理する方法をオーバーライドできます。

```javascript
// 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を使用することはできます）。