# Tab 配置系统开发规范

## 📋 功能说明

Tab 配置系统支持动态开关控制底部导航栏的 Tab 项显示/隐藏，配置自动保存到 SharedPreferences。

## 🔧 添加新 Tab 项的步骤

当需要添加新的 Tab 项时，必须按以下顺序修改 **3 个文件**：

### 1️⃣ 修改 `tab_config.dart` - 添加默认配置

**文件路径：** `lib/features/main_container/domain/tab_config.dart`

在 `TabConfig.defaultConfig()` 方法的 `items` 列表中添加新的 `TabConfigItem`：

```dart
TabConfigItem(
  id: 'your_tab_id',           // 唯一标识符（小写+下划线）
  name: '显示名称',             // 中文名称（简洁，建议2-4个字）
  nameEn: 'Display Name',      // 英文名称
  icon: 'icon_name_rounded',   // 图标名称（Material Icons）
  isEnabled: true,             // 默认是否启用（true/false）
  order: 7,                    // 排序序号（从1开始递增）
),
```

**注意事项：**
- `id` 必须唯一，建议使用有意义的英文标识
- `name` 要简洁，符合 TAB 命名规范
- `order` 决定 Tab 在导航栏中的显示顺序
- `isEnabled` 控制默认是否显示该 Tab

---

### 2️⃣ 修改 `custom_main_container.dart` - 添加页面映射

**文件路径：** `lib/features/main_container/presentation/pages/custom_main_container.dart`

#### 2.1 导入新页面

在文件顶部添加新页面的 import：

```dart
import 'package:maibu_satabot_v2/features/xxx/presentation/pages/your_page.dart';
```

#### 2.2 在 `_buildPages` 方法中添加 case

```dart
List<Widget> _buildPages(List<dynamic> enabledTabs) {
  return enabledTabs.map((tab) {
    switch (tab.id) {
      case 'home_v2':
        return const HomeV2Page();
      case 'home':
        return const HomePage();
      case 'device':
        return const DeviceStatusPage();
      case 'ai':
        return const AiPage();
      case 'warning':
        return const WarningCenterPage();
      case 'my':
        return const MyPage();
      case 'your_tab_id':      // 👈 新增这个 case
        return const YourPage();
      default:
        return const HomePage();
    }
  }).toList();
}
```

---

### 3️⃣ 修改 `tab_settings_page.dart` - 添加图标映射

**文件路径：** `lib/features/main_container/presentation/pages/tab_settings_page.dart`

在 `_getIconData` 方法中添加新图标的映射：

```dart
IconData _getIconData(String iconName) {
  switch (iconName) {
    case 'home_rounded':
      return Icons.home_rounded;
    case 'grid_view_rounded':
      return Icons.grid_view_rounded;
    case 'devices_rounded':
      return Icons.devices_rounded;
    case 'auto_awesome_rounded':
      return Icons.auto_awesome_rounded;
    case 'warning_amber_rounded':
      return Icons.warning_amber_rounded;
    case 'person_rounded':
      return Icons.person_rounded;
    case 'your_icon_name':    // 👈 新增这个 case
      return Icons.your_icon_name;
    default:
      return Icons.home_rounded;
  }
}
```

**注意：** 如果使用的是 Material Icons 标准图标，通常不需要修改此文件，除非使用了特殊图标。

---

## ✅ 检查清单

添加新 Tab 后，请确认：

- [ ] 已在 `tab_config.dart` 中添加 `TabConfigItem` 配置
- [ ] 已在 `custom_main_container.dart` 中导入新页面
- [ ] 已在 `custom_main_container.dart` 的 `switch` 中添加 case 分支
- [ ] 已在 `tab_settings_page.dart` 中添加图标映射（如需要）
- [ ] `id`、`order` 没有与其他 Tab 冲突
- [ ] 测试开关功能是否正常
- [ ] 测试切换 Tab 是否正常显示对应页面

---

## 🚀 完整示例：添加"消息"Tab

假设要添加一个"消息"Tab，显示消息中心页面：

### 步骤 1：修改 `tab_config.dart`

```dart
TabConfigItem(
  id: 'message',
  name: '消息',
  nameEn: 'Messages',
  icon: 'notifications_rounded',
  isEnabled: true,
  order: 7,
),
```

### 步骤 2：修改 `custom_main_container.dart`

```dart
// 顶部添加导入
import 'package:maibu_satabot_v2/features/message/presentation/pages/message_page.dart';

// 在 _buildPages 方法中添加
case 'message':
  return const MessagePage();
```

### 步骤 3：修改 `tab_settings_page.dart`

```dart
case 'notifications_rounded':
  return Icons.notifications_rounded;
```

---

## ⚠️ 常见问题

### Q1: 添加新 Tab 后看不到？
**A:** 点击 Tab 配置页面的"重置为默认"按钮，或清除应用数据重新运行。

### Q2: 点击 Tab 后页面不显示？
**A:** 检查 `custom_main_container.dart` 中的 `switch-case` 是否正确添加了新 Tab 的映射。

### Q3: 图标显示不正确？
**A:** 检查 `tab_settings_page.dart` 中的 `_getIconData` 方法是否添加了对应的图标映射。

### Q4: Tab 顺序不对？
**A:** 检查 `tab_config.dart` 中各 Tab 的 `order` 值，确保按期望顺序排列。

---

## 📝 核心原理

1. **配置管理：** `TabConfigCubit` 管理所有 Tab 的配置和选中状态
2. **持久化：** 配置自动保存到 SharedPreferences，重启应用后保持
3. **动态渲染：** 底部导航栏根据 `enabledItems` 动态渲染启用的 Tab
4. **页面切换：** 使用 `IndexedStack` 保持各页面状态，通过 `selectedIndex` 切换

---

## 🎯 最佳实践

1. **Tab 命名：** 保持简洁，中文 2-4 个字，避免过长
2. **默认状态：** 新功能建议设置 `isEnabled: false`，通过灰度发布逐步开放
3. **排序规划：** 预留 order 间隔（如 10, 20, 30），方便后续插入新 Tab
4. **图标选择：** 优先使用 Material Icons 的 `_rounded` 版本，风格统一
5. **测试验证：** 每次修改后测试开关、切换、持久化等功能

---

**最后更新：** 2026-05-20  
**维护者：** 开发团队