【ITニュース解説】Stimulus basics: what is a Stimulus controller?

Stimulusは、ウェブページにインタラクティブな機能を手軽に追加するためのフレームワークである。その中心的な役割を担うのが「コントローラー」と呼ばれるものだ。このコントローラーは、ウェブページ上の特定の要素に対して、動きや振る舞いを定義し、管理するための基本的な構成要素となる。Stimulusでは、複雑な機能を一つの大きな塊として作るのではなく、小さく、それぞれが独立して機能し、かつ再利用しやすいコントローラーとして設計することが推奨される。

Stimulusコントローラーの正体は、実はごく普通のJavaScriptクラスである。例えば、記事にあるようにclass Editor { constructor(content) { this.content = content } save() { console.log(this.content) } }という形式で記述される。これは、初期設定を行うconstructorと、具体的な処理を実行するsave()のようなメソッドを持つ、一般的なクラスの定義方法と同じだ。しかし、Stimulusのコントローラーとして機能させるためには、重要な違いが一つある。それは、Stimulusが提供する基本的なControllerクラスを「継承（extends）」する必要がある点だ。具体的には、export default class extends Controllerのように記述する。この継承によって、開発者が書いたクラスは、Stimulusが内蔵するライフサイクルメソッド（コントローラーがページに接続されたり切断されたりするタイミングで自動的に呼び出されるメソッド）や、特定のDOM要素を簡単に参照するための「ターゲット」、データ状態を管理する「値」といった、 Stimulus独自の便利な機能を自動的に利用できるようになる。これは、Ruby on Railsでいうところの、個別のコントローラーがApplicationControllerを継承して共通の機能を利用する仕組みと似ている。

コントローラーの定義方法には、主に二つのパターンがある。一つはexport default class extends Controllerのように、クラス自体に名前をつけない「匿名クラス」として定義する方法だ。Stimulusのアプリケーションでは、この匿名クラスの形式が最も一般的で推奨されている。その理由は、Stimulusがコントローラーの「識別子」をクラス名ではなく、そのJavaScriptファイルのファイル名（例えばeditor_controller.js）から取得するという慣習があるためである。このアプローチはコードをより簡潔にし、Stimulusの公式ドキュメントやコミュニティの多くの例で採用されているパターンと一致する。もう一つの方法は、export default class EditorController extends Controllerのように、クラスに明示的に名前を付ける「名前付きクラス」として定義することだ。この方法は、特にアプリケーションのデバッグ（プログラムの不具合を発見・修正する作業）を行う際に役立つことがある。ブラウザの開発者ツールやエラーの履歴（スタックトレース）において、名前付きのクラスはどのコントローラーが関与しているかを明確に示してくれるため、問題の追跡が容易になる場合がある。しかし、Stimulusにおいては、名前付きコントローラーの多用は、アプリケーションの設計が複雑になりすぎている兆候として捉えられることもある。

StimulusのControllerクラスは、さらに多くの強力な機能を提供する。これらは「静的プロパティ（static properties）」と呼ばれるJavaScriptの標準的なクラス機能を利用して宣言される。Stimulusは、コントローラーが初期化される際にこれらの静的プロパティを読み取り、ウェブページのDOM（Document Object Model、ウェブページの構造を表すもの）とコントローラーを自動的に連携させるための設定を行う。主要な静的プロパティには、以下のものがある。

static targets = ["input", "output"] これは、コントローラーが管理する範囲内の特定のDOM要素を、簡単かつ安全に参照できるようにするための宣言である。この宣言を行うことで、HTML側でdata-コントローラー名-target="input"といった属性を持つ要素に対し、コントローラー内からthis.inputTargetのようにアクセスできるようになる。Stimulusは、この宣言に基づいて自動的に該当する要素を検索し、プロパティとして提供してくれるため、開発者は自分でDOMを検索する手間が省ける。

static values = { content: String, count: Number } このプロパティは、HTMLのdata-コントローラー名-value属性と連携し、JavaScriptの変数のように扱えるリアクティブな（反応する）プロパティを定義する。HTML側の属性値が変更されると、自動的にコントローラー内の対応する値も更新され、それに応じて特定の処理を実行することも可能になる。

static classes = ["active", "hidden"] これはCSSのクラス名を管理するためのもので、HTML要素に対して特定のCSSクラスを簡単に追加したり削除したりする際に利用できる。

これらの静的プロパティは、Stimulus独自の特殊な構文ではなく、JavaScriptの標準的なクラスの機能である。Stimulusは、これらの宣言を読み取り、その背後で複雑な処理を自動的に行ってくれる。もしStimulusを使わずに同じ機能を実現しようとすれば、開発者は手動でDOM要素を検索し、要素の変化を監視し、必要に応じてエラーチェックを行うなど、大量の定型コードを自分で記述しなければならないだろう。例えば、static targetsの機能は、Stimulusを使えばstatic targets = ["input"]と宣言し、connect()メソッドの中でthis.inputTarget.focus()と書くだけで、inputというターゲット要素にフォーカスを当てることが可能だ。これをStimulusなしの通常のJavaScriptで実装しようとすると、constructor内で要素を検索し、存在しない場合のエラー処理を行い、さらにMutationObserverというAPIを使ってDOMの変更を監視し、ターゲット要素が動的に追加・削除された場合にも対応できるように準備する必要がある。そして、コントローラーがページから切断される際には、その監視を停止するdisconnect()処理も忘れずに行わなければならない。Stimulusは、このような複雑な要素の検索、エラーチェック、動的な更新処理といった「基盤となる処理」をすべて自動で担当してくれるため、開発者は本当に実装したい「振る舞い」の部分に集中できるという大きなメリットがある。

Stimulusコントローラーの特に優れた特徴の一つは、その「自動的なインスタンス化」と「ページへの接続」の仕組みにある。通常のJavaScriptクラスでは、ウェブページ上の特定のHTML要素に対して、手動でクラスのインスタンスを作成し、イベントリスナー（ユーザーの操作などを監視する仕組み）を設定するといった、多くの初期設定作業が必要になる。しかし、Stimulusはこの手間を省くために、ブラウザのMutationObserverというAPIを利用する。このAPIは、ウェブページのDOM（HTMLの構造）に加えられた変更をリアルタイムで監視できる機能だ。Stimulusは、このMutationObserverを使って、HTMLにdata-controllerという属性が付けられた要素が追加されたり削除されたりするのを常に見張っている。そして、例えばdata-controller="editor"という属性を持つ新しい要素がページに現れると、Stimulusは自動的にそれに対応するEditorControllerクラスのインスタンスを生成し、その要素に「接続」する。これにより、開発者は手動で初期化コードを書くことなく、HTMLに属性を追加するだけで、その要素に定義されたインタラクティブな機能が自動的に有効になるのだ。

以上がStimulusコントローラーの基本的な仕組みである。Stimulusは、JavaScriptの標準的な機能と、背後での賢い自動化によって、ウェブアプリケーションにインタラクティブな機能を追加するプロセスを大幅に簡素化し、開発者がより本質的な問題解決に集中できるように設計されている。