把 Word、Excel、PPT、PDF、Typst、压缩包、邮件、音视频、地理数据、字体、设计资产和结构化数据稳稳带进浏览器里。
@file-viewer/core 提供底层预览能力、格式矩阵、生命周期事件和操作 API；@file-viewer/pptx 等独立渲染引擎包负责可单独演进的重型格式能力；Vue3、Vue2.7、Vue2.6、React、React Legacy、Pure Web、jQuery、Svelte 等标准组件包只负责各自生态的原生组件体验、类型出口和交互封装。新项目建议优先使用 @file-viewer/* 标准包名，@flyfish-group/* 历史包名继续同步维护。
它不依赖后端转码服务，适合接入 OA、知识库、附件中心、流程系统和需要离线能力的业务场景。这个项目的目标很直接: 让文档预览不再像临时拼出来的功能，而是像一个可以放心交付、能独立演示、能持续维护的产品模块。
- 标准 npm 包:
@file-viewer/core、@file-viewer/pptx、@file-viewer/vue3、@file-viewer/vue2.7、@file-viewer/vue2.6、@file-viewer/react、@file-viewer/react-legacy、@file-viewer/web、@file-viewer/jquery、@file-viewer/svelte - 历史兼容 npm 包:
@flyfish-group/file-viewer3、file-viewer3、@flyfish-group/file-viewer、@flyfish-group/file-viewer-react、@flyfish-group/file-viewer-web - 官方网站: file-viewer.app
- 官方文档: doc.file-viewer.app
- 生态接入指南: doc.file-viewer.app/guide/ecosystem
- 在线 Demo: demo.file-viewer.app
- 文档比对 Demo: demo.file-viewer.app/compare.html
- Release 下载: github.com/flyfish-dev/file-viewer/releases
- Docker 镜像发布目标:
flyfishdev/file-viewer:latest - 开源总仓库(GitHub): github.com/flyfish-dev/file-viewer
- 开源总仓库(Gitee): gitee.com/flyfish-dev/file-viewer
- 打赏与优先支持: https://dev.flyfish.group/shop
Flyfish Viewer 会持续保持 Apache-2.0 开源。开源版适合通用 Web 预览、内网部署、业务附件中心和轻量级集成；如果你需要更高还原度、更极致性能、私有化交付、定制适配或优先技术支持，可以通过下面入口请我们喝杯柠檬水，也可以了解商业版原生文档引擎。
- 打赏与优先支持: dev.flyfish.group/shop
- 商业版介绍: product.flyfish.group
- 商业版 Demo: office.flyfish.dev
- 飞鱼开源工作室: flyfish.dev
| 微信赞赏码 | 微信支付 | 支付宝收款码 | 微信公众号 / 客服微信二维码 |
|---|---|---|---|
 |
 |
 |
 |
商业版来自 Flyfish Office 产品线，面向严肃企业场景提供自研原生 Office 文档引擎，重点解决 Word、Excel、PowerPoint 在复杂版式、大文件、分页布局、高保真渲染和稳定性能上的更高要求。开源版会继续维护，商业支持主要用于更快响应、私有化评估和定制交付。
当前版本以 npm registry 的 latest dist-tag 为准，共维护 15 个 npm 发布目标: 10 个标准/引擎包 + 5 个历史兼容 alias。新项目建议优先使用 @file-viewer/* 标准包名；旧项目继续使用 @flyfish-group/* 或 file-viewer3 时也会拿到同版本能力。
| 场景 | 推荐 npm 包 | 历史兼容包 | 版本策略 | 说明 |
|---|---|---|---|---|
| Core 底座 | @file-viewer/core |
无 | latest |
框架无关的格式矩阵、预览能力、资源加载、生命周期事件、搜索、缩放、打印、导出和操作 API |
| PPTX 原生引擎 | @file-viewer/pptx |
无 | latest |
从 Flyfish 历史稳定实现拆出的独立 PPTX 渲染引擎，Worker 渐进解析并可由 core 按需加载 |
| Vue3 | @file-viewer/vue3 |
@flyfish-group/file-viewer3、file-viewer3 |
latest |
Vue3 原生组件、插件安装、props、事件、ref/controller 和完整类型 |
| Vue2.7 | @file-viewer/vue2.7 |
@flyfish-group/file-viewer |
latest |
Vue2.7 原生组件，能力和 Vue3 保持一致 |
| Vue2.6 | @file-viewer/vue2.6 |
无 | latest |
Vue2.6 专线，面向仍停留在 Vue 2.6 的老项目 |
| React 18/19 | @file-viewer/react |
@flyfish-group/file-viewer-react |
latest |
React 原生组件和 hooks/controller，不通过 Vue 或 iframe 转接 |
| React 16.8/17 | @file-viewer/react-legacy |
无 | latest |
面向旧 React 项目的兼容组件包 |
| 纯 Web / script 标签 | @file-viewer/web |
@flyfish-group/file-viewer-web |
latest |
mountViewer(container, options)、IIFE、资源复制 CLI、Worker/WASM 自托管工具 |
| jQuery | @file-viewer/jquery |
无 | latest |
jQuery 插件式接入，适合传统后台系统 |
| Svelte | @file-viewer/svelte |
无 | latest |
Svelte 组件、action 和类型入口 |
生态边界很清楚: @file-viewer/core 只负责底层预览能力和 API；各标准组件包只依赖 core 和自己的框架依赖，不嵌套其他框架实现；历史兼容包只负责旧包名继续可用，不建议新项目优先选择。
常见安装方式:
pnpm add @file-viewer/vue3
pnpm add @file-viewer/react
pnpm add @file-viewer/web
pnpm add @file-viewer/core
pnpm add @file-viewer/pptx如果你在内网、离线环境，或者 npm 发布权限还没有完成配置，也可以直接使用开源总仓库 artifacts/ 里的 release tarball。离线安装 React 包时请先安装同版本 web 包:
npm install ./artifacts/file-viewer-core-*.tgz
npm install ./artifacts/file-viewer-pptx-*.tgz
npm install ./artifacts/file-viewer-vue3-*.tgz
npm install ./artifacts/file-viewer-vue2.7-*.tgz
npm install ./artifacts/file-viewer-vue2.6-*.tgz
npm install ./artifacts/file-viewer-react-*.tgz
npm install ./artifacts/file-viewer-react-legacy-*.tgz
npm install ./artifacts/file-viewer-web-*.tgz
npm install ./artifacts/file-viewer-jquery-*.tgz
npm install ./artifacts/file-viewer-svelte-*.tgz
npm install ./artifacts/flyfish-group-file-viewer3-*.tgz
npm install ./artifacts/flyfish-group-file-viewer-*.tgz
npm install ./artifacts/flyfish-group-file-viewer-web-*.tgz
npm install ./artifacts/flyfish-group-file-viewer-react-*.tgzCore、PPTX 原生引擎、Vue3、Vue2、React、React legacy、纯 JS、jQuery、Svelte 和历史兼容 tarball 都会随开源总仓库一起生成。file-viewer3 非 scoped 兼容包仍会同步发布到 npm，但它和 @flyfish-group/file-viewer3 包体重复，开源总仓库不再重复存储该 tarball。React / 纯 JS 包推荐用 npm install 获得完整依赖体验；如需自托管 Worker、WASM 和示例资源，可运行 pnpm exec file-viewer-copy-assets ./public/file-viewer。
GitHub Release 会同步提供完整下载项:
| 文件 | 用途 |
|---|---|
file-viewer-v2-*-demo.tar.gz |
主 Demo 静态站，解压后即可体验主预览和 /compare.html 文档比对 |
file-viewer-v2-*-component-demo.tar.gz |
React / 纯 JS 原生 组件演示站 |
file-viewer-v2-*-lib-dist.tar.gz |
Vue3 组件库构建产物，适合离线检查 dist 内容 |
file-viewer-v2-*-docs.tar.gz |
文档站静态产物 |
file-viewer-core-*.tgz |
@file-viewer/core 纯 TypeScript 底座本地 npm 安装包 |
file-viewer-pptx-*.tgz |
@file-viewer/pptx 原生 PPTX 渲染引擎本地 npm 安装包 |
file-viewer-vue3-*.tgz |
Vue3 标准包名本地 npm 安装包 |
file-viewer-vue2.7-*.tgz |
Vue2.7 标准组件包 本地 npm 安装包 |
file-viewer-vue2.6-*.tgz |
Vue2.6 标准组件包 本地 npm 安装包 |
file-viewer-react-*.tgz |
React 18/19 标准组件包 本地 npm 安装包 |
file-viewer-react-legacy-*.tgz |
React 16.8/17 标准组件包 本地 npm 安装包 |
file-viewer-web-*.tgz |
纯 Web 标准组件包，本地安装后可复制 Worker/WASM viewer assets |
file-viewer-jquery-*.tgz |
jQuery 标准组件包 本地 npm 安装包 |
file-viewer-svelte-*.tgz |
Svelte 标准组件包 本地 npm 安装包 |
flyfish-group-file-viewer3-*.tgz |
Vue3 本地 npm 安装包 |
flyfish-group-file-viewer-*.tgz |
Vue2.7 本地 npm 安装包 |
flyfish-group-file-viewer-web-*.tgz |
纯 JS 历史兼容包，提供 mountViewer 原生挂载和资源复制工具 |
flyfish-group-file-viewer-react-*.tgz |
React 历史兼容包，提供原生 React 组件入口 |
file-viewer3 非 scoped 历史兼容包仍会走 npm 发布链路；开源总仓库下载区使用 flyfish-group-file-viewer3-*.tgz 作为 Vue3 兼容 tarball，避免重复存储相同包体。
下面内容由 ecosystem/wrappers.json 和 packages/core/src/registry/formats.ts 自动生成。开源总仓库同步 README 时会携带同一份索引，确保用户可以从任意入口找到标准 npm 包、历史兼容包、分散组件仓库和 release 下载物。
核心底座包: @file-viewer/core。core 源码已公开，GitHub: https://github.com/flyfish-dev/file-viewer-core，Gitee: https://gitee.com/flyfish-dev/file-viewer-core。开源总仓库提供可直接运行的主 Demo 源码、core、标准组件包、兼容包、文档源码、构建产物、示例文件和 release tarball；私有 Gitea main 是完整原始聚合仓，用于统一自动化、内部集成历史、打赏支持和优先技术支持，不等同于 GitHub 开源总仓库。
| 框架 | 标准 npm 包 | 入口格式 | GitHub | Gitee | 兼容历史包 |
|---|---|---|---|---|---|
| Vue 3 | @file-viewer/vue3 |
ESM, 类型声明 | file-viewer-vue3 | file-viewer-vue3 | @flyfish-group/file-viewer3, file-viewer3 |
| Vue 2.7 | @file-viewer/vue2.7 |
ESM, 类型声明 | file-viewer-vue2.7 | file-viewer-vue2.7 | @flyfish-group/file-viewer |
| Vue 2.6 | @file-viewer/vue2.6 |
ESM, 类型声明 | file-viewer-vue2.6 | file-viewer-vue2.6 | 无 |
| React 18/19 | @file-viewer/react |
ESM, 类型声明 | file-viewer-react | file-viewer-react | @flyfish-group/file-viewer-react |
| React 16.8/17 | @file-viewer/react-legacy |
ESM, 类型声明 | file-viewer-react-legacy | file-viewer-react-legacy | 无 |
| Pure Web | @file-viewer/web |
ESM, 类型声明, script 标签 IIFE, Worker/WASM viewer 资源, 复制静态资源 CLI | file-viewer-web | file-viewer-web | @flyfish-group/file-viewer-web |
| jQuery | @file-viewer/jquery |
ESM, 类型声明 | file-viewer-jquery | file-viewer-jquery | 无 |
| Svelte | @file-viewer/svelte |
Svelte 组件, ESM, 类型声明 | file-viewer-svelte | file-viewer-svelte | 无 |
每个生态包都暴露原生接入方式。Vue3 保持轻量声明式 props；React、Pure Web、Svelte、jQuery 和 Vue2 适合需要 buffer、name、type、size 等命令式挂载参数的场景。完整示例见官方文档: https://doc.file-viewer.app/guide/ecosystem
| 组件 | 实际属性 / 入口 | 事件入口 | 定制入口 |
|---|---|---|---|
Vue 3 @file-viewer/vue3 |
url、file、options |
load-start、load-complete、unload-start、unload-complete、operation-before、operation-cancel、operation-availability-change、search-change、location-change、zoom-change |
模板 ref 暴露 FileViewerExpose；适合声明式接入。Blob / ArrayBuffer 建议包装成带扩展名的 File 后传给 file。 |
Vue 2.7 @file-viewer/vue2.7 |
url、file、buffer、name、filename、type、size、options、containerClass、containerStyle |
viewer-event / viewerEvent |
组件实例暴露 controller handle 全量方法；适合 Vue 2.7 项目和历史 @flyfish-group/file-viewer 平滑升级。 |
Vue 2.6 @file-viewer/vue2.6 |
同 Vue 2.7 | viewer-event / viewerEvent |
独立 Vue 2.6 构建，不要求业务升级到 Vue 2.7。 |
React @file-viewer/react |
ViewerMountOptions + div 原生属性，如 className、style、data-*、aria-* |
onEvent、onStateChange |
ref 暴露 FileViewerHandle；useFileViewer() 会返回 ref、props、state、handle，便于自定义工具栏。 |
React Legacy @file-viewer/react-legacy |
同 React 标准包 | onEvent、onStateChange |
面向 React 16.8 / 17；组件名和默认导出保持 legacy 生态友好。 |
Pure Web @file-viewer/web |
mountViewer(container, ViewerMountOptions, ViewerCoreOptions?) |
onEvent、onStateChange、controller.subscribe() |
返回 ViewerController；同时提供 ESM、IIFE script 标签包和 file-viewer-copy-assets。 |
jQuery @file-viewer/jquery |
$(el).fileViewer(ViewerMountOptions & { replace?: boolean }) |
onEvent、onStateChange 或 getFileViewerController(el).subscribe() |
插件方法支持 zoomIn、printRenderedHtml、searchDocument 等；replace:false 可在同一节点上原地更新。 |
Svelte @file-viewer/svelte |
ViewerMountOptions + className、containerStyle |
on:viewerEvent、onEvent、onStateChange |
bind:this 暴露 controller handle；也提供 use:fileViewer action，action 额外支持 replace。 |
内置工具栏可直接使用，也可以通过 toolbar:false 进入 headless 操作模式，自行用组件 ref、hook、controller、action 或 jQuery plugin method 组装业务工具栏。
| 工具栏配置 | 说明 |
|---|---|
toolbar: false |
隐藏内置工具栏，但不关闭下载、打印、导出、缩放等 controller API，适合完全自定义业务工具栏。 |
toolbar: true |
使用默认内置工具栏，下载、打印、HTML 导出和缩放按钮都会按能力动态显隐。 |
download / print / exportHtml / zoom |
表达业务是否允许展示对应按钮；最终仍会结合文件类型、渲染完成状态、导出适配器和缩放 provider 计算真实可用性。 |
position |
auto、top、bottom-right。默认 auto，PDF 自动悬浮右下角，减少和 PDF 自身页码 / 目录工具栏冲突。 |
beforeOperation |
工具栏层统一前置校验，会在 options.beforeOperation 后执行。返回 false 或抛错都会取消本次操作。 |
beforeDownload / beforePrint / beforeExportHtml |
单按钮前置校验；适合下载权限、打印审计、导出水印确认等细粒度业务规则。 |
共享 core 当前声明 23 条预览链路、194 个扩展名。完整格式说明见本文“支持格式”和官方文档: https://doc.file-viewer.app/guide/formats
- 纯前端 Serverless。 文档解析和展示全部在浏览器内完成，部署简单，不依赖 Office 服务端、LibreOffice 守护进程或额外转码链路。
- 格式覆盖完整。 当前内置 194 个扩展名映射，覆盖 Word、Excel、PowerPoint、PDF、OFD、Typst、压缩包、邮件、OLB/DRA、CAD、地理数据、3D 模型、Excalidraw、draw.io、EPUB、UMD、Markdown、图片、音频、视频、代码/文本、字体、设计资产和结构化数据，能覆盖绝大多数业务附件场景。
- 按需异步加载。 PDF、OFD、Typst、压缩包、邮件、OLB/DRA、CAD、地理数据、3D 模型、绘图、Office、EPUB、UMD、Markdown、代码高亮、HLS、HEIC、字体/数据资产渲染器都按需加载，重型解析依赖不会进入其他格式的首屏路径。
- 预览器操作完整。 内置下载原文件、打印完整渲染结果、导出渲染后 HTML、水印开关、水印 options、主题 options、搜索高亮、上一个 / 下一个命中、行级定位和 AI 友好文本切片；PDF 使用 PDF.js 原生搜索，Word / Markdown / 代码等文本类格式使用通用 DOM 搜索，避免污染 PDF 文本层、canvas 等特殊渲染结构；
theme支持light、dark、system，默认跟随系统，浅色业务 UI 可显式锁定light；打印按钮会按当前格式和渲染链路动态显隐，Word / PDF 使用专属完整页导出适配器，不依赖当前视口，适合合同、归档和审批类场景。 - 集成控制更完整。 提供加载/卸载生命周期钩子、原生事件回调和按钮前置校验机制，下载、打印、导出前可以接入权限验证、审计确认或业务二次弹窗。
- 阅读体验更像产品。
.doc、.docx、PDF 都保留灰色工作台、白色阅读面、居中阅读和自适应缩放；DOCX 使用自研@file-viewer/docx，默认走 Worker 解析、连续流式阅读和异步分批渲染，优先保证复杂目录、长表格、制表符、页眉页脚、字段和样式继承稳定；PDF 兼容旋转页和页面 / 目录导航，Excel 会尽量还原图片、自动文本色和可滚动的多 sheet 标签，避免“内容能打开但不好读”的落差。 - 明暗主题有边界。 Demo 外壳、Markdown 和代码预览会适配系统暗色模式；PDF、Word、Excel 等带原始版式的内容保持独立纸张或表格背景，避免全局主题污染文档。
- Demo 更适合验收。 示例文件按文档、表格、图纸、代码、图片等类型分组展示，点击样例即可打开并自动收起选择器。
- 独立文档比对入口。 生产 Demo 额外提供
/compare.html，左右并排预览两份文档，支持示例、URL、本地上传、交换、重置、同步滚动、聚焦文档搜索、行级定位和 PDF 工具栏隐藏，不污染主预览入口。 - 各框架体验一致。 core 聚焦底层预览能力，Vue3、Vue2、React、纯 Web、jQuery 和 Svelte 标准组件包 各自提供原生接入体验，并共享同一套 options、事件、搜索、缩放、打印和导出语义。
- Docker 一键部署。 提供 nginx 静态镜像、
Dockerfile和 buildx 发布脚本，发布镜像覆盖linux/amd64与linux/arm64。 - 适合开源分发和二次接入。 开源总仓库同时维护 core、独立渲染引擎包、标准组件包、兼容包、主 Demo 源码、文档源码、混淆压缩产物、npm tarball、静态部署产物和 release 下载物，便于下载、运行、验收和二次接入；私有 Gitea 作为完整聚合仓、自动化发布链路和优先技术支持入口继续提供价值。
当前版本内置 194 个扩展名映射，覆盖 23 条预览链路。
| 类别 | 扩展名 | 当前表现 | 适合场景 |
|---|---|---|---|
| Word | docx、docm、dotx、dotm |
自研 @file-viewer/docx，Worker 解析、连续流式阅读、目录字段缓存和异步分批渲染；模板/宏格式按只读预览处理 |
新生成的 Word 文档、正式文档、Word 模板 |
| Word | doc、dot |
msdoc-viewer + Word 风格页面容器，增强 CFB 容错和表格布局 |
历史 .doc 老文档、Word 97-2003 模板 |
| 兼容文档 | rtf、odt |
rtf.js / ODF content.xml 兼容预览 |
RTF 富文本、OpenDocument 文本文档 |
| Excel | xlsx、xltx |
styled-exceljs + 虚拟滚动，支持尺寸、合并、常见样式、自动文本色和 workbook drawing 图片；默认主线程解析，静态 Worker 需显式开启；打印按钮按能力隐藏，避免只打印当前视口 |
需要保留表格结构和样式的业务、Excel 模板 |
| Excel 兼容格式 | xlsm、xlsb、xls、xlt、xltm、csv、ods、fods、numbers |
统一解析，按格式可用信息渐进还原样式；同样遵循虚拟表格打印边界 | 老表格、轻量数据查看 |
| PowerPoint | pptx、pptm、potx、potm、ppsx、ppsm、odp |
基于独立开源 @file-viewer/pptx 原生引擎浏览幻灯片内容，Worker 渐进解析并按页输出；ODP 走 OpenDocument 幻灯片文本预览 |
汇报材料、课件、方案、演示模板 |
pdf |
基于 pdfjs-dist 预览，同源 URL 默认渐进读取；服务端支持 Range 时自动分片加载，支持缩放工具栏、旋转页、页侧边栏/目录树侧边栏切换、宽度自适应、完整打印和导出 HTML |
合同、票据、版式成品 | |
| OFD | ofd |
基于 DLTech21/ofd.js 仓库源码在线预览国产版式文档，避开 npm dist 授权 wasm 分支 |
电子发票、公文、归档材料 |
| Typst | typ、typst |
直接读取 Typst 源文件，按需加载 @myriaddreamin/typst.ts 浏览器 WASM 编译器并按页 SVG 渲染；支持完整预览、打印和导出 HTML |
技术报告、论文草稿、工程文档模板 |
| 压缩包 | zip、zipx、7z、rar、tar、gz、gzip、tgz、bz2、bzip2、tbz、tbz2、xz、txz、lzma、zst、tzst、cab、ar、cpio、iso、xar、lha、lzh、jar、war、ear、apk、cbz、cbr |
core 共享 archive renderer，基于 libarchive.js WASM Worker 读取目录，点击后按需解压内部文件并复用统一预览器，支持 IndexedDB 缓存和体积上限 |
归档附件、批量交付包、压缩包内文档快速查看 |
| 邮件 | eml、msg、mbox |
EML/MBOX 使用 postal-mime，MSG 使用 @kenjiuno/msgreader，支持头信息、HTML/文本正文、附件下载与附件预览 |
邮件归档、工单邮件、客户来信附件 |
| EDA | olb、dra |
使用 cfb 解析 OrCAD/Allegro 常见 CFB 容器，展示结构树、元件/封装/Padstack 候选、属性、诊断和可读字符串；退化时提供安全二进制索引 |
元件库、封装图纸、EDA 附件初筛 |
| CAD | dwg、dxf、dwf、dwfx、xps |
基于 @flyfish-dev/cad-viewer 预览图纸；DWG 通过 Worker + LibreDWG WASM 解析，DXF 使用 JS parser，DWF/DWFx/XPS 使用 native dwf-viewer 渲染 W2D/W3D/XPS 图形 |
工程图纸、二维 CAD 附件、AutoCAD 归档文件 |
| 3D 模型 | glb、gltf、obj、stl、ply、fbx、dae、3ds、3mf、amf、usd、usda、usdc、usdz、kmz、pcd、wrl、vrml、xyz、vtk、vtp、step、stp、iges、igs、ifc、3dm |
基于 Three.js 交互预览；工程 CAD/BIM 格式会给出不内置几何内核的原因和转换建议 | 设计模型、点云、三维资产、工程模型 |
| 地理数据 | geojson、kml、gpx、shp |
@tmcw/togeojson / shpjs 转 GeoJSON 后离线 SVG 预览 |
地理附件、轨迹、边界和轻量 GIS 数据 |
| Excalidraw | excalidraw |
基于官方 @excalidraw/excalidraw 的 restore + exportToSvg 输出只读预览 |
白板草图、流程草稿、产品沟通图 |
| draw.io | drawio、dio |
基于官方 diagrams.net GraphViewer 预览 mxGraphModel / mxfile |
流程图、架构图、业务泳道图 |
| 电子书 | epub |
基于 epubjs 解析目录和章节资源，使用兼容性更好的滚动阅读 |
电子书、培训手册、长篇阅读材料 |
| 电子书 | umd |
按 UMD 移动电子书结构解析元数据、目录和 zlib 压缩正文 | 旧移动电子书、历史小说附件 |
| Markdown | md、markdown |
Markdown 阅读样式，支持明暗主题阅读面 | README、知识文档、说明文档 |
| 图片 | gif、jpg、jpeg、bmp、tiff、tif、png、svg、webp、avif、ico、heic、heif、jxl |
原生图片浏览；HEIC/HEIF 命中时按需使用 heic2any 转换 |
图片附件、设计稿、Logo、移动端照片 |
| 代码/文本 | txt、json、jsonc、json5、ipynb、yaml、yml、toml、ini、proto、hcl、tex、gv、http、js、mjs、cjs、jsx、ts、tsx、vue、react、css、html、htm、xml、log、java、py、go、rs、rb、swift、kt、php、c、cpp、cc、h、hpp、cs、sh、bash、sql、diff |
使用 highlight.js 轻量高亮，HTML 按源码展示 |
日志、配置、代码片段、接口响应 |
| 音频 | mp3、mpeg、wav、ogg、oga、opus、m4a、aac、flac、weba、midi、mid |
浏览器原生音频播放；MIDI 使用 @tonejs/midi 展示轨道结构 |
录音、播客、语音附件、音效素材、MIDI 文件 |
| 视频 | mp4、webm、m3u8 |
浏览器原生视频播放；HLS 清单按需加载 hls.js |
演示视频、录屏、HLS 流 |
| 字体/设计/数据 | ttf、otf、woff、woff2、psd、ai、eps、sqlite、wasm、parquet、avro、webarchive |
core 共享 data renderer，基于 FontFace、ag-psd、sql.js、hyparquet、avsc、WebAssembly Module 和安全摘要；SQLite WASM 支持私有化配置 |
字体、设计资产、数据库、列式数据和 Web 归档 |
适合已经在 Vue 3 项目里开发，希望最短路径完成接入的团队。Vue3 标准组件包 直接使用共享 core 能力，并承担 Vue 生态内的插件安装、组件 props、ref API 和类型出口。
pnpm add @flyfish-group/file-viewer3import { createApp } from 'vue'
import App from './App.vue'
import FileViewer from '@flyfish-group/file-viewer3'
createApp(App).use(FileViewer).mount('#app')Vue3 入口会把样式一起带到安装器里，所以这里不需要再额外引入 dist/file-viewer3.css。
<script setup lang="ts">
import { ref } from 'vue'
const url = ref('https://example.com/demo.pdf')
</script>
<template>
<div style="height: 100vh">
<file-viewer :url="url" />
</div>
</template>适合仍在 Vue2.7 技术栈上，希望直接以内嵌组件方式完成接入的团队。Vue2 入口也会自动带上样式，不需要再额外 import CSS。
pnpm add @flyfish-group/file-viewerimport Vue from 'vue'
import App from './App.vue'
import FileViewer from '@flyfish-group/file-viewer'
Vue.use(FileViewer)
new Vue({
render: h => h(App)
}).$mount('#app')<template>
<div style="height: 100vh">
<file-viewer :url="url" />
</div>
</template>
<script>
export default {
data() {
return {
url: 'https://example.com/demo.pdf'
}
}
}
</script>React 与纯 Web 标准包都走 native controller，直接在业务页面挂载完整预览器。
npm install @file-viewer/react
npm install @file-viewer/webimport FileViewer from '@file-viewer/react'
export function Preview() {
return (
<div style={{ height: '100vh' }}>
<FileViewer
url="https://example.com/demo.docx"
/>
</div>
)
}@file-viewer/react 支持 React 17 / 18 / 19，内部使用本包本地 controller 调用 @file-viewer/core 与 core browser engine，不依赖纯 Web 组件实现。鉴权文件仍建议由宿主系统先下载成 Blob，再用 file + name 交给预览器。资源复制命令仍保留，用于 worker/WASM 和示例资源的自托管分发；标准组件包接入不需要额外的静态页面地址。
本仓库内置了一个组件演示应用，覆盖 React 组件、纯 Web helper、jQuery 和 Svelte 入口。调试时直接运行:
pnpm dev:components打开本地地址即可验证 React 组件和纯 JS mountViewer 的 native 预览效果。验证静态部署产物时运行:
pnpm build:component-demo
pnpm --filter @flyfish-group/file-viewer-component-demo preview确认无误后，apps/component-demo/dist 可以作为普通静态目录部署；其中只包含 React、Pure Web、Vue3、jQuery、Svelte 和 script 标签接入示例。正式在线预览站和文档比对入口由 apps/viewer-demo 承载。
适合内网、私有云、客户现场或希望直接运行完整 Demo 的场景。镜像发布后可直接运行:
docker run -d \
--name flyfish-viewer \
--restart unless-stopped \
-p 8080:80 \
flyfishdev/file-viewer:latest访问:
- 主预览:
http://localhost:8080/ - 文档比对:
http://localhost:8080/compare.html
源码仓库内也提供 Dockerfile，本地构建运行:
pnpm docker:build
docker run --rm -p 8080:80 flyfishdev/file-viewer:latest- 组件支持两条主要输入路径:
url?: string与file?: File - 独立文档比对页位于
/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 矢量图片；复杂 Office 特效仍建议用真实业务文件做回归 - OFD、Typst、压缩包、邮件、OLB/DRA、CAD、地理数据、3D 模型、绘图、EPUB、UMD、PDF、Office、Markdown、音视频、HLS、HEIC、字体/数据资产和代码高亮渲染器都按需异步加载，只有命中格式时才拉取对应代码块；Typst compiler / renderer WASM 可通过
options.typst.compilerWasmUrl、options.typst.rendererWasmUrl指向自托管地址，默认仅在打开.typ/.typst时加载 options.archive一般只需要配置cache、workerTimeoutMs和体积上限；预览器会先尝试当前部署 base 下的vendor/libarchive/worker-bundle.js。手机 WebView、本地临时服务器、MIME 或 CSP 导致 Worker 初始化超时时，会继续降级到 ZIP/TAR/GZIP 兼容模式，避免压缩包一直停在 loading。只有静态目录、CDN 路径或 WASM 位置特殊时，才需要显式传archive.workerUrl/archive.wasmUrloptions.theme支持light、dark、system，默认继续跟随系统；DOCX 默认使用@file-viewer/docx的 Worker 解析、真实浏览器 DOM 渲染、连续流式阅读、目录字段缓存和异步分批挂载，可通过options.docx.workerUrl、options.docx.workerJsZipUrl覆盖离线资源路径；如业务明确需要页式预览，可显式设置options.docx.visualPagination: true；Excel/XLSX 默认使用主线程解析，避免本地服务器、手机 WebView、MIME 或 CSP 导致 Worker 卡住，确实需要静态 Worker 时再传options.spreadsheet.worker: true和options.spreadsheet.workerUrl；options.pdf.workerUrl可覆盖 PDF.js Worker，适合内网、离线或 CSP 较严的私有化部署；options.watermark支持文字或图片水印；options.toolbar可控制下载原文件、打印完整渲染结果、导出 HTML、统一缩放按钮和操作栏位置，toolbar.zoom可单独控制缩放按钮显示，toolbar.position支持auto、top、bottom-right，PDF 默认悬浮到右下角以避开自身导航栏；统一缩放通过渲染器内部 provider 适配 PDF、Word、PPTX、Excel 虚拟表格、图片、CAD、OFD、Typst、Markdown、代码和绘图等链路，避免业务侧外层 CSS 缩放造成表格坐标或 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 })下面的命令适用于开源总仓库和私有 Gitea 完整聚合仓。GitHub / Gitee 会公开 core、独立渲染引擎包、Demo、标准组件包、兼容包和文档站源码；私有 Gitea 提供完整聚合仓、统一发布脚本、内部自动化和优先技术支持。普通用户仍建议优先通过 npm、开源总仓库 dist/ 或 artifacts/ 里的 tarball 使用。
pnpm install
pnpm dev常用脚本:
pnpm build: 构建示例站点pnpm build:vue3: 构建 Vue3 标准组件包产物pnpm docs:dev: 启动 VitePress 文档站pnpm docs:build: 构建文档站pnpm type-check: 执行 TypeScript 类型检查pnpm dev:components: 启动 React + 纯 JS 组件 Demopnpm build:component-demo: 构建 组件 Demopnpm docker:build: 构建本机架构 Docker 镜像pnpm docker:publish: 推送 Docker Hublinux/amd64/linux/arm64多架构镜像；可通过DOCKER_IMAGE替换命名空间pnpm release:ecosystem:list: 列出当前完整生态 npm 发布目标pnpm release:ecosystem:pack: 构建并打包 core、标准组件包 和历史兼容 npm tarball
Vue3 和 Vue2 发包时分别在对应分支执行同一套发布链路:
| 包 | 分支 | npm 名称 |
|---|---|---|
| Vue3 | v3 |
@flyfish-group/file-viewer3 |
| Vue2.7 | v2 |
@flyfish-group/file-viewer |
| Core | packages/core / file-viewer-core |
@file-viewer/core |
| React | 当前仓库子工程 | @file-viewer/react / @flyfish-group/file-viewer-react |
| 纯 JS | 当前仓库子工程 | @file-viewer/web / @flyfish-group/file-viewer-web |
| 其他组件包 | 当前仓库子工程 | @file-viewer/vue2.7 / @file-viewer/vue2.6 / @file-viewer/react-legacy / @file-viewer/jquery / @file-viewer/svelte |
建议在发布前执行下面这组命令:
pnpm type-check
pnpm build
pnpm build:vue3
pnpm obfuscate
pnpm docs:build
pnpm release:ecosystem:pack其中:
apps/viewer-demo/dist/是正式在线 Demo 和文档比对页的部署产物packages/components/vue3/dist/是 Vue3 标准组件包构建产物；执行pnpm obfuscate后会对其中的.js/.mjs进行压缩混淆pnpm build会生成可独立部署的 Demo 静态站点产物docs/.vitepress/dist/是文档站静态产物npm pack会生成可直接发布或分发的 npm 包 tarball
如果只是准备 npm 包，可以直接执行:
pnpm release:ecosystem:pack完整生态包发布前执行:
pnpm type-check:components
pnpm build:component-demo
pnpm release:ecosystem:list
pnpm release:ecosystem:pack
pnpm release:ecosystem:publish:dry-run
pnpm release:ecosystem:publish发布到 npm:
npm publish --dry-run --access public
npm publish --access public如果 npm 账号启用了 MFA，请使用交互式终端完成浏览器确认后再等待发布结果。
开源总仓库会提交 core、Demo、标准组件包、兼容包、文档源码，同时保留可直接使用的构建产物、示例文件和 npm tarball。为避免 Gitee 因历史二进制膨胀超过 1GB，同步 Gitee 时会使用最新完整快照的干净历史。私有 Gitea 仍作为完整聚合仓，保留统一发布脚本、内部集成历史和优先技术支持；需要支持项目或获得优先协助的用户，可以前往 https://dev.flyfish.group/shop，请我们喝杯柠檬水。
本项目使用 Apache-2.0 许可证。
二开或商用时，请按许可证要求保留版权、许可证和来源说明，并注明项目来源为 Flyfish Viewer / @flyfish-group/file-viewer3 或 @flyfish-group/file-viewer。如果你基于本项目修复了通用问题或增强了通用能力，也欢迎通过 issue / PR 一起贡献回来，让这套预览能力继续变得更稳。