# @aksel/structjs 中文文档 规范地址：https://npmcn.com/package/%40aksel/structjs/ 版本：1\.0\.0 npm 元数据更新时间：2022-04-04T12:31:22.043Z 中文译文更新时间：2026-11-06T05:39:37.314Z 软件包许可：ISC 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40aksel/structjs 原文对照：https://npmcn.com/package/%40aksel/structjs/?lang=original 项目主页：https://github.com/TheRealAksel/structjs#readme 源码仓库：https://github.com/TheRealAksel/structjs ## 关键信息（来自 npm 元数据） - 包体积（解压后）：19.8 kB，5 个文件 - 模块格式：CommonJS - TypeScript 类型：未声明 - 运行依赖：1 个 - 首次发布：2018-12-04T18:51:30.901Z - 最新版本发布：2018-12-04T18:51:31.202Z - 近 30 天下载量：4728（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：1（近 12 个月 0 个） ## 中文简介 Javascript 的活字结构 ## 安装 ```sh npm install @aksel/structjs ``` 也可以使用：`pnpm add @aksel/structjs`、`yarn add @aksel/structjs`、`bun add @aksel/structjs` ## README # structjs - javascript中的 Python 风格的 struct 模块 此模块执行 Javascript 值和作为 javascript 表示的 C 结构的转换 [矩阵缓冲](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) 对象。 这可用于处理存储在文件中的二进制数据或来自网络连接的数据等来源. 用这个 [格式字符串](https://npmcn.com/package/%40aksel/structjs/#readme-format-strings) 用于简洁描述 C 结构的布局和打算转换为/从 javascript 值. > **说明:** 与Python struct不同,这个模块不支持本土大小和对齐(这在javascript中不会有很多意义). 相反,请明确指定字节顺序并发出字节. 几种方法: [结构](https://npmcn.com/package/%40aksel/structjs/#readme-object) 使用缓冲参数。 这指的是 [矩阵缓冲](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) 对象. > **说明:** 在 Python struct 中,缓冲参数是指执行缓冲协议的对象. ## 职能 模块定义了以下函数: **结构**(单位:千美元)_格式_(中文(简体) ) 返回一个按照 [格式字符串](https://npmcn.com/package/%40aksel/structjs/#readme-format-strings) _格式_。 。 。 . > **说明:** 这不是一个建筑师, 不要使用新的。 在Python,这是一个构造器。 Python 具有打包和打包的功能,没有使用struct函数创建对象的中间步骤. 然而,我决定不列入这些功能,因为这些功能是多余的,我不想不必要地把接口弄乱。 它们现在都在代码中,但在注释中. ## 对象 编译的 Struct 对象返回 [结构](https://npmcn.com/package/%40aksel/structjs/#readme-struct) 支持下列方法和属性: **包装**(单位:千美元)_v1, v2, (英语)._(中文(简体) ) 返回一个 [矩阵缓冲](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) 包含值的对象 _v1, v2, (英语)._ 按 [格式](https://npmcn.com/package/%40aksel/structjs/#readme-format)。参数必须精确地与格式所要求的值相匹配(`result.byteLength` 将等于 [大小](https://npmcn.com/package/%40aksel/structjs/#readme-size)) (中文(简体) ). **装入**(单位:千美元)_缓冲,偏移,v1,v2,._(中文(简体) ) 包装值 _v1, v2, (英语)._ 根据 [格式](https://npmcn.com/package/%40aksel/structjs/#readme-format) 将已打包的字节写入 [矩阵缓冲](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) _缓冲_ 开始于位置 _页:1_。注意: _页:1_ 是一个必要的论据. **打开**(单位:千美元)_缓冲_(中文(简体) ) 解开包装 [矩阵缓冲](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) _缓冲_ (大概由 `pack()`根据 [格式](https://npmcn.com/package/%40aksel/structjs/#readme-format)。其结果是,即使它包含一个完全相同的物品,它也会是一团一团。 缓冲器在字节中的大小必须与格式所要求的大小相匹配,如 [大小](https://npmcn.com/package/%40aksel/structjs/#readme-size)。 。 。 . **打开**(单位:千美元)_页:1_(中文(简体) ) 解开包装从 [矩阵缓冲](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) _缓冲_ 开始于位置 _页:1_,根据 [格式](https://npmcn.com/package/%40aksel/structjs/#readme-format)。其结果是,即使它包含一个完全相同的物品,它也会是一团一团。 缓冲器的大小, 以字节为单位, 减去 _页:1_,必须至少是格式所要求的大小,如 [大小](https://npmcn.com/package/%40aksel/structjs/#readme-size)。 。 。 . **缩写( u)**(单位:千美元)_缓冲_(中文(简体) ) 根据 [格式](https://npmcn.com/package/%40aksel/structjs/#readme-format)。此函数返回从缓冲器读取大小相同的块,直到其全部内容被消耗为止。 以字节表示的缓冲器大小必须比 [格式](https://npmcn.com/package/%40aksel/structjs/#readme-format),反映于 [大小](https://npmcn.com/package/%40aksel/structjs/#readme-size) (这没有执行,剩下的字节被默默地忽略了). 每个迭代都产生一股由下列因素指定的二重力: [格式字符串](https://npmcn.com/package/%40aksel/structjs/#readme-format-strings)。 。 。 . **格式** 这个 [格式字符串](https://npmcn.com/package/%40aksel/structjs/#readme-format-strings) 用于构造此对象. **大小** 结构的计算大小(因此 [矩阵缓冲](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) 生成对象 [包( )](https://npmcn.com/package/%40aksel/structjs/#readme-pack) 方法)对应 [格式](https://npmcn.com/package/%40aksel/structjs/#readme-format)。 。 。 . [](https://npmcn.com/package/%40aksel/structjs/format-strings) ## 格式字符串 格式字符串是用于指定包装和打包数据时的预期布局的机制. 他们是从 [格式字符](https://npmcn.com/package/%40aksel/structjs/#readme-format-characters),它指定了数据包装/解包的类型。 此外,还有特殊字符来控制 [字节顺序](https://npmcn.com/package/%40aksel/structjs/#readme-byte-order)。 。 。 . > **说明:** 与 Python struct 不同的是,本模块没有用于表示本地大小和对齐的特殊格式字符. ### 字节顺序 默认情况下,C类型以标准格式和字节顺序表示,而不以任何方式对齐(没有插入垫字节). > **说明:** 这与使用本地格式的 Python struct 不同 . 根据下表,格式字符串的第一个字符可以用来表示字节顺序: | 字符 | 字节顺序 | | --- | --- | | < | 小恩地语 | | \> 翻译: | 大号 | | 如果第一个字符不是其中之一,则假设为">". | | > **与 Python 结构的区别 :** > Python struct有更多的选择,对于javascript来说没有那么合理. > 不使用“@”、“=”、“!” 。 使用“ >” 表示“! ” . > 无出土供养. > 无对接. 用"x"来做贴. ### 格式字符 格式字符有以下含义;C和ES值之间的转换应因其类型而明显. " Size " 一栏是指以字节表示的包装值的大小: | 格式 | C 类型 | ES 类型 | 大小 | | --- | --- | --- | --- | | 页:1 | 垫字节 | | 1个 | | c. 国家 | 字符 | 长度字符串 1 | 1个 | | 页:1 | 签名字符 | 数目 | 1个 | | 页:1 | 未签名字符 | 数目 | 1个 | | ? 吗? | 布尔( B) | 布尔 | 1个 | | 页:1 | 简称 | 数目 | 2个 | | 页:1 | 未签名的简短 | 数目 | 2个 | | (单位:千美元) | 单位 | 数目 | 页:1 | | 一、导 言 | 未签名 | 数目 | 页:1 | | f 时 | 浮动 | 数目 | 页:1 | | d. 国家 | 双 | 数目 | 第8条 | | 编号 | 字符 \[\] | 字符串 | | | 页:1 | 字符 \[\] | 字符串 | | > **与 Python 的区别 :** > 不取"l","l","q","Q","P",不取整数,不取活字,不取双数,只取数字. > 对于"l"和"L"使用"i"和"我". 对于"P",酌情使用"H"或"我". > 'q'和'Q'不能在javascript中充分代表. 用"i"或"我"来代替. > 没有'n'或'n'. 格式字符前可进行整体重复计数. 例如,格式字符串 `'4h'` 意思是完全一样 `'hhhh'`。 。 。 . 格式之间的空白字符不被接受. > **说明:** Python struct 忽略了白空间字符(一个计数及其格式虽然不能包含白空间). 对于''格式字符,计数被解释为字符串的大小,而不是像其他格式字符一样的重复计数;例如, `'10s'` 表示一个10字节字符串,而 `'10c'` 指十个人物. 如果不给出一个计数,则默认为 1. 包装时,串被切开或加上适当的无字节来使其适合. 对于打包,产生的字符串总是有精确的指定字节数. > **说明**: Python struct 接受特例;"0s"表示一单空字符串(而"0c"表示0个字符). > **说明:** Python 保证在使用一个整数格式('b','B','h','H','i','I','l','L','q','Q')来包装一个值x时,如果x超出了该格式的有效范围,则会提高struct.error. “ p” 格式字符编码为“ Pascal 字符串”, 意思是存储在一个 _固定字节数_,由伯爵给出. 存储的第一个字节是字符串的长度,或255,以较小者为准. 字符串的字节接踵而来. 如果字符串传递到 [包( )](https://npmcn.com/package/%40aksel/structjs/#readme-pack) 长度太长( 比数倒数 1 长), 只有领先 `count-1` 字符串的字节被存储 。 如果字符串短于 `count-1`,它用无字节来添加,这样就可以使用精确的字节。 请注意: [无包装 ()](https://npmcn.com/package/%40aksel/structjs/#readme-unpack),则 `'p'` 格式字符消耗 `count` 字节,但返回的字符串永远不能包含超过255个字符. 给 `'?'` 格式字符,返回值为 [真实](https://npmcn.com/package/%40aksel/structjs/link-to-es-true) 或者说 [虚假](https://npmcn.com/package/%40aksel/structjs/link-to-es-false)。在打包时,使用了参数对象的真值。 原生或标准布尔表示值中的0或1将被打包,任何非零值都将是 `true` 解开时. ### 实例: 包装/卸下三个整数的基本例子: ```javascript let struct = require("./struct"), s = struct('hhi'), b = new ArrayBuffer(s.size) s.pack(1, 2, 3) // ArrayBuffer {} new Uint8Array(s.pack(1, 2, 3)) // Uint8Array { '0': 0, '1': 1, '2': 0, '3': 2, '4': 0, '5': 0, '6': 0, '7': 3 } s.unpack(new Uint8Array([0, 1, 0, 2, 0, 0, 0, 3]).buffer) // [ 1, 2, 3 ] s.size // 8 s.pack_into(b, 0, 1, 2, 3) new Uint8Array(b) // Uint8Array { '0': 0, '1': 1, '2': 0, '3': 2, '4': 0, '5': 0, '6': 0, '7': 3 } ``` 未包装的字段可以通过指定变量来命名 : ```javascript let struct = require("./struct"), s = struct("<10sHHb") let record = s.pack("Raymond ", 4658, 264, 8) let [name, serialnum, school, gradelevel] = s.unpack(record) ``` ## 常见问题 ### @aksel/structjs 是什么？ Javascript 的活字结构 ### 如何安装 @aksel/structjs？ 在项目目录运行 npm install @aksel/structjs，或使用 pnpm add / yarn add / bun add。 ### @aksel/structjs 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aksel\_\_structjs 是否存在。 ### @aksel/structjs 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @aksel/structjs 可以商用吗？ @aksel/structjs 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @aksel/structjs 的下载量有多少？ 根据 npm 官方下载统计，@aksel/structjs 在 2026/10/06 – 2026/11/04 这 30 天内被下载 4,728 次，日均约 158 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @aksel/structjs 还在维护吗？ 最新版本 1\.0\.0 发布于 2018/12/05（7 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/12/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。