Archive（归档） PRO#

Archive 类用于读取、创建与修改压缩归档文件（如 ZIP 格式）。 它支持以同步或异步的方式向归档中添加文件、目录或从归档中提取文件内容。

概述#

Archive 提供了灵活的接口来管理压缩包内容，包括：

• 打开已有归档或创建新归档；
• 添加文件、目录或自定义数据；
• 支持异步与同步两种操作模式；
• 提取文件内容到内存或磁盘；
• 删除归档中的条目；
• 支持自定义压缩算法（如 deflate）；
• 可通过 entries() 获取归档中的所有条目信息。

静态方法#

static openForMode(path: string, accessMode: "update" | "read", options?: { pathEncoding?: Encoding }): Archive#

打开一个归档文件。

参数：

返回值： 返回一个 Archive 对象。

示例：

1const archive = Archive.openForMode("/tmp/example.zip", "update")

属性#

path: string#

归档文件的路径。

示例：

1console.log(archive.path)

data: Data | null#

归档的二进制数据内容（如果以内存方式打开）。

实例方法#

entries(pathEncoding?: Encoding): ArchiveEntry[]#

获取归档中所有条目的信息。

参数： pathEncoding 可选，指定路径的编码方式，默认为 "utf-8"。

返回值： 返回一个 ArchiveEntry 对象的数组，包含所有条目的信息。

getEntryPaths(encoding?: Encoding): string[]#

获取归档中所有条目的路径。

参数： encoding 可选，指定路径的编码方式，默认为 "utf-8"。

返回值： 返回一个字符串数组，包含所有条目的路径。

getEntry(path: string): ArchiveEntry | null#

获取归档中指定路径的条目。

参数： path 要获取的条目的路径。

返回值： 返回一个 ArchiveEntry 对象，或 null 如果条目不存在。

contains(path: string): boolean#

判断归档中是否包含指定路径的条目。

参数：

path 要判断的条目的路径。

返回值： true 表示存在，false 表示不存在。

示例：

1if (archive.contains("README.md")) {
2  console.log("Archive contains README.md")
3}

addEntry(path: string, toPath: string, options?: { compressionMethod?: "deflate" | "none"; bufferSize?: number }): Promise<void>#

向归档中添加一个现有文件（异步）。

参数：

示例：

1await archive.addEntry("/tmp/input.txt", "docs/input.txt", {
2  compressionMethod: "deflate"
3})

addEntrySync(path: string, toPath: string, options?)#

同步版本，与 addEntry() 功能相同。 若添加失败会抛出异常。

addFileEntry(path: string, uncompressedSize: number, provider: (offset: number, length: number) => Data, options?): Promise<void>#

通过数据提供函数添加文件到归档（异步）。

参数：

示例：

1const data = Data.fromRawString("abcdefg".repeat(100))
2await archive.addFileEntry("fromMemory.txt", data.count, (offset, length) => {
3  return data.slice(offset, offset + length)
4})

addFileEntrySync(...)#

同步版本，与上方异步方法功能一致。

addDirectoryEntry(path: string, options?): Promise<void>#

向归档中添加一个目录。

参数：

示例：

1await archive.addDirectoryEntry("images/")

addDirectoryEntrySync(...)#

同步版本，与 addDirectoryEntry() 功能相同。

removeEntry(path: string, options?): Promise<void>#

从归档中删除指定路径的条目（异步）。

参数：

示例：

1await archive.removeEntry("old/file.txt")

removeEntrySync(...)#

同步版本，与 removeEntry() 功能相同。

extract(path: string, consumer: (data: Data) => void, options?): Promise<void>#

从归档中提取指定文件，并将其数据通过回调函数分块返回（异步）。

参数：

示例：

1await archive.extract("docs/manual.txt", (chunk) => {
2  console.log("Received chunk:", chunk.count)
3})

extractSync(...)#

同步版本，与 extract() 功能一致。

extractTo(path: string, to: string, options?): Promise<void>#

将归档中的文件或目录提取到指定磁盘路径（异步）。

参数：

示例：

1await archive.extractTo("docs/", "/tmp/extracted/")

extractToSync(...)#

同步版本，与 extractTo() 功能一致。

ArchiveEntry 类型#

ArchiveEntry 表示归档中的一个条目（文件、目录或符号链接）。

示例：

1for (const entry of archive.entries()) {
2  console.log(`[${entry.type}] ${entry.path} (${entry.uncompressedSize} bytes)`)
3}

综合示例#

创建新压缩包并添加文件#

1const archive = Archive.openForMode("/tmp/example.zip", "update")
2
3await archive.addEntry(
4  "/tmp/hello.txt",
5  "docs/hello.txt",
6  { compressionMethod: "deflate" }
7)
8
9await archive.addDirectoryEntry("images/")
10await archive.addEntry("/tmp/logo.png", "images/logo.png")
11
12console.log("Archive entries:", archive.entries().length)

提取文件到本地目录#

1const archive = Archive.openForMode("/tmp/example.zip", "read")
2await archive.extractTo("docs/hello.txt", "/tmp/unpacked/hello.txt")