File Viewer

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

无需服务端转码，在浏览器端预览 Office、PDF/OFD、CAD、压缩包、邮件、图片、音视频、代码等常见业务附件。支持 Vue、React、Svelte、jQuery 和 Web Components。

在线 Demo · 文档 · GitHub Wiki · 快速开始 · 支持格式

简体中文 · English

项目定位

File Viewer 是面向业务系统的浏览器原生文件预览组件。它的核心场景是企业后台、OA、知识库、工单系统、附件中心、工程资料库和私有化交付项目中的附件预览。

无需后端转码服务，也不要求把私有文件交给云端转换。一个组件、一套 API，覆盖 Office、PDF、OFD、Typst、CAD、XMind、压缩包、邮件、绘图、音视频、代码、PSD、字体和结构化数据。当前内置 206 个扩展名映射和 24 条预览链路。

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

亮点

接入快。 Vanilla JS、Vue、React、Svelte、jQuery 都有原生组件；full 包可一步拿到完整能力。
覆盖广。 206 个扩展名，24 条预览链路，覆盖常见办公、工程、设计、数据和代码附件。
纯前端。 浏览器内解析和渲染，支持离线、内网、Docker、私有 CDN 和严格资源自托管。
模块化。 轻量组件、renderer、preset、full 包分层清晰，既能极简安装，也能一键全量。
按需加载。 PDF、Office、CAD、Typst、压缩包、图纸、PSD、Mermaid 等重型能力只在命中格式时加载。
操作完整。 搜索、高亮、缩放、打印、导出 HTML、下载、水印、主题、生命周期钩子和按钮前置校验都走统一 API。
生态一致。 Core 聚焦底层能力，各框架组件只做原生封装，参数、事件和 controller 体验保持一致。

按场景选择入口

用户	他们关心什么	推荐入口
企业后台 / OA 开发	Word、Excel、PPT、PDF 附件预览	快速开始 / Office preset
工程资料系统	DWG、DXF、DWF、图纸初筛	支持格式 / 格式完整度
前端组件使用者	Vue / React / Web Component 接入	生态组件总览
私有化交付团队	离线、内网、Worker / WASM 自托管	发布与分发 / Docker 部署

在线效果

打开 demo.file-viewer.app 可以直接体验 Word 合同、Excel 报表、PPT 材料、DWG 图纸、压缩包和邮件场景入口，也可以继续打开完整样例矩阵、上传自己的脱敏文件、复制当前样例的 React 接入代码，验证工具栏、文档比对和离线资产加载效果。

兼容性反馈

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

如果你手里有不涉密、可脱敏的 DOC / XLS / PPT / DWG / DWF / 压缩包 / 邮件样本，欢迎拿 Demo 试一下。遇到样式不一致、打不开、内网部署路径问题或移动端异常，都可以通过 issue 反馈。

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

快速开始

先选接入层，再按需选择格式能力。只想最快拿到完整体验时，直接使用 *-full 包。

场景	推荐安装
Script 标签 / CDN 完整能力	`@file-viewer/web-full`
Vanilla JS npm	`@file-viewer/web` + `@file-viewer/preset-all`
Vue 3	`@file-viewer/vue3-full`，或 `@file-viewer/vue3` + preset
Vue 2.7 / 2.6	`@file-viewer/vue2.7-full` / `@file-viewer/vue2.6-full`
React 18/19	`@file-viewer/react-full`
React 16.8/17	`@file-viewer/react-legacy-full`
Svelte	`@file-viewer/svelte-full`
jQuery	`@file-viewer/jquery-full`
精确裁剪	任意组件包 + `@file-viewer/preset-*` 或独立 renderer

CDN / Script 标签

<script src="https://cdn.jsdelivr.net/npm/@file-viewer/web-full@latest/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>

