Flutter XML解析插件training_center_xml的使用

Training Center XML

此包旨在使 Dart 和 Flutter 中处理 Training Center XML 文件（.tcx）变得简单。

特性

此包可以用于：

• 读取并打印 .tcx 文件的数据。
• 读取、修改并写回 .tcx 文件的数据。
• 从零创建一个新的 .tcx 文件。

开始使用

要使用此包，将其添加到您的 pubspec.yaml 文件中：

dependencies:
  training_center_xml: <latest_version>

或者运行以下命令：

flutter pub add training_center_xml

使用方法

哲学

该包的目标是模仿 TCX 文件的结构，其 XML 模式定义文件可在此处找到：https://www.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd。

因此，类结构可能显得有些晦涩或奇怪，但这是为了匹配模式定义。

对于某些字段，模式定义的要求如下：

• 如果模式期望恰好一个字段：TcxType field;
• 如果模式期望零个或一个字段：TcxType? field;
• 如果模式期望零个或多个字段：List<TcxType>? field;
• 如果模式期望一个或多个字段：List<TcxType> field;

读取文件

以下代码展示了如何从文件中读取 .tcx 数据：

final myTcxString = File('my_tcx_file.tcx').readAsStringSync();
var tcx = TcxTrainingCenterDatabase.fromXmlString(myTcxString);

修改文件

虽然可以修改的字段很多，这里仅展示一个简单的例子：将文件中第一个活动的运动类型更改为跑步。大多数文件只有一个活动，但根据 TCX 标准，可以有多个活动：

tcx.activities?.activity?.firstOrNull?.sport = TcxSport.running;

写回文件

以下是将修改后的数据写回文件的代码：

File('my_tcx_file_edited.tcx').writeAsStringSync(tcx.toXmlString());

创建新的 .tcx 文件

以下是一个简单的示例，用于从零开始创建一个新的 .tcx 文件。在实际应用中，通常会有更多的数据，例如更多的轨迹点和更长的活动。

var newTcx = TcxTrainingCenterDatabase(
    activities: TcxActivityList(
      activity: [
        TcxActivity(
          id: DateTime(2023, 08, 21, 18, 30), // 设置活动的开始时间
          lap: [
            TcxActivityLap(
              calories: 12, // 卡路里消耗
              distanceMeters: 150, // 距离（米）
              intensity: TcxIntensity.active, // 强度
              startTime: DateTime(2023, 08, 21, 18, 30), // 活动开始时间
              totalTimeSeconds: 120, // 总时长（秒）
              triggerMethod: TcxTriggerMethod.manual, // 触发方式
              track: [
                TcxTrack(
                  trackpoint: [
                    TcxTrackpoint(
                      time: DateTime(2023, 08, 21, 18, 30, 1), // 轨迹点的时间
                      distanceMeters: 1, // 距离（米）
                      heartRateBpm: TcxHeartRateInBeatsPerMinute(value: 90), // 心率
                      altitudeMeters: 56, // 高度（米）
                      position: TcxPosition(
                        latitudeDegrees: 0.0, // 纬度
                        longitudeDegrees: 0.0, // 经度
                      ),
                    ),
                    TcxTrackpoint(
                      time: DateTime(2023, 08, 21, 18, 30, 31), // 轨迹点的时间
                      distanceMeters: 10, // 距离（米）
                      heartRateBpm: TcxHeartRateInBeatsPerMinute(value: 100), // 心率
                      altitudeMeters: 57, // 高度（米）
                      position: TcxPosition(
                        latitudeDegrees: 0.1, // 纬度
                        longitudeDegrees: 0.2, // 经度
                      ),
                    ),
                  ],
                ),
              ],
              extensions: TcxExtensions(
                activityLapExtension: [
                  TcxActivityLapExtension(
                    maxRunCadence: 12, // 最大步频
                    avgSpeed: 40, // 平均速度
                  ),
                ],
              ),
            ),
          ],
          sport: TcxSport.running, // 运动类型
        ),
      ],
    ),
  );

// 将新创建的 TCX 文件写入磁盘
File('my_new_tcx_file.tcx').writeAsStringSync(newTcx.toXmlString());

其他信息

Bug 报告

如果发现任何问题、错误或缺失的功能，请在 此存储库 提交新问题。

此包最初是为 Movna（一个用 Flutter 编写的开源训练应用程序）开发的。如果您喜欢的功能缺失，请随时贡献！

关于 TCX 扩展

TCX 模式定义允许来自其他模式的自定义扩展。遗憾的是，目前还不可能将任意类放入 <code>TcxExtensions</code> 的字段中，但 Garmin 发布的两个扩展 <code>ActivityLapExtension</code> 和 <code>ActivityTrackpointExtension</code> 已被支持。如果您知道尚未支持的公共 TCX 扩展，请提交问题！

如何构建

如果您希望自行构建此包或进行贡献，请按以下步骤设置环境：

确保安装了 FVM。在 Android Studio 中，可以将项目的 Flutter SDK 路径设置为 <absolute/path/to/this/repository/.fvm/flutter_sdk/>。所有后续的 flutter 命令实际上是调用 fvm flutter。

安装所有依赖项：

flutter pub get

运行可用的测试：

flutter test