BizFileViewer 文件预览

文件在线预览：native 引擎（默认）零依赖——PDF 走浏览器内置查看器、图片直接渲染；pdfjs 引擎提供页码 / 缩放控制（可选）；office 内置渲染（可选）——注入 docx-lib（docx-preview）/ xlsx-lib（SheetJS）后，.docx / .xlsx / .xls / .csv 在组件容器内直接渲染（文档不出内网）；未注入时仍可由业务侧经 office-viewer 对接自建预览服务（kkFileView / onlyoffice）。合同 / 附件 / 扫描件在线查看。

依赖说明（按引擎区分）

• native 引擎（默认）：零第三方依赖，开箱即用（PDF / 图片）。
• pdfjs 引擎：需自装 pdfjs-dist（可选 peer）并配置 worker，经 pdfjs-lib 注入：

npm i pdfjs-dist

import * as pdfjsLib from 'pdfjs-dist'
import workerUrl from 'pdfjs-dist/build/pdf.worker.min.mjs?url'
pdfjsLib.GlobalWorkerOptions.workerSrc = workerUrl

• office 内置渲染（可选）：自装 docx-preview（docx）与 / 或 xlsx（SheetJS，覆盖 xlsx/xls/csv）后注入，无转换服务依赖：

npm i docx-preview xlsx

import * as docxLib from 'docx-preview'
import * as XLSX from 'xlsx'
const xlsxLib = { read: XLSX.read, sheet_to_html: (s, o) => XLSX.utils.sheet_to_html(s, o) }

• office 服务预览：不装上述库时，业务侧自建 kkFileView / onlyoffice 服务并传 office-viewer 地址模板。

pdfjs-dist v5+ 已知问题：其代码依赖尚未普及的 Map.prototype.getOrInsertComputed（TC39 提案，见 pdf.js#20680），页面渲染前需补 3 行 polyfill，或降级使用 4.x：

if (!Map.prototype.getOrInsertComputed) {
  Map.prototype.getOrInsertComputed = function (key, fn) {
    if (!this.has(key)) this.set(key, fn(key))
    return this.get(key)
  }
}

PDF 预览（native）

📄 采购合同-2026-098.pdf

native 引擎走浏览器 PDF 查看器（Chrome / Edge / Firefox 原生支持），无需安装任何依赖。

浏览器内置 PDF 查看器，零依赖。

<script setup lang="ts">
/** 场景：合同 PDF 预览——native 引擎（浏览器内置查看器，零依赖） */
import { BizFileViewer } from 'vue3-ep-biz-lib'
</script>

<template>
  <div style="max-width: 640px">
    <BizFileViewer src="/files/sample.pdf" name="采购合同-2026-098.pdf" :height="380" />
    <p style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      native 引擎走浏览器 PDF 查看器（Chrome / Edge / Firefox 原生支持），无需安装任何依赖。
    </p>
  </div>
</template>

显示代码

图片 / 扫描件

📄 发票扫描件-第1页.png

📄 发票扫描件-第2页.png

type=image 适配件预览。

<script setup lang="ts">
/** 场景：扫描件 / 图片附件预览 */
import { BizFileViewer } from 'vue3-ep-biz-lib'

const images = [
  { src: 'https://dummyimage.com/720x400/3a7afe/ffffff&text=Invoice+Scan+P1', name: '发票扫描件-第1页.png' },
  { src: 'https://dummyimage.com/720x400/2f9e6e/ffffff&text=Invoice+Scan+P2', name: '发票扫描件-第2页.png' },
]
</script>

<template>
  <div style="max-width: 640px; display: grid; gap: 14px">
    <BizFileViewer
      v-for="img in images"
      :key="img.src"
      :src="img.src"
      :name="img.name"
      :height="260"
      type="image"
    />
  </div>
</template>

显示代码

office 对接自建服务

📄 招标文件-2026-045.docx

组件不内置任何 office 转换服务（避免把内部文档外发第三方）：officeViewer 返回自建预览服务的完整 URL 后，以内嵌框架打开。示例服务为演示占位。

office-viewer 返回自建预览服务完整 URL，内嵌框架打开（文档不出内网）。

<script setup lang="ts">
/** 场景：office 文档——对接自建预览服务（kkFileView / onlyoffice），文档不出内网 */
import { BizFileViewer } from 'vue3-ep-biz-lib'

// 业务侧自建 kkFileView 的地址模板（示例域名，实际替换为内网服务）
// btoa 仅浏览器可用，SSR 构建渲染期降级 Buffer（kkFileView 要求 base64 编码地址）
const toBase64 = (s: string): string =>
  typeof Buffer !== 'undefined'
    ? Buffer.from(s, 'utf-8').toString('base64')
    : btoa(unescape(encodeURIComponent(s)))