web-full 的 CDN IIFE 首包只注册 Custom Element、controller 和 lazy full preset；PDF、Word、Excel、CAD、Typst、压缩包等重型 renderer 会在命中文件类型时从 dist/renderers/*.iife.js 异步加载。Worker、WASM、字体和 vendor 资源继续按脚本 URL 自动解析，内网部署时把 dist 目录完整镜像到自己的静态域即可。

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 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)

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 '@file-viewer/jquery-full'

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

full 包离线资产路径

Vue 3 / Vue 2.7 / Vue 2.6 full 包默认把 Archive、PDF、DOCX、Excel、PPTX、CAD、Typst、Draw.io、SQLite 等运行时资产指向 /file-viewer/。把 file-viewer-copy-assets 产物发布到这个目录后，通常不需要再手写 archive.workerUrl / archive.wasmUrl。

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" src="/file-viewer/iframe.html?from=https%3A%2F%2Fapp.example.com&name=report.docx"></iframe>
<script>
  const file = await fetch('/api/files/report.docx').then(response => response.blob())
  document.querySelector('#viewer').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、PPTX、CAD、Typst、Archive、Drawing、Data、EDA 等独立渲染能力。
@file-viewer/preset-*: lite、office、engineering、all 四类能力组合。
@file-viewer/web|vue3|vue2.7|vue2.6|react|react-legacy|svelte|jquery: 各生态的原生组件。
@file-viewer/*-full: 组件 + preset-all 的一步到位包，适合快速验证和全格式附件中心。

入口

入口	地址
官方网站	file-viewer.app
官方文档	doc.file-viewer.app
在线 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`
Linux Do 友链	linux.do
打赏与优先支持	dev.flyfish.group/sponsor?source=github

支持格式

当前版本内置 206 个扩展名映射，覆盖 24 条预览链路。

类别	扩展名	当前表现	适合场景
Word	`docx`、`docm`、`dotx`、`dotm`	`@file-viewer/renderer-word` + 自研 `@file-viewer/docx`，Worker 解析、连续流式阅读、目录字段缓存和异步分批渲染；模板/宏格式按只读预览处理	新生成的 Word 文档、正式文档、Word 模板
Word	`doc`、`dot`	`@file-viewer/renderer-word` + `msdoc-viewer`，使用 Word 风格页面容器，增强 CFB 容错和表格布局	历史 `.doc` 老文档、Word 97-2003 模板
兼容文档	`rtf`、`odt`	`@file-viewer/renderer-word` + `rtf.js` / ODF `content.xml` 兼容预览	RTF 富文本、OpenDocument 文本文档
Excel	`xlsx`、`xltx`	`@file-viewer/renderer-spreadsheet` + `styled-exceljs` + 虚拟滚动，支持尺寸、合并、常见样式、自动文本色、workbook drawing 图片和可选表头拖拽调整列宽；默认 `worker: auto`，大文件自动启用 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	`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`	`@file-viewer/renderer-archive` 基于 `libarchive.js` WASM Worker 读取目录，点击后按需解压内部文件并复用统一预览器，支持 IndexedDB 缓存、GBK/GB18030 旧 ZIP 中文文件名、ZIP/TAR/GZIP 兼容降级和体积上限	归档附件、批量交付包、压缩包内文档快速查看
邮件	`eml`、`msg`、`mbox`	`@file-viewer/renderer-email` 独立承接邮件链路；EML/MBOX 使用 `postal-mime`，MSG 使用 `@kenjiuno/msgreader`，支持头信息、HTML/文本正文、附件下载与附件预览	邮件归档、工单邮件、客户来信附件
EDA	`olb`、`dra`、`gds`、`oas`、`oasis`	`@file-viewer/renderer-eda` 独立承接；使用 `cfb` 解析 OrCAD/Allegro 常见 CFB 容器；标准 GDSII 会读取 structure、boundary、path、text、reference，小图输出 SVG，大元素集自动切到 WebGL canvas；OAS/OASIS 可读文本版图夹具会输出 SVG 预览，真实 SEMI 二进制 OASIS 先做安全结构索引、可读字符串、实体候选和诊断，不虚标专业电气/几何校核	元件库、封装图纸、芯片版图附件初筛
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`	`@file-viewer/renderer-3d` 基于 Three.js loaders 交互预览；工程 CAD/BIM 格式会给出不内置几何内核的原因和转换建议	设计模型、点云、三维资产、工程模型
地理数据	`geojson`、`kml`、`gpx`、`shp`	`@file-viewer/renderer-geo` 独立承接；`@tmcw/togeojson` / `shpjs` 转 GeoJSON，支持 CRS 归一化，并用离线 MapLibre 矢量地图叠加点线面，失败时回退 SVG 预览	地理附件、轨迹、边界和轻量 GIS 数据
XMind 脑图	`xmind`	基于 `@ljheee/xmind-parser` 解析 XMind 8 XML 与 XMind 2020+ JSON 包结构，离线渲染多 sheet 脑图、节点、标签、备注、链接、标记、图片和目录树，使用 `@panzoom/panzoom` 提供成熟的拖拽平移、移动端双指缩放、滚轮锚点缩放、键盘平移、统一 toolbar 状态同步、适配画布、搜索、打印、HTML 导出和缩放	脑图、项目规划、知识结构、会议纪要
Excalidraw	`excalidraw`	`@file-viewer/renderer-drawing` 默认使用 `roughjs` 输出稳定只读 SVG；运行环境提供官方 `@excalidraw/excalidraw` ESM 模块时会优先尝试 `restore` + `exportToSvg` 并自动回退	白板草图、流程草稿、产品沟通图
draw.io	`drawio`、`dio`	基于官方 diagrams.net `GraphViewer` 预览 mxGraphModel / mxfile	流程图、架构图、业务泳道图
Mermaid	`mermaid`、`mmd`	`@file-viewer/renderer-drawing` 按需加载官方 `mermaid`，输出主题适配 SVG，并通过 `@panzoom/panzoom` 支持拖动、缩放、重置和统一工具栏联动	架构图、流程图、状态图、序列图
PlantUML	`plantuml`、`puml`	使用 `plantuml-encoder` 生成渲染 payload，支持配置自托管 PlantUML SVG 服务；预览层同样支持拖动、缩放和主题容器适配	UML 时序图、组件图、部署图
电子书	`epub`	`@file-viewer/renderer-epub` 基于 `epubjs` 解析目录和章节资源，使用兼容性更好的滚动阅读	电子书、培训手册、长篇阅读材料
电子书	`umd`	按 UMD 移动电子书结构解析元数据、目录和 zlib 压缩正文	旧移动电子书、历史小说附件
Markdown	`md`、`markdown`	`@file-viewer/renderer-text` 提供 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`、`patch`、`bundle`、`bdl`	`@file-viewer/renderer-text` 使用 `highlight.js` 轻量高亮；patch 按需加载 `diff2html` 做左右比对，git bundle 解析 refs、历史记录、文件树和可读 blob 内容	日志、配置、代码片段、接口响应、代码评审
音频	`mp3`、`mpeg`、`wav`、`ogg`、`oga`、`opus`、`m4a`、`aac`、`flac`、`weba`、`midi`、`mid`	`@file-viewer/renderer-media` 使用浏览器原生音频播放；MIDI 命中时按需加载 `@tonejs/midi` 展示轨道结构	录音、播客、语音附件、音效素材、MIDI 文件
视频	`mp4`、`webm`、`m3u8`	`@file-viewer/renderer-media` 使用浏览器原生视频播放；HLS 清单必要时按需加载 `hls.js`	演示视频、录屏、HLS 流
字体/设计/数据	`ttf`、`otf`、`woff`、`woff2`、`psd`、`ai`、`eps`、`sqlite`、`wasm`、`parquet`、`avro`、`webarchive`	`@file-viewer/renderer-data` 独立承接，基于 FontFace、`ag-psd`、`sql.js`、`hyparquet`、`avsc`、WebAssembly Module 和安全摘要；PSD 支持图层选择显隐、重绘和统一缩放；SQLite WASM 支持私有化配置	字体、设计资产、数据库、列式数据和 Web 归档

能力组合

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

模式	适合场景	示例
`*-full`	想最快拥有完整格式能力	`@file-viewer/vue3-full`
组件 + preset	大多数业务系统，体积和能力平衡	`@file-viewer/vue3` + `@file-viewer/preset-office`
组件 + 多 preset	组合办公和工程附件	`preset: [officePreset, engineeringPreset]`
组件 + renderer	只要一个或少数格式	`@file-viewer/renderer-pdf`
CDN full	无构建工具、script 标签、快速验证	`@file-viewer/web-full`
Vite 插件	Vite 项目自动发现已安装 preset 并复制资产	`@file-viewer/vite-plugin`

Preset 选择:

preset	覆盖范围
`@file-viewer/preset-lite`	文本、Markdown、代码、图片、音频、视频
`@file-viewer/preset-office`	PDF、Word、Excel、PowerPoint、OFD、RTF、OpenDocument
`@file-viewer/preset-engineering`	CAD、3D、绘图、XMind、Geo、Typst、Archive、Data、EDA
`@file-viewer/preset-all`	官方 Demo 完整格式矩阵

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

当前 npm 生态

当前版本以 npm registry 的 latest dist-tag 为准，共维护 52 个 npm 发布目标: 46 个标准组件/完整 full 包/核心/renderer/preset/工程插件包 + 6 个历史兼容 alias。新项目建议优先使用 @file-viewer/* 标准包名；旧项目继续使用 @flyfish-group/* 或 file-viewer3 时也会拿到同版本能力。

场景	推荐 npm 包	历史兼容包	版本策略	说明
Core 底座	`@file-viewer/core`	无	`latest`	框架无关的格式矩阵、预览能力、资源加载、生命周期事件、搜索、缩放、打印、导出和操作 API
PPTX 原生引擎	`@file-viewer/pptx`	无	`latest`	从 Flyfish 历史稳定实现拆出的独立 PPTX 渲染引擎，Worker 渐进解析，由 `@file-viewer/renderer-presentation` 按需加载
Word renderer	`@file-viewer/renderer-word`	无	`latest`	标准 renderer 插件，承接 DOCX/DOC/DOT/RTF/ODT 链路，内部按需加载 `@file-viewer/docx`、`msdoc-viewer` 和 `rtf.js`，core-only 安装不再拉取 Word 重依赖
演示文稿 renderer	`@file-viewer/renderer-presentation`	无	`latest`	标准 renderer 插件，基于 `@file-viewer/pptx` 提供 PPTX/PPTM/POTX/POTM/PPSX/PPSM 按需预览、缩放、打印和导出
绘图 renderer	`@file-viewer/renderer-drawing`	无	`latest`	标准 renderer 插件，提供 Draw.io / diagrams.net 离线 viewer、Excalidraw 只读 SVG、Mermaid 官方 SVG 渲染、PlantUML SVG 服务接入、Panzoom 拖拽缩放、打印和 HTML 导出
3D 模型 renderer	`@file-viewer/renderer-3d`	无	`latest`	标准 renderer 插件，基于 Three.js loaders 提供 GLTF/GLB、OBJ、STL、PLY、FBX、DAE、3DS、3MF、USD/USDZ、点云和 VTK 等按需 WebGL 预览
数据资产 renderer	`@file-viewer/renderer-data`	无	`latest`	标准 renderer 插件，基于 `ag-psd`、`sql.js`、`hyparquet`、`avsc`、FontFace 和 WebAssembly Module 提供 PSD、SQLite、Parquet、Avro、字体、WASM、AI/EPS、WebArchive 预览
EDA renderer	`@file-viewer/renderer-eda`	无	`latest`	标准 renderer 插件，提供 OLB、DRA、GDSII、OASIS 结构预览，标准 GDSII 可生成 SVG/WebGL 版图预览，OASIS 文本夹具可生成 SVG，真实二进制 OASIS 保持结构诊断边界
轻量 renderer preset	`@file-viewer/preset-lite`	无	`latest`	一次装配文本、Markdown、代码、图片、音频和视频预览，适合常见轻附件场景
Office renderer preset	`@file-viewer/preset-office`	无	`latest`	一次装配 PDF、Word、Excel、PowerPoint、OFD、RTF 和 OpenDocument 文档链路
工程 renderer preset	`@file-viewer/preset-engineering`	无	`latest`	一次装配 CAD、3D、绘图、XMind、Geo、Typst、Archive、Data 和 EDA 工程附件链路
全量 renderer preset	`@file-viewer/preset-all`	无	`latest`	一次装配 Word、PDF、OFD、PPTX、CAD、Draw.io/Excalidraw/Mermaid/PlantUML、Typst、XMind、压缩包、邮件、电子书、代码/Markdown/Patch/Git Bundle、图片、音视频和 core 其余完整格式能力
Vite 按需装配插件	`@file-viewer/vite-plugin`	无	`latest`	免配置自动发现已安装 `@file-viewer/preset-*` 并激活对应能力；也可按 `formats`、`renderers` 或源码 hint 生成 `virtual:file-viewer-renderers`，只 import 命中的 renderer 包，并提供 renderer chunk 分组和 PDF/OFD/CAD/Drawing/Typst/Archive/Data 离线资产路线
独立 renderer 包	`@file-viewer/renderer-word`、`@file-viewer/renderer-pdf`、`@file-viewer/renderer-ofd`、`@file-viewer/renderer-presentation`、`@file-viewer/renderer-cad`、`@file-viewer/renderer-drawing`、`@file-viewer/renderer-3d`、`@file-viewer/renderer-data`、`@file-viewer/renderer-eda`、`@file-viewer/renderer-typst`、`@file-viewer/renderer-archive`、`@file-viewer/renderer-email`、`@file-viewer/renderer-epub`、`@file-viewer/renderer-text`、`@file-viewer/renderer-image`、`@file-viewer/renderer-media`、`@file-viewer/renderer-mindmap`、`@file-viewer/renderer-geo`	无	`latest`	用于按需安装 Word、重型版式、文本阅读、图片、媒体、3D、数据资产、EDA 和地理数据链路，避免业务只看轻量格式时安装 DOCX/DOC/PDF/OFD/PPTX/CAD/Draw.io/Excalidraw/Mermaid/PlantUML/Typst/压缩包/邮件/EPUB/XMind/OLB/DRA/GDS/OASIS/GeoJSON/KML/GPX/SHP/PSD/SQLite/Patch/Git Bundle/代码高亮/HEIC/HLS/MIDI 依赖
Vanilla JS / Pure Web / script 标签	`@file-viewer/web`	`@flyfish-group/file-viewer-web`	`latest`	`mountViewer(container, options)`、Custom Element、IIFE、资源复制 CLI、Worker/WASM 自托管工具
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 项目的兼容组件包
jQuery	`@file-viewer/jquery`	无	`latest`	jQuery 插件式接入，适合传统后台系统
Svelte	`@file-viewer/svelte`	无	`latest`	Svelte 组件、action 和类型入口

生态边界很清楚: @file-viewer/core 只负责底层预览能力和 API；各标准组件包只依赖 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/renderer-word
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-renderer-word-*.tgz
npm install ./artifacts/file-viewer-web-*.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-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-*.tgz

Core、PPTX 原生引擎、Vanilla JS / Pure Web、Vue3、Vue2、React、React legacy、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-*-official-demo-iframe.tar.gz`	官方 Demo 零依赖 iframe 交付包，包含 `iframe.html`、兼容原主 Demo 的 `index.html`、示例父页面、说明文件、样例和离线 Worker/WASM/vendor 资源
`file-viewer-v2-*-demo.tar.gz`	主 Demo 静态站，解压后即可体验主预览、`/iframe.html` 嵌入入口和 `/compare.html` 文档比对
`file-viewer-v2-*-component-demo.tar.gz`	Vanilla JS / React 原生组件演示站
`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 组件入口

客户只想把官方 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=... 集成不需要迁移。

file-viewer3 非 scoped 历史兼容包仍会走 npm 发布链路；开源总仓库下载区使用 flyfish-group-file-viewer3-*.tgz 作为 Vue3 兼容 tarball，避免重复存储相同包体。

如果 npm 11 安装 tgz 或依赖时报 Cannot read properties of null (reading 'matches')，通常不是 File Viewer 版本不匹配，而是 npm 在混用包管理器后的 node_modules symlink 上触发 Arborist 内部错误。请删除 node_modules 和当前锁文件后，用同一个包管理器重新安装；离线 tgz 场景请确保同版本 core、preset、renderer 和组件包能从私有 npm 源或本地 tarball 依赖闭包解析。项目发布前可运行 pnpm verify:npm-install-smoke，它会用 npm 11.17.0 验证 registry 与 tgz 安装。

标准生态包与公开仓库

下面内容由 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 索引；官方 Demo iframe 交付包、完整 Demo、component demo、文档站和样例构建产物通过 GitHub Release 或 Cloudflare Pages 分发，避免普通 clone 被静态产物拖大。私有 Gitea main 是完整原始聚合仓，用于统一自动化、内部集成历史、打赏支持和优先技术支持，不等同于 GitHub 开源总仓库。

框架	标准 npm 包	入口格式	GitHub	Gitee	兼容历史包
Vanilla JS / Pure Web	`@file-viewer/web`	ESM, 类型声明, script 标签 IIFE, Worker/WASM viewer 资源, 复制静态资源 CLI	file-viewer-web	file-viewer-web	`@flyfish-group/file-viewer-web`
Vanilla JS / Pure Web Full	`@file-viewer/web-full`	ESM, 类型声明, script 标签 IIFE	file-viewer-web-full	file-viewer-web-full	无
Vue 3	`@file-viewer/vue3`	ESM, 类型声明	file-viewer-vue3	file-viewer-vue3	`@flyfish-group/file-viewer3`, `file-viewer3`
Vue 3 Full	`@file-viewer/vue3-full`	ESM, 类型声明	file-viewer-vue3-full	file-viewer-vue3-full	无
Vue 2.7	`@file-viewer/vue2.7`	ESM, 类型声明	file-viewer-vue2.7	file-viewer-vue2.7	`@flyfish-group/file-viewer`
Vue 2.7 Full	`@file-viewer/vue2.7-full`	ESM, 类型声明	file-viewer-vue2.7-full	file-viewer-vue2.7-full	无
Vue 2.6	`@file-viewer/vue2.6`	ESM, 类型声明	file-viewer-vue2.6	file-viewer-vue2.6	无
Vue 2.6 Full	`@file-viewer/vue2.6-full`	ESM, 类型声明	file-viewer-vue2.6-full	file-viewer-vue2.6-full	无
React 18/19	`@file-viewer/react`	ESM, 类型声明	file-viewer-react	file-viewer-react	`@flyfish-group/file-viewer-react`
React 18/19 Full	`@file-viewer/react-full`	ESM, 类型声明	file-viewer-react-full	file-viewer-react-full	无
React 16.8/17	`@file-viewer/react-legacy`	ESM, 类型声明	file-viewer-react-legacy	file-viewer-react-legacy	无
React 16.8/17 Full	`@file-viewer/react-legacy-full`	ESM, 类型声明	file-viewer-react-legacy-full	file-viewer-react-legacy-full	无
jQuery	`@file-viewer/jquery`	ESM, 类型声明	file-viewer-jquery	file-viewer-jquery	无
jQuery Full	`@file-viewer/jquery-full`	ESM, 类型声明	file-viewer-jquery-full	file-viewer-jquery-full	无
Svelte	`@file-viewer/svelte`	Svelte 组件, ESM, 类型声明	file-viewer-svelte	file-viewer-svelte	无
Svelte Full	`@file-viewer/svelte-full`	Svelte 组件, ESM, 类型声明	file-viewer-svelte-full	file-viewer-svelte-full	无

工程级按需 renderer 装配

快速开始的核心是先跑通组件，再明确格式能力边界。推荐先安装当前生态组件包，再按产品形态选择 @file-viewer/preset-lite、@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。
    })
  ]
}

重度用户需要一次拥有官方 Demo 的完整能力时，直接把 preset 换成全量包；非 Vite 项目继续传 options.preset，Vite 配置也保持不变：

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 是全量一键方案，适合 demo、后台运维工具和企业全格式附件中心；普通业务仍建议优先选择更窄的 preset。

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

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

组件	实际属性 / 入口	事件入口	定制入口
Vanilla JS / Pure Web `@file-viewer/web`	`<flyfish-file-viewer>` 属性 `src/url`、`filename/name`、`type`、`size`、`theme`、`toolbar`、`toolbar-position`、`watermark`、`search`、`options`；也支持 `mountViewer(...)`	`viewer-ready`、`viewer-event`、`viewer-state-change`、`viewer-error`、`onEvent`、`onStateChange`、`controller.subscribe()`	Custom Element 实例暴露完整 controller handle；IIFE script 标签会自动注册元素，同时保留 `mountViewer` 命令式挂载和资源复制 CLI。
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`、`view-state-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 生态友好。
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`。

样式隔离与主题定制

推荐在 OA、低代码、微前端、门户和后台系统中优先使用 Pure Web / Web Component 或 full 包默认的 Shadow DOM 强隔离。宿主页面里的 *、button、table、img、svg、canvas 等全局样式不会直接侵入预览器工具栏和正文；预览器也不会把局部 reset 粗暴写到业务页面。

模式	说明
`auto`	默认值。`@file-viewer/web`、`@file-viewer/web-full`、IIFE 和 `<flyfish-file-viewer>` 默认走 Shadow DOM；Vue、React、Svelte、jQuery 为兼容旧项目保持 light DOM，但 renderer 内容可由 core 按需隔离。
`shadow`	显式创建 ShadowRoot 作为渲染面，适合宿主 CSS 不可控、微前端混挂、低代码平台和设计系统全局 reset 很强的页面。
`scoped`	不创建 ShadowRoot，使用稳定根选择器、`@layer file-viewer` 和局部 reset 约束样式权重，适合需要被外层 CSS 轻度继承但又不想污染页面的场景。
`none`	历史 light DOM 行为，保留给依赖深度 class 覆盖、旧主题 CSS 或自动化测试快照的项目。

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

flyfish-file-viewer {
  --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;
}

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

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

框架组件的推荐写法是在 options 中显式声明隔离策略：

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

内置工具栏可直接使用，也可以通过 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`、`top-center`、`bottom-right`。默认 `auto`，PDF 自动悬浮右下角，其他格式保持顶部靠右；需要顶部水平居中时传 `top-center`。
`beforeOperation`	工具栏层统一前置校验，会在 `options.beforeOperation` 后执行。返回 `false` 或抛错都会取消本次操作。
`beforeDownload` / `beforePrint` / `beforeExportHtml`	单按钮前置校验；适合下载权限、打印审计、导出水印确认等细粒度业务规则。

缩放状态由各格式 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" })。

共享格式矩阵当前声明 24 条预览链路、206 个扩展名。完整能力通过 renderer / preset 按需装配，格式说明见本文“支持格式”和官方文档: https://doc.file-viewer.app/guide/formats

支持项目与商业版

Flyfish Viewer 会持续保持 Apache-2.0 开源。开源版适合通用 Web 预览、内网部署、业务附件中心和轻量级集成；如果你需要更高还原度、更极致性能、私有化交付、定制适配或优先技术支持，可以通过下面入口请我们喝杯柠檬水，也可以了解商业版原生文档引擎。

打赏与优先支持: dev.flyfish.group/sponsor?source=github
商业版介绍: product.flyfish.group
商业版 Demo: office.flyfish.dev
飞鱼开源工作室: flyfish.dev

微信赞赏码	支付宝收款码	微信公众号二维码	用户交流群

商业版来自 Flyfish Office 产品线，面向严肃企业场景提供自研原生 Office 文档引擎，重点解决 Word、Excel、PowerPoint 在复杂版式、大文件、分页布局、高保真渲染和稳定性能上的更高要求。开源版会继续维护，商业支持主要用于更快响应、私有化评估和定制交付。

Demo 与 Docker

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

命令	说明
`pnpm dev`	主 Demo，和 demo.file-viewer.app 使用同一条链路
`pnpm dev:components`	Vanilla JS、Vue、React、Svelte、jQuery 生态组件演示
`pnpm build:component-demo`	构建组件演示静态产物
`pnpm docs:dev`	启动文档站

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

源码仓库内也提供 Dockerfile，本地构建运行:

pnpm docker:build
docker run --rm -p 8080:80 flyfishdev/file-viewer: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-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.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 })

本地开发

下面的命令适用于开源总仓库和私有 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 组件 Demo
pnpm build:component-demo: 构建组件 Demo
pnpm docker:build: 构建本机架构 Docker 镜像
pnpm docker:publish: 推送 Docker Hub linux/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、标准组件包、兼容包和文档源码；完整 Demo、component demo、文档静态站和样例构建产物改由 GitHub Release 或 Cloudflare Pages 分发，避免普通 clone 被大体积静态产物拖慢。为避免 Gitee 因历史二进制膨胀超过 1GB，同步 Gitee 时会使用最新源码快照的干净历史。私有 Gitea 仍作为完整聚合仓，保留统一发布脚本、内部集成历史和优先技术支持；需要支持项目或获得优先协助的用户，可以前往 https://dev.flyfish.group/sponsor?source=github，请我们喝杯柠檬水。

文档导航

开源说明

本项目使用 Apache-2.0 许可证。

二开或商用时，请按许可证要求保留版权、许可证和来源说明，并注明项目来源为 Flyfish Viewer / @flyfish-group/file-viewer3 或 @flyfish-group/file-viewer。如果你基于本项目修复了通用问题或增强了通用能力，也欢迎通过 issue / PR 一起贡献回来，让这套预览能力继续变得更稳。

Star History