# @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