Stimulusのバリュー（Values）を理解しよう【Rails × Stimulus入門】

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アプリケーションのフロントエンド開発をより効率的に進めましょう。