songchunyi/feature-next-arch

Fork 0

Files

Songzex afef5c4ef1 所有一级页面和不分二级页面

2026-05-25 12:58:29 +08:00

5.7 KiB

Raw Permalink Blame History

Tab 配置系统开发规范

📋 功能说明

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

🔧 添加新 Tab 项的步骤

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

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

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

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

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：

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

2.2 在 `_buildPages` 方法中添加 case

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 方法中添加新图标的映射：

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`

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

步骤 2：修改 `custom_main_container.dart`

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

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

步骤 3：修改 `tab_settings_page.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 值，确保按期望顺序排列。

📝 核心原理

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

🎯 最佳实践

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

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

5.7 KiB Raw Permalink Blame History Unescape Escape