149 个格式入口全量可查,文档比对和 PPTX 痛点修复上线:File Viewer 1.0.22 今日发布

今天这次更新，来自几份非常真实的客户文件。

一份 PPTX 打开后白屏，一份 PDF 点目录后页面横向偏移，一套暗色系统把 Markdown 阅读面带得发灰，另一个业务系统上线后发现文档比对入口漏进了产物校验。

这些问题听起来分散，落到用户面前却都指向同一件事：文档预览要面对的远远超过演示文件夹里的几个样例，它每天接触的是工作流里流转的合同、标书、邮件、图纸、压缩包、表格、演示稿和历史附件。

File Viewer 今天推进到 1.0.22。从上次发文到现在，主线完成了 1.0.21 和 1.0.22 两轮连续维护：149 个格式入口全量梳理，文档比对入口进入正式产物校验，PPTX 兼容性补强，PDF 阅读细节继续打磨，主题和工具栏体验也跟着向前一步。 🌈

先看这次更新带来了什么

这次没有把能力写成一串模糊的“增强”。每一个点都能落到一类真实场景：客户 PPTX 打开、长 PDF 阅读、暗色系统接入、并排比对、内网部署、离线安装。

文档比对入口：合同、方案、报告终于可以左右并排看

文档比对页的入口很直接：

https://viewer.flyfish.dev/compare.html

它支持三种输入方式：内置示例、远程 URL、本地上传。左右两个面板可以交换、重置，也可以开启同步滚动。

如果业务系统已经知道左右文件地址，可以直接通过查询参数预置：

https://viewer.flyfish.dev/compare.html?left=/example/test.doc&right=/example/word.docx

适合放在这些位置：

它的定位是视觉并排预览。语义 diff、逐字标红、修订痕迹解析仍应由业务侧专业 diff 服务负责。File Viewer 负责让两个文件以一致、清楚、可滚动的方式摆到用户眼前。

PPTX 痛点修复：把客户现场的白屏拆开处理

这次 1.0.22 最重要的修补集中在 PPTX。

客户反馈的文件有一个共同特点：它们来自真实办公链路，文件结构未必像标准样例那样完整。某些 PPTX 会缺少 docProps/app.xml，某些关系字段会从数组变成单对象，某些 slide layout、master、theme、diagram 属于可选部件，缺失后旧逻辑容易一路空指针，最终整份演示稿白屏。

这版做了几件基础但关键的事情：

PPTX 的复杂度常常被低估。它远不止把图片贴到页面上，还包含主题、布局、组合图形、图片裁剪、EMF 矢量图、关系表和一层层 XML 引用。前端纯浏览器渲染要把这些内容读出来，可靠性往往来自大量边界文件的反复修补。

这次我们把崩溃路径往后挪，把可选信息当作可选信息处理，让更多文件先打开、先看见、先进入业务流程。

完整支持格式：149 个扩展名，20 条预览链路

很多用户第一次接入时会问：到底支持哪些文件？

现在文档站、README、公开成品仓库都已经统一到 1.0.22 的清单。核心覆盖如下：

这些格式并没有塞进一个巨大的首屏包里。PDF、Office、OFD、Typst、压缩包、邮件、CAD、3D、EPUB、UMD、Markdown、代码高亮等链路都会按需异步加载。用户打开图片或 Markdown 时，浏览器不需要提前下载 PDF.js、libarchive、Typst WASM 或 Three.js loader。

PDF 和工具栏：把阅读空间还给文档

PDF 视图继续保留页侧栏和目录树两种导航。用户可以看页面缩略入口，也可以切到目录结构，在长文档里快速跳转。

这版还做了一个细节：PDF.js 的目录目标可能携带横向坐标，跳转后会把页面横向滚到某个文字位置。对于宽文档或缩放后的页面，这种行为会让用户感觉文档突然“跑开”。现在目录跳转会稳定横向滚动位置，优先保持文档在当前阅读宽度里。

通用下载、打印、HTML 导出也不再一股脑堆到顶部。toolbar.position 支持：

PDF 自身已经有页码、缩放、旋转和导航按钮，通用操作悬浮到右下角后，文档主体区域清爽很多。

暗色模式：让阅读面保持可读，也让原始文档保持独立

暗色系统里最容易出问题的其实是 Markdown、代码和 Typst 这类阅读面。如果外层应用切了暗色，内部文本颜色还沿用浅色背景的逻辑，就会出现“字几乎看不见”的尴尬。

1.0.21 新增 options.theme：

const options = {theme: 'light', // light / dark / systemtoolbar: { position: 'auto' }}

这里的策略很明确：Markdown、代码、Typst 等阅读面会适配明暗主题；PDF、Word、Excel 等带原始版式的内容保留自己的白色纸张、灰色页面底或表格背景，避免全局主题污染原始文档。

浅色业务系统运行在深色操作系统上时，可以显式传 theme: 'light'。深色控制台、运维系统、知识库则可以使用 dark 或 system。

Word、打印和导出：让本地可看，也能完整输出

不少客户反馈过一个细节：本地预览看着正常，点打印却只出来第一页，或者页面被滚动容器截断。

这背后通常有两类原因。第一，浏览器默认打印的是当前 DOM 的可见结构；第二，很多预览器为了滚动和缩放，会在外层包一层固定高度容器。直接打印这个容器，就容易只拿到当前视口。

File Viewer 现在按渲染链路动态显隐打印按钮。Word、PDF、Typst 等具备完整分页导出能力的格式会走专属适配器；Excel 等虚拟表格链路会隐藏打印按钮，避免给用户一个看似可用、实际会截断的结果。

Word 预览继续保留白色纸张、灰色页面底、居中阅读和完整页面导出。对合同、协议、审批材料来说，这种“像文档”的感觉，比单纯把内容塞进一个网页容器里重要得多。

发布链路也在继续补齐

这两版还补了一些不太显眼、却能提升交付效率的东西：

这些工作看起来没有太强标题感，却会直接影响你在客户现场复制静态目录、离线安装 tarball、部署 Docker 镜像、打开文档站、排查真实文件时的效率。

验证记录

这次发文前，我基于最新提交重新跑了本地验证：

部分构建体积也记录下来，方便大家判断私有化部署时的资源边界：

能力越多，越要珍惜首屏。按需异步加载仍然是这个组件的底线。

怎么升级到最新版

Vue3：

npm install @flyfish-group/file-viewer3@1.0.22

Vue2.7：

npm install @flyfish-group/file-viewer@1.0.22

React 与纯 Web：

npm install @flyfish-group/file-viewer-react@1.0.22npm install @flyfish-group/file-viewer-web@1.0.22

常用入口：

完整源码通过飞鱼小铺象征性打赏开通，一杯蜜雪冰城 即可自助获得全部源码以及后续仓库更新。公开成品仓库会持续提供混淆压缩后的构建产物、Demo 静态站、示例文件和 npm tarball，便于直接下载、部署和验收。

二次开发或商业使用时，请保留来源说明；如果你在真实项目中遇到新的样例文件、特殊打印场景、复杂 PPTX、奇怪 PDF 或内网部署问题，也欢迎把反馈带回来。组件的质量，最终会在这些细小而真实的文件里一点点长出来。

谢谢每一位把真实文件、控制台报错和现场反馈带回来的人。File Viewer 能走到今天，靠的是这些具体的文件、具体的边界、具体的业务现场。你们让这个项目从一个预览组件，慢慢长成可以被团队信任的交付工具。后面我们继续把每一次反馈写进代码，把每一次修补沉淀成文档，把这份开源做得更踏实、更清楚。✨

引用链接