# huijia-viewfile

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

## 安装

```bash
npm i huijia-viewfile
```

或

```bash
pnpm add huijia-viewfile
```

或

```bash
yarn add huijia-viewfile
```

要求：Vue 3（peerDependency）。

## 快速开始（全局注册）

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

```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")
```

在页面中直接使用：

```vue
<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](https://github.com/501351981/vue-office)**: 用于 `docx` 文档的渲染。
- **[pdfjs-dist](https://github.com/mozilla/pdf.js)**: 用于 `pdf` 文档的解析与渲染。
- **[exceljs](https://github.com/exceljs/exceljs)**: 用于 `xlsx` 表格数据的解析与处理。
- **[x-data-spreadsheet](https://github.com/myliang/x-data-spreadsheet)**: 用于 `xlsx` 表格的 UI 渲染与交互。
- **[huijia-pptxtojson](https://github.com/wobushiyoushen0214/pptxtojson)**: 用于 `pptx` 演示文稿的解析，基于(https://github.com/pipipi-pikachu/pptxtojson)修改。
- **[html2canvas](https://github.com/niklasvh/html2canvas)**: 用于辅助某些格式的视觉转换。
- **[tinycolor2](https://github.com/bgrins/TinyColor)**: 用于表格与演示文稿中的颜色处理。
- **[lodash-es](https://github.com/lodash/lodash)**: 提供高性能的 JavaScript 工具函数。

## 读取文件并预览

### 读取本地文件

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

```vue
<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 获取文件并预览

```ts
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 }`

示例：

```vue
<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，必要时通过后端代理获取。