vue3-files-preview

vue3-files-preview

Vue3 多格式文档 / 模型预览组件。单个 <FilePreview> 按文件类型自动分发到对应查看器，支持本地 File 对象与远程 URL 两种数据源。

支持格式

旧版二进制格式（.doc / .ppt / .xls）无法在浏览器端解析，会回退到 UnsupportedViewer 并给出「另存为新格式」的补救提示；其余不支持的格式同样回退到 UnsupportedViewer。

安装

npm install vue3-files-preview

yarn add vue3-files-preview

pnpm add vue3-files-preview

本包以 peerDependencies 声明全部运行时依赖（vue 之外还有 docx-preview、exceljs、pdfjs-dist、three、dxf-viewer、mermaid、katex、marked、highlight.js、dompurify、pptx-preview、vue-pdf-embed、jszip、ssf、xgplayer、xgplayer-flv、xgplayer-hls、core-js）。npm 7+ / pnpm / yarn 会自动安装 peer 依赖；如果手动管理依赖，请按需安装上表格式对应的库。其中：

• pdfjs-dist 与 vue-pdf-embed 为精确锁定版本（两者必须共享同一个 pdf.js 实例），请勿自行升级；
• three / dxf-viewer 体积较大且仅 3D / DXF 格式用到，宿主若确认不预览这两类格式，可自行省略（对应查看器分包不会被加载）；
• xgplayer / xgplayer-flv / xgplayer-hls / core-js 仅视频的第三方播放器模式（videoPlayer="xgplayer"）用到，分包按需懒加载；native 模式（默认）不下载对应代码。core-js 是 xgplayer 自身声明的依赖。

Vite 插件（必须）

本包依赖 vue-pdf-embed、pdfjs-dist、dxf-viewer 等库，在 Vite 消费时存在预构建兼容、CJS 互操作等问题。请务必在消费项目的 vite.config.ts 中添加内置 Vite 插件：

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { vue3FilesPreviewPlugin } from "vue3-files-preview/plugin";

export default defineConfig({
  plugins: [vue(), vue3FilesPreviewPlugin()]
});

该插件一站式解决以下问题：

使用

<template>
  <FilePreview :url="fileUrl" style="width: 100%; height: 600px" @close="onClose" />
</template>

<script setup>
import { FilePreview } from "vue3-files-preview";
import "vue3-files-preview/dist/style.css";

const fileUrl = "https://example.com/model.glb";
</script>

本地文件预览：

<FilePreview :file="fileObj" />

单独使用某个查看器

除聚合入口 FilePreview 外，各格式的查看器也可单独按需引入（均为异步组件，用到哪个才加载对应分包）：

<template>
  <ImageViewer :source="file" file-name="示例.png" />
</template>

<script setup>
import { ImageViewer } from "vue3-files-preview";
import "vue3-files-preview/dist/style.css";
</script>

可单独使用的查看器：ThreeViewer、DxfViewer、ImageViewer、DocumentViewer（纯文本）、MarkdownViewer、DocxViewer、XlsxViewer、CsvViewer、PdfViewer、PptxViewer、AudioViewer、VideoViewer、ArchiveViewer、UnsupportedViewer。

• 公共 props：source（必填，File 对象或 url 字符串）、fileName（可选）、requestHeaders（可选，见「带鉴权的远程文件」一节；传入本地 File 时查看器内部会自动忽略）。
• 专属 props：ThreeViewer / UnsupportedViewer 需 ext（扩展名）；PdfViewer 支持 mode / showModeToggle；PptxViewer 支持 mode / showPageNav；VideoViewer 支持 videoPlayer（"native" 默认 / "xgplayer" 西瓜播放器，flv 与 m3u8 仅后者可播）；ThreeViewer 还支持 background / autoRotate / showGrid / showAxis / dracoDecoderPath。注意 ThreeViewer 单独使用时自身的默认值与 FilePreview 聚合入口不同：showGrid 为 true、background 为 #171717（聚合入口由容器统一下发，故 showGrid 默认 false、背景随主题令牌）。
• 事件：loaded / error 照常触发（3D、DXF 另有 progress）。
• 上下文：单独使用时不会注入 FilePreview 的上下文，顶栏的保存 / 关闭 / 主题按钮会自动隐藏，不影响核心预览。

Props

事件

宿主方法（ref expose）

