Zipreader ZIP 目录读取工具

GB.Zipreader 是一个零依赖的浏览器端 ZIP 目录读取工具。它通过 FileReader 解析本地 ZIP 文件的文件头，返回文件名、压缩方式和大小等元数据，不会解压或读取文件正文。

安装与引入

浏览器直接引入

<script src="https://cloud.m775.net/js/zipreader.js"></script>

npm 项目

npm i @gentbo/zipreader

import '@gentbo/zipreader';

快速开始

将文件输入框的选择器传给 get()，通过 success() 异步接收 ZIP 条目列表。

<input id="zipFile" type="file" accept=".zip,application/zip">

<script>
GB.Zipreader()
  .success(files => {
    console.table(files);
  })
  .error(error => {
    console.error('ZIP 读取失败：', error);
  })
  .get('#zipFile');
</script>

读取 File 对象

除了文件输入框选择器，get() 也可以直接接收浏览器的 File 对象，适合拖放上传等场景。

dropArea.addEventListener('drop', event => {
  event.preventDefault();

  GB.Zipreader()
    .simple()
    .success(names => console.log(names))
    .error(error => console.error(error))
    .get(event.dataTransfer.files[0]);
});

输出格式

默认返回对象数组，并过滤以 / 结尾的目录条目。

[
  {
    name: 'images/photo.jpg',
    method: 'Deflate',
    size: 18420,
    unsize: 35680,
    utf8: true
  }
]

nameZIP 内的完整文件路径。

method压缩方式名称，包括 Stored、Deflate、BZIP2、LZMA、PPMd 或 OTHER。

size压缩后的字节数。

unsize原始文件的字节数。

utf8ZIP 文件头是否声明文件名使用 UTF-8。

简单列表与目录

.simple()本次读取只返回文件路径字符串数组；读取完成或失败后自动恢复默认详细模式。

.directory()保留目录条目；不调用时默认只返回文件。

GB.Zipreader()
  .simple()
  .directory()
  .success(entries => {
    // ['images/', 'images/photo.jpg', 'readme.txt']
    console.log(entries);
  })
  .get('#zipFile');

API 速查

GB.Zipreader()创建独立读取器。

.success(callback)设置解析成功回调，参数为条目数组。

.error(callback)设置 FileReader、解析或文件名解码错误回调。

.simple()将下一次结果切换为文件路径数组。

.directory()在结果中包含目录条目。

.get(selectorOrFile, index = 0)异步读取文件并立即返回当前实例；index 用于选择文件输入框中的第几个文件。

使用边界

只读目录只解析本地文件头元数据，不校验 CRC，也不解压文件内容。

ZIP 特性依赖标准本地文件头；使用数据描述符、ZIP64、加密或特殊扩展的压缩包可能无法完整读取。

调用时机选择器必须指向已经存在的 file 输入框，并且用户已经选择文件。

异步结果get() 不返回 Promise；后续业务必须放在 success() 或 error() 回调中。