在React/Inertia环境中排查Preline UI JavaScript函数失效问题

核心问题 #

使用Laravel、Vite、React、Inertia技术栈时，基于HeadlessUI过渡效果实现的Preline折叠侧边栏无法正常触发Preline交互函数。仅在页面首次加载时通过组件初始化能临时解决，但Inertia单页导航后，新渲染的组件会重复出现同类问题。

解决方案 #

1. 全局监听Inertia导航事件，自动重新初始化Preline #

Inertia是单页应用，页面切换不会刷新整个页面，Preline的初始化逻辑仅在首次加载执行，后续导航后新DOM元素未被初始化。通过监听Inertia的page:finish事件，在每次页面切换完成后重新触发Preline的自动初始化：

// 在你的Inertia配置文件（如resources/js/app.js）中添加
import { router } from '@inertiajs/react';

// 监听页面导航完成事件
router.on('page:finish', () => {
  // 调用Preline的全局初始化方法
  if (typeof window.HSStaticMethods !== 'undefined') {
    window.HSStaticMethods.autoInit();
  }
});

2. 组件级适配HeadlessUI过渡的异步渲染 #

HeadlessUI的过渡效果是异步执行的，Preline初始化时可能目标DOM元素还未完成渲染。在侧边栏组件中，通过useEffect配合定时器（匹配过渡时长），等待元素渲染完成后手动初始化对应组件：

import { useEffect, useRef } from 'react';
import { Transition } from '@headlessui/react';

const Sidebar = ({ isOpen }) => {
  const sidebarContainer = useRef(null);
  const collapseTrigger = useRef(null);

  useEffect(() => {
    // 等待HeadlessUI过渡完成（这里设置300ms匹配过渡动画时长，可根据实际调整）
    const initTimer = setTimeout(() => {
      // 初始化折叠组件
      if (typeof window.HSCollapse !== 'undefined' && collapseTrigger.current) {
        new window.HSCollapse(collapseTrigger.current);
      }
      // 初始化侧边栏内所有Preline组件
      if (typeof window.HSStaticMethods !== 'undefined' && sidebarContainer.current) {
        window.HSStaticMethods.autoInit(sidebarContainer.current);
      }
    }, 300);

    return () => clearTimeout(initTimer);
  }, [isOpen]); // 监听侧边栏显示状态，状态变化时重新初始化

  return (
    <Transition
      show={isOpen}
      enter="transition-all duration-300 ease-in-out"
      enterFrom="translate-x-full"
      enterTo="translate-x-0"
      leave="transition-all duration-300 ease-in-out"
      leaveFrom="translate-x-0"
      leaveTo="translate-x-full"
    >
      <div ref={sidebarContainer} className="fixed top-0 right-0 h-full w-64 bg-white shadow-lg">
        {/* 折叠触发按钮 */}
        <button 
          ref={collapseTrigger}
          data-hs-collapse="#sidebar-nav-links"
          className="p-2"
        >
          折叠导航
        </button>
        {/* 导航链接容器 */}
        <div id="sidebar-nav-links" className="hidden p-4">
          <a href="#" className="block py-2">首页</a>
          <a href="#" className="block py-2">设置</a>
        </div>
      </div>
    </Transition>
  );
};

export default Sidebar;

3. 优化Inertia初始化逻辑，确保每次渲染后执行Preline初始化 #

修改Inertia的setup函数，在每次App组件渲染完成后，主动触发Preline初始化，覆盖首次加载和后续导航的场景：

createInertiaApp({
    title: (title) => `${appName} | ${title}`,
    resolve: (name) =>
        resolvePageComponent(
            `./Pages/${name}.jsx`,
            import.meta.glob("./Pages/**/*.jsx")
        ),
    setup({ el, App, props }) {
        const root = createRoot(el);

        root.render(<App {...props} />);

        // 每次渲染后初始化Preline
        if (typeof window.HSStaticMethods !== 'undefined') {
          window.HSStaticMethods.autoInit();
        }

        delete el.dataset.page;
    },
    progress: {
         color: "#fbbf24",
    },
});

原理说明 #

• Inertia单页导航不会重新加载全局JS，因此Preline的初始化代码仅在首次执行，后续新DOM元素需要重新触发初始化。
• HeadlessUI的过渡动画是异步的，DOM元素会延迟渲染，直接初始化会找不到目标节点，需要等待动画完成后再执行Preline的初始化逻辑。

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