198 lines
5.7 KiB
Markdown
198 lines
5.7 KiB
Markdown
# 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
|
||
**维护者：** 开发团队
|