# @garmin/fitsdk 中文文档

规范地址：https://npmcn.com/package/%40garmin/fitsdk/

版本：21\.221\.0
npm 元数据更新时间：2026-11-03T21:03:10.855Z
中文译文更新时间：2026-11-15T23:27:05.734Z
软件包许可：SEE LICENSE IN LICENSE\.txt

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

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

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

- 包体积（解压后）：1.5 MB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-09-19T18:48:59.732Z
- 最新版本发布：2026-11-03T21:03:10.509Z
- 近 30 天下载量：336340（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 14 个）

## 中文简介

FIT 爪哇脚本 SDK

## 安装

```sh
npm install @garmin/fitsdk
```

也可以使用：`pnpm add @garmin/fitsdk`、`yarn add @garmin/fitsdk`、`bun add @garmin/fitsdk`

## 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运行时引擎的浏览器.

## 安装

FIT JavaScript SDK 在 npm 作为节点JS 软件包发布 [@ garmin/ 齐克](https://www.npmjs.com/package/@garmin/fitsdk) 并可以安装 npm cli.

```sh
npm install @garmin/fitsdk
```

## 解码器

### 使用量

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

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/fitsdk/#readme-creatingstreams) 以获取关于构建流对象的更多信息.

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

### 是FIT 方法

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

```bash
  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等于ASCII值".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) => {},
    mesgDefinitionListener: (mesgDefinition) => {},
    fieldDescriptionListener: (key, developerDataIdMesg, fieldDescriptionMesg) => {},
    applyScaleAndOffset: true,
    expandSubFields: true,
    expandComponents: true,
    convertTypesToStrings: true,
    convertDateTimesToDates: true,
    includeUnknownData: false,
    mergeHeartRates: true,
    decodeMemoGlobs: false,
    skipHeader: false,
    dataOnly: false,
    legacyArrayMode: false, // Deprecated
});
```

#### 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);
```

#### mesg 定义倾听者 : (mesg Definition) \* \* \* \* \* \* \*

可选的回调功能,可以用来检查信件定义,因为它们是从文件中解码的.

#### 字段描述倾听器 :( 键, 开发者 DataIdMesg, 字段描述Mesg) QQQ

可选的回调功能,可用于检查开发者从文件中解码的字段描述.

#### 应用缩放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消息时,此选项对记录信件没有效果.

#### 解码MemoGlobs:真 QQ 假

当属实时,解码器会从备忘录Glob消息中重建字符串. 每个被重建的字符串会覆盖目标的信息字段.

#### 跳过页眉: 真 QQ 假

当真实时,解码器会读取过14字节头并忽略其内容. 然后解码器从文件流的大小假设文件数据大小.

#### 数据只显示:真 QQ 假

当真实时,解码器会读取文件,仿佛14字节标题没有被写入. 解码器然后假设文件从消息定义开始,并假设文件数据大小从文件流的大小开始.

#### 遗留的箭头模式:真 QQ 假 _(已过期)_

eOY 2026 将删除.

当虚假 _(默认)_,解码器将坚持数组字段的配置.

阵列字段总是作为数组返回, 即使只有一个元素 非阵列字段将总是返回一个单一的值, 即使存在多个值 将遗留的ArrayMode 选项设置为真实, 将恢复到 v21. 205 前置行为

## 创建流

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

#### 从字节阵列

```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);
```

## 编码器

### 使用量

```js
// Import the SDK
import { Encoder, Profile} from "@garmin/fitsdk";

// Create an Encoder
const encoder = new Encoder();

//
// Write messages to the output-stream
//
// The message data should match the format returned by
// the Decoder. Field names should be camelCase. The fields
// definitions can be found in the Profile.
//

// Pass the MesgNum and message data as separate parameters to the onMesg() method
encoder.onMesg(Profile.MesgNum.FILE_ID, {
  manufacturer: "development",
  product: 1,
  timeCreated: new Date(),
  type: "activity",
});

// The writeMesg() method expects the mesgNum to be included in the message data
// Internally, writeMesg() calls onMesg()
encoder.writeMesg({
  mesgNum: Profile.MesgNum.FILE_ID,
  manufacturer: "development",
  product: 1,
  timeCreated: new Date(),
  type: "activity",
});

// Unknown values in the message will be ignored by the Encoder
encoder.onMesg(Profile.MesgNum.FILE_ID, {
  manufacturer: "development",
  product: 1,
  timeCreated: new Date(),
  type: "activity",
  customField: 12345, // This value will be ignored by the Encoder
});

// Subfield values in the message will be ignored by the Encoder
encoder.onMesg(Profile.MesgNum.FILE_ID, {
  manufacturer: "development",
  product: 4440, // This is the main product field, which is a uint16
  garminProduct: "edge1050", // This value will be ignored by the Encoder, use the main field value instead
  timeCreated: new Date(),
  type: "activity",
});

// Closing the encoder returns the file as an UInt8 Array
const uint8Array = encoder.close();

// Write the file to disk,
import * as fs from "fs";
fs.writeFileSync("example.fit", uint8Array);

```

见 [编码活动路径](https://github.com/garmin/fit-javascript-sdk/blob/main/test/encode-activity-recipe.test.js) 用于使用 FIT JavaScript SDK 编码 FIT 活动文件的完整实例.

## 常见问题

### @garmin/fitsdk 是什么？

FIT 爪哇脚本 SDK

### 如何安装 @garmin/fitsdk？

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

### @garmin/fitsdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @garmin/fitsdk 支持 ESM 还是 CommonJS？

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

### @garmin/fitsdk 可以商用吗？

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

### @garmin/fitsdk 的下载量有多少？

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

### @garmin/fitsdk 还在维护吗？

最新版本 21\.221\.0 发布于 2026/11/04（12 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 14 个；首次发布于 2023/09/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

