如何在含Turbo、ImportMaps、Stimulus的Rails7应用加载页面专属自定义JS

1. 模块加载时机与Turbo事件冲突 #

你当前在模块内部监听turbo:load，但通过javascript_import_module_tag动态注入模块时，常出现模块加载完成时turbo:load事件已经触发的情况（比如Turbo快速导航后才加载模块），导致初始化函数没执行。

修复方式 #

把模块改为导出初始化函数，导入时立即调用，同时监听Turbo的turbo:render事件处理动态内容：
修改app/javascript/components/table_row.js：

export function initTableRow() {
  // 先移除旧事件，避免重复绑定
  document.querySelectorAll('table tr[data-url]').forEach(row => {
    row.removeEventListener('click', handleClick);
  });

  const rows = document.querySelectorAll('table tr[data-url]');
  rows.forEach(row => {
    row.addEventListener('click', handleClick);
  });
}

function handleClick(e) {
  const url = this.dataset.url;
  window.document.location = url;
}

// 初始加载执行
initTableRow();
// Turbo渲染新内容后重新执行
document.addEventListener('turbo:render', initTableRow);

页面中导入方式不变：

<% content_for(:head) do %>
  <%= javascript_import_module_tag "components/table_row" %>
<% end %>

2. ImportMap动态加载优先级问题 #

你当前的pin_all_from未设置预加载，Turbo快速导航时，模块可能还没加载完成就触发页面渲染，导致初始化失败。

修复方式 #

如果是高频使用的组件，直接在ImportMap中设置预加载：

# config/importmap.rb
pin_all_from "app/javascript/components", under: "components", preload: true

或者在页面导入时单独标记预加载：

<%= javascript_import_module_tag "components/table_row", preload: true %>

3. Turbo Head缓存导致模块未更新 #

Turbo Drive会缓存页面head内容，通过content_for(:head)动态注入的模块标签，可能被缓存的旧head覆盖，新页面无法加载对应模块。

修复方式 #

给模块标签添加data-turbo-track="reload"，强制Turbo重新加载：

<% content_for(:head) do %>
  <%= javascript_import_module_tag "components/table_row", "data-turbo-track": "reload" %>
<% end %>

4. 更适配Rails7的方案：迁移到Stimulus控制器 #

把页面特定逻辑改成Stimulus控制器，完全适配Turbo动态渲染，无需手动监听事件：
创建app/javascript/controllers/table_row_controller.js：

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    this.bindRowClicks();
    // 监听Turbo帧加载事件（如果用了Turbo Frames）
    this.element.addEventListener('turbo:frame-load', this.bindRowClicks.bind(this));
  }

  bindRowClicks() {
    const rows = this.element.querySelectorAll('tr[data-url]');
    rows.forEach(row => {
      row.addEventListener('click', this.handleClick.bind(this));
    });
  }

  handleClick(e) {
    const url = e.currentTarget.dataset.url;
    window.document.location = url;
  }
}

页面中给表格绑定控制器：

<table data-controller="table-row">
  <!-- 表格内容 -->
</table>

调试技巧 #

如果问题还存在，用以下方式排查：

• 打开浏览器控制台，查看网络请求，确认components/table_row.js是否每次都成功加载；
• 在初始化函数开头加console.log('Initializing table rows')，检查是否每次页面渲染都执行；
• 控制台输入Turbo.setDebug(true)开启Turbo调试模式，查看导航过程中的事件触发顺序。

内容的提问来源于stack exchange，提问作者Tintin81