Flutter跨平台开发：剧本杀App游戏记录功能实现

1. 项目概述

剧本杀作为一种新兴的社交娱乐方式，近年来在国内迅速流行。作为一款专为剧本杀爱好者设计的组队App，游戏记录功能是用户留存和体验提升的关键模块。这个功能不仅能让玩家回顾自己的游戏历程，还能为未来的剧本选择提供参考依据。

在Flutter for OpenHarmony环境下实现这一功能，我们面临着跨平台适配和性能优化的双重挑战。游戏记录页面需要展示丰富的信息，包括剧本名称、游戏日期、扮演角色、个人评分等，同时还要支持筛选、排序和分享等交互功能。

2. 核心需求解析

2.1 功能需求分析

游戏记录页面的核心功能可以分为以下几个部分：

1. 记录展示：清晰呈现用户玩过的剧本信息
2. 筛选排序：支持按时间、评分等条件筛选和排序
3. 统计概览：展示用户的游戏数据统计
4. 社交分享：允许用户分享游戏体验

2.2 技术选型考量

在技术实现上，我们选择了以下方案：

• UI框架：Flutter Material Design组件库
• 状态管理：GetX轻量级框架
• 数据存储：本地SQLite数据库
• 路由导航：GetX路由系统

这种组合在保证开发效率的同时，也能满足OpenHarmony平台的性能要求。GetX的轻量级特性特别适合移动端应用，避免了状态管理带来的性能开销。

3. 实现细节与代码解析

3.1 数据结构设计

游戏记录的数据结构设计至关重要，我们采用了Map<String, dynamic>类型来存储单条记录：

dart复制{
  'id': '1',  // 唯一标识
  'script': '年轮',  // 剧本名称
  'type': '情感本',  // 剧本类型
  'store': '迷雾剧本杀',  // 游戏店铺
  'date': '2024-01-15',  // 游戏日期
  'rating': 5,  // 用户评分(1-5星)
  'role': '凶手',  // 扮演角色
  'duration': '120分钟',  // 游戏时长
  'players': 6,  // 参与人数
  'comment': '非常精彩的剧本，剧情紧凑，反转精彩',  // 用户评论
}

这种设计具有以下优点：

1. 灵活性高，可以随时添加新字段
2. 与JSON格式兼容，便于网络传输
3. 类型安全，通过dynamic可以存储各种类型数据

3.2 页面布局实现

页面整体采用Column+ListView的经典布局：

dart复制Scaffold(
  appBar: AppBar(
    title: const Text('游戏记录'),
    actions: [FilterButton()],
  ),
  body: Column(
    children: [
      StatisticsBar(),  // 统计信息栏
      Expanded(
        child: ListView.builder(
          itemCount: records.length,
          itemBuilder: (ctx, index) => RecordItem(records[index]),
        ),
      ),
    ],
  ),
)

这种布局方式确保了：

1. 统计栏固定在顶部
2. 记录列表可以滚动
3. 充分利用屏幕空间

3.3 统计信息计算

统计栏展示三个关键指标：

dart复制int totalGames = records.length;
double avgRating = records.isEmpty ? 0 : 
    records.fold(0, (sum, item) => sum + item['rating']) / totalGames;
String favoriteRole = _calculateFavoriteRole();

计算最爱角色的方法：

dart复制String _calculateFavoriteRole() {
  final roleCount = <String, int>{};
  for (var record in records) {
    final role = record['role'];
    roleCount[role] = (roleCount[role] ?? 0) + 1;
  }
  return roleCount.entries.reduce((a, b) => a.value > b.value ? a : b).key;
}

4. 交互功能实现

4.1 筛选与排序功能

筛选菜单使用GetX的bottomSheet实现：

dart复制void _showFilterMenu() {
  Get.bottomSheet(
    Container(
      child: Column(
        children: [
          Text('时间筛选'),
          Wrap(
            children: ['全部', '本月', '本年', '去年'].map((filter) {
              return ChoiceChip(
                label: Text(filter),
                selected: _selectedFilter == filter,
                onSelected: (_) => _applyFilter(filter),
              );
            }).toList(),
          ),
          // 排序选项类似
        ],
      ),
    ),
  );
}

筛选逻辑实现：

