README

介绍

Stimulus 是一个雄心勃勃的JavaScript框架。它并不寻求接管你的整个前端，实际上，它根本不关心渲染HTML。相反，它旨在用最基本的行为增强HTML，使其熠熠生辉。Stimulus与Turbo完美搭配，提供了一种简单的方法来构建快速、引人注目的应用程序，只需最少的努力。它们共同构成了Hotwire的核心。

Stimulus for Laravel使得使用此简洁框架与导入映射和JavaScript捆绑应用程序变得容易。它依赖于Importmap Laravel来通过ESM提供Stimulus，或者使用Node支持的Laravel使用Vite将Stimulus包含在捆绑中。请确保首先安装其中之一！

灵感

此包受到了stimulus-rails gem的启发。

安装步骤

Stimulus Laravel可以通过composer安装

composer require hotwired-laravel/stimulus-laravel

接下来，如果您使用的是新的Laravel应用（如果您不是，请参阅#手动安装），您可以运行安装命令

php artisan stimulus:install

这就完成了。安装命令将自动检测您是否正在使用Importmap Laravel或Vite来管理您的JavaScript依赖项。如果您使用Importmap Laravel，我们将固定Stimulus依赖项，并将本地依赖项发布到您的public/vendor文件夹中，并固定它，这样您就不必注册Stimulus控制器。如果您使用Vite，我们将添加Stimulus依赖项到您的package.json。

安装命令生成一个resources/js/libs/stimulus.js文件，用于安装Stimulus。它还创建了一个位于resources/js/libs/controllers/hello_controller.js的第一个Stimulus控制器。它还会创建一个resources/js/libs/index.js文件，以确保resources/js/controllers/index.js模块被导入。

当使用Importmap Laravel时，resources/js/controllers/index.js将使用发布的stimulus-loading依赖项自动预加载或延迟加载您的Stimulus控制器注册，这样您就无需手动注册它们。当使用Vite时，该文件将在您创建新的Stimulus控制器或手动运行php artisan stimulus:manifest时自动生成。

创建新的控制器

要创建新的Stimulus控制器，请运行

php artisan stimulus:make hello_controller

这应该会为您使用脚手架创建文件，以便准备好控制器。当使用Vite时，它还会自动重新生成resources/js/controllers/index.js文件，以自动注册您创建的新Stimulus控制器。

还有关于如何在DOM中使用控制器的提示注释，例如

import { Controller } from "@hotwired/stimulus"

// Connects to data-controller="hello"
export default class extends Controller {
    connect() {
    }
}

重新生成清单

stimulus:make 命令会为您重新生成 resources/js/controllers/index.js 文件，并注册所有控制器。如果您想手动触发重新生成，可以运行

php artisan stimulus:manifest

手动安装

如果您在一个现有的 Laravel 应用程序上安装此包，逐步手动安装可能很有用。

如果您使用 Importmap Laravel，请遵循Importmap 步骤，否则请遵循Vite 步骤。

1. 无论如何，您都需要首先使用 composer 安装该库

composer require hotwired-laravel/stimulus-laravel

Importmap 步骤

1. 创建 resources/js/controllers/index.js 并按如下方式加载您的控制器

import { Stimulus } from 'libs/stimulus'

// Eager load all controllers defined in the import map under controllers/**/*_controller
import { eagerLoadControllersFrom } from '@hotwired/stimulus-loading'
eagerLoadControllersFrom('controllers', Stimulus)

1. 创建一个包含以下内容的 resources/js/libs/stimulus.js

import { Application } from '@hotwired/stimulus'

const Stimulus = Application.start()

// Configure Stimulus development experience
Stimulus.debug = false

window.Stimulus = Stimulus

export { Stimulus }

1. 创建一个包含以下内容的 resources/js/libs/index.js 文件（如果不存在的话）（或者如果您已经有了这样的文件，请添加以下内容）

import 'controllers'

1. 将以下行添加到您的 resources/js/app.js 文件中

import 'libs'

1. 发布供应商依赖项

php artisan vendor:publish --tag=stimulus-laravel-assets

1. 固定 Stimulus 依赖项

php artisan importmap:pin @hotwired/stimulus

1. 最后，在 routes/importmap.php 文件上固定 stimulus-loading 依赖项

Importmap::pin("@hotwired/stimulus-loading", to: "vendor/stimulus-laravel/stimulus-loading.js", preload: true);

Vite 步骤

1. 创建一个 resources/js/controllers/index.js 并选择您是否想手动注册控制器

   手动注册控制器

   // This file is auto-generated by `php artisan stimulus:install`
   // Run that command whenever you add a new controller or create them with
   // `php artisan stimulus:make controllerName`
   
   import { Stimulus } from '../libs/stimulus'
   
   import HelloController from './hello_controller'
   Stimulus.register('hello', HelloController)

   自动注册控制器

   如果您希望自动注册控制器，可以使用 stimulus-vite-helpers NPM 包。

   // resources/js/controllers/index.js
   
   import { Stimulus } from '../libs/stimulus'
   import { registerControllers } from 'stimulus-vite-helpers'
   
   const controllers = import.meta.glob('./**/*_controller.js', { eager: true })
   
   registerControllers(Stimulus, controllers)

   并安装该 NPM 包

   npm install stimulus-vite-helpers

2. 创建包含以下内容的 resources/js/libs/stimulus.js

import { Application } from '@hotwired/stimulus'

const Stimulus = Application.start()

// Configure Stimulus development experience
Stimulus.debug = false

window.Stimulus = Stimulus

export { Stimulus }

1. 创建（如果不存在的话）并添加以下行到 resources/js/libs/index.js 文件中

import '../controllers'

1. 将以下行添加到您的 resources/js/app.js 文件中

import './libs';

1. 最后，将 Stimulus 包添加到 NPM

npm install @hotwired/stimulus

变更日志

请参阅CHANGELOG 了解最近更改的详细信息。

贡献

请参阅CONTRIBUTING 了解详细信息。

安全漏洞

如果您想报告安全漏洞，请给我发邮件至tonysm@hey.com。

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。

致谢

• Tony Messias
• 所有贡献者