如何在Next.js的NProgress模板中嵌入自定义React组件

你遇到的问题本质是NProgress的template属性只接受HTML字符串，而<MyCustomComponent />是React元素对象，直接插值会被转成[object Object]。下面给两种可行的解决方案：

方案一：把React组件转成HTML字符串传入template #

利用ReactDOMServer.renderToString将React组件渲染成HTML字符串，再传给NProgress的template：

import NProgress from 'nprogress';
import ReactDOMServer from 'react-dom/server';
import CircularProgress from '@mui/material/CircularProgress';

// 将Material UI组件转成HTML字符串
const customSpinner = ReactDOMServer.renderToString(
  <CircularProgress size={24} color="inherit" />
);

// 配置NProgress
NProgress.configure({
  showSpinner: false, // 关闭默认加载动画
  template: `
    <div class="nprogress-container">
      <div class="bar" role="bar"></div>
      <div class="spinner" role="spinner">${customSpinner}</div>
    </div>
  `
});

注意：如果组件依赖内联样式（比如Material UI的动态样式），renderToString会把这些样式一并输出，但要确保这些样式能被正确应用到页面中。

方案二：独立渲染自定义组件（更推荐React生态的方式） #

不用修改NProgress的template，而是通过状态控制自定义组件的显示，配合CSS定位到进度条区域：

1. 首先配置NProgress关闭默认 spinner：

NProgress.configure({ showSpinner: false });

2. 在你的Next.js布局组件（比如layout.js）中，监听NProgress的状态，渲染自定义组件：

'use client';
import { useState, useEffect } from 'react';
import NProgress from 'nprogress';
import CircularProgress from '@mui/material/CircularProgress';

export default function RootLayout({ children }) {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    const startHandler = () => setIsLoading(true);
    const doneHandler = () => setIsLoading(false);

    // 监听NProgress的开始和结束事件
    NProgress.configure({ showSpinner: false });
    window.addEventListener('NProgressStart', startHandler);
    window.addEventListener('NProgressDone', doneHandler);

    return () => {
      window.removeEventListener('NProgressStart', startHandler);
      window.removeEventListener('NProgressDone', doneHandler);
    };
  }, []);

  return (
    <html lang="en">
      <body>
        {children}
        {/* 自定义加载组件，用CSS定位到NProgress的位置 */}
        {isLoading && (
          <div className="custom-nprogress-spinner">
            <CircularProgress size={24} color="primary" />
          </div>
        )}
      </body>
    </html>
  );
}

3. 添加对应的CSS：

.custom-nprogress-spinner {
  position: fixed;
  top: 10px;
  right: 10px;
  z-index: 9999; /* 和NProgress的层级保持一致 */
}

这种方式更符合React的组件思维，不需要处理HTML字符串转换，也能更好地控制组件的状态和样式。

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