dart复制void _applyFilter(String filter) {
  List<Map<String, dynamic>> filtered = [..._allRecords];
  
  // 时间筛选
  if (filter != '全部') {
    final now = DateTime.now();
    filtered = filtered.where((record) {
      final date = DateTime.parse(record['date']);
      switch (filter) {
        case '本月':
          return date.month == now.month && date.year == now.year;
        case '本年':
          return date.year == now.year;
        case '去年':
          return date.year == now.year - 1;
        default:
          return true;
      }
    }).toList();
  }
  
  // 排序逻辑
  filtered.sort((a, b) {
    switch (_sortBy) {
      case '最新':
        return b['date'].compareTo(a['date']);
      case '最旧':
        return a['date'].compareTo(b['date']);
      case '评分最高':
        return b['rating'].compareTo(a['rating']);
      case '评分最低':
        return a['rating'].compareTo(b['rating']);
      default:
        return 0;
    }
  });
  
  setState(() => _records = filtered);
}

4.2 记录项点击交互

点击记录项跳转到详情页：

dart复制GestureDetector(
  onTap: () => Get.to(() => ScriptDetailPage(scriptId: record['id'])),
  child: RecordItemWidget(record),
)

5. UI细节优化

5.1 记录卡片设计

单个游戏记录卡片采用多层次信息展示：

dart复制Container(
  decoration: BoxDecoration(
    color: Colors.white,
    borderRadius: BorderRadius.circular(12),
    boxShadow: [BoxShadow(color: Colors.black12, blurRadius: 6)],
  ),
  child: Column(
    children: [
      // 剧本名称和角色标签
      Row(
        children: [
          Expanded(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(record['script'], style: TextStyle(fontWeight: FontWeight.bold)),
                Text(record['type'], style: TextStyle(color: Colors.grey)),
              ],
            ),
          ),
          RoleTag(role: record['role']),
        ],
      ),
      // 店铺和日期信息
      Row(
        children: [
          Icon(Icons.store, size: 14),
          Text(record['store']),
          Spacer(),
          Icon(Icons.calendar_today, size: 14),
          Text(record['date']),
        ],
      ),
      // 评分和人数
      Row(
        children: [
          Text('我的评分:'),
          StarRating(rating: record['rating']),
          Spacer(),
          Text('${record['players']}人'),
        ],
      ),
      // 评论（如果有）
      if (record['comment'] != null && record['comment'].isNotEmpty)
        CommentBox(comment: record['comment']),
    ],
  ),
)

5.2 星级评分组件

自定义星级评分组件：

dart复制class StarRating extends StatelessWidget {
  final int rating;
  
  StarRating({required this.rating});
  
  @override
  Widget build(BuildContext context) {
    return Row(
      children: List.generate(5, (index) {
        return Icon(
          index < rating ? Icons.star : Icons.star_border,
          size: 16,
          color: Colors.amber,
        );
      }),
    );
  }
}

6. 性能优化技巧

6.1 列表性能优化

对于可能很长的游戏记录列表，我们采取了以下优化措施：

1. 使用ListView.builder而不是ListView直接构建
2. 为每个记录项添加const构造函数
3. 使用AutomaticKeepAliveClientMixin保持滚动位置

dart复制ListView.builder(
  itemCount: records.length,
  itemBuilder: (context, index) {
    return RecordItem(
      key: ValueKey(records[index]['id']),
      record: records[index],
    );
  },
)

6.2 图片加载优化

如果记录中包含剧本封面图片：

dart复制CachedNetworkImage(
  imageUrl: record['coverUrl'],
  placeholder: (ctx, url) => Placeholder(),
  errorWidget: (ctx, url, err) => Icon(Icons.error),
  fadeInDuration: Duration(milliseconds: 300),
)

7. 测试与调试

7.1 单元测试要点

针对游戏记录页面的关键测试场景：

dart复制test('测试筛选逻辑', () {
  // 准备测试数据
  final testRecords = [...];
  final page = HistoryPage();
  
  // 测试时间筛选
  page._applyFilter('本月');
  expect(page._records.length, equals(2));
  
  // 测试排序
  page._sortBy = '评分最高';
  page._applyFilter('全部');
  expect(page._records.first['rating'], equals(5));
});

7.2 集成测试场景

主要测试用户交互流程：

dart复制testWidgets('测试完整用户流程', (tester) async {
  await tester.pumpWidget(MyApp());
  
  // 1. 进入游戏记录页
  await tester.tap(find.text('游戏记录'));
  await tester.pumpAndSettle();
  
  // 2. 点击筛选按钮
  await tester.tap(find.byIcon(Icons.filter_list));
  await tester.pumpAndSettle();
  
  // 3. 选择"本月"筛选
  await tester.tap(find.text('本月'));
  await tester.pumpAndSettle();
  
  // 验证筛选结果
  expect(find.text('年轮'), findsOneWidget);
  expect(find.text('古木吟'), findsNothing);
});

