@qin_sunrise/tab/MIGRATION.zh-CN.md

A lightweight tab management package based on zustand state management for React applications

# 迁移指南

本指南帮助您从原始的标签页功能迁移到新的 `@qin_sunrise/tab` 包。

## 迁移前（原始实现）

```tsx
// 使用 Redux Toolkit
import { useAppDispatch, useAppSelector } from '@/store';
import { 
  addTab, 
  removeTabById, 
  setActiveTabId,
  selectTabs,
  selectActiveTabId 
} from '@/features/tab/tabStore';

function MyComponent() {
  const dispatch = useAppDispatch();
  const tabs = useAppSelector(selectTabs);
  const activeTabId = useAppSelector(selectActiveTabId);

  const handleAddTab = (route) => {
    dispatch(addTab(route));
  };

  const handleRemoveTab = (tabId) => {
    dispatch(removeTabById(tabId));
  };
}
```

## 迁移后（新的 @qin_sunrise/tab 包）

```tsx
// 使用 Zustand
import { useTabManager, useTabs, useActiveTabId } from '@qin_sunrise/tab';

function MyComponent() {
  const { addTab, removeTabById } = useTabManager();
  const tabs = useTabs();
  const activeTabId = useActiveTabId();

  const handleAddTab = (route) => {
    addTab(route);
  };

  const handleRemoveTab = (tabId) => {
    removeTabById(tabId);
  };
}
```

## 主要变化

### 1. 状态管理
- **迁移前**: 使用 Redux Toolkit 的 `useAppDispatch` 和 `useAppSelector`
- **迁移后**: 使用 Zustand 的直接hooks

### 2. Store 创建
- **迁移前**: Redux store 中的 slices
- **迁移后**: Zustand store 中的 `createTabStore()`

### 3. Hooks
- **迁移前**: 使用 Redux selectors 的自定义 hooks
- **迁移后**: 直接使用 `@qin_sunrise/tab` 的直接hooks

### 4. Actions
- **迁移前**: `dispatch(action())`
- **迁移后**: 直接函数调用

## 迁移步骤

### 步骤 1: 安装新包
```bash
pnpm add @qin_sunrise/tab
```

### 步骤 2: 替换导入
```tsx
// 删除旧的导入
// import { useAppDispatch, useAppSelector } from '@/store';
// import { addTab, removeTabById, selectTabs } from '@/features/tab/tabStore';

// 添加新的导入
import { useTabManager, useTabs, useActiveTabId } from '@qin_sunrise/tab';
```

### 步骤 3: 更新组件逻辑
```tsx
// 迁移前
function MyComponent() {
  const dispatch = useAppDispatch();
  const tabs = useAppSelector(selectTabs);
  const activeTabId = useAppSelector(selectActiveTabId);

  const handleAddTab = (route) => {
    dispatch(addTab(route));
  };
}

// 迁移后
function MyComponent() {
  const { addTab } = useTabManager();
  const tabs = useTabs();
  const activeTabId = useActiveTabId();

  const handleAddTab = (route) => {
    addTab(route);
  };
}
```

### 步骤 4: 更新所有相关组件

#### 标签页管理组件
```tsx
// 迁移前
import { useAppDispatch, useAppSelector } from '@/store';
import { 
  addTab, 
  removeTabById, 
  setActiveTabId,
  selectTabs,
  selectActiveTabId 
} from '@/features/tab/tabStore';

function TabBar() {
  const dispatch = useAppDispatch();
  const tabs = useAppSelector(selectTabs);
  const activeTabId = useAppSelector(selectActiveTabId);

  const handleTabClick = (tab) => {
    dispatch(setActiveTabId(tab.id));
  };

  const handleCloseTab = (tabId) => {
    dispatch(removeTabById(tabId));
  };
}

// 迁移后
import { useTabManager, useTabs, useActiveTabId } from '@qin_sunrise/tab';

function TabBar() {
  const { setActiveTabId, removeTabById } = useTabManager();
  const tabs = useTabs();
  const activeTabId = useActiveTabId();

  const handleTabClick = (tab) => {
    setActiveTabId(tab.id);
  };

  const handleCloseTab = (tabId) => {
    removeTabById(tabId);
  };
}
```

#### 路由集成组件
```tsx
// 迁移前
import { useAppDispatch } from '@/store';
import { addTab } from '@/features/tab/tabStore';

function RouteHandler() {
  const dispatch = useAppDispatch();

  useEffect(() => {
    dispatch(addTab({
      id: route.path,
      label: route.title,
      path: route.path
    }));
  }, [route]);
}

// 迁移后
import { useTabManager } from '@qin_sunrise/tab';

function RouteHandler() {
  const { addTab } = useTabManager();

  useEffect(() => {
    addTab({
      id: route.path,
      label: route.title,
      path: route.path
    });
  }, [route]);
}
```

## 功能对比

| 功能 | 迁移前 (Redux) | 迁移后 (Zustand) |
|------|----------------|------------------|
| 添加标签页 | `dispatch(addTab(tab))` | `addTab(tab)` |
| 删除标签页 | `dispatch(removeTabById(id))` | `removeTabById(id)` |
| 激活标签页 | `dispatch(setActiveTabId(id))` | `setActiveTabId(id)` |
| 获取标签页列表 | `useAppSelector(selectTabs)` | `useTabs()` |
| 获取激活标签页 | `useAppSelector(selectActiveTabId)` | `useActiveTabId()` |
| 清理操作 | `dispatch(clearAllTabs())` | `clearAllTabs()` |

## 配置选项

新包支持配置选项：

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

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

## 注意事项

1. **类型安全**: 新包提供完整的TypeScript支持
2. **性能**: Zustand比Redux更轻量，性能更好
3. **持久化**: 内置localStorage支持，可配置
4. **兼容性**: 保持所有原始功能，API更简洁

## 故障排除

### 常见问题

1. **导入错误**: 确保正确安装了 `@qin_sunrise/tab` 包
2. **类型错误**: 检查TypeScript类型是否正确导入
3. **状态不更新**: 确保使用了正确的hooks

### 调试技巧

```tsx
// 调试状态变化
import { useTabStore } from '@qin_sunrise/tab';

function DebugComponent() {
  const store = useTabStore();
  
  useEffect(() => {
    console.log('Tab store:', store.getState());
  }, [store]);
}
```

## 总结

迁移到 `@qin_sunrise/tab` 包提供了：
- ✅ 更简洁的API
- ✅ 更好的性能
- ✅ 完整的TypeScript支持
- ✅ 内置持久化
- ✅ 更好的开发体验

迁移过程相对简单，主要是替换导入和移除dispatch调用。