# @foliojs-fork/restructure 中文文档

规范地址：https://npmcn.com/package/%40foliojs-fork/restructure/

版本：2\.0\.2
npm 元数据更新时间：2022-04-05T11:35:55.184Z
中文译文更新时间：2026-11-15T04:06:38.521Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40foliojs-fork/restructure
原文对照：https://npmcn.com/package/%40foliojs-fork/restructure/?lang=original
项目主页：https://github.com/foliojs-fork/restructure
源码仓库：https://github.com/foliojs-fork/restructure

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

- 包体积（解压后）：118 kB，35 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2021-07-01T08:52:15.855Z
- 最新版本发布：2021-08-02T05:20:13.022Z
- 近 30 天下载量：7507397（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

解码并解码二进制数据

## 安装

```sh
npm install @foliojs-fork/restructure
```

也可以使用：`pnpm add @foliojs-fork/restructure`、`yarn add @foliojs-fork/restructure`、`bun add @foliojs-fork/restructure`

## README

# 结构分叉 [![npm](https://img.shields.io/npm/v/@foliojs-fork/restructure.svg)](https://www.npmjs.com/package/@foliojs-fork/restructure)

重组允许您声明编码并解码二进制数据. 它支持各种各样的类型,使你能够表达多种 二进制格式,而不写入任何解析代码.

支持的一些功能是C型结构,版本结构, 指针,任意类型的阵列,大量编码的字符串,enum, 比特菲尔德,还有更多。 详情见下文.

## 为什么是叉子?

