File Viewer 非常棒的一款前端文件预览插件

面向企业后台、内网和私有化系统的纯前端文件预览组件。

项目定位

为了预览一份内部 DOCX 就把文件上传到第三方，既慢也不合适。File Viewer 把预览留在浏览器内，让企业后台、OA、知识库、工单、附件中心和工程资料库使用同一套 API，而不是继续拼接一堆互不一致的查看器。

当前内置 274 个已注册扩展名（224 个稳定、50 个实验）和 47 条预览链路。Office、PDF、OFD、Typst、CAD、STEP、XMind、压缩包、邮件、绘图、音视频、代码、Adobe 设计文件、字体、结构化数据、DICOM、数字签名容器和显式二进制检查器共享文件源、生命周期、搜索、缩放、打印、导出和下载契约；重型 Worker、WASM、字体与 vendor 资产保持按需加载，并可完全托管在自己的网络中。

源码新增显式启用的 BPMN 流程图 和 XML 校验与转换配置，尚未包含在 npm 3.1.1 中。Full 包的默认依赖和兼容范围不变。

新项目优先使用 @file-viewer/*；@flyfish-group/* 历史包继续同步维护。

当前版本与新增能力

当前稳定版为 v3.1.1。本页说明当前源码的能力；主分支与在线 Demo 可能包含稳定版之后的修复，使用 npm 或 Release 归档时请按对应版本验证。

• 二进制检查器 @file-viewer/renderer-binary 提供十六进制、ASCII、字段树和字节范围联动，可检查 BIN、HEX、ELF、PE、Java Class 与 Mach-O 文件，只读分析，不执行文件。
• IFC 可通过 @file-viewer/renderer-3d/ifc 显式启用，提供本地几何预览、构件选择与属性查看；需要另行安装依赖并自托管 Worker/WASM，见 IFC 接入说明。
• Adobe 设计文件、DICOM、数字签名容器和二进制检查按需安装，不会悄悄进入现有 Full 包。签名的密码学检查结果与证书信任、策略符合性及法律有效性分别呈现。
• Vue 2.6/2.7、React 16.8/17 等旧项目仍有对应组件和示例；Full 包保持已发布的兼容范围，具体边界见下文。

亮点

• 一个组件起步。 Vanilla JS / Web Component 优先，并提供 Vue、React、Svelte、jQuery 原生组件。
• 矩阵可核验。 274 个已注册扩展名（224 个稳定、50 个显式按需实验项）映射到 47 条预览链路，覆盖办公、工程、设计、数据、音视频、代码、DICOM、数字签名和二进制检查附件。
• 部署不出网。 浏览器内解析和渲染，支持离线网络、Docker、私有 CDN 和完整资源自托管。
• 模块化。 轻量组件、renderer、preset、full 包分层清晰，可以只安装需要的格式，也可以使用预置组合。
• 按需加载。 PDF、Office、CAD、Typst、压缩包、图纸、PSD、Mermaid 等重型能力只在命中格式时加载。
• 有界多页 TIFF。 CCITT Group 4 TIFF 在独立懒加载边界逐页解码，并支持整组缩放、旋转、适宽、页码状态和大图查看。
• 识别 Vite 版本。 Vite 5 至 7 继续使用 Rollup manualChunks；Vite 8 使用 Rolldown 分组，不覆盖业务已有分组和优先级。
• 操作完整。 搜索、高亮、缩放、打印、导出 HTML、下载、水印、主题、生命周期钩子和按钮前置校验都走统一 API。
• 生态一致。 Core 聚焦底层能力，各框架组件只做原生封装，参数、事件和 controller 体验保持一致。

按场景选择入口

在线效果

打开 demo.file-viewer.app 即可使用上图中的产品工作台：固定玻璃工具栏、点击文件名展开的样例库、本地最近打开记录、明暗主题、移动端单一“更多”入口，以及只让文档容器滚动的沉浸画布。内置样例覆盖 Word、Excel、二进制 PPT、PPTX、PDF/OFD、DWG、STEP、压缩包、邮件和其余已注册矩阵；也可以上传脱敏文件或粘贴 URL。

兼容性反馈

这个项目还在持续打磨，尤其需要真实业务文件来验证兼容性。

如果文件渲染异常，请先在 Demo 验证，再使用带标注说明的 Bug 表单 或 文件兼容性表单。所有 Bug 必须提供公开/脱敏样例、公开复现链接，或注明私有样例已发送到 admin@flyfish.dev；截图可以帮助对比，但不能替代样例。

如果这个方向刚好对你有用，也欢迎收藏项目。比起单纯 Star，我更希望收到真实场景下的兼容性反馈。

快速开始

新项目可以用 CLI 生成示例，已有项目可按提示添加组件和资产配置：

npm create file-viewer@latest my-viewer
# 在已有项目中接入
npx file-viewer-cli@latest add .

CLI 默认使用 Standard 组合；--profile full 选择 Full 兼容包并添加 DICOM、数字签名能力，Adobe 设计和二进制检查仍需显式选择。各选项见 CLI 文档。

手动接入时，先选组件，再选格式能力。*-full 已内置 preset-all 的兼容基线：221 个扩展名、32 条预览链路；npm 项目还需一次性部署同版本运行时资产。

官方 8 个 Full 包是 @file-viewer/web-full、@file-viewer/vue3-full、@file-viewer/vue2.7-full、@file-viewer/vue2.6-full、@file-viewer/react-full、@file-viewer/react-legacy-full、@file-viewer/svelte-full 和 @file-viewer/jquery-full。

*-full 表示已内置 preset-all 兼容矩阵及其同版本 Worker、WASM、字体和 vendor 资产，使用这部分能力无需重复安装 preset。Adobe 设计、DICOM、数字签名、二进制检查等专业 renderer，以及 IFC 可选入口，需显式装配。Vite 配置资产插件后可自动复制资源；其它构建工具使用 Full 包自带的同版本 CLI 完成自托管。

默认资产 URL 是 <部署基址>/file-viewer/（根部署即 /file-viewer/）。缺少该目录时，轻量格式和少数兼容路径可能仍能工作，但不属于完整格式支持。

Script 标签 / 自托管

<script src="/file-viewer/dist/flyfish-file-viewer-web-full.iife.js"></script>

<flyfish-file-viewer
  src="/files/report.pdf"
  theme="light"
  toolbar-position="bottom-right"
  style="display:block;height:720px"
></flyfish-file-viewer>

先将 @file-viewer/web-full 的完整 dist/ 部署到示例中的 /file-viewer/dist/。IIFE 首包只注册 Custom Element、controller 和 lazy full preset；PDF、Word、Excel、二进制 PPT、PPTX、CAD、Typst、压缩包、CHM 等重型 renderer 会在命中文件类型时从 dist/renderers/*.iife.js 异步加载。完整部署 dist/ 即可：其中 vendor/ppt/ 已包含经过完整性校验的 @file-viewer/ppt@0.3.4 ESM、Worker、WASM、CJK 字体与帧缓存模块，vendor/chm/ 包含 CHM Rust/WASM Worker，并与其它版本对齐的资产一起交付。二进制 .ppt 和 CHM 默认无需配置运行时 URL；格式专用 URL 选项只用于非标准资产路径覆盖。

Vanilla JS

npm i @file-viewer/web @file-viewer/preset-all

import { mountViewer } from '@file-viewer/web'
import presetAll from '@file-viewer/preset-all'

mountViewer(document.querySelector('#viewer')!, {
  url: '/files/report.docx',
  options: { preset: presetAll, theme: 'light' }
})

Vue 3

npm i @file-viewer/vue3-full

import { createApp } from 'vue'
import App from './App.vue'
import FileViewer from '@file-viewer/vue3-full'

createApp(App).use(FileViewer).mount('#app')

<file-viewer url="/files/report.docx" />

Vue 2

npm i @file-viewer/vue2.7-full
# Vue 2.6 项目使用 @file-viewer/vue2.6-full

import Vue from 'vue'
import FileViewer from '@file-viewer/vue2.7-full'

Vue.use(FileViewer)

Vue 2.6 + Vue CLI 3 / webpack 4 老项目可参考独立示例 examples/vue2.6-cli3-office，其中保留旧工具链所需的转译、alias、预览服务和离线资产配置。PDF runtime 的包内路径冲突已在源码修复，无需业务侧修改 renderer。升级时仍请保留适用于项目工具链的配置。

React

npm i @file-viewer/react-full

import FileViewer from '@file-viewer/react-full'

export function Preview() {
  return <FileViewer url="/files/report.pdf" style={{ height: 720 }} />
}

Svelte

npm i @file-viewer/svelte-full

<script>
  import FileViewer from '@file-viewer/svelte-full'
</script>

<FileViewer url="/files/report.pdf" containerStyle="height:720px" />

jQuery

npm i @file-viewer/jquery-full

import $ from 'jquery'
import installFileViewer from '@file-viewer/jquery-full'

installFileViewer($)
$('#viewer').fileViewer({ url: '/files/report.pdf' })

full 包运行时资产

所有 full 包默认把 Archive、CHM、PDF、DOCX、Excel、二进制 PPT、PPTX、CAD、Typst、Draw.io、SQLite 等运行时资产指向部署基址下的 file-viewer/（根部署即 /file-viewer/）。Vite 配置资产插件复制资源或随包 CLI 写入 ./public/file-viewer 后，这些 URL 不需要逐项配置；经过校验的 @file-viewer/ppt@0.3.4 运行时位于 vendor/ppt/，CHM Worker、JavaScript bridge 与 Rust/WASM 文件位于 vendor/chm/，并保留各自 LICENSE 与 NOTICE。

import { setDefaultFullAssetBaseUrl } from '@file-viewer/vue3-full'

setDefaultFullAssetBaseUrl('/static/file-viewer/')

显式传入的 options.archive.*、options.pdf.*、options.typst.* 等配置仍然优先，便于内网网关、租户路径或灰度静态资源覆盖。

按需组合

npm i @file-viewer/vue3 @file-viewer/preset-office

import officePreset from '@file-viewer/preset-office'

const options = {
  preset: officePreset,
  theme: 'light',
  toolbar: { position: 'bottom-right' }
}

Vite 项目可额外安装 @file-viewer/vite-plugin，自动发现已安装 preset 并复制 Worker/WASM/字体/vendor 资源；非 Vite 项目直接使用 options.preset，不需要额外插件。

零依赖 iframe 集成

不想在业务项目安装任何 npm 包时，下载 GitHub Release 的 file-viewer-v2-*-official-demo-iframe.tar.gz，解压到静态目录后直接嵌入:

<iframe
  src="/file-viewer/iframe.html?url=/files/report.docx"
  style="width:100%;height:720px;border:0"
  allow="fullscreen"
></iframe>

业务接口返回二进制时，父页面只需要把 Blob 发给 Demo 入口:

<iframe id="viewer" title="文件预览" style="width:100%;height:720px;border:0"></iframe>
<script type="module">
  const iframe = document.querySelector('#viewer')
  const ready = new Promise(resolve => iframe.addEventListener('load', resolve, { once: true }))
  iframe.src = 'https://static.example.com/file-viewer/iframe.html?from=https%3A%2F%2Fapp.example.com&name=report.docx'
  const file = await fetch('/api/files/report.docx').then(response => response.blob())
  await ready
  iframe.contentWindow.postMessage(file, 'https://static.example.com')
</script>

iframe.html 是推荐的无外壳入口，支持 clean URL 的静态平台也可以写成 /iframe；原主 Demo index.html 也保留同一套 url、from、name 和 postMessage(Blob) 协议，方便兼容已有客户集成。

架构

• @file-viewer/core: 格式识别、资源加载、renderer 协议、生命周期、搜索、缩放、打印、导出和 controller API。
• @file-viewer/renderer-*: PDF、Word、PPT/PPTX、CAD、Typst、Archive、CHM、Drawing、Data、EDA 等独立渲染能力。
• @file-viewer/preset-*: lite、standard、office、engineering、all 五类能力组合。
• @file-viewer/web|vue3|vue2.7|vue2.6|react|react-legacy|svelte|jquery: 各生态的原生组件。
• @file-viewer/*-full: 组件 + preset-all；完整支持还需把同版本运行时资源发布到 <部署基址>/file-viewer/，适合需要 Full 兼容范围的附件中心。

入口

支持格式

ecosystem/format-catalog.json 是唯一格式事实源：当前源码注册 274 个不重复扩展名和 47 条预览链路，其中 224 个稳定、50 个实验。下表按文件家族列出已注册扩展名。注册并不代表所有格式都能高还原：具体支持级别、已知限制和验证样例见 格式矩阵，上线前请用业务文件验证。

能力组合

组件包默认保持轻量，格式能力通过 preset 或 renderer 装配。

Preset 选择:

国际化、主题、水印、工具栏、搜索、打印、导出、生命周期和前置权限校验都通过同一套 options 配置。完整 API 见 官方文档。

当前 npm 生态

v3.1.1 对应 89 个 npm 发布目标：88 个包为 3.1.1，msdoc-viewer 独立版本为 0.2.8；按用途分为 81 个标准包和 8 个历史兼容包。@file-viewer/docx、@file-viewer/ppt 等独立引擎依赖有各自版本，不计入这 89 个目标。实际安装版本以 npm dist-tag 和项目锁文件为准。新项目优先使用 @file-viewer/*；历史兼容包继续维护。

Adobe 创意文件能力是显式专业包：安装 @file-viewer/renderer-design 后按需启用 PSD/PSB/PDD/PSDT、AI/AIT、EPS/PS、InDesign exchange 与嵌入预览、XD、现代 FLA/XFL、色板和 Photoshop 资源预设；它不会静默进入冻结的 preset-all / Full 兼容基线。

独立 renderer 集合已包含 @file-viewer/renderer-chm，只需要 CHM 的业务无需安装完整 preset。生态边界很清楚: @file-viewer/core 只负责底层预览能力和 API；各标准组件包只依赖 core 和自己的框架依赖，不嵌套其他框架实现；历史兼容包只负责旧包名继续可用，不建议新项目优先选择。

文件列表需要批量生成缩略图时，可安装独立的 @file-viewer/thumbnail。它会先复用 EPUB 封面、OOXML/OpenDocument/3MF 缩略图、XMind 预览图、Numbers Quick Look 图片等包内资源，再回退到浏览器 renderer、固定并发 viewer 池和可选的原生 thumbnail adapter，默认输出 320 × 240 WebP；generateBatch() 保持输入顺序，generateStream() 支持边生成边上传。该包不会把截图或压缩包依赖加入 core，也不会持久化源文件或结果。

常见安装方式:

pnpm add @file-viewer/web
pnpm add @file-viewer/vue3
pnpm add @file-viewer/react
pnpm add @file-viewer/core
pnpm add @file-viewer/thumbnail
pnpm add @file-viewer/renderer-word
pnpm add @file-viewer/pptx

内网或离线部署可以从 GitHub Releases 下载同一版本的 npm tarball，放入项目自己的 vendor/ 目录，或导入企业 npm 镜像。仓库不再保存 artifacts/ 构建产物。

例如，下载 v3.1.1 的 core 与 Web 组件包：

gh release download v3.1.1 --repo flyfish-dev/file-viewer \
  --pattern 'file-viewer-core-3.1.1.tgz' \
  --pattern 'file-viewer-web-3.1.1.tgz' --dir ./vendor
npm install ./vendor/file-viewer-core-3.1.1.tgz ./vendor/file-viewer-web-3.1.1.tgz

这只安装示例中的两个包，不包含全部格式或所有传递依赖。完全断网前，还需准备所选组件、preset、renderer、框架及第三方依赖的完整缓存或内网镜像；运行时则部署匹配版本的 Worker、WASM、字体和 vendor 目录。

Core、PPTX、所有框架组件、Full 包和历史兼容包均可从 Release 获取。file-viewer3 和 @flyfish-group/file-viewer3 两个兼容包都提供 tarball。二进制 PPT 使用独立版本的 @file-viewer/ppt@0.3.4，其匹配运行时随 Demo、Full 资产和 IIFE 交付。非 Vite Full 项目仍使用随包 CLI 复制资产：npx --no-install file-viewer-copy-assets ./public/file-viewer。

GitHub Release 会同步提供完整下载项:

客户只想把官方 Demo 当成独立页面嵌入时，优先下载 file-viewer-v2-*-official-demo-iframe.tar.gz。解压后把整个目录发布到同一个静态路径，然后使用:

<iframe
  src="/file-viewer/iframe.html?url=/files/demo.docx"
  style="width:100%;height:720px;border:0"
  allow="fullscreen"
></iframe>

如果文件只能由父页面接口取回，可使用包内 iframe-example.html 展示的 postMessage(Blob) 方案: iframe.html?from=<父页面 origin>&name=<文件名> 会保持无 Demo 外壳状态，收到父页面传入的 Blob 后按指定文件名预览。原主 Demo index.html 使用同一套协议，已有 index.html?from=...&name=... 集成不需要迁移。

如果 npm 11 安装 tgz 或依赖时报 Cannot read properties of null (reading 'matches')，先在空目录中用同一包管理器复现，并检查 Node/npm 版本、锁文件和依赖来源；混用包管理器留下的 symlink 是可能原因之一，不要直接删除项目锁文件。离线安装还需确认同版本 core、preset、renderer 与组件依赖都能从本地缓存或内网镜像解析。仍可复现时，请在 issue 中提供最小项目和完整安装日志。

标准生态包与公开仓库

包与组件入口见 ecosystem/wrappers.json，格式范围见 ecosystem/format-catalog.json。本仓库包含 core、renderers、presets、标准组件、兼容包、CLI、Demo 与文档源码；发布包和静态站归档放在 GitHub Releases，不随源码重复存储。

Core 也可从 file-viewer-core 查看。各框架组件入口如下：

工程级按需 renderer 装配

快速开始的核心是先跑通组件，再明确格式能力边界。推荐先安装当前生态组件包，再按产品形态选择 @file-viewer/preset-lite、@file-viewer/preset-standard、@file-viewer/preset-office、@file-viewer/preset-engineering 或 @file-viewer/preset-all。Webpack、Rspack、Rollup、Umi、传统多页应用等非 Vite 项目，优先通过 options.preset 或 options.renderers 显式注入能力；Vite 插件只是进一步省掉手动 import 并复制离线资产。

npm i @file-viewer/vue3 @file-viewer/preset-office

import officePreset from '@file-viewer/preset-office'

const options = {
  preset: officePreset,
  rendererMode: 'replace'
}

需要组合办公文档与工程图纸等能力时，继续使用同一个 preset 字段传数组即可：

import officePreset from '@file-viewer/preset-office'
import engineeringPreset from '@file-viewer/preset-engineering'

const options = {
  preset: [officePreset, engineeringPreset],
  rendererMode: 'replace'
}

如果只需要少数格式，也可以安装单 renderer 并传给 options.renderers：

import { pdfRenderer } from '@file-viewer/renderer-pdf'

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

Vite 项目可以再加插件，插件会免配置发现已安装 preset、注入 virtual module，并按命中格式复制 Worker / WASM / 字体 / vendor 资源：

npm i -D @file-viewer/vite-plugin

import { fileViewerRenderers } from '@file-viewer/vite-plugin'

export default {
  plugins: [
    fileViewerRenderers({
      copyAssets: true
      // 无需 preset 配置：插件会自动发现已安装的 @file-viewer/preset-office。
    })
  ]
}

需要 Full 兼容范围时，可将 preset 换成 preset-all；非 Vite 项目继续传 options.preset，Vite 配置保持不变。在线 Demo 还显式装配了专业 renderer，不能把 Demo 的全部能力等同于 preset-all：

npm i @file-viewer/vue3 @file-viewer/preset-all

需要自定义装配时，再显式配置插件：

fileViewerRenderers({
  preset: 'auto',        // 同时开启源码扫描时，仍自动发现已安装 preset
  scan: true,            // 识别 fileViewerFormats、data-file-viewer-formats、accept
  formats: ['pdf'],      // 在已安装 preset 之外额外补充精确 renderer
  copyAssets: true,
  chunkStrategy: 'renderer'
})

严格裁剪或组件库内部测试时，可以关闭自动注入并显式传入 virtual module：

// vite.config.ts
fileViewerRenderers({ formats: ['pdf'], inject: false, copyAssets: true })

// 业务组件入口
import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'

const options = {
  renderers: configuredFileViewerRenderers,
  rendererMode: 'replace'
}

• Vue、React、Svelte、jQuery、Vanilla JS / Pure Web 都传同一份 options，只是在各自生态中映射为 props、hook、action、plugin 或 mountViewer(...) 参数。
• preset-lite 面向文本、Markdown、代码、图片和音视频；preset-office 面向 PDF / Word / Excel / PowerPoint / OFD；preset-engineering 面向 CAD / 3D / 绘图 / XMind / Geo / Typst / EDA / Data。
• 想要最小包体时，可以不用 preset，直接安装 @file-viewer/renderer-pdf、@file-viewer/renderer-word 等单个 renderer，并通过 options.renderers 手动注入。
• fileViewerRenderers() 或 fileViewerRenderers({ copyAssets:true }) 会免配置自动发现已安装 preset；如果同时开启 scan:true，请使用 preset:'auto' 或 autoPresets:true 保留 preset 自动发现。
• scan:true 会识别 fileViewerFormats、data-file-viewer-formats 和上传控件 accept，调试与打包时自动选择 renderer。
• copyAssets:true 会复制 PDF/CAD/Typst/Archive/Data 等 worker、WASM 和 vendor 资源，满足离线和企业内网部署；压缩包目录会优先使用 vendor/libarchive/worker-bundle.js / libarchive.wasm，Worker 不可用时只对 ZIP/TAR/GZIP 进入兼容路径。
• builtinRenderers 仍可用于高级基线控制或历史兼容；普通快速接入只需要 preset / renderers 与 rendererMode。
• 如果打开的是支持矩阵内但未装配的格式，预览器会提示应安装的 preset / renderer；只有真正不在矩阵中的扩展名才提示不支持。
• @file-viewer/preset-all 提供 Full 兼容基线，不自动包含后续专业 renderer；Worker、WASM、字体和 vendor 资源仍需通过 Vite 插件或 file-viewer-copy-assets 部署。*-full 包已内置该 preset，无需重复安装。

二进制检查器

安装 @file-viewer/renderer-binary 后，可在已有组件中显式添加：

import { binaryRenderer } from '@file-viewer/renderer-binary'

const options = {
  rendererMode: 'extend',
  renderers: [binaryRenderer],
  binary: { maxFileBytes: 16 * 1024 * 1024 }
}

它只接管已声明的二进制扩展名，不会抢占 PNG、ZIP、WASM 等已有专用预览。更多限制见 二进制检查器说明。

组件属性与工具栏定制摘要

每个生态包都暴露原生接入方式。Vanilla JS / Pure Web 优先面向非框架、Custom Element 和 script 标签场景；Vue3 保持轻量声明式 props；React、Svelte、jQuery 和 Vue2 适合需要 buffer、name、type、size 等命令式挂载参数的场景。完整示例见官方文档: https://doc.file-viewer.app/guide/ecosystem

样式隔离与主题定制

所有标准组件默认使用 Shadow DOM 强隔离。宿主页面里的 *、button、table、img、svg、canvas 等全局样式不会直接侵入预览器工具栏和正文；预览器也不会把局部 reset 粗暴写到业务页面。

styleIsolation 是挂载边界配置；运行时切换模式时请重新挂载组件。scoped 与 none 都属于 Light DOM，仍可能被宿主的高权重或 !important 全局规则覆盖。

定制优先级建议是：先使用 --file-viewer-* CSS 变量覆盖颜色、字体、间距、圆角、工具栏和按钮；需要命中内部结构时再使用稳定 Shadow Parts。当前 Web shell 暴露 host、shell、toolbar、toolbar-group、toolbar-status、button、input 和 content，后续 renderer 扩展应继续使用 state-panel、watermark 这类稳定命名。不要依赖内部 class 名，它们只服务实现细节。

下面的 file-viewer-host 是实际 Shadow host 的 class：Vue 3 通过 class，Vue 2 通过 containerClass，React / Svelte 通过 className 传入，jQuery 则直接加在初始化节点上。

.file-viewer-host {
  --file-viewer-bg: #f7f9fc;
  --file-viewer-text: #172033;
  --file-viewer-toolbar-bg: rgba(255, 255, 255, 0.96);
  --file-viewer-button-color: #154b83;
  --file-viewer-button-radius: 6px;
}

.file-viewer-host::part(toolbar) {
  border: 1px solid rgba(20, 60, 100, 0.14);
}

.file-viewer-host::part(button) {
  font-weight: 600;
}

框架组件无需额外配置即可使用 Shadow DOM；也可以在 options 中显式声明以固定策略：

const options = {
  styleIsolation: 'shadow',
  theme: 'light',
  toolbar: { position: 'bottom-right' }
}

内置工具栏可直接使用，也可以通过 toolbar:false 进入 headless 操作模式，自行用组件 ref、hook、controller、action 或 jQuery plugin method 组装业务工具栏。

缩放状态由各格式 renderer 的内部 provider 上报。首屏自适应、容器尺寸变化或 PDF / Word / 图片等异步布局完成后，内置工具栏会显示真实缩放比例，而不是固定显示 100%；自定义工具栏也应监听 zoom-change / operation-availability-change，或读取 getZoomState() / getOperationAvailability()。

视图状态同步用于投屏、双端协同和恢复阅读进度。所有通过标准 renderer loader 挂载的格式都会获得通用 view-state provider，至少能记录 renderer、当前缩放和滚动位置；PDF、XMind、Geo、3D、CAD 等高交互路径会补充页码、导航、画布 pan、地图中心、相机视角或底层视图快照。初始化可传 options.initialViewState，运行中监听 view-state-change；Pure Web / Vue3 controller 可直接调用 getViewState() 和 applyViewState(state, { source: "api", action: "restore" })。

生态当前维护 89 个 npm 发布目标（81 个标准包 + 8 个历史兼容包）；格式目录声明 47 条预览链路、274 个扩展名（已注册），其中 224 个稳定、50 个实验。格式说明见官方文档: https://doc.file-viewer.app/guide/formats

支持项目与商业版

File Viewer 自有源码保持 Apache-2.0 开源，部分运行时依赖采用独立许可证，见文末说明。GitHub Sponsors 支持一次性或持续赞助；国内支持方式见下方入口。赞助用于开源维护，不影响开源功能；私有化交付、定制适配或需要明确响应时间的需求，请使用企业技术支持入口。

• GitHub Sponsors: github.com/sponsors/wybaby168
• 企业技术支持: dev.flyfish.group/shop
• 商业版介绍: product.flyfish.group
• 商业版 Demo: office.flyfish.dev
• 飞鱼开源工作室: flyfish.dev

感谢以下赞助者

感谢你对 File Viewer 兼容性修复、文档完善和持续发布工作的支持。

国内赞赏、联系与商业支持请使用 官方支持入口。

商业版来自 Flyfish Office 产品线，提供自研 Office 文档引擎，面向复杂版式、大文件和分页渲染等需求。开源版会继续维护；商业支持提供私有化评估、定制适配和约定的响应时间，具体效果请用业务样例评估。

Demo 与 Docker

本仓库保留多个可运行演示入口:

Docker 适合内网、私有云、客户现场或希望直接运行完整 Demo 的场景:

docker run -d \
  --name flyfish-viewer \
  --restart unless-stopped \
  -p 8080:80 \
  flyfishdev/file-viewer:latest

访问:

• 主预览: http://localhost:8080/
• iframe 嵌入: http://localhost:8080/iframe.html?url=/example/word.docx
• 文档比对: http://localhost:8080/compare.html

从源码构建自己的镜像时，先按下文完成安装并运行 pnpm build，然后在仓库根目录添加 Dockerfile.demo：

FROM nginx:alpine
COPY apps/viewer-demo/dist/ /usr/share/nginx/html/

docker build -f Dockerfile.demo -t file-viewer-local .
docker run --rm -p 8080:80 file-viewer-local

该镜像只托管已构建的静态 Demo，不负责转码。生产部署还应配置 HTTPS、缓存及访问控制；使用预构建镜像时，可固定镜像摘要以避免 latest 漂移。

使用说明

• 组件支持两条主要输入路径: url?: string 与 file?: File
• 官方零依赖 iframe 入口位于 /iframe.html，支持 ?url= 直接传文件地址，也支持 ?from=<父页面 origin>&name=<文件名> 后由父页面 postMessage(Blob) 传文件数据；原主 Demo /index.html 保留同一套协议，完整说明见 Demo 文档
• 独立文档比对页位于 /compare.html，可通过 ?left=/example/test.doc&right=/example/word.docx 预置左右文件；它支持同步滚动、当前聚焦文档的浮层搜索、高亮命中、上一个 / 下一个、行级定位和 PDF 工具栏隐藏，但只做视觉并排预览，不做语义 diff，完整说明见 Demo 文档
• 当 file 和 url 同时存在时，会优先渲染 file
• 如果业务侧拿到的是 Blob 或 ArrayBuffer，推荐先包装成带扩展名的 File
• 预览器会填满父容器，请为父容器提供稳定高度
• 使用 url 预览时，目标资源需要允许浏览器访问；跨域场景下需要正确配置 CORS
• 如果下载地址本身没有明确扩展名，建议先在业务侧取回文件，再包装成 File
• PPTX 渲染器已拆分为独立包 @file-viewer/pptx / flyfish-dev/pptxjs，会尽量还原常见组合图形、旋转/翻转、主题背景、图片裁剪和 EMF 矢量图片；内网、严格 CSP、自托管 CDN 或旧 WebView 可通过 options.presentation.workerUrl / options.presentation.workerType 固定 PPTX Worker；复杂 Office 特效仍建议用真实业务文件做回归
• OFD、Typst、XMind、压缩包、邮件、OLB/DRA/GDS/OASIS、CAD、地理数据、3D 模型、绘图、EPUB、UMD、PDF、Office、Markdown、音视频、HLS、HEIC、字体/数据资产和代码高亮渲染器都按需异步加载，只有命中格式时才拉取对应代码块；Typst compiler / renderer WASM 和默认字体可通过 options.typst.compilerWasmUrl、options.typst.rendererWasmUrl、options.typst.fontAssetsUrl 指向自托管地址，默认仅在打开 .typ / .typst 时加载
• 普通业务优先通过 options.preset 装配 @file-viewer/preset-lite、@file-viewer/preset-standard、@file-viewer/preset-office、@file-viewer/preset-engineering 或 @file-viewer/preset-all；多个能力包直接使用 preset: [officePreset, engineeringPreset]。builtinRenderers 仅作为高级基线控制或历史兼容开关保留；UMD / EPUB 电子书均由 @file-viewer/renderer-epub 按需提供
• options.ui.density 支持 comfortable 和 compact。默认 comfortable 保持历史间距；compact 会收紧工具栏、压缩包目录、嵌套预览头部、徽标、小按钮和搜索输入等操作界面，适合效率型附件中心或数据密集后台
• options.text.toolbar: false 可隐藏文本 renderer 内部的文件类型、索引状态和行数元信息栏，不影响 Viewer 全局工具栏。普通文本和代码可通过 options.text.lineNumbers: true 显示行号；wrapLongLines: true 会在普通和虚拟文本路径中按逻辑行视觉换行，不修改源码字节。prettyPrint: true 会为 JSON、JSONC、JSON5、HTML、XML、Vue、JavaScript、TypeScript、CSS、YAML 等已安装 Prettier parser 支持的格式生成明确标记且可切回原文的显示副本；prettyPrintMaxBytes 只限制格式化，默认继承 virtualizeAboveBytes（未配置时 512 KiB）。超限、异常、不支持或 whitespace-sensitive XML 会无错误回退到原始源码，下载始终使用原文件。文本和代码超过 virtualizeAboveBytes 后仍使用稀疏索引和有界虚拟行；Markdown 默认保持排版阅读视图，只有显式设置 markdownVirtualizeAboveBytes 时才切换为有界源码视图。全文搜索仍覆盖完整源文件；超长单行按 maxRenderedLineBytes（默认 16 KiB）分段浏览，可用 virtualOverscanLines 调整可视区缓冲行数
• options.archive 一般只需要配置 cache、workerTimeoutMs 和体积上限；需要控制压缩包内部文件的下载按钮时，可用 archive.entryActions.download: false 全局隐藏，或传 (entry) => boolean 按路径、扩展名、大小等元数据判断。这个选项只影响内部条目，不会关闭顶层 viewer 下载原始压缩包的动作。预览器会先尝试当前部署 base 下的 vendor/libarchive/worker-bundle.js。手机 WebView、本地临时服务器、MIME 或 CSP 导致 Worker 初始化超时时，会继续降级到 ZIP/TAR/GZIP 兼容模式，避免压缩包一直停在 loading。只有静态目录、CDN 路径或 WASM 位置特殊时，才需要显式传 archive.workerUrl / archive.wasmUrl
• 表格列宽拖拽通过 options.spreadsheet.resizableColumns: true 显式开启，默认关闭以保持历史交互兼容；官方 Demo 默认开启，方便查看被截断的长文本
• options.theme 支持 light、dark、system，默认继续跟随系统；DOCX 由 @file-viewer/renderer-word 内部 @file-viewer/docx 自动选择 Worker 或主线程解析，HTTP/HTTPS 默认 Worker，Electron file:// 等本地不安全协议自动回退，真实浏览器 DOM 渲染、连续流式阅读、目录字段缓存和异步分批挂载，可通过 options.docx.workerUrl、options.docx.workerJsZipUrl 覆盖离线资源路径；如业务明确需要页式预览，可显式设置 options.docx.visualPagination: true；Excel/XLSX 默认使用 options.spreadsheet.worker: 'auto'，小文件走主线程兼容路径，大文件达到 options.spreadsheet.workerAutoThreshold（默认 1MB）后自动尝试 vendor/xlsx/sheet.worker.js，静态目录特殊时再传 options.spreadsheet.workerUrl，不希望自动启用时设为 worker: false；PDF 默认探测站点根路径的 PDF.js Worker，可用时使用真实 Worker，不存在或被回退成 HTML 时自动懒加载包内 worker handler 兜底，options.pdf.workerUrl 可覆盖为内网、离线或严格 CSP 的自托管地址；options.watermark 支持文字或图片水印；options.toolbar 可控制下载原文件、打印完整渲染结果、导出 HTML、统一缩放按钮和操作栏位置，toolbar.zoom 可单独控制缩放按钮显示，toolbar.position 支持 auto、top、top-center、bottom-right，PDF 默认悬浮到右下角以避开自身导航栏；统一缩放通过渲染器内部 provider 适配 PDF、Word、PPTX、Excel 虚拟表格、图片、CAD、OFD、Typst、Markdown、代码和绘图等链路，首屏自适应后的 zoom-change 会返回真实比例，避免业务侧外层 CSS 缩放或默认缓存 100% 造成表格坐标、canvas 交互或工具栏状态偏移；Excel 多 sheet 时标签栏按内容宽度展示并横向滚动，不会被平均压缩；options.pdf.toolbar 可隐藏 PDF 自身页码缩放工具栏；options.search 可控制搜索高亮、整词/大小写和命中数量；options.ai 可开启文本切片结构，返回行号、页码、锚点和 label 等溯源字段，便于业务侧做向量化、召回、AI 摘要、高亮回填和来源定位；options.hooks 可接收加载/卸载生命周期；options.beforeOperation 可在下载、打印、导出和缩放前做权限校验；打印按钮会结合当前文件类型、渲染完成状态和导出适配器动态显隐，Word / PDF 会生成完整页面，Excel 等虚拟表格会隐藏打印按钮，避免只打印当前视口或第一页

const blob = await response.blob()
const file = new File([blob], 'contract.pdf', { type: blob.type })

本地开发

建议使用 Node.js 24，并按根目录 package.json 的 packageManager 字段选择 pnpm 版本。首次运行需要先构建 workspace 依赖：

pnpm install --frozen-lockfile
pnpm build
pnpm dev

首次运行浏览器测试可用 pnpm exec playwright install chromium 准备 Chromium。贡献规范见 CONTRIBUTING.md；只改文档不必重复构建全部 renderer，修改代码时按受影响范围执行检查。

打包与部署

不需要自己构建时，直接下载 GitHub Release 中对应版本的完整归档。需要从源码部署时，在完成上节安装后执行：

pnpm build
pnpm build:component-demo
pnpm docs:build

部署时保留完整目录结构，不要只复制入口 JavaScript。WASM 应返回 application/wasm，Worker 应返回 JavaScript MIME；静态资源请求不能被 SPA 回退为 HTML。跨域文件和资产需配置相应 CORS，子路径部署需保持构建基址与资源基址一致。内网环境应使用已准备好的本地字体、Worker 和 WASM，而不是临时依赖公网 CDN。

组件接入、资产路径覆盖与静态托管配置见 发布与分发 和 Docker 部署。

文档导航

• 文档导览
• 快速开始
• Demo 说明
• 组件用法
• 支持格式
• 本地开发与打包
• Docker 部署

开源说明

File Viewer 自有源码采用 Apache-2.0。DWG/DWF/DWFX 运行时（@flyfish-dev/cad-viewer、dwf-viewer）采用 AGPL-3.0-only，使用或分发 CAD 能力时需遵守其许可证。

旧版 PPT 运行时 @file-viewer/ppt 保留独立 LICENSE、NOTICE 和内置水印；移除水印需商业授权。其他依赖按各自许可证使用，不因被 File Viewer 引用而改为 Apache-2.0。

欢迎通过 issue / PR 贡献通用修复与改进，参与方式见 CONTRIBUTING.md。