@qin_sunrise/tab

一个基于zustand状态管理的轻量级标签页管理包，适用于React应用。

特性

• 🚀 轻量级且快速，基于zustand
• 💾 内置持久化支持
• 🎯 TypeScript支持
• 🔧 灵活的配置选项
• 🎨 UI无关 - 仅提供功能，不提供UI组件
• 📦 易于集成

安装

npm install @qin_sunrise/tab
# 或
yarn add @qin_sunrise/tab
# 或
pnpm add @qin_sunrise/tab

快速开始

基本用法

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>
  );
}

带配置的用法

import { createTabStore } from '@qin_sunrise/tab';

// 创建带配置的store
const tabStore = createTabStore({
  cache: true, // 启用持久化
  storageKey: 'my-tabs', // 自定义存储键
  homePath: '/dashboard' // 自定义首页路径
});

API 参考

类型定义

Tab

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

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)

从路由获取激活的一级菜单键。

示例

基本标签页管理

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>
  );
}

与路由集成

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 />;
}

带持久化

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 获取详细的迁移步骤。

许可证

MIT