因为原始的repo无法在npm上发布新版本 [foliojs/结构#45](https://github.com/foliojs/restructure/issues/45)。 。 。 . 这道叉与原始回波相同并保持了最新.

## 安装

```
npm install @foliojs-fork/restructure
```

## 示例

这只是一个小的例子 重建可以做什么。 检查 API 文档 详情见下文.

```javascript
var r = require('restructure');

var Person = new r.Struct({
  name: new r.String(r.uint8, 'utf8'),
  age: r.uint8
});

// decode a person from a buffer
var stream = new r.DecodeStream(buffer);
Person.decode(stream); // returns an object with the fields defined above

// encode a person from an object
// pipe the stream to a destination, such as a file
var stream = new r.EncodeStream();
stream.pipe(fs.createWriteStream('out.bin'));

Person.encode(stream, {
  name: 'Devon',
  age: 21
});

stream.end();
```

## API 密码

下列所有类型都支持三种标准方法:

-   `decode(stream)` - 从给定的解码站解码类型实例
-   `size(value)` - 返回编码后值将占用的空格
-   `encode(stream, value)` - 将给定值编码入给定的 EncodeStream

调整结构支持多种类型,但是如果您需要为 一些不能用它们来表示的自定义用途,您只需执行即可 以上方法。 然后,你可以使用你的类型 就像你喜欢的其他类型,在结构 和什么没有.

### 数量类型

现有内置编号类型如下:

```javascript
uint8, uint16, uint24, uint32, int8, int16, int24, int32, float, double, fixed16, fixed32
```

数字默认为大-endian(网络顺序),但小-endian也被支持:

```javascript
uint16le, uint24le, uint32le, int16le, int24le, int32le, floatle, doublele, fixed16le, fixed32le
```

为了避免模棱两可,可以明确使用大词:

```javascript
uint16be, uint24be, uint32be, int16be, int24be, int32be, floatbe, doublebe, fixed16be, fixed32be
```

### 布尔

布尔编码为 `0` 或者说 `1` 使用上述数字类型之一.

```javascript
var bool = new r.Boolean(r.uint32);
```

### 准备金

这个 `Reserved` 字段. 编码产生零.

```javascript
// 10 reserved uint8s (default is 1)
var reserved = new r.Reserved(r.uint8, 10);
```

### 可选

这个 `Optional` 键入只有给定条件为真实时的编码或解码.

```javascript
// includes field
var optional = new r.Optional(r.uint8, true);

// excludes field
var optional = new r.Optional(r.uint8, false);

// determine whether field is to be included at runtime with a function
var optional = new r.Optional(r.uint8, function() {
  return this.flags & 0x50;
});
```

### 数字

这个 `Enum` 键入数组中该索引的数值.

```javascript
var color = new r.Enum(r.uint8, ['red', 'orange', 'yellow', 'green', 'blue', 'purple']);
```

### 比特菲尔德

这个 `Bitfield` 类型将数字映射到一个对象,其中布尔键映射到该数字中的每个比特, 在数组中定义.

```javascript
var bitfield = new r.Bitfield(r.uint8, ['Jack', 'Kack', 'Lack', 'Mack', 'Nack', 'Oack', 'Pack', 'Quack']);
bitfield.decode(stream);

var result = {
  Jack: true,
  Kack: false,
  Lack: false,
  Mack: true,
  Nack: true,
  Oack: false,
  Pack: true,
  Quack: true
};

bitfield.encode(stream, result);
```

### 缓冲

提取缓冲部分到节点 `Buffer`。长度可以是常数,也可以取自 a 父结构中的上一个字段.

```javascript
// fixed length
var buf = new r.Buffer(2);

// length from parent structure
var struct = new r.Struct({
  bufLen: r.uint8,
  buf: new r.Buffer('bufLen')
});
```

### 字符串

A 类 `String` 将 JavaScript 字符串映射到二进制编码。 长度可以是恒定的 从父结构中的上一个字段,或用紧接字符串前的数字类型编码.

支持的编码包括 `'ascii'`, (中文(简体) ), `'utf8'`, (中文(简体) ), `'ucs2'`, (中文(简体) ), `'utf16le'`, (中文(简体) ), `'utf16be'`,如果您同时安装 [图标-升](https://github.com/ashtuchkin/iconv-lite)还有许多其他遗留的解码器.

```javascript
// fixed length, ascii encoding by default
var str = new r.String(2);

// length encoded as number before the string, utf8 encoding
var str = new r.String(r.uint8, 'utf8');

// length from parent structure
var struct = new r.Struct({
  len: r.uint8,
  str: new r.String('len', 'utf16be')
});

// null-terminated string (also known as C string)
var str = new r.String(null, 'utf8')
```

### 阵列

一个 `Array` 包含子类型实例的 JavaScript 阵列。 长度可以是一个常数, 取自父结构中的上一个字段,立即使用数字类型编码 在字符串之前,或由函数计算.

```javascript
// fixed length, containing numbers
var arr = new r.Array(r.uint16, 2);

// length encoded as number before the array containing strings
var arr = new r.Array(new r.String(10), r.uint8);

// length computed by a function
var arr = new r.Array(r.uint8, function() { return 5 });

// length from parent structure
var struct = new r.Struct({
  len: r.uint8,
  arr: new r.Array(r.uint8, 'len')
});

// treat as amount of bytes instead (may be used in all the above scenarios)
var arr = new r.Array(r.uint16, 6, 'bytes');
```

### 懒惰箭头

这个 `LazyArray` 类型从 `Array` 类型,并且对不需要按顺序访问的大型数组有用. 它避免了将整个阵列在前方解码,而是只根据需要解码并缓存单个项目. 只有当 数组中的元素具有固定大小.

而不是返回 JavaScript 阵列 `LazyArray` 类型返回可用于访问元素的自定义对象.

```javascript
var arr = new r.LazyArray(r.uint16, 2048);
var res = arr.decode(stream);

// get a single element
var el = res.get(2);

// convert to a normal array (decode all elements)
var array = res.toArray();
```

### 结构

A 类 `Struct` 用于 JavaScript 对象的地图,包含以前讨论过的各种类型的密钥。 次级结构, 支持结构阵列,并指向其他类型(下文讨论).

```javascript
var Person = new r.Struct({
  name: new r.String(r.uint8, 'utf8'),
  age: r.uint8
});
```

### 版本结构

A 类 `VersionedStruct` 是一个 `Struct` 这有多个版本。 该版本通常编码于 结构的开始,或作为母结构中的一个字段。 有可选的 `header` 为所有版本所共有,并为每个版本编号列出单独的字段.

```javascript
// the version is read as a uint8 in this example
// you could also get the version from a key on the parent struct
var Person = new r.VersionedStruct(r.uint8, {
  // optional header common to all versions
  header: {
    name: new r.String(r.uint8, 'utf8')
  },
  0: {
    age: r.uint8
  },
  1: {
    hairColor: r.Enum(r.uint8, ['black', 'brown', 'blonde'])
  }
});
```

### 指针

指针将一个被编码为数字的地址或抵消映射到缓冲器中其它处被编码的值. 有一些选项可供您使用 : `type`, (中文(简体) ), `relativeTo`, (中文(简体) ), `allowNull`,以及 `nullValue`。 。 。 . 这个 `type` 选项有这些可能的值:

-   `local` (默认) - 被编码的偏移相对于包含结构的起始
-   `immediate` - 与指针本身的位置相对的编码偏移
-   `parent` - 与直接容器的母结构相对的编码抵消
-   `global` - 编码后偏移是全局到文件开始

这个 `relativeTo` 选项接受一个函数的回调,该回调应当将字段返回到编码后相对的所包含结构上。 召回以上下文为参数. 默认情况下,指针是相对于所包含结构的起始(`local`) (中文(简体) ).

这个 `allowNull` 选项,允许您指定是否允许零偏移或是否应当生产 `null`这是 设置为 `true` 默认。 这个 `nullValue` 选项关联,并让您覆盖编码的值 显示 `null`默认情况下 `nullValue` 为零.

这个 `lazy` 选项允许通过定义母对象上的获取器来懒惰地解码指针的值. 这只有在指针被包含在 Struct 中时才有效, 但可用于加速解码 当不是所有的数据 需要马上.

```javascript
var Address = new r.Struct({
  street: new r.String(r.uint8),
  zip: new r.String(5)
});

var Person = new r.Struct({
  name: new r.String(r.uint8, 'utf8'),
  age: r.uint8,
  ptrStart: r.uint8,
  address: new r.Pointer(r.uint8, Address)
});
```

如果指针的类型被设定为“ 无效 ” , 它不会被解码, 并且会计算出缓冲器中的地址 仅返回。 要编码空指针,请创建 `new r.VoidPointer(type, value)`。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @foliojs-fork/restructure 是什么？

解码并解码二进制数据

### 如何安装 @foliojs-fork/restructure？

在项目目录运行 npm install @foliojs-fork/restructure，或使用 pnpm add / yarn add / bun add。

### @foliojs-fork/restructure 支持 TypeScript 吗？

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

### @foliojs-fork/restructure 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @foliojs-fork/restructure 可以商用吗？

@foliojs-fork/restructure 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @foliojs-fork/restructure 的下载量有多少？

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

### @foliojs-fork/restructure 还在维护吗？

最新版本 2\.0\.2 发布于 2021/08/02（5 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/07/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。