纯前端文件预览如何接入：File Viewer 221 种格式浏览器端预览指南-港品优选

纯前端文件预览如何接入：File Viewer 221 种格式浏览器端预览指南

【免费下载链接】file-viewerBrowser-native Office / PDF / CAD / archive viewer for internal web apps, with Vue, React, Svelte, jQuery, Web Components, and no server-side conversion.项目地址: https://gitcode.com/gh_mirrors/file/file-viewer

File Viewer 是纯前端文件预览组件库，面向 OA、内网与私有化后台：Word、Excel、PDF、CAD、压缩包等 221 种格式在浏览器内解析与渲染，全程不依赖服务端转码。

先划清边界：它擅长什么、不擅长什么

先说它不做什么。File Viewer 是只读预览工具，不是 Office 或 CAD 编辑器，不能改内容后保存。保真度也不做统一承诺：渲染结果受文件结构、内嵌字体、厂商扩展和浏览器能力影响。轻量组件不会悄悄带上任何渲染器——只装@file-viewer/vue3就传一个 .pptx，看到的是提示安装对应 preset 的状态页，而不是预览画面。

它能覆盖的部分：

Office 与 PDF- .doc/.docx/.xls/.xlsx/.ppt/.pptx、PDF、OFD、RTF、OpenDocument，属于 32 条预览管线的一部分
CAD 与 3D- DWG、DXF、DWF/DWFX 走本地 WASM 解析，另有 glTF、STL、STEP 等模型格式
压缩包与邮件- 20 多种压缩格式支持嵌套文件预览，.eml/.msg/.mbox 可拆出正文和附件
框架覆盖- Vue 3、Vue 2.6/2.7、React 16.8–19、Svelte、jQuery、原生 Web Component，共 57 个 npm 目标

各格式支持级别不同，以完整格式矩阵为准，别按扩展名想当然。

从 0 到第一次预览：最小可运行路径

第一次接入建议用 full 包：它内置preset-all和同版本 Worker、WASM、字体资产，不需要再装 preset。以 Vue 3 为例：

npm install @file-viewer/vue3-full

<script setup lang="ts"> import { FileViewer } from '@file-viewer/vue3-full' </script> <template> <FileViewer url="/files/handbook.pdf" /> </template>

React 项目换成@file-viewer/react-full，原生 JS 用@file-viewer/web-full的mountViewer。Vite 项目加装@file-viewer/vite-plugin并开启copyAssets: true，开发和构建都会把 Worker、WASM、字体资产发布到public/file-viewer；Webpack、Vue CLI 走 full 包自带的file-viewer-copy-assetsCLI。运行时默认从/file-viewer/取资产，缺资产时轻量格式仍能打开，但全格式能力不完整。

场景走查

OA 文档附件：Word、Excel、PPT

用户动作：在合同列表点击一个 .docx 附件。配置：办公类系统装@file-viewer/preset-office，传给options.preset：

import officePreset from '@file-viewer/preset-office' const options = { rendererMode: 'replace', preset: officePreset }

看到的效果：Word 按灰底白页分页显示，支持缩放和文档内搜索；Excel 保留公式、图表与单元格内图片；PPTX 经 Worker 引擎渲染复杂图形。有保密要求时加watermark: { text: 'Internal', opacity: 0.14 }，启用的水印会出现在打印输出里。

工程图纸与压缩包

用户动作：打开工程资料库里的 DWG 图纸或 zip 附件。配置：装@file-viewer/preset-engineering，覆盖 DWG/DXF/DWF、3D、EDA、压缩包等管线；重管线按格式懒加载。看到的效果：DWG 由本地 WASM 渲染，文件不出浏览器；zip 目录树里点击嵌套文件直接预览，不必先下载再用别的软件打开。

内网离线部署

用户动作：运维需要在物理隔离环境跑起完整预览能力。配置：把 full 包的 Worker、WASM、字体、vendor 资产发布到自己的源，或直接使用官方flyfishdev/file-viewer镜像并固定版本 tag。看到的效果：内网打开开发者工具，外部请求为零，解析与渲染全部在浏览器完成。分发细节见内网分发指南。

