Vue3 集成

For Vue 3 Projects

如果你的业务工程本身就是 Vue 3，这条路线几乎是最顺手的。 安装组件、注册一次，然后把文件 URL 或二进制交给它，剩下的渲染工作交给预览器处理。

当前 Vue3 npm 包是 @flyfish-group/file-viewer3@1.0.8。在线 Demo viewer.flyfish.dev 和后续生产上线均以 v3 分支产物作为最终来源。

安装

pnpm add @flyfish-group/file-viewer3

也可以使用 npm:

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

全局注册

包默认导出的是一个 Vue 插件，推荐在 main.ts 中全局注册:

import { createApp } from 'vue'
import App from './App.vue'
import FileViewer from '@flyfish-group/file-viewer3'

createApp(App).use(FileViewer).mount('#app')

页面中使用

通过 URL 预览

<script setup lang="ts">
import { ref } from 'vue'

const url = ref('https://example.com/demo.pdf')
</script>

<template>
  <div class="viewer-shell">
    <file-viewer :url="url" />
  </div>
</template>

<style scoped>
.viewer-shell {
  height: 100vh;
}
</style>

通过上传文件预览

<script setup lang="ts">
import { ref } from 'vue'

const file = ref<File | undefined>()

function onChange(event: Event) {
  const input = event.target as HTMLInputElement
  const value = input.files?.item(0)
  if (value) file.value = value
}
</script>

<template>
  <div class="page">
    <input type="file" @change="onChange" />
    <div class="viewer-shell">
      <file-viewer :file="file" />
    </div>
  </div>
</template>

<style scoped>
.page {
  height: 100vh;
}

.viewer-shell {
  height: calc(100vh - 40px);
}
</style>

参数行为

参数	类型	说明
url	string	组件内部会使用 axios 拉取文件，再交给对应渲染器解析
file	File	推荐直接传入带正确扩展名的 File，适合本地上传预览或业务侧已完成鉴权下载的场景

当 file 和 url 同时存在时，组件会优先渲染 file。如果后续 file 被清空，组件会回退到 url 继续加载。

如果你的业务侧拿到的是 Blob 或 ArrayBuffer，推荐先包装成带扩展名的 File 再传入，例如:

file.value = new File([blob], 'contract.pdf', { type: blob.type })

常见接入建议

给容器一个明确高度

预览器默认会填满父容器，所以父容器必须是有高度的。最常见的写法是 100vh，或者在后台页面里使用 Flex 布局撑开:

<template>
  <div class="page">
    <header class="toolbar">工具栏</header>
    <main class="content">
      <file-viewer :url="url" />
    </main>
  </div>
</template>

<style scoped>
.page {
  height: 100vh;
  display: flex;
  flex-direction: column;
}

.content {
  flex: 1;
  min-height: 0;
}
</style>

URL 方案要注意 CORS

如果你使用 url 参数，本质上是在浏览器里请求目标文件。只要文件地址不可直接访问，或者服务端没有返回正确的跨域头，预览就会失败。这种场景建议切换到 file 参数，或者直接使用 iframe 独立部署方案。

局部注册也可以

如果你不想全局 use()，也可以从包中按需导出组件:

import { FileViewer } from '@flyfish-group/file-viewer3'

Vue2 项目怎么选

Vue2.7 项目请使用 @flyfish-group/file-viewer@1.0.8，插件注册方式是 Vue.use(FileViewer)。两条包线的文件格式能力、Demo 样例和 iframe 协议保持一致，详细步骤见 Vue2 集成。

更适合平台化的方案

如果你正在做的是统一附件中心、多个系统共用一套预览器，或者担心解析依赖进入业务包后带来维护成本，建议直接看 Iframe 嵌入。