# keepalive-for-react **Repository Path**: collectors/keepalive-for-react ## Basic Information - **Project Name**: keepalive-for-react - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-22 - **Last Updated**: 2025-12-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

keepalive-for-react logo

React KeepAlive 组件

一个类似Vue中keep-alive的React KeepAlive组件

[English](./README.md) | 中文 [![NPM版本](https://img.shields.io/npm/v/keepalive-for-react.svg?style=flat)](https://npmjs.com/package/keepalive-for-react) [![NPM下载量](https://img.shields.io/npm/dm/keepalive-for-react.svg?style=flat)](https://npmjs.com/package/keepalive-for-react) ## 包信息 | 包名 | 版本 | 描述 | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | | [keepalive-for-react](./packages/core) | [![NPM版本](https://img.shields.io/npm/v/keepalive-for-react.svg?style=flat)](https://npmjs.com/package/keepalive-for-react) | 核心keepalive功能 | | [keepalive-for-react-router](./packages/router) | [![NPM版本](https://img.shields.io/npm/v/keepalive-for-react-router.svg?style=flat)](https://npmjs.com/package/keepalive-for-react-router) | React Router集成 | ## 特性 - 支持react-router-dom v6+ 或 react-router v7+ - 支持React v16+ ~ v18+ (v19.2 Activity component support [v5.0.0]) - 支持Suspense和懒加载导入 - 支持错误边界 - 支持自定义容器 - 支持使用className `active`和`inactive`进行切换动画过渡 - 简单实现,无需任何额外依赖和hack方式 - 压缩后仅6KB大小 - 支持中断state Effect当组件不活动时 (v5.0.0) ## 注意事项 - **版本兼容性**： - React 18 请使用 `keepalive-for-react@4.x.x` - React 19.2+ 请使用 `keepalive-for-react@5.x.x` - 请勿使用 ,它在开发模式下无法与keepalive-for-react一起工作。因为它可能会导致一些意外行为。 - 在路由中仅支持react-router-dom v6+ ## 安装 ```bash npm install keepalive-for-react ``` ```bash yarn add keepalive-for-react ``` ```bash pnpm add keepalive-for-react ``` ## 使用 ### 配合react-router-dom v6+ 或 react-router v7+使用 1. 安装react-router-dom v6+ 或 react-router v7+ ```bash # v6+ npm install react-router-dom keepalive-for-react keepalive-for-react-router@1.x.x # v7+ npm install react-router keepalive-for-react keepalive-for-react-router@2.x.x ``` 2. 在项目中使用KeepAlive ```tsx // v6+ keepalive-for-react-router@1.x.x // v7+ keepalive-for-react-router@2.x.x import KeepAliveRouteOutlet from "keepalive-for-react-router"; function Layout() { return (
); } ``` 或者 ```tsx import { useMemo } from "react"; import { useLocation } from "react-router-dom"; import { KeepAlive, useKeepAliveRef } from "keepalive-for-react"; function Layout() { const location = useLocation(); const aliveRef = useKeepAliveRef(); const outlet = useOutlet(); // 确定哪个路由组件处于活动状态 const currentCacheKey = useMemo(() => { return location.pathname + location.search; }, [location.pathname, location.search]); return (
}> {outlet}
); } ``` 详情请参见 [examples/react-router-dom-simple-starter](./examples/react-router-dom-simple-starter) [![在StackBlitz中打开](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/react-router-dom-simple-starter) ### 在简单标签页中 ```bash npm install keepalive-for-react ``` ```tsx const tabs = [ { key: "tab1", label: "标签1", component: Tab1, }, { key: "tab2", label: "标签2", component: Tab2, }, { key: "tab3", label: "标签3", component: Tab3, }, ]; function App() { const [currentTab, setCurrentTab] = useState("tab1"); const tab = useMemo(() => { return tabs.find(tab => tab.key === currentTab); }, [currentTab]); return (
{/* ... */} {tab && }
); } ``` 详情请参见 [examples/simple-tabs-starter](./examples/simple-tabs-starter) [![在StackBlitz中打开](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/simple-tabs-starter) ## KeepAlive 属性 类型定义 ```tsx interface KeepAliveProps { // 确定哪个组件处于活动状态 activeCacheKey: string; children?: KeepAliveChildren; /** * 最大缓存数量 默认10 */ max?: number; exclude?: Array | string | RegExp; include?: Array | string | RegExp; onBeforeActive?: (activeCacheKey: string) => void; customContainerRef?: RefObject; cacheNodeClassName?: string; containerClassName?: string; errorElement?: ComponentType<{ children: ReactNode; }>; /** * 过渡效果 默认false */ transition?: boolean; /** * 使用view transition来过渡组件 默认false * @see https://developer.chrome.com/docs/web-platform/view-transitions/ */ viewTransition?: boolean; /** * 过渡时间 默认200ms */ duration?: number; aliveRef?: RefObject; /** * 缓存节点最大存活时间 (秒) * @default 0 (无限制) */ maxAliveTime?: number | MaxAliveConfig[]; /** * 启用 Activity 组件 from react 19+ * @default false * Activity 组件可以提高性能，但是会影响过渡效果 * 注意: 如果启用 Activity 组件, useEffect 会在组件激活时触发 */ enableActivity?: boolean; } interface MaxAliveConfig { match: string | RegExp; expire: number; } ``` ## Hooks ### useEffectOnActive ```tsx useEffectOnActive(() => { console.log("active"); }, []); ``` ### useLayoutEffectOnActive ```tsx useLayoutEffectOnActive( () => { console.log("active"); }, [], false, ); // 第三个参数是可选的,默认为false, // 如果为true,表示在首次渲染时触发useLayoutEffect时会跳过回调 ``` ### useKeepAliveContext 类型定义 ```ts interface KeepAliveContext { /** * 组件是否处于活动状态 */ active: boolean; /** * 刷新组件 * @param {string} [cacheKey] - 组件的缓存键。如果未提供，将刷新当前缓存的组件。 */ refresh: (cacheKey?: string) => void; /** * 销毁组件 * @param {string} [cacheKey] - 组件的缓存键，如果未提供，将销毁当前活动的缓存组件。 */ destroy: (cacheKey?: string | string[]) => Promise; /** * 销毁所有组件 */ destroyAll: () => Promise; /** * 销毁除提供的cacheKey外的其他组件 * @param {string} [cacheKey] - 组件的缓存键。如果未提供，将销毁除当前活动缓存组件外的所有组件。 */ destroyOther: (cacheKey?: string) => Promise; /** * 获取缓存节点 */ getCacheNodes: () => Array; } ``` ```tsx const { active, refresh, destroy, getCacheNodes } = useKeepAliveContext(); // active 是一个布尔值，true表示活动，false表示非活动 // refresh 是一个函数，你可以调用它来刷新组件 // destroy 是一个函数，你可以调用它来销毁组件 // ... // getCacheNodes 是一个函数，你可以调用它来获取缓存节点 ``` ### useKeepAliveRef 类型定义 ```ts interface KeepAliveRef { refresh: (cacheKey?: string) => void; destroy: (cacheKey?: string | string[]) => Promise; destroyAll: () => Promise; destroyOther: (cacheKey?: string) => Promise; getCacheNodes: () => Array; } ``` ```tsx function App() { const aliveRef = useKeepAliveRef(); // aliveRef.current 是一个 KeepAliveRef 对象 // 你可以在 aliveRef.current 上调用 refresh 和 destroy aliveRef.current?.refresh(); // 通常不需要手动调用 destroy,KeepAlive 会自动处理 aliveRef.current?.destroy(); return {/* ... */}; } // 或者 function AppRouter() { const aliveRef = useKeepAliveRef(); // aliveRef.current 是一个 KeepAliveRef 对象 // 你可以在 aliveRef.current 上调用 refresh 和 destroy aliveRef.current?.refresh(); aliveRef.current?.destroy(); return ; } ``` ## 开发 安装依赖 ```bash pnpm install ``` 构建包 ```bash pnpm build ``` [discord-link]: https://discord.gg/ycf896w7eA [discord-shield]: https://img.shields.io/discord/1232158668913381467?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square [discord-shield-badge]: https://img.shields.io/discord/1232158668913381467?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=for-the-badge