Flutter时间追踪插件time_tracker的使用

简介

一个常见的任务是记录一个过程的开始时间、暂停/恢复的时间以及完成时间。一个类型为 <code>TimeTracker</code> 的对象被设计用于执行此任务。它类似于 <code>StopWatch</code>，但不是记录经过的时间戳，而是记录状态变化时的 <code>DateTime</code> 点。

下图展示了由枚举 <code>TimeStatus</code> 定义的状态（蓝色字体）和由类 <code>TimeTracker</code> 定义的状态转换（橙色箭头）。

状态改变的方法用绿色字体表示。调用一个未定义转换的状态改变方法不会产生效果。例如：当对象的状态为 <code>TimeStatus.ready</code> 时调用 <code>end()</code> 方法不会有任何效果。

除了用于记录时间点的方法外，混入 <code>TimeTracker</code> 还提供了用于 JSON 序列化的辅助方法。建议包含 <code>TimeTracker</code> 的类重写等号运算符，以便反序列化后的对象与原始对象相等。

使用

要使用此库，请在 pubspec.yaml 文件中包含 <code>time_tracker</code> 作为依赖项。

以下示例展示了如何使用带有 <code>TimeTracker</code> 混入的 <code>TennisMatch</code> 类构造器。该对象会自行记录时间点。注意：重写了 <code>hashCode</code> 和等号运算符，以确保解码后的对象与原始对象相等。

import 'package:exception_templates/exception_templates.dart';
import 'package:time_tracker/time_tracker.dart';

/// 展示如何使用 TimeTracker。
class TennisMatch with TimeTracker {
  final _players = <String>[];

  TennisMatch(List<String> players) {
    _players.addAll(players);
  }

  /// 从 JSON 映射构造对象。
  TennisMatch.fromJson(Map<String, dynamic> json) {
    if (json case {'players': List players}) {
      _players.addAll(players.cast<String>());

      // 使用 JSON 条目初始化时间跟踪器状态。
      initTrackerfromJson(json);
    } else {
      throw ErrorOf<TennisMatch>(
        message: '验证玩家列表时出错。',
        invalidState: '发现映射: $json',
      );
    }
  }

  @override
  Map<String, dynamic> toJson() {
    // 添加与时间跟踪器相关的映射条目。
    final json = trackerToJson();
    json['players'] = List<String>.of(_players);
    return json;
  }

  @override
  int get hashCode => Object.hash(trackerHashCode, _players);

  /// 如果两个实例具有相同的时间状态、时间点和玩家列表，则返回 `true`。
  @override
  bool operator ==(Object other) {
    return other is TennisMatch &&
        _players.equal(other._players) &&
        trackerEqual(other);
  }

  @override
  String toString() {
    return 'TennisMatch: players: $_players | status: ${status.name} '
        '| duration: $duration';
  }
}

以下程序演示了如何使用 <code>TennisMatch</code> 对象来启动、暂停、恢复和结束比赛。同时展示了如何使用 <a href="https://api.dart.dev/stable/dart-convert/dart-convert-library.html">'dart:convert'</a> 进行序列化和反序列化。

void main() async {
  /// 创建对象（记录开始时间）
  final match = TennisMatch(['Tim', 'Andy'])..start();

  print('----- 创建一个 TennisMatch 对象 -----');
  print('状态: ${match.status.name} 时间: ${match.startTime}');

  await Future.delayed(const Duration(milliseconds: 3), () {
    // 暂停对象
    match.pause();
    print('状态: ${match.status.name} 时间: ${match.lastTimePoint}');
  });

  await Future.delayed(const Duration(milliseconds: 1), () {
    // 恢复对象
    match.resume();
    print('状态: ${match.status.name} 时间: ${match.lastTimePoint}');
  });

  await Future.delayed(const Duration(milliseconds: 2), () {
    // 结束对象
    match.end();
    print('状态: ${match.status.name} 时间: ${match.lastTimePoint}');
  });

  print('');
  print('---------- JSON 编码 -------------');
  final jsonString = jsonEncode(match);
  print('序列化对象:');
  print(jsonString);

  var decodedMatch = TennisMatch.fromJson(jsonDecode(jsonString));
  print('');
  print('反序列化对象:');
  print(decodedMatch);

  print('');
  print('match == decodedMatch: ${match == decodedMatch}');
}

点击展开控制台输出：

$ dart example/bin/time_tracker_example.dart
----- 创建一个 TennisMatch 对象 -----
状态: started 时间: 2024-05-23 18:30:06.167586

状态: paused 时间: 2024-05-23 18:30:06.176602

状态: resumed 时间: 2024-05-23 18:30:06.180479

状态: ended 时间: 2024-05-23 18:30:06.183586

---------- JSON 编码 -------------
序列化对象:
{"_status":{"timeStatus":"ended"},
 "_timePoints":[
   1716485406167586,
   1716485406176602,
   1716485406180479,
   1716485406183586,
 ],
 "players":["Tim","Andy"],
}

反序列化对象:
TennisMatch: players: [Tim, Andy] | status: ended | duration: 0:00:00.012123

match == decodedMatch: true