feat: keep alive

Author: diandian18

README-en.md

@@ -7,6 +7,7 @@
 [🔗Live Preview](https://template.react-antd-console.site) | [📒Documentation](https://doc.react-antd-console.site) | [中文](./README.md) | English
 
 Now supports **React 19**!
+Now supports **KeepAlive** (experimental)!
 
 <p align="center">
   <img width="100%" src="https://static.react-antd-console.site/template.png?g=1">
@@ -41,6 +42,7 @@ This project minimally encapsulates essential features like login, authenticatio
 - **💾 Data Management**: Layered (data and view) architecture design. The data management solution theoretically supports any UI rendering library/framework (including but not limited to React/Vue/Angular)
 - **🎨 Theme Customization**: Supports arbitrary color switching in dark/light modes
 - **🏷️ Multi-Tabs**: Draggable multi-tabs with persistence, right-click menus, etc.
+- **✨ Keep alive**: Supports page state caching, retaining the page state before switching when returning to the page.
 - **🎬 Elegant Animations**: Supports route transition animations, tab, menu, and button animations
 - **🧩 Other Features**: `Responsive design`, `internationalization`, `Mock`, `environment configuration`, `engineering standards`, etc.
 

README.md

@@ -7,6 +7,7 @@
 [🔗在线预览](https://template.react-antd-console.site) | [📒文档](https://doc.react-antd-console.site) | 中文 | [English](./README-en.md)
 
 已支持**React 19**！
+已支持**KeepAlive**（实验性）！
 
 <p align="center">
   <img width="100%" src="https://static.react-antd-console.site/template.png?b=1">
@@ -39,6 +40,7 @@ react-antd-console 是一个后台管理系统的前端解决方案，封装了
 - **💾 数据管理**: `分层`（数据和视图）架构设计，数据管理方案理论上支持接入任意UI渲染库/框架（包括不限于React/Vue/Angular）
 - **🎨 颜色换肤**: 支持深/浅肤色模式下的任意颜色切换
 - **🏷️ 多标签页**: 可拖拽的多标签页，支持持久化、右键菜单等
+- **✨ 页面缓存**: 支持页面状态缓存，切换回页面后，保留切换前的页面状态
 - **🎬 优雅动画**: 支持路由切换动画，标签页、菜单、功能按钮动画等
 - **🧩 其他功能**: 如`响应式设计`、`国际化`、`Mock`、`环境配置`、`工程化规范`等
 

docs/.vitepress/config.ts

@@ -46,6 +46,7 @@ export default withMermaid({
           { text: 'Icon', link: '/development/icon' },
           { text: '国际化', link: '/development/i18n' },
           { text: '搜索列表', link: '/development/search-list' },
+          { text: 'KeepAlive', link: '/development/keep-alive' },
           { text: '常见问题', link: '/development/qa' },
         ]
       }

docs/development/keep-alive.md

@@ -0,0 +1,60 @@
+# KeepAlive
+
+`keepAlive` 功能，类似 `vue` 的 `KeepAlive` 功能，用于在组件间进行切换时，缓存被移除的组件实例
+
+## 启用
+
+使用 `KeepAlive` 能力需要安装 `react` 和 `react-dom` 的 `experimental` 版本:
+
+```shell
+npm i react@experimental react-dom@experimental -S --legacy-peer-deps
+```
+
+在 `ConsoleLayout` 组件中引入并使用 `KeepAliveOutlet` 代替 `react-router` 的 `Outlet`:
+
+::: code-group
+
+```tsx [src/layouts/ConsoleLayout/index.tsx]
+import { Outlet } from 'react-router'; // [!code --]
+import KeepAliveOutlet from '@/components/KeepAliveOutlet'; // [!code ++]
+import { motion } from 'framer-motion'; // [!code --]
+import { Animations } from './animations'; // [!code --]
+
+return (
+  <div>
+    <div className="console-layout__right-side">
+      {/* [!code --] */}
+      <div className="console-layout__right-side-main-wrap"> 
+        {refreshing ? null : ( // [!code --]
+          <motion.div // [!code --]
+            className={ClassName__ConsoleLayout_RightSideMain} // [!code --]
+            key={location.pathname} // [!code --]
+            variants={Animations['fadeIn']} // [!code --]
+            initial="initial" // [!code --]
+            animate="in" // [!code --]
+            transition={{ type: 'tween', duration: 0.15, ease: 'easeIn' }} // [!code --]
+          {/* [!code --] */}
+          >
+            {/* [!code --] */}
+            <Outlet />
+          </motion.div> // [!code --]
+        {/* [!code --] */}
+        )}
+      {/* [!code --] */}
+      </div>
+      {/* [!code ++] */}
+      <div className={`console-layout__right-side-main-wrap ${ClassName__ConsoleLayout_RightSideMain}`}>
+        {/* [!code ++] */}
+        {refreshing ? null : <KeepAliveOutlet />}
+      {/* [!code ++] */}
+      </div>
+    </div>
+  </div>
+);
+```
+
+:::
+
+## 查看效果
+
+在 `/home/alive` 页的输入框输入一个数字，切换到其他页面，再切换回来，看看数字是否仍然在

docs/guide/what.md

@@ -21,6 +21,7 @@ react-antd-console 是一个后台管理系统的前端解决方案，封装了
 - **💾 数据管理**: `分层`（数据和视图）架构设计，数据管理方案理论上支持接入任意UI渲染库/框架（包括不限于React/Vue/Angular）
 - **🎨 颜色换肤**: 支持深/浅肤色模式下的任意颜色切换
 - **🏷️ 多标签页**: 可拖拽的多标签页，支持持久化、右键菜单等
+- **✨ 页面缓存**: 支持页面状态缓存，切换回页面后，保留切换前的页面状态
 - **🎬 优雅动画**: 支持路由切换动画，标签页、菜单、功能按钮动画等
 - **🧩 其他功能**: 如`响应式设计`、`国际化`、`Mock`、`环境配置`、`工程化规范`等
 

package.json

@@ -48,9 +48,9 @@
     "i18next": "^25.1.2",
     "immer": "^10.1.1",
     "nprogress": "^0.2.0",
-    "react": "^19.1.0",
+    "react": "^0.0.0-experimental-8ce15b0f-20250522",
     "react-contexify": "^6.0.0",
-    "react-dom": "^19.1.0",
+    "react-dom": "^0.0.0-experimental-8ce15b0f-20250522",
     "react-i18next": "^15.5.1",
     "react-router": "^7.6.0",
     "react-router-toolset": "^0.0.9",
@@ -89,4 +89,4 @@
       "public"
     ]
   }
