Back to Details

stimulus

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<essential_principles>
<essential_principles>

How Stimulus Works

Stimulus 工作原理

Stimulus is a modest JavaScript framework that connects JavaScript behavior to HTML via data attributes. It doesn't render HTML—it enhances existing HTML with interactivity.
Stimulus是一款轻量型JavaScript框架，通过数据属性将JavaScript行为与HTML关联起来。它不负责渲染HTML——而是为现有HTML添加交互性。

1. HTML-First Philosophy

1. HTML优先理念

State lives in the DOM, not JavaScript. Controllers can be discarded between page changes and reinitialize from cached HTML. Design controllers to read state from data attributes and restore themselves on reconnection.
状态存储在DOM中，而非JavaScript中。在页面切换时，控制器可以被销毁，并从缓存的HTML中重新初始化。设计控制器时，应从数据属性中读取状态，并在重新连接时恢复自身状态。

2. Convention Over Configuration

2. 约定优于配置

Stimulus uses predictable naming conventions:
  • Controller: 
    data-controller="clipboard"
  • Targets: 
    data-clipboard-target="source"
  • Actions: 
    data-action="click->clipboard#copy"
  • Values: 
    data-clipboard-url-value="/api/copy"
  • Classes: 
    data-clipboard-supported-class="visible"
  • Outlets: 
    data-clipboard-result-outlet="#result"
Stimulus采用可预测的命名约定：
  • 控制器：
    data-controller="clipboard"
  • 目标：
    data-clipboard-target="source"
  • 动作：
    data-action="click->clipboard#copy"
  • 值：
    data-clipboard-url-value="/api/copy"
  • 类：
    data-clipboard-supported-class="visible"
  • 出口：
    data-clipboard-result-outlet="#result"

3. Lifecycle Awareness

3. 生命周期感知

Controllers have three lifecycle callbacks:
  • initialize()
    - Called once when controller is instantiated
  • connect()
    - Called when controller is connected to DOM (can happen multiple times with Turbo)
  • disconnect()
    - Called when controller is removed from DOM
Always clean up in 
disconnect()
what you set up in 
connect()
(timers, event listeners, observers).
控制器拥有三个生命周期回调函数：
  • initialize()
    - 控制器实例化时调用一次
  • connect()
    - 控制器连接到DOM时调用（在Turbo环境下可能会被多次调用）
  • disconnect()
    - 控制器从DOM中移除时调用
务必在
disconnect()
中清理
connect()
中设置的内容（计时器、事件监听器、观察者）。

4. Scope Isolation

4. 作用域隔离

Each controller only sees elements within its scope (the element with 
data-controller
and its descendants). Targets must be within scope. Use outlets to communicate across controller boundaries.
每个控制器只能看到其作用域内的元素（即带有
data-controller
的元素及其后代元素）。目标必须位于作用域内。使用出口（outlets）实现跨控制器边界的通信。

5. Progressive Enhancement

5. 渐进式增强

Build HTML that works without JavaScript first. Use Stimulus to enhance, not replace. Check for API support before using features:
javascript
connect() {
  if ("clipboard" in navigator) {
    this.element.classList.add(this.supportedClass)
  }
}
</essential_principles>
<intake> **What would you like to do?**
  1. Build a new controller
  2. Debug an existing controller
  3. Add a feature to a controller
  4. Review controller(s) for best practices
  5. Optimize performance
  6. Implement a UI pattern (modal, dropdown, tabs, etc.)
  7. Integrate with Turbo
  8. Handle forms
  9. Something else
Wait for response before proceeding. </intake>
<routing> | Response | Workflow | |----------|----------| | 1, "new", "create", "build", "start" | `workflows/build-new-controller.md` | | 2, "broken", "fix", "debug", "crash", "bug", "not working" | `workflows/debug-controller.md` | | 3, "add", "feature", "extend", "modify" | `workflows/add-feature.md` | | 4, "review", "audit", "check", "best practices", "patterns" | `workflows/review-controller.md` | | 5, "slow", "optimize", "performance", "fast", "memory" | `workflows/optimize-performance.md` | | 6, "modal", "dropdown", "tabs", "accordion", "toggle", "UI", "pattern" | `workflows/implement-ui-pattern.md` | | 7, "turbo", "frames", "streams", "hotwire" | `workflows/integrate-turbo.md` | | 8, "form", "validation", "submit", "input" | `workflows/handle-forms.md` | | 9, other | Clarify, then select workflow or references |
After reading the workflow, follow it exactly. </routing>
<verification_loop>
首先构建无需JavaScript即可正常工作的HTML。使用Stimulus进行增强，而非替代。在使用特性前先检查API支持情况：
javascript
connect() {
  if ("clipboard" in navigator) {
    this.element.classList.add(this.supportedClass)
  }
}
</essential_principles>
<intake> **你想要执行什么操作？**
  1. 构建新控制器
  2. 调试现有控制器
  3. 为控制器添加功能
  4. 审查控制器的最佳实践
  5. 优化性能
  6. 实现UI模式（模态框、下拉菜单、标签页等）
  7. 与Turbo集成
  8. 处理表单
  9. 其他操作
