Garmin Monkey C 自定义字段为何未出现在 FIT 活动报告中？

2026-11-04数据阿明

使用 MESG_TYPE_SESSION 保存整次活动的跳跃总数是合适的。仅凭现有代码还无法确定故障原因。应先核对字段 ID 是否一致、活动是否完整保存，再判断是 FIT 文件中没有数据，还是报告页面没有显示。运行时字段创建成功，只能说明对象创建成功。

为什么更新了字段仍可能看不到

MESG_TYPE_SESSION 的数据在录制结束时写入，每次会话写入一次，适合保存总次数等汇总指标。反复调用 setData(_jumpCount) 更新的是这个汇总值，不会为每次跳跃生成独立记录。因此，只检查逐秒的 record 消息可能找不到它，还应检查 session 消息。Garmin FitContributor 文档

原代码没有展示 JUMPS_COUNTER_FIELD_ID 的值，也没有展示结束活动时的保存逻辑。这两处需要优先核对，但不能直接认定它们已经写错或缺失。

1. 核对代码与 XML 中的字段 ID

XML 使用的是 id="0"，因此创建 Jumps 字段时传入的 JUMPS_COUNTER_FIELD_ID 也应为 0：

const JUMPS_COUNTER_FIELD_ID = 0;

如果已有该常量，核对或修改原定义即可，不要重复声明。同时检查 @Strings.jumps_label 和 @Strings.jumps_units 对应的字符串资源，以及当前构建配置是否包含该 XML。

原配置已设置 displayInActivitySummary="true"，还需确认实际构建产物是否使用了这份配置。

2. 检查结束活动时是否保存了会话

stop() 停止录制，save() 才会完成会话并将 FIT 文件保存到文件系统。原代码只展示了 start()，需要检查结束活动的处理函数是否执行了保存，并检查返回值。Garmin Session 文档

下面的示例可放在持有这些成员变量的类中，用于补充结束流程；它假设 _jumpCount 已正确累计：

function finishActivity() {
    if (_session == null || _customJumpsCounterField == null) {
        return false;
    }

    // 保存前提交最终计数。
    _customJumpsCounterField.setData(_jumpCount);

    if (_session.isRecording()) {
        if (!_session.stop()) {
            return false;
        }
    }

    var saved = _session.save();
    if (saved) {
        _customJumpsCounterField = null;
        _session = null;
    }

    return saved;
}

示例用于说明保存顺序，不能据此认定原程序缺少这些调用。保存失败时，应用应保留相应状态，避免直接退出后丢失排查线索。

新建活动时还应同步初始化计数：

if (_session == null) {
    _jumpCount = 0;
    // 随后创建 session 和自定义字段。
}

只在新建活动时清零；暂停后继续录制时，应保留已有计数。

3. 直接检查保存后的 FIT 文件

使用支持 FIT developer fields 的解码工具检查原始文件。可以使用 Garmin FIT SDK 中的 FitCSVTool，或通过 SDK 解码消息。Garmin FIT SDK 工具

重点检查：

developer_data_id：识别自定义数据来源。
field_description：是否存在对应的 Jumps 字段定义，并核对字段编号与单位。
session 消息的 developer fields：是否包含最终跳跃次数。

Connect IQ 写入的自定义数据属于 developer fields。如果自写解析器只遍历标准字段，也可能漏掉这些值。Garmin Developer Data 说明

如果文件中没有对应字段，继续检查字段创建流程、事件回调是否执行、最终计数和保存结果。如果字段定义存在但没有预期数值，重点检查 setData() 的执行时机，以及计数是否被重置。

如果 session 中已有正确数值，说明数据已写入，接下来应检查报告工具是否支持展示该字段。使用 Garmin Connect 时，还需要核对字段展示资源、应用标识和实际安装的构建。当前代码不足以确定这一层的原因。

是否需要改成 MESG_TYPE_RECORD

如果需求只是显示整次活动的跳跃总数，保留 MESG_TYPE_SESSION 即可。只有需要展示活动过程中的计数变化时，才考虑额外创建 MESG_TYPE_RECORD 字段。

不要为了让总数显示而直接更换消息类型；这会改变数据所在的位置，也会改变排查和展示方式。