进阶用法

按需只装需要的格式

只预览 PDF 的系统，装@file-viewer/renderer-pdf并传renderers: [pdfRenderer]，配rendererMode: 'replace'从空注册表开始，装什么就是什么。Vite 项目加fileViewerRenderers({ copyAssets: true })，插件会自动发现已安装的@file-viewer/preset-* 并注入生成的虚拟模块；chunkStrategy: 'renderer'按渲染器拆 chunk，方便缓存与体积排查。Webpack、Rspack、Rollup 构建走同一套 CLI 复制资产，不需要改打包配置。

主题定制：Shadow DOM 与 CSS 变量

styleIsolation默认'auto'即 Shadow DOM，宿主全局 CSS 无法破坏工具栏和文档内容；需要继承宿主字体与主题变量时改用'scoped'。定制主题不碰内部类名：在组件节点或:root上设置--file-viewer-bg、--file-viewer-text、--file-viewer-font、--file-viewer-toolbar-bg等变量即可，结构调整用::part(toolbar)、::part(button)、::part(content)这类稳定命名。theme支持'light'、'dark'、'system'三档。

性能由懒加载兜底：PDF、CAD、Typst、压缩包等重格式按格式加载，首屏 JS 不含这些管线；文本与代码超过 512 KiB 自动切虚拟行；压缩包结果可缓存到 IndexedDB。水印、工具栏、搜索、precheckFileViewerSource预检等其余选项见 usage 文档。

它是怎么做到的

分层很直接：每层职责单一，渲染器只在被需要时才参与。

组件层- Vue、React、Svelte、jQuery、原生 Web Component 各实现自己的原生生命周期，不嵌套别的框架实现
核心层-@file-viewer/core，与框架无关的 TypeScript，统一源加载、生命周期、工具栏、搜索、缩放、打印等共享协议
预设与渲染器层- 221 个注册扩展名映射到 32 条预览管线，每个渲染器包各管一条格式管线，preset 按场景组合
运行资产层- Worker、WASM、字体、vendor 资产，全部从自己的源提供，预览路径留在浏览器内

坑与限制

资产不完整是最常见故障- 只拷 JS 入口并不完整，Worker、WASM、字体和 vendor 资产必须同版本且同源；用copyAssets: true或file-viewer-copy-assetsCLI，确认/file-viewer/基础路径可访问。
保真度随文件浮动- 内嵌字体、厂商扩展、浏览器能力都会影响结果；PDF 文本提取是分级支持，扫描件需要 OCR，不完整的多页提取会给出明确提示而不是半成品。
大文件和加密压缩包要留余量- 内存占用上升；挂载前用precheckFileViewerSource校验文件签名，避免加载后白屏；上线前在 Chromium、Firefox、WebKit 目标浏览器各跑一遍冒烟集。

FAQ

它是编辑器吗，能否修改后保存？

只读预览工具。支持打印、导出 HTML（toolbar.exportHtml）和水印遮罩打印，但没有编辑保存路径。

full 包和 preset 怎么选？

full包内置preset-all与同版本资产集，一步到位但体积更大；preset 用于精确控制交付哪些格式。已装 full 包时不要再装另一个 preset。

哪些浏览器能用？

官方覆盖 Chromium、Firefox、WebKit 主流浏览器，依赖 Web Worker 与 WASM；内网老版本浏览器需自行验证兼容性。

扫描件 PDF 能搜索和比对吗？

没有文本层就不行。文本层 PDF 可以搜索，文档比对目前对 DOCX 与文本文件稳定，PDF 比对属分级支持，扫描件需外接 OCR。

接入自有系统时，先用 full 包跑通链路，再按实际格式占比切到 preset。可运行的示例工程在 examples/，内网与隔离环境的细节对照内网分发指南逐项核对。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析