CSS 类

在 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 类属性添加到你的控制器

使用这些属性将 CSS 类应用于元素，方法是使用 DOM classList API 的 add() 和 remove() 方法。

例如，要在获取结果之前在 search 控制器元素上显示加载指示器，你可以像这样实现 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 类定义中使用驼峰式大小写来指定逻辑名称。逻辑名称映射到驼峰式大小写 CSS 类属性

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

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

在 HTML 中，以连字符分隔形式编写 CSS 类属性

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

在构建 CSS 类属性时，遵循 控制器：命名约定 中所述的标识符约定。

下一步：使用 Typescript