@qin_sunrise/tab

# @qin_sunrise/tab 一个基于zustand状态管理的轻量级标签页管理包，适用于React应用。 ## 特性 - 🚀 轻量级且快速，基于zustand - 💾 内置持久化支持 - 🎯 TypeScript支持 - 🔧 灵活的配置选项 - 🎨 UI无关 - 仅提供功能，不提供UI组件 - 📦 易于集成 ## 安装 ```bash npm install @qin_sunrise/tab # 或 yarn add @qin_sunrise/tab # 或 pnpm add @qin_sunrise/tab ``` ## 快速开始 ### 基本用法 ```tsx import { useTabManager, useTabs, useActiveTabId } from '@qin_sunrise/tab'; function App() { const { addTab, removeTabById, switchRouteByTab } = useTabManager(); const tabs = useTabs(); const activeTabId = useActiveTabId(); // 添加新标签页 const handleAddTab = (route) => { addTab(route); }; // 删除标签页 const handleRemoveTab = (tabId) => { removeTabById(tabId); }; // 切换到标签页 const handleTabClick = (tab) => { switchRouteByTab(tab); }; return ( <div> {/* 你的标签页UI */} </div> ); } ``` ### 带配置的用法 ```tsx import { createTabStore } from '@qin_sunrise/tab'; // 创建带配置的store const tabStore = createTabStore({ cache: true, // 启用持久化 storageKey: 'my-tabs', // 自定义存储键 homePath: '/dashboard' // 自定义首页路径 }); ``` ## API 参考 ### 类型定义 #### `Tab` ```tsx interface Tab { fixedIndex?: number | null; // 固定索引 fullPath: string; // 完整路径 i18nKey?: string | null; // 国际化键 icon?: string; // 图标 id: string; // 标签页ID keepAlive: boolean; // 是否保持活跃 label: string; // 标签页标题 localIcon?: string; // 本地图标 newLabel?: string; // 新标题 oldLabel?: string | null; // 旧标题 routeKey: string; // 路由键 routePath: string; // 路由路径 } ``` #### `TabConfig` ```tsx interface TabConfig { cache?: boolean; // 是否启用缓存 storageKey?: string; // 存储键名 homePath?: string; // 首页路径 } ``` ### Hooks #### `useTabStore(config?)` 获取标签页store实例。 #### `useTabs()` 获取所有标签页。 #### `useActiveTabId()` 获取当前激活的标签页ID。 #### `useActiveFirstLevelMenuKey()` 获取激活的一级菜单键。 #### `useRemoveCacheKey()` 获取移除缓存键。 #### `useTabActions()` 获取所有标签页操作函数。 #### `useTabManager(navigate?)` 获取带导航支持的标签页管理器。 #### `useCacheTabs()` 自动在页面卸载前缓存标签页的hook。 #### `useTabScroll()` 获取标签页滚动工具。 ### Store 操作 #### `addTab(tab: Tab)` 向store添加新标签页。 #### `updateTab(index: number, tab: Tab)` 更新指定索引的标签页。 #### `setActiveTabId(tabId: string)` 设置激活的标签页ID。 #### `setActiveFirstLevelMenuKey(key: string)` 设置激活的一级菜单键。 #### `setTabs(tabs: Tab[])` 设置所有标签页。 #### `changeTabLabel(index: number, label?: string)` 更改标签页标题。 #### `removeTabById(tabId: string)` 根据ID移除标签页。 #### `clearAllTabs()` 清除除固定标签页外的所有标签页。 #### `clearLeftTabs(tabId: string)` 清除指定标签页左侧的标签页。 #### `clearRightTabs(tabId: string)` 清除指定标签页右侧的标签页。 #### `clearOtherTabs(tabId: string)` 清除除指定标签页和固定标签页外的所有标签页。 #### `setRemoveCacheKey(keys: string[] | null)` 设置移除缓存键。 ### 工具函数 #### `getTabByRoute(route: Route, homePath?: string)` 将路由转换为标签页对象。 #### `isTabInTabs(tabId: string, tabs: Tab[])` 检查标签页是否存在于标签页数组中。 #### `getFixedTabs(tabs: Tab[])` 获取所有固定标签页。 #### `getTabById(tabId: string, tabs: Tab[])` 根据ID获取标签页。 #### `isTabRetain(tabId: string, tabs: Tab[])` 检查标签页是否为保留（固定）标签页。 #### `getActiveFirstLevelMenuKey(route: Route)` 从路由获取激活的一级菜单键。 ## 示例 ### 基本标签页管理 ```tsx import { useTabManager, useTabs } from '@qin_sunrise/tab'; function TabBar() { const { addTab, removeTabById, switchRouteByTab } = useTabManager(); const tabs = useTabs(); return ( <div className="tab-bar"> {tabs.map((tab) => ( <div key={tab.id} className="tab" onClick={() => switchRouteByTab(tab)}> <span>{tab.label}</span> <button onClick={() => removeTabById(tab.id)}>×</button> </div> ))} </div> ); } ``` ### 与路由集成 ```tsx import { useTabManager } from '@qin_sunrise/tab'; import { useRouter } from 'your-router'; function App() { const router = useRouter(); const { addTab } = useTabManager(router.navigate); // 路由变化时添加标签页 useEffect(() => { addTab({ fullPath: router.pathname, pathname: router.pathname, id: router.route, handle: { title: router.route, keepAlive: true } }); }, [router.pathname]); return <YourApp />; } ``` ### 带持久化 ```tsx import { createTabStore } from '@qin_sunrise/tab'; const tabStore = createTabStore({ cache: true, storageKey: 'my-app-tabs' }); function App() { return ( <TabProvider store={tabStore}> <YourApp /> </TabProvider> ); } ``` ## 迁移指南如果你正在从Redux Toolkit迁移到本包，请参考 [MIGRATION.md](./MIGRATION.md) 获取详细的迁移步骤。 ## 许可证 MIT