请先回复，再继续下一步。 </intake>
<routing> | 回复内容 | 工作流 | |----------|----------| | 1, "new", "create", "build", "start" | `workflows/build-new-controller.md` | | 2, "broken", "fix", "debug", "crash", "bug", "not working" | `workflows/debug-controller.md` | | 3, "add", "feature", "extend", "modify" | `workflows/add-feature.md` | | 4, "review", "audit", "check", "best practices", "patterns" | `workflows/review-controller.md` | | 5, "slow", "optimize", "performance", "fast", "memory" | `workflows/optimize-performance.md` | | 6, "modal", "dropdown", "tabs", "accordion", "toggle", "UI", "pattern" | `workflows/implement-ui-pattern.md` | | 7, "turbo", "frames", "streams", "hotwire" | `workflows/integrate-turbo.md` | | 8, "form", "validation", "submit", "input" | `workflows/handle-forms.md` | | 9, other | 先明确需求，再选择工作流或参考资料 |
阅读工作流后，请严格按照其执行。 </routing>
<verification_loop>

After Every Change

每次修改后需执行的检查

  1. Does it connect? Check browser console for Stimulus connection messages
  2. Do targets resolve? Verify 
    this.hasXxxTarget
    returns true
  3. Do actions fire? Add temporary console.log in action methods
  4. Does it clean up? Navigate away and back - no errors, no memory leaks
javascript
// Debug mode - add to application.js
application.debug = true
Report to the user:
  • "Controller connects: ✓"
  • "Targets found: X of Y"
  • "Actions working: ✓/✗"
  • "Ready for testing" </verification_loop>
<reference_index>
  1. 是否能正常连接？ 检查浏览器控制台中的Stimulus连接消息
  2. 目标是否能解析？ 验证
    this.hasXxxTarget
    返回true
  3. 动作是否触发？ 在动作方法中添加临时的console.log
  4. 是否能正确清理？ 导航离开再返回页面——无错误、无内存泄漏
javascript
// 调试模式 - 添加到application.js
application.debug = true
向用户反馈：
  • "控制器已连接: ✓"
  • "找到目标数: X/Y"
  • "动作正常工作: ✓/✗"
  • "准备就绪，可以测试" </verification_loop>
<reference_index>

Domain Knowledge

领域知识

All in 
references/
:
Core APIs: architecture.md, targets.md, values.md, actions.md, outlets.md, classes.md Ecosystem: stimulus-use.md, ui-patterns.md Integration: turbo-integration.md Quality: testing-debugging.md, performance.md, anti-patterns.md </reference_index>
<workflows_index>
所有内容位于
references/
目录下：
核心API： architecture.md, targets.md, values.md, actions.md, outlets.md, classes.md 生态系统： stimulus-use.md, ui-patterns.md 集成： turbo-integration.md 质量： testing-debugging.md, performance.md, anti-patterns.md </reference_index>
<workflows_index>

Workflows

工作流

All in 
workflows/
:
FilePurpose
build-new-controller.mdCreate new controller from scratch
debug-controller.mdFind and fix bugs
add-feature.mdAdd functionality to existing controller
review-controller.mdAudit controllers for best practices
optimize-performance.mdProfile and speed up
implement-ui-pattern.mdBuild modals, dropdowns, tabs, etc.
integrate-turbo.mdWork with Turbo Frames/Streams
handle-forms.mdForm validation and submission
</workflows_index>
所有内容位于
workflows/
目录下：
文件用途
build-new-controller.md从零开始创建新控制器
debug-controller.md查找并修复bug
add-feature.md为现有控制器添加功能
review-controller.md审查控制器的最佳实践
optimize-performance.md性能分析与优化
implement-ui-pattern.md构建模态框、下拉菜单、标签页等
integrate-turbo.md与Turbo Frames/Streams协作
handle-forms.md表单验证与提交
</workflows_index>