# 刺激适度的 JavaScript 框架，通过数据属性将 JS 对象连接到 HTML。 Stimulus 不会渲染 HTML——它通过行为增强服务器渲染的 HTML。心智模型：HTML 是事实来源，JavaScript 控制器附加到元素上，数据属性是接线。 AssetMapper 不需要构建步骤。 ## 快速参考 data-controller="name" 将控制器附加到元素 data-name-target="item" 将元素标记为目标 data-action="event->name#method" 将事件绑定到控制器方法 data-name-key-value="..." 将键入的数据传递给控制器 data-name-key-class="..." 配置CSS类名 data-name-other-outlet=".selector" 引用另一个控制器实例 ## 控制器骨架 // 资产/控制器/example_controller.js 从“@hotwired/stimulus”导入{控制器}；导出默认类扩展控制器{ 静态目标 = ['输入', '输出']; 静态值 = { url: String, 延迟: { 类型: Number, 默认值: 300 } }; 静态类= ['加载']; 静态插座 = ['其他']; 连接（）{ // 当控制器连接到 DOM 时调用 } 断开连接（）{ // 当控制器断开连接时调用——在这里清理 } 提交（事件）{ // 动作方法 } } 文件命名约定：`hello_controller.js` 映射到 `data-controller="hello"`。子目录使用 `--` 作为分隔符：`components/modal_controller.js` 映射到 `data-controller="components--modal"`。 ## HTML 接线示例 ### 基本控制器

<输入数据-hello-target =“名称”类型=“文本”>

### 来自服务器的值 (Twig) 通过值属性将服务器数据传递给控制器。值被键入并自动解析。

可用类型：“字符串”、“数字”、“布尔值”、“数组”、“对象”。值发生变化时会触发“{name}ValueChanged()”回调。 ### 行动格式为“事件->控制器#方法”。每个元素类型都存在默认事件（单击按钮、输入输入、提交表单），因此可以省略该事件。 {# 显式事件#} {# 默认事件（点击按钮）#} {# 对同一元素执行多个操作#} <输入类型=“文本” data-action="focus->field#highlight 模糊->field#normalize input->field#validate"> {# 防止默认#}

{# 键盘快捷键#}

{# 全局事件（窗口/文档）#}

### CSS 类外部化 CSS 类名，使控制器保持通用： <按钮数据控制器=“按钮” data-button-loading-class="opacity-50 光标等待" 数据按钮-active-class =“bg-blue-600” 数据操作=“点击->按钮#提交”> 提交 // 在控制器中 this.element.classList.add(...this.loadingClasses); ### 多个控制器一个元素可以有多个控制器：

...

### Outlets（跨控制器通信）通过 CSS 选择器引用其他控制器实例：

歌曲 1
歌曲 2

// 在玩家控制器中静态插座 = ['播放列表']; 播放下一个（）{ const Tracks = this.playlistOutlet.trackTargets; // ... } ### 延迟加载（严重依赖）仅当元素出现在视口中时才加载控制器 JS。用于具有严重依赖性的控制器（图表库、编辑器、地图）。 /*stimulusFetch: '懒惰' */ 从“@hotwired/stimulus”导入{控制器}；从“chart.js”导入图表；导出默认类扩展控制器{ 连接（）{ // Chart.js 仅当该元素进入视口时才加载 } } `/*stimulusFetch: 'lazy' */` 注释必须是文件的第一行。 ## Symfony / Twig 集成原始数据属性是推荐的方法——它们在任何地方都适用，易于阅读，并且不需要特殊的帮助。 {# 原始属性（首选）#}

Twig 助手适用于复杂情况或以编程方式生成属性时： {#树枝助手#}

{# 链接多个控制器#}

{# 目标和操作助手#} <输入{{stimulus_target('搜索','查询')}}> <按钮 {{stimulus_action('搜索', '提交') }}> ## 关键原则 **HTML 驱动，JS 响应。** 控制器不创建标记——它们将行为附加到现有的 HTML。如果您发现自己在控制器中生成 DOM，请考虑 TwigComponent 还是 LiveComponent 哪个更好。 **一个控制器，一个关注点。** 下拉控制器处理下拉菜单。工具提示控制器处理工具提示。在同一元素上组成多个控制器，而不是构建大型控制器。 **在disconnect()中进行清理。**如果`connect()`添加了事件监听器、计时器或第三方库实例，则`disconnect()`必须删除它们。当页面更改时，涡轮导航将断开并重新连接控制器。 **值优于数据属性。** 对于控制器需要读取或监视的数据，使用刺激值（类型化，带有更改回调）而不是原始“data-*”属性。 ## 参考文献 * **完整 API** （生命周期、目标、值、操作、类、出口）：[references/api.md]() * **模式**（反跳、获取、模态、表单等）：[references/patterns.md]() * **陷阱**（常见错误、调试、Turbo 兼容性）：[references/gotchas.md]()

刺激

包含技能