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
• 所有贡献者