huijia-viewfile

一个基于 Vue 3 的多格式文件预览组件，支持文档、表格、演示文稿、图片与纯文本/代码的在线预览。

安装

npm i huijia-viewfile

或

pnpm add huijia-viewfile

或

yarn add huijia-viewfile

要求：Vue 3（peerDependency）。

快速开始（全局注册）

在入口文件（如 main.ts）中安装插件，并引入样式：

import { createApp } from "vue"
import App from "./App.vue"

import ViewFilePlugin from "huijia-viewfile"
import "huijia-viewfile/style.css"

createApp(App).use(ViewFilePlugin).mount("#app")

在页面中直接使用：

<template>
  <view-file :file="fileObject" />
</template>

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

const fileObject = ref({
  filename: "示例文件.pdf",
  type: "pdf",
  fileBuffer: null as ArrayBuffer | null,
})
</script>

Props

file

file 为一个对象，核心字段如下：

| 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | filename | string | 建议 | 文件名（用于展示与辅助推断类型） | | type | string | 是 | 文件扩展名（不带点），如 pdf / docx / xlsx | | fileBuffer | ArrayBuffer | null | 是 | 文件二进制内容（ArrayBuffer） | | size | number | 否 | 文件大小（仅用于兜底 UI 展示） | | name | string | 否 | 兜底文件名（仅用于兜底 UI 展示） |

支持的文件类型

• 文档：docx、pdf
• 表格：xlsx
• 演示：pptx
• 图片：gif、jpg、jpeg、bmp、tiff、tif、png、svg
• 文本/代码：txt、json、js、css、java、py、html、jsx、ts、tsx、xml、md、log

不支持的类型会展示“该类型文件不支持在线预览”的兜底视图。

使用的开源库

本项目集成了以下优秀的开源库来实现多格式预览：

• docx-preview: 用于 docx 文档的渲染。
• pdfjs-dist: 用于 pdf 文档的解析与渲染。
• exceljs: 用于 xlsx 表格数据的解析与处理。
• x-data-spreadsheet: 用于 xlsx 表格的 UI 渲染与交互。
• huijia-pptxtojson: 用于 pptx 演示文稿的解析，基于(https://github.com/pipipi-pikachu/pptxtojson)修改。
• html2canvas: 用于辅助某些格式的视觉转换。
• tinycolor2: 用于表格与演示文稿中的颜色处理。
• lodash-es: 提供高性能的 JavaScript 工具函数。

读取文件并预览

读取本地文件

组件导出了读取工具函数，推荐直接从包名导入：

<template>
  <input type="file" @change="onChange" />
  <view-file :file="fileObject" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { readBuffer } from "huijia-viewfile"

const fileObject = ref({
  filename: "",
  type: "",
  fileBuffer: null as ArrayBuffer | null,
})

function onChange(e: Event) {
  const input = e.target as HTMLInputElement
  const f = input.files?.[0]
  if (!f) return

  readBuffer(f)
    .then((buffer) => {
      const ext = (f.name.split(".").pop() || "").toLowerCase()
      fileObject.value = {
        filename: f.name,
        type: ext,
        fileBuffer: buffer,
      }
    })
    .catch((err) => {
      console.error("读取文件失败:", err)
    })
}
</script>

从 URL 获取文件并预览

function fetchArrayBuffer(url: string) {
  return fetch(url)
    .then((res) => {
      if (!res.ok) throw new Error(`HTTP ${res.status}`)
      return res.arrayBuffer()
    })
}

拿到 ArrayBuffer 后，填充到 fileObject.fileBuffer 即可。

插槽（图片自定义渲染）

当文件类型为图片时，提供 image 具名插槽，可用于自定义展示与预览交互。

插槽参数：

• src：当前图片 src
• srcList：图片列表（当前实现为单图，保留扩展能力）
• index：当前预览索引
• file：原始 file 对象
• preview：预览控制对象 { visible, open, close, next, prev }

示例：

<view-file :file="fileObject">
  <template #image="{ src, preview }">
    <img :src="src" style="max-width: 100%; max-height: 100%" @click="preview.open(0)" />
  </template>
</view-file>

常见问题

1. fileBuffer 必须是 ArrayBuffer，不要直接传 Blob / File。
2. 传入的 type 建议使用真实扩展名（不带 .），组件会据此选择渲染器。
3. 预览远端文件时注意 CORS，必要时通过后端代理获取。