README

简介

Stimulus 是一个雄心勃勃的 JavaScript 框架。它并不想接管你的整个前端，实际上，它根本不关心渲染 HTML。相反，它旨在通过添加足够的行为来增强 HTML，使其更加出色。Stimulus 与 Turbo 配合使用，提供了一种简洁的解决方案，可以快速创建引人入胜的应用程序，而不需要付出太多努力。它们共同构成了 Hotwire 的核心。

Stimulus for Laravel 使您能够轻松地在导入映射和 JavaScript 打包的应用程序中使用这个低调的框架。它依赖于 Importmap Laravel 通过 ESM 使 Stimulus 可用，或者使用 Vite（一个 Node 兼容的 Laravel）将 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。它还会创建您的第一个 Stimulus 控制器，位于 resources/js/libs/controllers/hello_controller.js。它还会创建一个 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

更新日志

有关最近更改的更多信息，请参阅更新日志

贡献

有关详细信息，请参阅贡献指南

安全漏洞

如果您想报告安全漏洞，请发送电子邮件至tonysm@hey.com

许可证

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

致谢

• Tony Messias
• 所有贡献者