通过模板 ref 可调用组件暴露的两个方法：

const previewRef = ref();
previewRef.value.reload(); // 重新加载当前源（整只查看器重建，重新拉取/解析）
previewRef.value.clearCache(); // 清空本实例的远程源内存缓存，下次访问重新拉取

reload() 在没有当前源时为空操作（不会报错）。

另外，切换 url / file 时在途的网络请求会被自动取消（AbortController），不会等旧文件下载完才切换；url 与 file 同时清空时组件回到空态拖拽提示。

主题

组件内置深 / 浅两态：默认跟随系统 prefers-color-scheme，用户点击顶栏主题按钮后以手动选择为准（可用 showThemeToggle 关闭该按钮）。根元素带 data-theme="light|dark"，颜色统一走 --mv-* 设计令牌，宿主可覆盖以自定义配色。

令牌清单

在宿主样式里覆盖令牌即可定制配色（写在能作用到 .file-preview 的选择器上）：

.file-preview {
  --mv-accent: #7c5cff; /* 例如：把品牌色换成紫罗兰 */
}

尺寸 / 圆角 / 阴影 / 缓动等结构令牌（--mv-radius*、--mv-shadow、--mv-blur、--mv-ease）两套主题共用，仅颜色类令牌随主题切换。

文案（locale）

界面默认为中文，可通过 locale prop 覆盖任意条目（浅合并，未提供的键回落默认值）：

<FilePreview :url="url" :locale="{ save: 'Save', close: 'Close', loadFailedTitle: 'Failed to load' }" />

可覆盖键见类型 ViewerLocale（包的类型导出）：顶栏按钮（save / close / toLightTheme / toDarkTheme …）、容器状态（loading / loadFailedTitle / dropToPreview / 错误映射 errNetwork / err403 …）、面板（panelModelTree / panelLayers / hideAll / showAll / 页签 tabFloor / tabComponent 等）、Markdown 目录（toc / tocAria / tocExpand / tocCollapse / tocChildExpandPrefix / tocChildCollapsePrefix / tocChildSuffix）、表格图片预览（clickPreviewTitle / imagePreviewAria / closeEscTitle / closeImagePreviewAria / imagePreviewAlt）、PPTX 失败兜底（pptxNoSlides）。完整键位与内置中文文案见类型声明。注意 locale 初始化后固定，不响应式更新。

交互

• 空态：未提供数据源时显示拖拽提示。
• 拖拽：支持直接把文件拖入组件区域预览。
• 全屏：图片 / 音视频 / 3D 等查看器顶栏提供全屏按钮。

水印

企业预览场景（图纸 / 合同类文档）常要求在预览区叠加当前用户标识，防止截屏外传：

<!-- 字符串简写 -->
<FilePreview :url="url" watermark="预览人：张三 2026-10-06" />

<!-- 完整配置 -->
<FilePreview
  :url="url"
  :watermark="{
    text: ['内部资料', '预览人：张三'],
    opacity: 0.16,
    fontSize: 15,
    rotate: -22,
    gapX: 180,
    gapY: 140,
    color: 'rgba(255, 255, 255, 0.9)'
  }"
/>

水印为 canvas 绘制的平铺图层，覆盖整个预览区（含顶栏/底栏），pointer-events 穿透不影响任何交互与全屏；未配置 color 时按深/浅主题自动取前景色，主题切换自动重绘。tile 按设备像素比绘制、按逻辑像素平铺（background-size），高分屏上文字不发虚。

防篡改

水印默认开启防篡改保护：水印节点被删除、style/class 被改动时自动恢复——MutationObserver 即时校正 + 周期巡检兜底（观察器本身被脚本 disconnect 也能恢复），且关键属性（背景图/平铺尺寸/层级/点击穿透）以 !important 行内样式写入，可抵御外部样式表的 !important 覆盖。宿主需要自行操控水印 DOM 时可关闭：

<FilePreview :watermark="{ text: '内部资料', tamperProof: false }" />

查看器工具栏的全屏按钮全屏的是组件根容器而非查看器自身区域，水印与顶栏/底栏在全屏下同样覆盖——不存在「全屏后无水印可截图」的绕过口（独立使用某个查看器组件、无容器注入时回落为全屏查看器自身）。