-}
+}

src/assets/svg/kun.svg

@@ -0,0 +1,81 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+import React, { useState, useEffect, useRef } from 'react';
+import { useOutlet, useLocation } from 'react-router';
+// import ActivityComponent from './Activity.js';
+
+// @ts-ignore
+// const Activity = React.unstable_Activity || ActivityComponent;
+const Activity = React.unstable_Activity;
+interface ActivityItem {
+  outlet: React.ReactElement | null;
+  key: string;
+  pathname: string;
+}
+
+interface OutletProps {
+  // The limitation number of outlets to keep alive.
+  limit?: number;
+  // When paths is configured, only the specified paths will be kept alive.
+  paths?: string[];
+}
+
+const OUTLET_LIMIT = 500;
+
+export default function KeepAliveOutlet(props: OutletProps) {
+  if (!Activity) {
+    throw new Error('`<KeepAliveOutlet />` now requires react experimental version. Please install it first.');
+  }
+  const [outlets, setOutlets] = useState<ActivityItem[]>([]);
+  const location = useLocation();
+  const outlet = useOutlet();
+  const outletLimit = props.limit || OUTLET_LIMIT;
+  const keepAlivePaths = props.paths;
+
+  // Save the first outlet for SSR hydration.
+  const outletRef = useRef<ActivityItem | null>({
+    key: location.key,
+    pathname: location.pathname,
+    outlet,
+  });
+  useEffect(() => {
+    // If outlets is empty, save the first outlet for SSR hydration,
+    // and should not call setOutlets to avoid re-render.
+    if (outlets.length !== 0 ||
+      outletRef.current?.pathname !== location.pathname) {
+      let currentOutlets = outletRef.current ? [outletRef.current] : outlets;
+      // Check current path if exsist before filter, to avoid infinite setOutlets loop.
+      const result = currentOutlets.some(o => o.pathname === location.pathname);
+      if (keepAlivePaths && keepAlivePaths.length > 0) {
+        currentOutlets = currentOutlets.filter(o => keepAlivePaths.includes(o.pathname));
+      }
+      if (!result) {
+        setOutlets([
+          ...currentOutlets,
+          {
+            key: location.key,
+            pathname: location.pathname,
+            outlet,
+          },
+        ].slice(-outletLimit));
+        outletRef.current = null;
+      }
+    }
+  }, [location.pathname, location.key, outlet, outlets, outletLimit, keepAlivePaths]);
+
+  // Render initail outlet for SSR hydration.
+  const renderOutlets = outlets.length === 0 ? [outletRef.current] : outlets;
+
+  return (
+    <>
+      {
+        renderOutlets.map((o) => {
+          return (
+            <Activity key={o?.key} mode={location.pathname === o?.pathname ? 'visible' : 'hidden'}>
+              {o?.outlet}
+            </Activity>
+          );
+        })
+      }
+    </>
+  );
+}

src/components/KeepAliveOutlet/index.tsx

@@ -1,5 +1,6 @@
 import { FC } from 'react';
-import { Outlet } from 'react-router';
+// import { Outlet } from 'react-router';
+import KeepAliveOutlet from '@/components/KeepAliveOutlet';
 import SideMenu from '@/layouts/SideMenu';
 import withAuth from '@/components/business/withAuth';
 import Header from '@/layouts/Header';
@@ -9,8 +10,8 @@ import { baseModel } from '@/models/base';
 import { ClassName__ConsoleLayout_RightSideMain } from './consts';
 import Provider from './store/Provider';
 import Tabs from '@/layouts/Tabs';
-import { motion } from 'framer-motion';
-import { Animations } from './animations';
+// import { motion } from 'framer-motion';
+// import { Animations } from './animations';
 import Collapse from '../Collapse';
 import classNames from 'classnames';
 import { isMobile } from '@/utils/browser';
@@ -40,7 +41,7 @@ const ConsoleLayout: FC = () => {
           <Collapse />
           <Tabs />
         </div>
-        <div className="console-layout__right-side-main-wrap">
+        {/* <div className="console-layout__right-side-main-wrap">
           {refreshing ? null : (
             <motion.div
               className={ClassName__ConsoleLayout_RightSideMain}
@@ -53,6 +54,9 @@ const ConsoleLayout: FC = () => {
               <Outlet />
             </motion.div>
           )}
+        </div> */}
+        <div className={`console-layout__right-side-main-wrap ${ClassName__ConsoleLayout_RightSideMain}`}>
+          {refreshing ? null : <KeepAliveOutlet />}
         </div>
         <Footer />
       </div>

src/layouts/ConsoleLayout/index.tsx

@@ -7,6 +7,7 @@ function formatPermissions(permissions: string[]) {
   return {
     home: set.has('home'),
     homeIndex: set.has('home:index'),
+    homeAlive: set.has('home:alive'),
     homeGrid: set.has('home:grid'),
     profile: set.has('profile'),