在应用程序中安装 Stimulus

要在应用程序中安装 Stimulus，请将 @hotwired/stimulus npm 包添加到 JavaScript 捆绑包中。或者，在 <script type="module"> 标签中导入 stimulus.js。

﹟ 在 Rails 中使用 Stimulus

如果你将 Stimulus for Rails 与 import map 一起使用，集成将自动加载来自 app/javascript/controllers 的所有控制器文件。

﹟ 控制器文件名映射到标识符

将控制器文件命名为 [identifier]_controller.js，其中 identifier 对应于 HTML 中每个控制器的 data-controller 标识符。

Stimulus for Rails 通常使用下划线分隔文件名中的多个单词。控制器文件名中的每个下划线在标识符中转换为破折号。

你还可以使用子文件夹对控制器进行命名空间。命名空间控制器文件路径中的每个正斜杠在标识符中变为两个破折号。

如果你愿意，可以在控制器文件名的任何位置使用破折号代替下划线。Stimulus 将它们视为相同。

如果控制器文件被命名为…	它的标识符将是…
clipboard_controller.js	clipboard
date_picker_controller.js	date-picker
users/list_item_controller.js	users--list-item
local-time-controller.js	local-time

﹟ 使用 Webpack 帮助程序

如果你使用 Webpack 作为 JavaScript 捆绑器，则可以使用 @hotwired/stimulus-webpack-helpers 包来获得与 Stimulus for Rails 相同形式的自动加载行为。首先添加包，然后像这样使用它

import { Application } from "@hotwired/stimulus"
import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"

window.Stimulus = Application.start()
const context = require.context("./controllers", true, /\.js$/)
Stimulus.load(definitionsFromContext(context))

﹟ 使用其他构建系统

Stimulus 也适用于其他构建系统，但不支持控制器自动加载。相反，你必须使用应用程序实例显式加载和注册控制器文件

// src/application.js
import { Application } from "@hotwired/stimulus"

import HelloController from "./controllers/hello_controller"
import ClipboardController from "./controllers/clipboard_controller"

window.Stimulus = Application.start()
Stimulus.register("hello", HelloController)
Stimulus.register("clipboard", ClipboardController)

如果你将 stimulus-rails 与 esbuild 等构建器一起使用，则可以使用 stimulus:manifest:update Rake 任务和 ./bin/rails generate stimulus [controller] 生成器自动更新位于 app/javascript/controllers/index.js 的控制器索引文件。

﹟ 在不使用构建系统的情况下使用

如果你不想使用构建系统，则可以在 <script type="module"> 标签中加载 Stimulus

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script type="module">
    import { Application, Controller } from "https://unpkg.com/@hotwired/stimulus/dist/stimulus.js"
    window.Stimulus = Application.start()

    Stimulus.register("hello", class extends Controller {
      static targets = [ "name" ]

      connect() {
      }
    })
  </script>
</head>
<body>
  <div data-controller="hello">
    <input data-hello-target="name" type="text">
    …
  </div>
</body>
</html>

﹟ 覆盖属性默认值

如果 Stimulus data-* 属性与项目中的其他库冲突，则可以在创建 Stimulus Application 时覆盖它们。

data-controller
data-action
data-target

这些核心 Stimulus 属性可以被覆盖（参见：schema.ts)

// src/application.js
import { Application, defaultSchema } from "@hotwired/stimulus"

const customSchema = {
  ...defaultSchema,
  actionAttribute: 'data-stimulus-action'
}

window.Stimulus = Application.start(document.documentElement, customSchema);

﹟ 错误处理

Stimulus 对应用程序代码的所有调用都包含在一个 try ... catch 块中。

如果你的代码抛出一个错误，它将被 Stimulus 捕获并记录到浏览器控制台中，包括额外的详细信息，例如控制器名称和正在调用的事件或生命周期函数。如果你使用定义了 window.onerror 的错误跟踪系统，Stimulus 也会将错误传递给它。

你可以通过定义 Application#handleError 来覆盖 Stimulus 处理错误的方式

// src/application.js
import { Application } from "@hotwired/stimulus"
window.Stimulus = Application.start()

Stimulus.handleError = (error, message, detail) => {
  console.warn(message, detail)
  ErrorTrackingSystem.captureException(error)
}

﹟ 调试

如果你已将 Stimulus 应用程序分配给 window.Stimulus，则可以使用 Stimulus.debug = true 从控制台开启调试模式。你也可以在源代码中配置应用程序实例时设置此标志。

﹟ 浏览器支持

Stimulus 开箱即用地支持所有常青自更新桌面和移动浏览器。Stimulus 3+ 不支持 Internet Explorer 11（但你可以使用 Stimulus 2 与 @stimulus/polyfills 一起使用）。