React懒加载触发时如何保留旧UI并显示Suspense加载spinner

默认React.lazy + Suspense的组合在懒加载资源触发pending状态时，会直接卸载Suspense边界内的已渲染内容，替换为fallback节点，这就是旧UI直接消失的根本原因。要实现加载阶段保留旧UI、叠加加载提示，加载完成后再替换UI，有两种成熟的函数组件/Hooks实现方案：

方案1：React 18+ 原生useTransition实现（推荐） #

React 18提供的useTransition Hook支持将状态更新标记为非紧急的过渡更新，过渡期间React会在后台准备新的UI，在新UI可渲染前完全保留当前已展示的旧内容，不会触发Suspense的fallback替换逻辑，我们只需要通过Hook返回的pending状态自行控制加载提示的展示即可。

import { lazy, Suspense, useState, useTransition } from 'react';
// 正常用React.lazy导入懒加载组件
const LazyHeavyPage = lazy(() => import('./HeavyPage'));

export default function App() {
  const [showHeavyPage, setShowHeavyPage] = useState(false);
  // 拿到过渡加载状态、启动过渡的方法
  const [isLoading, startTransition] = useTransition();

  const handleEnterHeavyPage = () => {
    // 将触发懒加载的状态更新包裹在过渡回调中
    startTransition(() => {
      setShowHeavyPage(true);
    });
  };

  return (
    <div className="app-container">
      <button onClick={handleEnterHeavyPage} disabled={isLoading}>
        {isLoading ? '页面加载中' : '进入重页面'}
      </button>
      {/* Suspense边界包裹内容区，fallback设为null，不需要默认替换逻辑 */}
      <Suspense fallback={null}>
        <div 
          className="content-area"
          style={{ position: 'relative', opacity: isLoading ? 0.6 : 1 }}
        >
          {/* 加载未完成时一直展示旧UI，加载完成自动替换为懒加载组件 */}
          {showHeavyPage ? <LazyHeavyPage /> : <div className="home-ui">原有首页内容</div>}
          {/* 加载期间在旧UI上层叠加spinner，样式可自行调整 */}
          {isLoading && (
            <div 
              className="spinner"
              style={{
                position: 'absolute',
                inset: 0,
                display: 'grid',
                placeItems: 'center',
                background: 'rgba(255,255,255,0.4)'
              }}
            >
              加载中...
            </div>
          )}
        </div>
      </Suspense>
    </div>
  );
}

核心逻辑说明：

• 不要依赖Suspense的fallback渲染加载提示，将fallback设为null，避免触发内容替换
• 所有会触发懒加载组件挂载的状态更新，都要放在startTransition回调中执行
• isLoading状态完全可控，可以根据需求实现半透明遮罩、顶部进度条、角落加载提示等任意效果，不会影响旧UI的交互和展示

方案2：React 17及以下版本 自定义懒加载包装实现 #

低版本React没有过渡更新能力，可以通过自定义高阶组件封装懒加载逻辑，自行控制资源加载时机，等资源完全加载完成后再触发UI切换，全程保留旧UI。

import { useState, useEffect } from 'react';

/**
 * 自定义懒加载包装HOC
 * @param {() => Promise} importFunc 懒加载导入函数
 * @returns 包装后的懒加载组件，自带preload预加载方法
 */
function customLazy(importFunc) {
  let LoadedComponent = null;
  let loadError = null;
  let pendingLoadPromise = null;
  const subscriberSet = new Set();

  // 触发资源加载
  const triggerLoad = () => {
    if (!pendingLoadPromise) {
      pendingLoadPromise = importFunc()
        .then(mod => {
          LoadedComponent = mod.default;
          subscriberSet.forEach(update => update());
        })
        .catch(err => {
          loadError = err;
          subscriberSet.forEach(update => update());
        });
    }
    return pendingLoadPromise;
  };

  const WrappedComponent = (props) => {
    const [, forceRender] = useState({});

    useEffect(() => {
      if (!LoadedComponent && !loadError) triggerLoad();
      const update = () => forceRender({});
      subscriberSet.add(update);
      return () => subscriberSet.delete(update);
    }, []);

    if (loadError) throw loadError;
    if (LoadedComponent) return <LoadedComponent {...props} />;
    throw pendingLoadPromise;
  };

  WrappedComponent.preload = triggerLoad;
  return WrappedComponent;
}

// 使用示例
const LazyHeavyPage = customLazy(() => import('./HeavyPage'));
export default function App() {
  const [showHeavyPage, setShowHeavyPage] = useState(false);
  const [isLoading, setIsLoading] = useState(false);

  const handleEnterHeavyPage = async () => {
    setIsLoading(true);
    // 先预加载资源，加载完成前不切换UI
    await LazyHeavyPage.preload();
    // 资源就绪后再更新状态切换UI，全程旧UI保留
    setShowHeavyPage(true);
    setIsLoading(false);
  };

  return (
    <div className="app-container">
      <button onClick={handleEnterHeavyPage} disabled={isLoading}>
        {isLoading ? '页面加载中' : '进入重页面'}
      </button>
      <div 
        className="content-area"
        style={{ position: 'relative', opacity: isLoading ? 0.6 : 1 }}
      >
        {showHeavyPage ? <LazyHeavyPage /> : <div className="home-ui">原有首页内容</div>}
        {isLoading && (
          <div 
            className="spinner"
            style={{
              position: 'absolute',
              inset: 0,
              display: 'grid',
              placeItems: 'center',
              background: 'rgba(255,255,255,0.4)'
            }}
          >
            加载中...
          </div>
        )}
      </div>
    </div>
  );
}

实现注意事项 #

• 路由懒加载场景同样适用：用useTransition包裹路由跳转的状态更新，即可实现路由切换时保留当前页面、叠加加载提示，避免页面白屏或内容突然消失
• 如果需要保留旧UI的交互能力，不要给内容区加透传的遮罩层，可将spinner固定在角落或者顶部，加载期间用户依然可以操作旧页面内容
• 不需要额外引入第三方加载状态库，上述两种方案完全覆盖组件、路由等所有懒加载场景的保活需求

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