桌面应用文档【免费下载链接】sumatrapdfSumatraPDF reader项目地址https://gitcode.com/gh_mirrors/su/sumatrapdf点击查看免费下载导读本文基于当前仓库 ext/mupdf/docs/reference/javascript/types/Archive.rst 编写系统讲解 MuPDF JavaScript 绑定mupdf.js中mupdf.Archive类的全部 API——包括构造函数与五个实例方法。Archive 是 MuPDF JS 引擎读写 ZIP、TAR 归档文件以及本地目录的统一入口在 SumatraPDF 集成的 MuPDF 引擎中负责字体包、资源包等打包文件的按需读取。读完本文你将掌握如何创建 Archive、枚举条目、判断条目是否存在、读取条目二进制内容并能结合仓库源码理解其底层调用链与设计意图。一、Archive 是什么MuPDF JS 绑定的统一归档抽象Archive是 MuPDF JavaScript 绑定中用于打包文件集合的抽象类型。它把三种截然不同的物理载体统一成一个接口物理载体说明ZIP 文件基于 zip 格式的压缩归档TAR 文件基于 tar 格式的归档通常不压缩本地目录把磁盘上的一个文件夹当作归档逐文件读取在文档中该类型标注了|only_mutool|即此绑定接口随 MuPDF 自带的小型 JavaScript 解释器mutool run / murun一同提供是mupdf.js面向 Node.js 等宿主环境的 JS 封装。从源码看MuPDF 底层有多个归档 handlerzip、tar、directory 等统一通过fz_archive结构暴露。JS 绑定层ext/mupdf/source/tools/murun.c 中的ffi_new_Archive等函数只是对 C 层fz_archiveAPI 的薄封装因此 Archive 的方法语义与 MuPDF C API 一一对应。二、构造函数三种创建方式2.1new mupdf.Archive(path)—— 按路径创建new mupdf.Archive(path)参数path字符串归档文件或目录的路径。行为MuPDF 会先判断该路径是否指向目录是目录 → 以目录模式打开等价于 C 层fz_open_directory否则 → 按文件模式打开等价于 C 层fz_open_archive内部按 zip/tar 等格式逐一识别。文档给出的三个示例var archive1 new mupdf.Archive(example1.zip) var archive2 new mupdf.Archive(example2.tar) var archive3 new mupdf.Archive(images/)三个示例分别演示了 ZIP、TAR 与目录三种载体。源码中这一分支逻辑清晰可见ext/mupdf/source/tools/murun.c#L3677-L3687if (fz_is_directory(ctx, path)) arch fz_open_directory(ctx, path); else arch fz_open_archive(ctx, path);底层fz_open_archiveext/mupdf/source/fitz/archive.c#L207-L223先以文件流方式打开路径再交由fz_open_archive_with_stream遍历已注册的 handler 逐个调用recognize嗅探格式直到某 handler 识别成功若全部失败会抛出FZ_ERROR_FORMATcannot recognize archive。因此传入无法识别的文件如纯文本会直接报错。2.2new mupdf.Archive(buffer)—— 从内存缓冲区创建new mupdf.Archive(buffer)参数bufferBuffer | ArrayBuffer | Uint8Array | string包含归档内容的缓冲区。行为将内存数据包装成流后按格式识别不落盘适合网络下载或加密容器中解出的归档。var archive1 new mupdf.Archive(fs.readFileSync(example1.zip)) var archive2 new mupdf.Archive(fs.readFileSync(example1.tar))fs.readFileSync返回 Node.js 的Buffer可直接传入。底层对应ffi_new_Archive中的fz_open_bufferfz_open_archive_with_stream路径ext/mupdf/source/tools/murun.c#L3664-L3673其中ffi_tonewbuffer负责把 JS 侧的 Buffer/ArrayBuffer/Uint8Array/字符串统一规整为 MuPDF 的fz_buffer。三、实例方法五个核心操作3.1getFormat()—— 获取归档格式archive.getFormat()返回值string描述归档格式。说明内部调用fz_archive_format(ctx, arch)ext/mupdf/source/tools/murun.c#L3693-L3703。不同 handler 会返回不同的格式名从 MuPDF 的 zip/tar/directory handler 实现看返回值一般为zip、tar、dir等类型名。var archive new mupdf.Archive(example1.zip) print(archive.getFormat())在 mutool 解释器中print()可用在 Node.js 环境请改用console.log()。3.2countEntries()—— 统计条目数量archive.countEntries()返回值number归档内的条目总数。说明内部调用fz_count_archive_entries(ctx, arch)ext/mupdf/source/tools/murun.c#L3705-L3715直接返回 C 层计数。var archive new mupdf.Archive(example1.zip) var numEntries archive.countEntries()该数值是遍历全部条目的循环上界常与listEntry配合使用见第五节完整示例。3.3listEntry(idx)—— 按索引列出条目名archive.listEntry(idx)参数idxnumber条目索引从 0 开始。返回值string | null第idx个条目的名称若索引越界返回null。var archive new mupdf.Archive(example1.zip) var entry archive.listEntry(0)底层实现在 ext/mupdf/source/tools/murun.c#L3717-L3731调用fz_list_archive_entry后若返回非空指针则压入字符串否则向 JS 栈压入null——这正是返回值可为null的来源。注意文档并未承诺条目顺序与 zip 内部存储顺序的关系跨归档遍历时建议只把索引当作序号使用。3.4hasEntry(name)—— 判断条目是否存在archive.hasEntry(name)参数namestring要查找的条目名。返回值boolean指定名称的条目是否存在。var archive new mupdf.Archive(example1.zip) var hasEntry archive.hasEntry(file1.txt)底层调用fz_has_archive_entry(ctx, arch, name)ext/mupdf/source/tools/murun.c#L3733-L3744返回布尔值。在读取前先做存在性检查可以避免对不存在的条目触发readEntry的异常是健壮性最佳实践。3.5readEntry(name)—— 读取条目内容archive.readEntry(name)参数namestring要读取的条目名。返回值Buffer条目的完整二进制内容。var archive new mupdf.Archive(example1.zip) var contents archive.readEntry(file1.txt)底层调用fz_read_archive_entry得到fz_buffer再通过ffi_pushbuffer_own以接管所有权方式包装成 JS 侧的 Buffer 返回ext/mupdf/source/tools/murun.c#L3746-L3757。返回值是二进制缓冲区即使条目是文本文件也建议显式指定编码转换如Buffer.from(contents).toString(utf8)后再做字符串处理。四、错误与边界行为传入不存在的路径、无法识别的归档或读取不存在的条目均会抛出异常。这与底层fz_throw(ctx, FZ_ERROR_FORMAT, cannot recognize archive)的行为一致ext/mupdf/source/fitz/archive.c#L198-L205。listEntry(idx)越界时返回null而非抛异常这是文档明确约定、源码确认的行为。Archive(buffer)构造时MuPDF 会以只读方式包装传入的缓冲区fz_open_buffer随后在fz_always块中释放归档流与缓冲引用ext/mupdf/source/tools/murun.c#L3669-L3673内存生命周期由绑定层托管无需 JS 侧手动释放。目录模式dir下条目名即目录内文件的相对路径名readEntry按名回读文件内容目录访问会受宿主机文件系统权限约束。五、完整示例遍历并打印归档全部条目文档末尾给出了一个遍历归档的完整示例它组合了countEntries、listEntry与readEntry三个方法var archive new mupdf.Archive(example1.zip) var n archive.countEntries() for (var i 0; i n; i) { var entry archive.listEntry(i) var contents archive.readEntry(entry) console.log(entry, entry, contents.length) }该模式可以推广为通用的归档转储脚本先统计条目数再按索引取名称最后按名称读取内容并打印字节长度。若需要在读取前防御性检查可先调用archive.hasEntry(entry)过滤。六、与相邻类型的协同Archive 并非孤立存在MuPDF JS 绑定还提供两种衍生类型都记录在 ext/mupdf/docs/reference/javascript/types/index.rst 的 Common 分组中MultiArchive虚拟归档可把多个 Archive 挂载到不同路径前缀下new mupdf.MultiArchive()mountArchive(subArchive, path)见 ext/mupdf/source/tools/murun.c#L3759-L3791常用于资源分片或覆盖式打包。TreeArchive内存中的目录树式归档可通过add(name, buffer)动态添加条目ext/mupdf/source/tools/murun.c#L3793-L3805适合程序化构建虚拟文件系统。此外MuPDF 的文档与图片加载接口如mupdf.Document.openDocument系列同样接受fz_archive类型的参数因此 Archive 也可作为资源容器注入到文档打开流程中。需要深度应用时可继续阅读 ext/mupdf/docs/reference/javascript/types/MultiArchive.rst 与 ext/mupdf/docs/reference/javascript/types/TreeArchive.rst。七、在 SumatraPDF 项目中的定位SumatraPDF 仓库以ext/mupdf子目录方式内嵌 MuPDF 源码本次讲解的 Archive JS 绑定ext/mupdf/source/tools/murun.c与底层归档实现ext/mupdf/source/fitz/archive.c均来自该内嵌副本。需要说明的是mupdf.Archive是MuPDF 自带 JavaScript 解释器mutool run及 mupdf.js 绑定的能力面向 Node.js 等宿主环境它属于 MuPDF 独立能力并非 SumatraPDF Windows 桌面程序运行时的内置对象也不属于 SumatraPDF 的 C/Win32 UI 代码路径在 SumatraPDF 中MuPDF 更多以 C 引擎形式src/EngineMupdf.cpp被调用PDF、EPUB、MOBI 等文档引擎正是通过该 C 层对归档/资源的读取能力来加载文档内嵌资源的。因此若你正在开发基于 mupdf.js 的 Web 或 Node 工具如资源提取、字体打包校验Archive是直接可用的 API若你关注的是 SumatraPDF 桌面端如何用 MuPDF 读档则应从 src/EngineMupdf.cpp 的 C API 调用入手。八、小结mupdf.Archive用五个方法覆盖了归档读取的全部常见诉求方法作用返回getFormat()获取格式名stringcountEntries()统计条目数numberlistEntry(idx)按索引取条目名string | nullhasEntry(name)判断条目是否存在booleanreadEntry(name)读取条目二进制内容Buffer配合路径/缓冲两种构造函数它可以在 ZIP、TAR、目录三种载体之间做到无差别访问是 mupdf.js 中轻量而实用的虚拟文件系统入口。赞分享桌面应用文档【免费下载链接】sumatrapdfSumatraPDF reader项目地址https://gitcode.com/gh_mirrors/su/sumatrapdf点击查看免费下载相关推荐Dokku 使用 tar/zip 归档初始化应用仓库git:from-archive 完整指南Dokku 使用 tar/zip 归档初始化应用仓库git:from archive 完整指南 导读 dokku git:from archive 是 Dok即时通讯后端微服务WebSocketchezmoi archive 命令完全指南导出目标状态为 tar/zip 归档chezmoi archive 命令完全指南导出目标状态为 tar/zip 归档 本文围绕 chezmoi 的 archive 命令展开讲解如何将当前机器上开发工具CLI配置管理SumatraPDF 内置 MuPDF 的 JavaScript 绑定Point 类型与坐标变换实战指南SumatraPDF 内置 MuPDF 的 JavaScript 绑定Point 类型与坐标变换实战指南 本文以 ext/mupdf/docs/referen桌面应用文档上一篇pi coding agent 快速上手指南统一 LLM API、会话树与扩展生态下一篇IDM下载加速不失效开源脚本冻结试用期的完整实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