8. 扩展功能实现

8.1 数据持久化

将游戏记录保存到本地数据库：

dart复制class RecordDatabase {
  static final RecordDatabase _instance = RecordDatabase._internal();
  factory RecordDatabase() => _instance;
  
  late Database _db;
  
  Future<void> init() async {
    _db = await openDatabase(
      'records.db',
      version: 1,
      onCreate: (db, version) {
        return db.execute('''
          CREATE TABLE records(
            id TEXT PRIMARY KEY,
            script TEXT,
            type TEXT,
            store TEXT,
            date TEXT,
            rating INTEGER,
            role TEXT,
            duration TEXT,
            players INTEGER,
            comment TEXT
          )
        ''');
      },
    );
  }
  
  Future<List<Map<String, dynamic>>> getRecords() async {
    return await _db.query('records');
  }
  
  Future<void> addRecord(Map<String, dynamic> record) async {
    await _db.insert('records', record);
  }
}

8.2 社交分享功能

集成社交平台分享SDK：

dart复制void _shareRecord(Map<String, dynamic> record) async {
  final shareText = '''
  我在${record['store']}玩了《${record['script']}》！
  扮演角色：${record['role']}
  我的评分：${'⭐' * record['rating']}
  ${record['comment'] ?? ''}
  ''';
  
  await Share.share(shareText);
}

9. 常见问题解决

9.1 数据同步问题

当从网络获取最新记录时，需要注意：

1. 显示加载状态
2. 处理网络错误
3. 合并本地和远程数据

dart复制Future<void> _loadRecords() async {
  setState(() => _isLoading = true);
  
  try {
    final remoteRecords = await Api.getRecords();
    final localRecords = await RecordDatabase().getRecords();
    
    // 合并并去重
    final allRecords = {...localRecords, ...remoteRecords}.values.toList();
    
    setState(() {
      _allRecords = allRecords;
      _records = allRecords;
      _isLoading = false;
    });
  } catch (e) {
    setState(() => _isLoading = false);
    Get.snackbar('错误', '加载记录失败: ${e.toString()}');
  }
}

9.2 空状态处理

当没有游戏记录时显示友好提示：

dart复制Widget _buildContent() {
  if (_isLoading) {
    return Center(child: CircularProgressIndicator());
  }
  
  if (_records.isEmpty) {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Icon(Icons.history, size: 80, color: Colors.grey[300]),
          Text('还没有游戏记录'),
          TextButton(
            onPressed: _goToLobby,
            child: Text('去组队大厅'),
          ),
        ],
      ),
    );
  }
  
  return _buildRecordList();
}

10. 项目部署与发布

10.1 OpenHarmony适配要点

在OpenHarmony平台上需要注意：

1. 使用ohos_flutter插件处理平台特定功能
2. 适配鸿蒙系统的UI风格
3. 处理权限申请

dart复制// 在main.dart中初始化
void main() {
  if (Platform.isOpenHarmony) {
    initOpenHarmony();
  }
  runApp(MyApp());
}

10.2 性能监控

添加性能监控代码：

dart复制void _monitorPerformance() {
  FlutterFPSMonitor().start();
  
  // 记录关键操作耗时
  final stopwatch = Stopwatch()..start();
  _applyFilter('本月');
  stopwatch.stop();
  
  Analytics().logEvent('filter_time', {
    'duration': stopwatch.elapsedMilliseconds,
    'filter': '本月',
  });
}

在实际开发中，我发现游戏记录页面的性能瓶颈主要出现在大量数据渲染时。通过以下几点优化可以显著提升体验：

1. 分页加载数据，避免一次性渲染过多记录
2. 使用isolate处理复杂计算（如统计计算）
3. 对图片等资源进行缓存
4. 使用const构造函数减少Widget重建开销

另一个值得注意的点是数据同步策略。在移动网络环境下，频繁同步大量游戏记录会消耗用户流量并影响性能。我们最终采用的方案是：

• 首次加载时同步最近30条记录
• 滚动到底部时加载更多
• 提供手动刷新按钮
• 在WiFi环境下自动同步全部记录

这种策略在保证数据及时性的同时，也兼顾了性能和流量消耗的平衡。