Stimulusを使ったRailsアプリケーション開発では、「バリュー（Values）」という仕組みを使って、HTML要素からJavaScriptコントローラーに値を簡単に渡すことができます。
この記事では、Stimulus公式ドキュメントの「Values」の内容を日本語でわかりやすく解説します。
Stimulusのバリュー（Values）とは？
Stimulusのバリューとは、HTMLのデータ属性を使ってStimulusコントローラーに値を渡す仕組みです。
バリューを使うことで、HTML側で指定した値をJavaScript側で簡単に取得・利用できます。
Stimulusでは、HTMLのdata-[コントローラー名]-[値名]-value属性を使って、値を指定します。
基本的なバリューの使い方
Stimulusのバリューを使うには、以下のようにHTML要素にdata-[コントローラー名]-[値名]-value属性を指定します。
HTMLの例
<div data-controller="hello" data-hello-name-value="Stimulus">
<button data-action="click->hello#greet">挨拶する</button>
</div>上記の例では、helloコントローラーにnameという名前のバリューを指定しています。
このバリューの値は「Stimulus」です。
JavaScriptの例
// hello_controller.js
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
static values = { name: String }
greet() {
alert(`こんにちは、${this.nameValue}さん！`)
}
}- コントローラー内で
static valuesオブジェクトにバリュー名と型を指定します。 - JavaScript内では、
this.[バリュー名]Valueというプロパティでバリューの値にアクセスできます。
バリューの型（Types）について
Stimulusのバリューには、以下の型を指定できます。
String（文字列）Number（数値）Boolean（真偽値）Array（配列）Object（オブジェクト）
型を指定することで、Stimulusが自動的に値を適切な型に変換してくれます。
型指定の例
static values = {
name: String,
age: Number,
active: Boolean,
tags: Array,
config: Object
}HTMLの例（型ごとの指定方法）
<div data-controller="example"
data-example-name-value="Stimulus"
data-example-age-value="30"
data-example-active-value="true"
data-example-tags-value='["rails", "stimulus", "javascript"]'
data-example-config-value='{"theme":"dark","layout":"grid"}'>
</div>- HTML側では、文字列以外の型も文字列として指定しますが、Stimulusが自動的に指定した型に変換します。
バリューのデフォルト値を指定する方法
Stimulusでは、バリューにデフォルト値を指定することも可能です。
HTML側で値が指定されていない場合に、デフォルト値が使われます。
JavaScriptの例（デフォルト値の指定）
static values = {
name: { type: String, default: "ゲスト" },
age: { type: Number, default: 20 },
active: { type: Boolean, default: false }
}- HTML側で値が指定されていない場合、デフォルト値が使われます。
バリューの変更を検知する方法（Value Changedコールバック）
Stimulusでは、バリューの値が変更されたときに自動的に呼び出されるコールバックメソッドを定義できます。
コールバックメソッドの名前は、[バリュー名]ValueChangedという形式で指定します。
JavaScriptの例（変更検知）
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
static values = { name: String }
nameValueChanged(newValue, oldValue) {
console.log(`名前が「${oldValue}」から「${newValue}」に変更されました。`)
}
}- バリューの値が変更されると、
[バリュー名]ValueChangedメソッドが自動的に呼び出されます。 - 新しい値と古い値を引数として受け取ることができます。
バリューのベストプラクティスと注意点
- バリューを使うことで、HTML側からJavaScriptコントローラーに簡単に値を渡せます。
- バリュー名は、役割が明確にわかる名前を付けましょう（例：name, age, activeなど）。
- 型を適切に指定することで、値の変換をStimulusに任せることができます。
- バリューの変更を検知したい場合は、
[バリュー名]ValueChangedメソッドを活用しましょう。
まとめ
Stimulusのバリューを使うことで、HTML要素からJavaScriptコントローラーに値を簡単に渡すことができます。
- HTML側で
data-[コントローラー名]-[値名]-value属性を指定 - JavaScript側で
static valuesオブジェクトにバリュー名と型を指定 - 値は
this.[バリュー名]Valueで取得 - デフォルト値を指定可能
- 値の変更を検知するコールバックメソッドを定義可能
Stimulusのバリューを理解して、Railsアプリケーションのフロントエンド開発をより効率的に進めましょう。