const officeViewer = (src: string): string =>
  `https://kkfileview.internal.example.com/onlinePreview?url=${encodeURIComponent(toBase64(src))}`
</script>

<template>
  <div style="max-width: 640px">
    <BizFileViewer
      src="https://oss.example.com/contracts/招标文件-2026-045.docx"
      name="招标文件-2026-045.docx"
      :office-viewer="officeViewer"
      :height="320"
    />
    <p style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      组件不内置任何 office 转换服务（避免把内部文档外发第三方）：officeViewer
      返回自建预览服务的完整 URL 后，以内嵌框架打开。示例服务为演示占位。
    </p>
  </div>
</template>

显示代码

docx 内置预览

📄 设备采购合同.docx

使用方自装 docx-preview 后经 docx-lib 注入（与 pdfjs 引擎同一注入模式，库不打包该依赖）； 渲染发生在组件容器内，文档不出内网。旧版 .doc 不支持（走 officeViewer 服务或降级提示）。

注入 docx-preview 库，.docx 在组件容器内直接渲染——无需预览服务、文档不出内网。

<script setup lang="ts">
/** 场景：docx 内置预览——注入 docx-preview 库，合同文档容器内渲染（无文档外发） */
import * as docxLib from 'docx-preview'
import { BizFileViewer } from 'vue3-ep-biz-lib'
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 100%">
    <BizFileViewer src="/files/sample.docx" name="设备采购合同.docx" :docx-lib="docxLib" :height="420" />
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      使用方自装 <code>docx-preview</code> 后经 <code>docx-lib</code> 注入（与 pdfjs 引擎同一注入模式，库不打包该依赖）；
      渲染发生在组件容器内，文档不出内网。旧版 .doc 不支持（走 officeViewer 服务或降级提示）。
    </p>
  </el-space>
</template>

显示代码

xlsx 内置预览（多 sheet）

📄 设备台账.xlsx

使用方自装 xlsx（SheetJS）后组装 { read, sheet_to_html } 注入； .xlsx / .xls / .csv 以 HTML 表格渲染，多 sheet 自动出页签（示例含「设备台账 / 维保记录」两个 sheet）。

自装 SheetJS 组装 { read, sheet_to_html } 注入；.xlsx / .xls / .csv 以表格渲染，多 sheet 页签切换。

<script setup lang="ts">
/** 场景：xlsx 内置预览——注入 SheetJS 组装对象，多 sheet 页签切换 */
import * as XLSX from 'xlsx'
import { BizFileViewer } from 'vue3-ep-biz-lib'
import type { BizFileViewerXlsxLib } from 'vue3-ep-biz-lib'

/** CommonJS 库组装为组件契约对象（read + sheet_to_html） */
const xlsxLib: BizFileViewerXlsxLib = {
  read: XLSX.read,
  sheet_to_html: (sheet, opts) => XLSX.utils.sheet_to_html(sheet as XLSX.WorkSheet, opts),
}
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 100%">
    <BizFileViewer src="/files/sample.xlsx" name="设备台账.xlsx" :xlsx-lib="xlsxLib" :height="420" />
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      使用方自装 <code>xlsx</code>（SheetJS）后组装 <code>{ read, sheet_to_html }</code> 注入；
      .xlsx / .xls / .csv 以 HTML 表格渲染，多 sheet 自动出页签（示例含「设备台账 / 维保记录」两个 sheet）。
    </p>
  </el-space>
</template>

显示代码

pdfjs 引擎（页码 / 缩放）

📄 验收报告.pdf1 / ?

PDF 加载中...

工具栏出现「上一页 / 下一页 / 缩放」即 pdfjs 引擎生效；需项目内 npm i pdfjs-dist 并配置 worker。

自装 pdfjs-dist 注入实例，工具栏出现翻页与缩放。

<script setup lang="ts">
/** 场景：pdfjs 引擎——自装 pdfjs-dist 注入实例，页码 / 缩放可控 */
import { onMounted, ref } from 'vue'
import { BizFileViewer } from 'vue3-ep-biz-lib'
import type { BizFileViewerPdfjsLib } from 'vue3-ep-biz-lib'

// pdfjs-dist 为可选 peer：使用方自行安装并配置 worker（此处演示在浏览器端动态装配）
const pdfjsLib = ref<BizFileViewerPdfjsLib>()

