# @garmin-fit/sdk 中文文档

规范地址：https://npmcn.com/package/%40garmin-fit/sdk/

版本：21\.115\.0
npm 元数据更新时间：2023-09-19T19:16:56.110Z
中文译文更新时间：2026-11-15T23:27:38.282Z
软件包许可：SEE LICENSE IN LICENSE\.txt

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40garmin-fit/sdk
原文对照：https://npmcn.com/package/%40garmin-fit/sdk/?lang=original
项目主页：https://github.com/garmin/fit-javascript-sdk#readme
源码仓库：https://github.com/garmin/fit-javascript-sdk

弃用说明：This package has been renamed\. Please use @garmin/fitsdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：851 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2022-10-03T19:51:02.430Z
- 最新版本发布：2023-06-20T16:44:08.907Z
- 近 30 天下载量：2149（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 0 个）

## 中文简介

FIT 爪哇脚本 SDK

## 安装

```sh
npm install @garmin-fit/sdk
```

也可以使用：`pnpm add @garmin-fit/sdk`、`yarn add @garmin-fit/sdk`、`bun add @garmin-fit/sdk`

## README

# 加尔明 - FIT JavaScript SDK

## FIT SDK 文档

FIT SDK 文档可在 [https://developer.garmin.com/fit (英语)](https://developer.garmin.com/fit)。 。 。 .

## FIT SDK 开发者论坛

分享你的知识,问问题, 并获得最新的FIT SDK新闻 [FIT SDK 开发者论坛](https://forums.garmin.com/developer/)。 。 。 .

## FIT JavaScript SDK 要求

FIT JavaScript SDK使用ECMAScript模块语法,并需要node.js v14.0或更高,或者一个带有兼容的JavaScript运行时引擎的浏览器.

## 安装

```sh
npm install @garmin-fit/sdk
```

## 使用量

```js
import { Decoder, Stream, Profile, Utils } from '@garmin-fit/sdk';

const bytes = [0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00];

const stream = Stream.fromByteArray(bytes);
console.log("isFIT (static method): " + Decoder.isFIT(stream));

const decoder = new Decoder(stream);
console.log("isFIT (instance method): " + decoder.isFIT());
console.log("checkIntegrity: " + decoder.checkIntegrity());

const { messages, errors } = decoder.read();

console.log(errors);
console.log(messages);
```

## 解码器

### 构造器

解码器对象由Streams创建,代表要解码的二进制 FIT 文件数据. 见 [创建流](https://npmcn.com/package/%40garmin-fit/sdk/#readme-creatingstreams) 以获取关于构建流对象的更多信息.

一旦创建了解码器对象,就可以用来检查Stream是FIT文件,FIT文件有效,并读取FIT文件的内容.

### 是FIT 方法

所有有效的FIT文件应当包括一个12或14字节文件头. 14字节标题是首选标题大小和最常用的大小. 标题中的字节8-11包含ASCII值 ".FIT " 。 此字符串在文本或十六进制编辑器中打开二进制 FIT 文件时很容易被发现.

```
  Offset: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
00000000: 0E 10 43 08 78 06 09 00 2E 46 49 54 96 85 40 00    ..C.x....FIT..@.
00000010: 00 00 00 07 03 04 8C 04 04 86 07 04 86 01 02 84    ................
00000020: 02 02 84 05 02 84 00 01 00 00 19 28 7E C5 95 B0    ...........(~E.0
```

IsFIT方法读取文件头并返回真实,如果字节8–11等于ACSII值".FIT". isFIT提供了在试图解码文件之前快速检查文件为FIT文件的方法.

解码器类包括静态和实例版本的isFIT方法.

### 检查完整性方法

检查完整性方法对一个FIT文件进行三次检查:

1.  检查标题中的字节 8-11 是否包含 ASCII 值 ".FIT " .
2.  检查文件总大小是否等于标题大小+数据大小+CRC大小.
3.  读取文件内容,计算CRC,然后检查计算出来的CRC是否与文件CRC相匹配.

一个文件必须通过所有这些测试,才能被视为有效的FIT文件. 见 [IsFIT (), 检查完整性 (), 并读 () 方法配方](https://npmcn.com/fit/cookbook/isfit-checkintegrity-read/) 用于应使用检查完整性方法的用例,以及最好避免使用的方法.

### 读取方法

"读取"方法解码出输入流的所有消息,并返回包含解码过程中遇到的一系列错误的对象和按消息类型分组的解码消息词典. 解码过程中遇到的任何例外都会被读取方法所捕捉并被添加到出错的数组中.

"读取"方法接受一个可选选项对象,可以用来自定义字段数据如何在解码后的消息中表示. 所有选项默认启用 。 禁用选项可能会加快文件解码. 也可以根据如何使用已解码的数据启用或禁用选项.

```js
const { messages, errors } = decoder.read({
    mesgListener: (messageNumber, message) => {},
    applyScaleAndOffset: true,
    expandSubFields: true,
    expandComponents: true,
    convertTypesToStrings: true,
    convertDateTimesToDates: true,
    includeUnknownData: false,
    mergeHeartRates: true
});
```

#### mesg 听取者 = (消息号码,消息) => {}

可选的回调功能,在消息被完全解码并全部应用后,可用于检查或操纵消息. 消息是可变的,我们会从消息词典中的Read方法返回.

实例 mesg 听取器调用, 跟踪所有记录信件的字段名称 .

```js
const recordFields = new Set();

const onMesg = (messageNumber, message) => {
    if (Profile.types.mesgNum[messageNumber] === "record") {
        Object.keys(message).forEach(field => recordFields.add(field));
    }
}

const { messages, errors } = decoder.read({
    mesgListener = onMesg
});

console.log(recordFields);
```

#### 应用缩放AndOffset:真 QQ 假

当对原始字段值适用FIT配置中定义的缩放和相抵值时.

```js
{
  altitude: 1587 // with a scale of 5 and offset of 500 applied
}
```

当假用生字段值.

```js
{
  altitude: 10435 // raw value store in file
}
```

#### 扩展子字段: 真 QQ 假

当为FIT配置中定义的字段创建了真子字段时.

```js
{
  event: 'rearGearChange',
  data: 16717829,
  gearChangeData:16717829 // Sub Field of data when event == 'rearGearChange'
}
```

当虚空子域被省去时.

```js
{
  event: 'rearGearChange',
  data: 16717829
}
```

#### 扩展组件:真 QQ 假

当FIT配置中定义的真字段组件被扩展为新字段. 扩展Sub 字段必须设置为真实,以便扩展子字段

```js
{
  event: 'rearGearChange'
  data: 16717829,
  gearChangeData:16717829, // Sub Field of data when event == 'rearGearChange
  frontGear: 2, // Expanded field of gearChangeData, bits 0-7
  frontGearNum: 53, // Expanded field of gearChangeData, bits 8-15
  rearGear: 11, // Expanded field of gearChangeData, bits 16-23
  rearGearNum: 1, // Expanded field of gearChangeData, bits 24-31
}
```

当不扩展假字段组件时 .

```js
{
  event: 'rearGearChange',
  data: 16717829,
  gearChangeData: 16717829 // Sub Field of data when event == 'rearGearChange
}
```

#### 转换 TypesToStrings: true QQ 假

当真字段值从原始整数值转换为FIT配置中定义的相应字符串值时.

```js
{ type:'activity'}
```

当假用原始整数值时.

```js
{ type: 4 }
```

#### 转换 DateTimesToDates: true QQ 假

当将真实的 FIT Epoch 值转换为 JavaScript Date 对象时.

```js
{ timeCreated: {JavaScript Date object} }
```

当使用 FIT Epoch 值时.

```js
{ timeCreated: 995749880 }
```

当假的Utils.convertDateTimeToDate方法可能用于将FIT Epoch值转换为JavaScript Date对象.

#### 包括未知数据: 真 QQ 假

当使用字段 ID 作为密钥存储在信件中时 .

```js
{ 249: 1234} // Unknown field with an id of 249
```

#### 合并HeartRates: true QQ 虚假

当真实自动将HR消息的心率值合并到"记录"消息中时. 此选项需要启用应用 ScaleAndOffset并扩展组件选项 。 当解码信件中没有HR消息时,此选项对记录信件没有效果.

## 创建流

流对象包含要解码的二进制 FIT 数据. 流对象可以由字节阵列,ArrayBuffers和Node.jsBuffers来创建. 内部流级使用一个矩阵缓冲器来管理字节流.

#### 从字节阵列

```js
const streamFromByteArray = Stream.fromByteArray([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00]);
console.log("isFIT: " + Decoder.isFIT(streamFromByteArray));
```

#### 从矩阵缓冲器

```js
const uint8Array = new Uint8Array([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00]);
const streamFromArrayBuffer = Stream.fromArrayBuffer(uint8Array.buffer);
console.log("isFIT: " + Decoder.isFIT(streamFromArrayBuffer));
```

#### 从节点起跑

```js
const buffer = Buffer.from([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00]);
const streamFromBuffer = Stream.fromBuffer(buffer);
console.log("isFIT: " + Decoder.isFIT(streamFromBuffer));
```

#### 从使用 Node.js 的文件中

```js
const buf = fs.readFileSync('activity.fit');
const streamfromFileSync = Stream.fromBuffer(buf);
console.log("isFIT: " + Decoder.isFIT(streamfromFileSync));
```

## 用户

Utils对象既包含常数,也包含使用解码消息和字段的工作方法.

### FIT EPOCH MS (英语). 常数

FIT EPOCH MS常数代表了Unix Epoch和FIT Epoch之间的毫秒数.

```js
const FIT_EPOCH_MS = 631065600000;
```

FIT EPOCH MS值可用于将FIT Epoch值转换为JavaScript Date对象.

```js
const jsDate = new Date(fitDateTime * 1000 + Utils.FIT_EPOCH_MS);
```

### 转换时间到日期方法

一个将 FIT Epoch 值转换为 JavaScript Date 对象的说服方法.

```js
const jsDate = Utils.convertDateTimeToDate(fitDateTime);
```

## 常见问题

### @garmin-fit/sdk 是什么？

FIT 爪哇脚本 SDK注意：该包已被作者标记为弃用——This package has been renamed\. Please use @garmin/fitsdk

### 如何安装 @garmin-fit/sdk？

在项目目录运行 npm install @garmin-fit/sdk，或使用 pnpm add / yarn add / bun add。

### @garmin-fit/sdk 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/garmin-fit\_\_sdk 是否存在。

### @garmin-fit/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @garmin-fit/sdk 可以商用吗？

@garmin-fit/sdk 使用 SEE LICENSE IN LICENSE\.txt 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @garmin-fit/sdk 的下载量有多少？

根据 npm 官方下载统计，@garmin-fit/sdk 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,149 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @garmin-fit/sdk 还在维护吗？

最新版本 21\.115\.0 发布于 2023/06/21（3 年前）；至今共发布 9 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/10/04。作者已将其标记为弃用，新项目建议寻找替代方案。