防篡改针对的是 DevTools 手动删改与常规脚本移除，无法对抗页面内任意脚本——客户端水印本质是视觉威慑，强对抗需求请配合服务端手段（下载/导出文件烙印水印、访问审计等）。

带鉴权的远程文件

文件服务需要登录态/签名时，通过 requestHeaders 传入请求头，组件内所有远程读取统一携带（各查看器也可单独使用时各自传入）：

<FilePreview :url="fileUrl" :request-headers="{ Authorization: `Bearer ${token}` }" />

实现方式按载体自动区分：文档解析（docx/xlsx/pptx/md/文本）、pdf.js 渲染（httpHeaders，支持 Range 分片）、3D 模型（three loader 原生携带）直接随请求发送；无法携带请求头的载体（<img>、<video>/<audio>、iframe 模式 PDF、dxf-viewer）自动先拉取为 blob 中转。注意：

• blob 中转意味着整包下载，大视频/大 PDF（iframe 模式）没有流式范围请求；
• 3D 多文件格式（.gltf + 外部贴图、.obj + .mtl）中主文件携带请求头，由 three 内部加载器发起的贴图等子资源不保证携带——此类场景建议 .glb 内嵌资源或经代理直连；
• 顶栏「保存」同样携带请求头。带请求头的地址若 fetch 失败（鉴权过期、断网），保存会判定为失败并在顶栏给出提示，而不是静默降级为必然失败的直链；未带请求头时跨域 fetch 失败仍会降级为直链下载。预览与保存共用内存缓存，保存不触发二次整包下载。

导出

除默认导出的 FilePreview 组件外，还导出：

• 工具函数：detectViewerType、getFileExtension、getFileName、normalizeExtension、formatDuration，以及类型判断 isImage / isText / isCsv / isMarkdown / isPdf / isOffice / isAudio / isVideo / isThree / isSupportedExtension。
• 扩展名常量：IMAGE_EXTENSIONS、TEXT_EXTENSIONS、MARKDOWN_EXTENSIONS、PDF_EXTENSIONS、OFFICE_EXTENSIONS、LEGACY_OFFICE_EXTENSIONS、CSV_EXTENSIONS、AUDIO_EXTENSIONS、VIDEO_EXTENSIONS、THREE_EXTENSIONS、ARCHIVE_EXTENSIONS、SUPPORTED_EXTENSIONS，以及可直接用于 <input type="file" :accept="ACCEPT_ATTR"> 的 ACCEPT_ATTR。
• 文案：zhCN（内置中文文案全量对象，可作为自定义 locale 的基底）、mergeLocale（Partial<ViewerLocale> 与内置值的浅合并函数）。
• 类型声明：ModelViewerProps、ModelViewerEmits、ViewerType、FileSource、ViewerLoadedResult、ViewerProps、ViewerEmits、ProgressViewerEmits、ViewerTheme、ViewerLocale、ThreeViewerProps、PdfMode、PdfViewerProps、PptxMode、PptxViewerProps、UnsupportedViewerProps、ModelInfo、DxfLayer、MediaInfo、WatermarkOptions。

注意事项

PDF 大文件

pdf.js 模式按页虚拟渲染：只有视口附近（前后各 2 页）的页面实际渲染成 canvas，其余页以同高占位槽撑出滚动条，几百上千页的文档不会把内存打爆；页码跟踪、缩放锚点均基于占位槽定位。

Excel 解析器

xlsx 由 exceljs 解析（值、公式缓存结果、合并区、单元格样式、行高列宽、WPS 内嵌图片 ID）；数值与日期按 Excel 数字格式（numFmt）渲染。整表超过 5000 行 / 200 列会截断并在底栏提示。旧版二进制 .xls（BIFF 格式）无法解析，见「支持格式」一节的回退说明。

大表走虚拟滚动：只渲染视口附近的行（视口前后留 buffer），上下用同高占位行撑出滚动条。

表格图片预览

xlsx 里的图片统一按「锚点单元格内绝对定位」渲染，支持两类来源：WPS 单元格函数图（DISPIMG）与 drawing.xml 浮动图。