onMounted(async () => {
  // pdfjs v5+ 依赖尚未普及的 Map.prototype.getOrInsertComputed（TC39 提案），先补 polyfill
  if (typeof Map !== 'undefined' && !(Map.prototype as unknown as Record<string, unknown>).getOrInsertComputed) {
    ;(Map.prototype as unknown as Record<string, unknown>).getOrInsertComputed = function (
      this: Map<unknown, unknown>,
      key: unknown,
      fn: (key: unknown) => unknown
    ) {
      if (!this.has(key)) this.set(key, fn(key))
      return this.get(key)
    }
  }
  const pdfjs = await import('pdfjs-dist')
  const worker = await import('pdfjs-dist/build/pdf.worker.min.mjs?url')
  pdfjs.GlobalWorkerOptions.workerSrc = worker.default
  pdfjsLib.value = pdfjs as unknown as BizFileViewerPdfjsLib
})
</script>

<template>
  <div style="max-width: 640px">
    <BizFileViewer
      src="/files/sample.pdf"
      name="验收报告.pdf"
      engine="pdfjs"
      :pdfjs-lib="pdfjsLib"
      :height="420"
    />
    <p style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      工具栏出现「上一页 / 下一页 / 缩放」即 pdfjs 引擎生效；需项目内 <code>npm i pdfjs-dist</code> 并配置 worker。
    </p>
  </div>
</template>

显示代码

类型自动分流

📄 立项批复.pdf

📄 现场照片.jpg

该文件类型不支持在线预览

可下载后本地打开，或配置 officeViewer 对接自建预览服务

📄 2026预算表.xlsx

📄 BIM模型.rvt

该文件类型不支持在线预览

可下载后本地打开，或配置 officeViewer 对接自建预览服务

type="auto" 按扩展名分流 PDF / 图片 / office / 不支持降级。

<script setup lang="ts">
/** 场景：附件列表——type=auto 按扩展名自动分流（PDF / 图片 / office / 不支持） */
import { BizFileViewer } from 'vue3-ep-biz-lib'

const files = [
  { src: '/files/sample.pdf', name: '立项批复.pdf' },
  { src: 'https://dummyimage.com/600x300/e6a23c/ffffff&text=Site+Photo', name: '现场照片.jpg' },
  { src: 'https://oss.example.com/plan/2026预算表.xlsx', name: '2026预算表.xlsx' },
  { src: 'https://oss.example.com/plan/模型文件.rvt', name: 'BIM模型.rvt' },
]

// btoa 仅浏览器可用，SSR 构建渲染期降级 Buffer（kkFileView 要求 base64 编码地址）
const toBase64 = (s: string): string =>
  typeof Buffer !== 'undefined'
    ? Buffer.from(s, 'utf-8').toString('base64')
    : btoa(unescape(encodeURIComponent(s)))

const officeViewer = (src: string): string =>
  `https://kkfileview.internal.example.com/onlinePreview?url=${encodeURIComponent(toBase64(src))}`
</script>

<template>
  <div style="max-width: 640px">
    <div v-for="f in files" :key="f.src" style="margin-bottom: 14px">
      <BizFileViewer :src="f.src" :name="f.name" :height="220" :office-viewer="officeViewer" />
    </div>
  </div>
</template>

显示代码

极简模式

隐藏工具栏纯预览（弹窗内嵌）。

<script setup lang="ts">
/** 场景：极简模式——隐藏工具栏纯预览（弹窗内嵌场景） */
import { ref } from 'vue'
import { ElButton, ElDialog } from 'element-plus'
import { BizFileViewer } from 'vue3-ep-biz-lib'

const visible = ref(false)
</script>

<template>
  <div style="max-width: 640px">
    <ElButton type="primary" @click="visible = true">查看附件（弹窗）</ElButton>
    <ElDialog v-model="visible" title="附件预览" width="720px">
      <BizFileViewer
        src="/files/sample.pdf"
        name="资质文件.pdf"
        :height="440"
        :show-toolbar="false"
      />
    </ElDialog>
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
src	string	''	文件地址
name	string	''	文件名（工具栏展示与下载命名）
type	'auto' | 'pdf' | 'image' | 'office' | 'unknown'	'auto'	文件类型（auto 按扩展名推断）
engine	'native' | 'pdfjs'	'native'	预览引擎
pdfjs-lib	BizFileViewerPdfjsLib	—	pdfjs 引擎必传：注入的 pdfjs-dist 模块
docx-lib	BizFileViewerDocxLib	—	.docx 容器内渲染：注入的 docx-preview 模块（可选自装）
xlsx-lib	BizFileViewerXlsxLib	—	.xlsx / .xls / .csv 表格渲染：注入的 SheetJS 组装对象（可选自装）
office-viewer	(src: string) => string	—	office 预览服务地址模板（未注入上述两库时生效）
height	number	480	视口高度（px）
show-toolbar	boolean	true	工具栏（文件名 / 翻页 / 缩放）
show-download	boolean	true	下载按钮

Expose

名称	类型	说明
renderPdf	() => Promise<void>	pdfjs 引擎手动重渲染
loadOffice	() => Promise<void>	office 内置渲染手动重载（docx / sheet 通道）