dsj-model-viewer

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

支持格式

| 类型 | 扩展名 | | -------- | -------------------------------------------------------------------------------------------------------- | | 3D 模型 | glb / gltf / obj / fbx / stl / ply（含视图立方体 26 方位、模型树楼层/构件显隐、漫游、截图、网格/坐标轴） | | CAD 图纸 | dxf（图层面板、测量） | | 文档 | pdf / docx / doc / xlsx / xls / pptx / ppt / md / txt 等 | | 媒体 | 常见图片、音频、视频格式 |

不支持的格式回退到 UnsupportedViewer。

安装

npm i dsj-model-viewer

yarn add add dsj-model-viewer

pnpm add dsj-model-viewer

使用

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

<script setup>
import { FilePreview } from "dsj-model-viewer";
import "dsj-model-viewer/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 "dsj-model-viewer";
import "dsj-model-viewer/dist/style.css";
</script>

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

• 公共 props：source（必填，File 对象或 url 字符串）、fileName（可选）。
• 专属 props：ThreeViewer / UnsupportedViewer 需 ext（扩展名）；PptxViewer 支持 mode / showPageNav；ThreeViewer 还支持 background / autoRotate / showGrid / showAxis / dracoDecoderPath。
• 事件：loaded / error 照常触发（3D、DXF 另有 progress）。
• 上下文：单独使用时不会注入 FilePreview 的上下文，顶栏的保存 / 关闭 / 主题按钮会自动隐藏，不影响核心预览。

Props

| 属性 | 类型 | 默认值 | 说明 | | ---------------- | ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | string | "" | 远程文件地址，与 file 二选一 | | file | File \| null | null | 本地文件对象；与 url 同时存在时 file 优先 | | type | string | "" | 强制指定文件扩展名（不含点，如 glb/docx），用于 url 无扩展名或扩展名与实际格式不符的场景；缺省时从文件名推断 | | background | string | #111827 | 3D 场景背景色 | | autoRotate | boolean | false | 3D 模型自动旋转（仅初始化生效，运行时请用视图工具栏切换） | | showGrid | boolean | true | 3D 视图显示地面网格（仅初始化生效） | | showAxis | boolean | false | 3D 视图显示坐标轴（仅初始化生效） | | dracoDecoderPath | string | "" | glTF 内嵌 DRACO 压缩时的解码器目录；默认留空即可，使用 three 自带的本地 wasm 解码器，仅在需指向自建/CDN 路径时覆盖 | | pptxMode | "slide" \| "list" | — | PPTX 呈现方式：slide=单页翻页，list=全部页纵向连续滚动。不传时由组件内部维护（默认 list）并在工具栏提供「单页/连续」切换；传入后由宿主固定，用户无法切换 | | pptxShowPageNav | boolean | false | 是否在 PPTX 工具栏显示「上一页/下一页」按钮，仅 slide 模式有意义 | | showClose | boolean | false | 顶栏最右侧显示「关闭」按钮，点击触发 close 事件 | | showThemeToggle | boolean | true | 顶栏显示「深/浅主题切换」按钮 | | showTopBar | boolean | true | 是否显示顶栏（文件名 / 工具栏 / 保存 / 全屏 / 关闭），对所有查看器生效 | | showBottomBar | boolean | true | 是否显示底栏（帮助提示 / 媒体信息），对所有查看器生效 |

事件

| 事件 | 载荷 | 说明 | | -------- | --------------------------- | --------------------------------------------------------- | | loaded | { type, ... } | 解析成功；type 为命中的查看器类型，其余字段随查看器不同 | | error | unknown（通常为 Error） | 文件加载 / 解析失败 | | progress | number（0-100） | 加载进度，仅 3D / DXF 等有进度的查看器触发 | | close | — | 点击顶栏「关闭」按钮，由宿主决定关闭弹窗 / 清空预览 |

主题

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

交互

• 空态：未提供数据源时显示拖拽提示与「选择文件」按钮（键盘 / 触屏用户可用）。
• 拖拽：支持直接把文件拖入组件区域预览。
• 全屏：图片 / 音视频 / 3D 等查看器顶栏提供全屏按钮。

导出

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

• 工具函数：detectViewerType、getFileExtension、getFileName、normalizeExtension、toggleFullscreen、formatDuration，以及类型判断 isImage / isText / isMarkdown / isPdf / isOffice / isAudio / isVideo / isThree / isSupportedExtension。
• 扩展名常量：IMAGE_EXTENSIONS、TEXT_EXTENSIONS、MARKDOWN_EXTENSIONS、PDF_EXTENSIONS、OFFICE_EXTENSIONS、LEGACY_OFFICE_EXTENSIONS、AUDIO_EXTENSIONS、VIDEO_EXTENSIONS、THREE_EXTENSIONS、SUPPORTED_EXTENSIONS，以及可直接用于 <input type="file" :accept="ACCEPT_ATTR"> 的 ACCEPT_ATTR。
• 类型声明：ModelViewerProps、ModelViewerEmits、ViewerType、FileSource、ViewerLoadedResult、ModelInfo、DxfLayer、MediaInfo 等。

注意事项

DXF 预览需要的构建别名

dxf-viewer 内部 import opentype from "opentype.js"，而 opentype.js 的 ESM 构建没有 default 导出。若消费方使用 Vite 且需要 DXF 预览，请在 vite.config 中添加别名指向其 CJS 构建：

import { createRequire } from "node:module";
import { dirname } from "node:path";

const require = createRequire(import.meta.url);
const dxfViewerEntry = require.resolve("dxf-viewer");
const opentypeCjsEntry = require.resolve("opentype.js", { paths: [dirname(dxfViewerEntry)] });

export default defineConfig({
  resolve: {
    alias: { "opentype.js": opentypeCjsEntry }
  }
});

Draco 压缩模型

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