Stimulus リファレンス: CSSクラス

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

HTMLではCSSクラスはclass属性を使用して要素に適用できる一連のスタイルを定義します。

CSSクラスはスタイルを変更したりプログラムでアニメーションを再生したりするための便利なツールです。 たとえばStimulusコントローラーはバックグラウンドで操作を実行しているときに"loading"クラスを要素に追加し、CSSでそのクラスをスタイルして進行状況インジケーターを表示する場合があります。

<form data-controller="search" class="search--busy">

.search--busy {
  background-image: url(throbber.svg) no-repeat;
}

クラスをJavaScript文字列でハードコーディングする代わりにStimulusを使用すると、データ属性とコントローラープロパティの組み合わせを使用して論理名でCSSクラスを参照できます。

定義

static classes配列を使用してコントローラーでCSSクラスを論理名で定義します。

// controllers/search_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static classes = [ "loading" ]  // …
}

属性

コントローラーのstatic classes配列で定義された論理名はコントローラーの要素のCSS クラス属性にマップされます。

<form data-controller="search"
      data-search-loading-class="search--busy">
  <input data-action="search#loadResults">
</form>

コントローラー識別子と論理名をdata-[identifier]-[logical-name]-classの形式で結合してCSSクラス属性を作成します。属性の値は単一のCSSクラス名または複数のクラス名のリストにすることができます。

注： CSSクラス属性はdata-controller属性と同じ要素で指定する必要があります。

論理名に複数のCSSクラスを指定する場合はクラスをスペースで区切ります。

<form data-controller="search"
      data-search-loading-class="bg-gray-500 animate-spinner cursor-busy">
  <input data-action="search#loadResults">
</form>

プロパティ

static classes配列で定義された論理名ごとにStimulusは次のCSSクラスプロパティをコントローラーに追加します。

種類	名前	値
単数	this.[logicalName]Class	logicalNameに対応するCSSクラス属性の値
複数	this.[logicalName]Classes	スペースで区切られた対応するCSSクラス属性のすべてのクラスの配列
存在	this.has[LogicalName]Class	CSS クラス属性が存在するかどうかを示すブール値

これらのプロパティを使用してDOM classList APIのadd()およびremove()メソッドでCSSクラスを要素に適用します。

たとえば結果を取得する前に検索コントローラーの要素に読み込みインジケーターを表示するには、次のようにloadResultsアクションを実装できます。

export default class extends Controller {
  static classes = [ "loading" ]

  loadResults() {
    this.element.classList.add(this.loadingClass)

    fetch(/* … */)
  }
}

CSSクラス属性にクラス名のリストが含まれている場合、その単一のCSSクラスプロパティはリストの最初のクラスを返します。

CSSクラスプロパティの複数形を使用してすべてのクラス名に配列としてアクセスします。これをスプレッド構文と組み合わせて複数のクラスを一度に適用します。

export default class extends Controller {
  static classes = [ "loading" ]

  loadResults() {
    this.element.classList.add(...this.loadingClasses)

    fetch(/* … */)
  }
}

注： 一致するCSSクラス属性が存在しないときにCSSクラスプロパティにアクセスしようとするとStimulusはエラーをスローします。

命名規則

CSSクラス定義で論理名を指定するにはcamelCaseを使用します。論理名はcamelCaseのCSSクラスプロパティにマップされます。

export default class extends Controller {
  static classes = [ "loading", "noResults" ]

  loadResults() {
    // …
    if (results.length == 0) {
      this.element.classList.add(this.noResultsClass)
    }
  }
}

HTMLではCSSクラス属性をkebab-caseで記述します。

<form data-controller="search"
      data-search-loading-class="search--busy"
      data-search-no-results-class="search--empty">

CSSクラス属性を構築するときは、コントローラーの命名規則で説明されている識別子の規則に従います。