# @file-viewer/renderer-archive 中文文档

规范地址：https://npmcn.com/package/%40file-viewer/renderer-archive/

版本：3\.3\.3
npm 元数据更新时间：2026-10-31T11:11:58.010Z
中文译文更新时间：2026-11-14T17:42:18.010Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40file-viewer/renderer-archive
原文对照：https://npmcn.com/package/%40file-viewer/renderer-archive/?lang=original
项目主页：https://doc.file-viewer.app/guide/on-demand-renderers
源码仓库：https://github.com/flyfish-dev/file-viewer

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

- 包体积（解压后）：117 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-06-23T06:21:10.852Z
- 最新版本发布：2026-10-31T11:11:57.688Z
- 近 30 天下载量：47718（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 57 个）

## 中文简介

用于文件查看器的独立归档渲染器插件,有libarchive work,ZIP/TAR倒置,索引DB缓存,和嵌入预览.

## 安装

```sh
npm install @file-viewer/renderer-archive
```

也可以使用：`pnpm add @file-viewer/renderer-archive`、`yarn add @file-viewer/renderer-archive`、`bun add @file-viewer/renderer-archive`

## README

# @file-viewer/renderer-archive

[English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/archive/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/archive/README.zh-CN.md)

Flyfish File Viewer 的独立压缩包 renderer 包。它用 `libarchive.js` Worker + WASM 读取 RAR、7z、ZIP、TAR 等压缩包目录，并在点击内部文件时才按需解压、缓存和调用 File Viewer 的嵌套渲染能力。

## 用法

```ts
import FileViewer from '@file-viewer/vue3'
import { archiveRenderer } from '@file-viewer/renderer-archive'

const options = {
  rendererMode: 'replace',
  renderers: archiveRenderer,
}
```

也可以和其他 renderer 一起组合：

```ts
import { archiveRenderer } from '@file-viewer/renderer-archive'
import { pdfRenderer } from '@file-viewer/renderer-pdf'
import { cadRenderer } from '@file-viewer/renderer-cad'

const options = {
  rendererMode: 'replace',
  renderers: [pdfRenderer, cadRenderer, archiveRenderer],
}
```

## 能力边界

-   支持 ZIP、TAR、GZIP、RAR、7z 等常见压缩包目录预览。
-   `.cbz` / `.cbr` 自动进入漫画阅读模式：只展示图片页，按路径自然排序并自动打开封面，支持翻页按钮、页码、方向键、PageUp/PageDown、Home/End、空格键和触摸滑动。页面继续复用统一图片 renderer 的适屏、缩放和灯箱能力。
-   漫画模式完全复用现有 Worker、RAR4/RAR5、ZIP fallback、密码、按需解压、IndexedDB 缓存、体积限制和资源配置，不维护第二套解包逻辑。
-   自动兼容未声明 UTF-8、实际使用 GBK/GB18030 编码的旧 ZIP 中文文件名。
-   支持加密压缩包：检测到加密内容后使用 `libarchive.js` 统一解密，默认弹框要求用户输入密码，密码正确后继续读取目录或预览内部文件。
-   优先使用 `libarchive.js` Worker + WASM，避免大压缩包阻塞主线程。
-   Worker 不可用时自动回退到 ZIP / TAR / GZIP 兼容模式，适合手机 WebView、本地临时服务器和内网静态部署排障；加密压缩包不会走 fallback，必须发布 libarchive Worker/WASM。
-   点击内部文件后才按需解压，并通过 `renderNestedBuffer` 或 core dispatcher 复用 PDF、Office、CAD、XMind、图片、代码等现有 renderer。
-   内置体积上限、单文件预览上限、Worker 超时、IndexedDB 缓存和可配置的内部条目下载入口，避免一次性把压缩包全部展开到内存。

## 离线资产

默认会从 viewer assets 下读取：

-   `vendor/libarchive/worker-bundle.js`
-   `vendor/libarchive/libarchive.wasm`

私有化部署时可以通过 `options.archive.workerUrl` 和 `options.archive.wasmUrl` 覆盖。 Vue 3 / Vue 2.7 / Vue 2.6 full 包默认把 viewer assets 根设为 `/file-viewer/`，会自动指向这两个 libarchive 文件；如果部署在其它静态前缀，先调用对应 full 包导出的 `setDefaultFullAssetBaseUrl('/your-prefix/')` 即可。

```ts
const options = {
  archive: {
    workerUrl: '/file-viewer/vendor/libarchive/worker-bundle.js',
    wasmUrl: '/file-viewer/vendor/libarchive/libarchive.wasm',
    cache: true,
    workerTimeoutMs: 30000,
  },
}
```

## 内部条目下载权限

压缩包内部文件预览栏的下载按钮默认保持可见。需要隐藏时可以配置全局布尔值：

```ts
const options = {
  archive: {
    entryActions: {
      download: false,
    },
  },
}
```

也可以按内部路径、扩展名、大小等元数据做判断：

```ts
const options = {
  archive: {
    entryActions: {
      download(entry) {
        return entry.path.startsWith('public/')
      },
    },
  },
}
```

这个选项只影响压缩包内部条目的下载按钮，不会关闭顶层 viewer 下载原始压缩包的工具栏动作。

## 加密压缩包

默认情况下，检测到加密内容会显示内置密码弹框。业务也可以预置密码，或接管密码获取流程：

```ts
const options = {
  archive: {
    password: initialPasswordFromYourSystem,
    async requestPassword(context) {
      // context.filename / context.entryName / context.reason / context.attempt
      return await openYourPermissionCheckedPasswordModal(context)
    },
  },
}
```

`requestPassword` 返回字符串时继续解密；返回 `null` 或 `undefined` 时取消预览并展示友好提示。错误密码会重新请求密码，不会切换到 JSZip fallback。

## 迁移说明

`@file-viewer/core` 已不再内置 archive renderer，也不再为压缩包链路直接安装 `libarchive.js`。ZIP/TAR/GZIP fallback、`jszip`、缓存和 Worker 逻辑由本包维护；core 在 OFD 完全拆出前可能仍会因 OFD vendor 临时保留 `jszip`。需要压缩包预览时，请显式安装本包，或直接使用 `@file-viewer/preset-all` 聚合能力。

## 常见问题

### @file-viewer/renderer-archive 是什么？

用于文件查看器的独立归档渲染器插件,有libarchive work,ZIP/TAR倒置,索引DB缓存,和嵌入预览\.

### 如何安装 @file-viewer/renderer-archive？

在项目目录运行 npm install @file-viewer/renderer-archive，或使用 pnpm add / yarn add / bun add。

### @file-viewer/renderer-archive 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @file-viewer/renderer-archive 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @file-viewer/renderer-archive 可以商用吗？

@file-viewer/renderer-archive 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @file-viewer/renderer-archive 的下载量有多少？

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

### @file-viewer/renderer-archive 还在维护吗？

最新版本 3\.3\.3 发布于 2026/10/31（14 天前）；至今共发布 57 个版本，其中过去 12 个月发布了 57 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。