dsj-model-viewer

dsj-model-viewer

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

支持格式

不支持的格式回退到 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

事件

主题

组件内置深 / 浅两态：默认跟随系统 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）。