• 定位：以图片所在 td 为坐标系，位置由表格布局本身决定，不受视口尺寸、滚动位置、是否全屏影响；尺寸取文件里记录的行高/列宽（或 ext 原始像素），与 Excel / WPS 保存的值一致。
• 放大：点击单元格图片打开灯箱浮层，原图按 object-fit: contain 铺满视口；点击空白处或右上角关闭按钮关闭。
• 与全屏叠加：全屏状态下浮层自动 teleport 到全屏元素内部（浏览器只会渲染全屏子树，挂在 body 上的浮层会被整块盖住、表现为「点了没反应」）；退出全屏后自动搬回 body。
• Esc 分层退出：全屏 + 浮层同时存在时，第一次 Esc 只退出全屏、图片保留，再按一次才关闭图片；未全屏时 Esc 直接关闭。ESC 处理挂在 document 捕获阶段，不会冒泡到外层导致整个预览被关掉。

PPTX 解析失败

第三方生成器（如 pptxgenjs）产出的结构不完整文件，pptx-preview 可能静默吞掉解析异常并表现为「成功解析出 0 页」。此时查看器按 locale.pptxNoSlides 给出明确提示（建议用 PowerPoint 重新导出），而不是留一个空白画面。

该兜底在 slide（单页翻页）与 list（连续滚动）两种模式下均生效——slide 模式下库会尝试渲染不存在的首页导致 TypeError，查看器捕获后统一转为友好报错，不会把原始技术错误泄漏给用户，也不会因 ResizeObserver 触发重建循环而刷屏。

安全

Office 文档（docx / pptx）由 docx-preview / pptx-preview 把文档 XML 直接转成 HTML 插入页面；上传方可控的恶意 XML 可能携带脚本、事件属性或 javascript: 链接，构成存储型 XSS 面。库在渲染完成后对产物 DOM 执行一次 DOMPurify 就地消毒（IN_PLACE 模式，保留元素实例与 data:/blob: 图片 URI），Markdown 同样经 DOMPurify 处理。xlsx 走 Vue 文本插值（自动转义）且图片为 blob: src，构造上安全，不额外消毒。

压缩文件预览

zip 压缩包由 jszip 解析，预览时左侧显示条目列表（文件名、扩展名标签、体积），点击条目即在右侧内联预览——条目按扩展名自动分发到与直接预览同一文件完全相同的查看器（3D / PDF / Office / 图片 / 音视频等），内嵌查看器的工具栏经 Teleport 托管到外层顶栏，视觉与独立预览一致。

• 条目管理：列表支持按包内路径前缀过滤（大小写不敏感）、循环切换排序（默认 → 名称 → 大小 → 类型）；条目按目录分组显示。列表可收起让预览视口占满，收起后展开入口位于压缩包顶栏工具栏（不与预览区左上角冲突——那里是内层查看器的面板位：Markdown 目录、3D 模型树、DXF 图层面板都会占）；仅当宿主隐藏了顶栏（showTopBar=false）时才回落到预览区左上角的悬浮按钮。宿主通过 archiveShowList=false 关闭列表时不给任何展开入口。
• 单条目下载：每个条目右侧带下载按钮，带实时进度百分比；单个条目下载失败时内联红字提示，不影响其余条目预览。
• 嵌套压缩包：zip 内嵌 zip 时自动递归预览，内层压缩包保持自带顶栏（显示内层包名），列表跟随外层 archiveShowList 开关。
• 体积防线：archiveEntryMaxSize（默认 200MB）按中央目录声明的原始体积事前拦截超大条目，超限直接拒绝解压并提示可下载，而非解压到一半内存耗尽才崩溃。条目解析失败只在该条目的预览区给出内联提示，列表保持可用可换条目。
• 保存：顶栏「保存」下载的是压缩包本身（当前层），而非当前预览的条目。

UnsupportedViewer 连续切换

连续切换多个不支持的文件（如 .doc → .xls → .ppt → .xyz）时，Vue 会复用同一个 UnsupportedViewer 实例（组件类型相同且 key 未变），onMounted 不会再次触发。查看器内部 watch 了 source 变化，每次切源都会重新上报 loaded 事件，确保宿主的 loading 遮罩不会永久停留。

Draco 压缩模型

预览 draco 压缩的 glb/gltf 无需额外配置：three 的 DRACOLoader 默认使用自带的本地 wasm 解码器，打包器会自动产出对应静态资源。仅当需要指向自建 / CDN 上的 three 官方解码器 目录时，才通过 draco-decoder-path 传入（该目录需含 draco_wasm_wrapper.js 与 draco_decoder.wasm）。