huijia-viewfile 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -172
- package/dist-lib/huijia-viewfile.css +1 -1
- package/dist-lib/index.cjs +70 -70
- package/dist-lib/index.js +30707 -28391
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,227 +1,164 @@
|
|
|
1
|
-
|
|
2
|
-
ViewFile 是一个功能强大的文件预览组件，支持多种文件格式的在线预览，包括文档、表格、演示文稿、图片和文本文件等。该组件能够根据文件类型自动选择合适的渲染器进行内容展示，为用户提供便捷的文件预览体验。该项目基于 Vue 3.5 开发，请确保您的项目使用 Vue 3.x 版本。
|
|
3
|
-
|
|
4
|
-
<h2 id="SK0VG">2. 组件结构</h2>
|
|
5
|
-
ViewFile 组件采用模块化设计，主要包含以下部分：
|
|
6
|
-
|
|
7
|
-
```plain
|
|
8
|
-
view_file/
|
|
9
|
-
├── index.vue # 主组件入口
|
|
10
|
-
├── index.less # 样式文件
|
|
11
|
-
├── util.js # 工具函数
|
|
12
|
-
├── renders.js # 渲染器注册
|
|
13
|
-
└── vendors/ # 各类型文件渲染器
|
|
14
|
-
├── image/ # 图片渲染
|
|
15
|
-
├── other/ # 不支持预览的文件处理
|
|
16
|
-
├── pdf/ # PDF渲染
|
|
17
|
-
├── pptx/ # PPT渲染
|
|
18
|
-
├── text/ # 文本渲染
|
|
19
|
-
└── xlsx/ # Excel渲染
|
|
20
|
-
└── colz/ # Colz渲染
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
<h2 id="shZJb">3. 使用方法</h2>
|
|
24
|
-
<h3 id="i1B2h">3.1 基本用法</h3>
|
|
25
|
-
1. 安装依赖包
|
|
1
|
+
# huijia-viewfile
|
|
26
2
|
|
|
27
|
-
|
|
28
|
-
| :---: | :---: | :---: |
|
|
29
|
-
| docx-preview | 0.3.5 | Word 文档预览 |
|
|
30
|
-
| exceljs | 4.4.0 | Excel 文件解析 |
|
|
31
|
-
| pdfjs-dist | 5.1.91 | PDF 文档预览 |
|
|
32
|
-
| html2canvas | 1.4.1 | HTML 转图像 |
|
|
33
|
-
| tinycolor2 | 1.6.0 | 颜色处理 |
|
|
34
|
-
| x-data-spreadsheet | 1.1.9 | Excel 表格渲染 |
|
|
35
|
-
| lodash-es | 4.17.21 | JavaScript 工具库 |
|
|
36
|
-
| element-plus | 2.9.8 | el-image 显示图片 |
|
|
3
|
+
一个基于 Vue 3 的多格式文件预览组件，支持文档、表格、演示文稿、图片与纯文本/代码的在线预览。
|
|
37
4
|
|
|
5
|
+
## 安装
|
|
38
6
|
|
|
39
7
|
```bash
|
|
40
|
-
npm
|
|
8
|
+
npm i huijia-viewfile
|
|
41
9
|
```
|
|
42
10
|
|
|
11
|
+
或
|
|
12
|
+
|
|
43
13
|
```bash
|
|
44
|
-
|
|
14
|
+
pnpm add huijia-viewfile
|
|
45
15
|
```
|
|
46
16
|
|
|
17
|
+
或
|
|
18
|
+
|
|
47
19
|
```bash
|
|
48
|
-
|
|
20
|
+
yarn add huijia-viewfile
|
|
49
21
|
```
|
|
50
22
|
|
|
51
|
-
|
|
23
|
+
要求：Vue 3（peerDependency）。
|
|
52
24
|
|
|
53
|
-
|
|
54
|
-
<template>
|
|
55
|
-
<view-file
|
|
56
|
-
:file="fileObject"
|
|
57
|
-
/>
|
|
58
|
-
</template>
|
|
25
|
+
## 快速开始（全局注册）
|
|
59
26
|
|
|
60
|
-
|
|
61
|
-
import { ref } from 'vue'
|
|
62
|
-
import ViewFile from "@/components/view_file/index.vue"
|
|
27
|
+
在入口文件（如 `main.ts`）中安装插件，并引入样式：
|
|
63
28
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
29
|
+
```ts
|
|
30
|
+
import { createApp } from "vue"
|
|
31
|
+
import App from "./App.vue"
|
|
32
|
+
|
|
33
|
+
import ViewFilePlugin from "huijia-viewfile"
|
|
34
|
+
import "huijia-viewfile/style.css"
|
|
35
|
+
|
|
36
|
+
createApp(App).use(ViewFilePlugin).mount("#app")
|
|
70
37
|
```
|
|
71
38
|
|
|
72
|
-
|
|
73
|
-
Props
|
|
39
|
+
在页面中直接使用：
|
|
74
40
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
41
|
+
```vue
|
|
42
|
+
<template>
|
|
43
|
+
<view-file :file="fileObject" />
|
|
44
|
+
</template>
|
|
78
45
|
|
|
46
|
+
<script setup lang="ts">
|
|
47
|
+
import { ref } from "vue"
|
|
79
48
|
|
|
80
|
-
|
|
49
|
+
const fileObject = ref({
|
|
50
|
+
filename: "示例文件.pdf",
|
|
51
|
+
type: "pdf",
|
|
52
|
+
fileBuffer: null as ArrayBuffer | null,
|
|
53
|
+
})
|
|
54
|
+
</script>
|
|
55
|
+
```
|
|
81
56
|
|
|
82
|
-
|
|
83
|
-
| :---: | :---: | :---: | :---: |
|
|
84
|
-
| filename | String | 文件名称 | 是 |
|
|
85
|
-
| type | String | 文件类型（扩展名，如docx、xlsx等） | 是 |
|
|
86
|
-
| fileBuffer | ArrayBuffer | 文件内容的二进制数据 | 是 |
|
|
57
|
+
## Props
|
|
87
58
|
|
|
59
|
+
### file
|
|
88
60
|
|
|
89
|
-
|
|
90
|
-
ViewFile 组件支持以下文件类型的在线预览：
|
|
61
|
+
`file` 为一个对象，核心字段如下：
|
|
91
62
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
63
|
+
| 字段 | 类型 | 必填 | 说明 |
|
|
64
|
+
| --- | --- | --- | --- |
|
|
65
|
+
| filename | string | 建议 | 文件名（用于展示与辅助推断类型） |
|
|
66
|
+
| type | string | 是 | 文件扩展名（不带点），如 `pdf` / `docx` / `xlsx` |
|
|
67
|
+
| fileBuffer | ArrayBuffer \| null | 是 | 文件二进制内容（ArrayBuffer） |
|
|
68
|
+
| size | number | 否 | 文件大小（仅用于兜底 UI 展示） |
|
|
69
|
+
| name | string | 否 | 兜底文件名（仅用于兜底 UI 展示） |
|
|
95
70
|
|
|
96
|
-
|
|
97
|
-
+ Excel表格 ：xlsx
|
|
71
|
+
## 支持的文件类型
|
|
98
72
|
|
|
99
|
-
|
|
100
|
-
|
|
73
|
+
- 文档：`docx`、`pdf`
|
|
74
|
+
- 表格：`xlsx`
|
|
75
|
+
- 演示：`pptx`
|
|
76
|
+
- 图片：`gif`、`jpg`、`jpeg`、`bmp`、`tiff`、`tif`、`png`、`svg`
|
|
77
|
+
- 文本/代码：`txt`、`json`、`js`、`css`、`java`、`py`、`html`、`jsx`、`ts`、`tsx`、`xml`、`md`、`log`
|
|
101
78
|
|
|
102
|
-
|
|
103
|
-
支持多种图片格式：
|
|
79
|
+
不支持的类型会展示“该类型文件不支持在线预览”的兜底视图。
|
|
104
80
|
|
|
105
|
-
|
|
106
|
-
+ jpg/jpeg
|
|
107
|
-
+ bmp
|
|
108
|
-
+ tiff/tif
|
|
109
|
-
+ png
|
|
110
|
-
+ svg
|
|
81
|
+
## 读取文件并预览
|
|
111
82
|
|
|
112
|
-
|
|
113
|
-
支持多种文本和代码文件：
|
|
83
|
+
### 读取本地文件
|
|
114
84
|
|
|
115
|
-
|
|
116
|
-
+ json（JSON数据）
|
|
117
|
-
+ js（JavaScript）
|
|
118
|
-
+ css（样式表）
|
|
119
|
-
+ java（Java代码）
|
|
120
|
-
+ py（Python代码）
|
|
121
|
-
+ html（HTML文档）
|
|
122
|
-
+ jsx（React JSX）
|
|
123
|
-
+ ts/tsx（TypeScript）
|
|
124
|
-
+ xml（XML文档）
|
|
125
|
-
+ md（Markdown）
|
|
126
|
-
+ log（日志文件）
|
|
85
|
+
组件导出了读取工具函数，推荐直接从包名导入：
|
|
127
86
|
|
|
128
|
-
<h2 id="wc5fk">5. 示例代码</h2>
|
|
129
|
-
<h3 id="XRxq1">5.1 从文件对象创建预览</h3>
|
|
130
87
|
```vue
|
|
131
88
|
<template>
|
|
132
|
-
<
|
|
133
|
-
|
|
134
|
-
<view-file
|
|
135
|
-
:file="fileObject"
|
|
136
|
-
/>
|
|
137
|
-
</div>
|
|
89
|
+
<input type="file" @change="onChange" />
|
|
90
|
+
<view-file :file="fileObject" />
|
|
138
91
|
</template>
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
import {
|
|
92
|
+
|
|
93
|
+
<script setup lang="ts">
|
|
94
|
+
import { ref } from "vue"
|
|
95
|
+
import { readBuffer } from "huijia-viewfile"
|
|
142
96
|
|
|
143
97
|
const fileObject = ref({
|
|
144
98
|
filename: "",
|
|
145
99
|
type: "",
|
|
146
|
-
fileBuffer: null
|
|
100
|
+
fileBuffer: null as ArrayBuffer | null,
|
|
147
101
|
})
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
const
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
102
|
+
|
|
103
|
+
function onChange(e: Event) {
|
|
104
|
+
const input = e.target as HTMLInputElement
|
|
105
|
+
const f = input.files?.[0]
|
|
106
|
+
if (!f) return
|
|
107
|
+
|
|
108
|
+
readBuffer(f)
|
|
109
|
+
.then((buffer) => {
|
|
110
|
+
const ext = (f.name.split(".").pop() || "").toLowerCase()
|
|
111
|
+
fileObject.value = {
|
|
112
|
+
filename: f.name,
|
|
113
|
+
type: ext,
|
|
157
114
|
fileBuffer: buffer,
|
|
158
115
|
}
|
|
159
|
-
}
|
|
160
|
-
|
|
161
|
-
|
|
116
|
+
})
|
|
117
|
+
.catch((err) => {
|
|
118
|
+
console.error("读取文件失败:", err)
|
|
119
|
+
})
|
|
162
120
|
}
|
|
163
121
|
</script>
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### 从 URL 获取文件并预览
|
|
164
125
|
|
|
126
|
+
```ts
|
|
127
|
+
function fetchArrayBuffer(url: string) {
|
|
128
|
+
return fetch(url)
|
|
129
|
+
.then((res) => {
|
|
130
|
+
if (!res.ok) throw new Error(`HTTP ${res.status}`)
|
|
131
|
+
return res.arrayBuffer()
|
|
132
|
+
})
|
|
133
|
+
}
|
|
165
134
|
```
|
|
166
135
|
|
|
167
|
-
|
|
168
|
-
假设请求返回数据格式response.data
|
|
136
|
+
拿到 `ArrayBuffer` 后，填充到 `fileObject.fileBuffer` 即可。
|
|
169
137
|
|
|
170
|
-
|
|
171
|
-
| :---: | :---: | :---: |
|
|
172
|
-
| filename | String | 文件名称 |
|
|
173
|
-
| file | Blob | 文件内容数据 |
|
|
138
|
+
## 插槽（图片自定义渲染）
|
|
174
139
|
|
|
140
|
+
当文件类型为图片时，提供 `image` 具名插槽，可用于自定义展示与预览交互。
|
|
175
141
|
|
|
176
|
-
|
|
177
|
-
<template>
|
|
178
|
-
<view-file
|
|
179
|
-
:file="fileObject"
|
|
180
|
-
/>
|
|
181
|
-
</template>
|
|
182
|
-
<script setup>
|
|
183
|
-
import { ref, onMounted } from 'vue'
|
|
184
|
-
import { useRoute } from 'vue-router'
|
|
185
|
-
import ViewFile from "@/components/view_file/index.vue"
|
|
186
|
-
import { readBuffer } from "@/components/view_file/util"
|
|
187
|
-
import axios from 'axios'
|
|
188
|
-
|
|
189
|
-
const route = useRoute()
|
|
190
|
-
const fileObject = ref({
|
|
191
|
-
filename: "",
|
|
192
|
-
type: "",
|
|
193
|
-
fileBuffer: null
|
|
194
|
-
})
|
|
142
|
+
插槽参数：
|
|
195
143
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
fileObject.value.filename = name
|
|
202
|
-
fileObject.value.type = name.split('.').pop().toLowerCase()
|
|
203
|
-
const arrayBuffer = await readBuffer(response.data.file)
|
|
204
|
-
fileObject.value.fileBuffer = arrayBuffer
|
|
205
|
-
} catch (error) {
|
|
206
|
-
console.error('文件获取失败', error)
|
|
207
|
-
}
|
|
208
|
-
}
|
|
144
|
+
- `src`：当前图片 src
|
|
145
|
+
- `srcList`：图片列表（当前实现为单图，保留扩展能力）
|
|
146
|
+
- `index`：当前预览索引
|
|
147
|
+
- `file`：原始 `file` 对象
|
|
148
|
+
- `preview`：预览控制对象 `{ visible, open, close, next, prev }`
|
|
209
149
|
|
|
210
|
-
|
|
211
|
-
// 从路由参数获取文件ID
|
|
212
|
-
const fileId = route.params.fileId
|
|
213
|
-
if (fileId) {
|
|
214
|
-
fetchFile(fileId)
|
|
215
|
-
}
|
|
216
|
-
})
|
|
217
|
-
</script>
|
|
150
|
+
示例：
|
|
218
151
|
|
|
152
|
+
```vue
|
|
153
|
+
<view-file :file="fileObject">
|
|
154
|
+
<template #image="{ src, preview }">
|
|
155
|
+
<img :src="src" style="max-width: 100%; max-height: 100%" @click="preview.open(0)" />
|
|
156
|
+
</template>
|
|
157
|
+
</view-file>
|
|
219
158
|
```
|
|
220
159
|
|
|
221
|
-
|
|
222
|
-
1. 确保提供正确的文件类型（扩展名），组件根据扩展名选择渲染器
|
|
223
|
-
2. 文件内容必须是 ArrayBuffer 格式
|
|
224
|
-
3. 大文件可能会影响性能，特别是复杂的Excel或PDF文件
|
|
225
|
-
4. 对于不支持的文件类型，组件会显示提示信息而不是尝试渲染
|
|
226
|
-
5. 组件内部已处理异常，但建议在外部添加错误处理逻辑
|
|
160
|
+
## 常见问题
|
|
227
161
|
|
|
162
|
+
1. `fileBuffer` 必须是 `ArrayBuffer`，不要直接传 `Blob` / `File`。
|
|
163
|
+
2. 传入的 `type` 建议使用真实扩展名（不带 `.`），组件会据此选择渲染器。
|
|
164
|
+
3. 预览远端文件时注意 CORS，必要时通过后端代理获取。
|