handy-uploader 2.0.3 → 3.0.0
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 +186 -300
- package/dist/components/handyUploader.vue.d.ts +3 -3
- package/dist/composables/deprecation.d.ts +2 -0
- package/dist/composables/useErrorHandler.d.ts +4 -0
- package/dist/composables/useFileUpload.d.ts +5 -0
- package/dist/core/attachments.d.ts +91 -0
- package/dist/core/fileUtils.d.ts +56 -0
- package/dist/core/index.d.ts +3 -0
- package/dist/core/videoThumbnail.d.ts +32 -0
- package/dist/handy-uploader.cjs +1 -0
- package/dist/handy-uploader.css +1 -1
- package/dist/handy-uploader.mjs +1110 -0
- package/dist/language-CYpPw-mk.mjs +551 -0
- package/dist/language-fvWXvWRx.js +1 -0
- package/dist/lib/index.d.ts +8 -19
- package/dist/lib/language.d.ts +3 -0
- package/dist/lib/shared.d.ts +5 -0
- package/dist/lib/vuetify.d.ts +15 -0
- package/dist/types/index.d.ts +4 -0
- package/dist/utils/fileUtils.d.ts +1 -56
- package/dist/vue/components/HandyDialog.vue.d.ts +31 -0
- package/dist/vue/components/HandyDropzone.vue.d.ts +38 -0
- package/dist/vue/components/HandyFileIcon.vue.d.ts +9 -0
- package/dist/vue/components/HandyFileList.vue.d.ts +65 -0
- package/dist/vue/components/HandyIcon.vue.d.ts +10 -0
- package/dist/vue/components/HandyUploader.vue.d.ts +137 -0
- package/dist/vue/index.d.ts +9 -0
- package/dist/vue/types.d.ts +5 -0
- package/dist/vue/useUploader.d.ts +46 -0
- package/dist/vuetify.cjs +1 -0
- package/dist/vuetify.mjs +1870 -0
- package/package.json +31 -7
- package/dist/handy-uploader.es.js +0 -2308
- package/dist/handy-uploader.umd.js +0 -1
package/README.md
CHANGED
|
@@ -7,34 +7,25 @@
|
|
|
7
7
|
|
|
8
8
|
## 🚀 [Live Demo](https://illustrious-griffin-257b43.netlify.app)
|
|
9
9
|
|
|
10
|
-
A
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
- **
|
|
22
|
-
- **
|
|
23
|
-
- **
|
|
24
|
-
- **
|
|
25
|
-
- **
|
|
26
|
-
- **
|
|
27
|
-
- **
|
|
28
|
-
|
|
29
|
-
### 🎨 **Multiple Upload Styles**
|
|
30
|
-
- **ThumbnailUploader**: Grid-based layout with file previews
|
|
31
|
-
- **TableUploader**: Table-based layout for detailed file information
|
|
32
|
-
- **SimpleUploader**: Minimalist drag-and-drop interface
|
|
33
|
-
|
|
34
|
-
### 🌍 **Internationalization**
|
|
35
|
-
- **8 languages**: English, Chinese, Spanish, French, German, Japanese, Korean, Arabic
|
|
36
|
-
- RTL support for Arabic
|
|
37
|
-
- Easy language switching
|
|
10
|
+
A Vue 3 file uploader with **automatic video thumbnails**, **image compression**, three layouts (thumbnail, simple, table), per-file names, descriptions and tags, and translations for 5 languages.
|
|
11
|
+
|
|
12
|
+
It comes in two flavours with **the same props and events**:
|
|
13
|
+
|
|
14
|
+
| Import | Needs | Styling |
|
|
15
|
+
| --- | --- | --- |
|
|
16
|
+
| `handy-uploader` | Vue 3 only | Plain CSS, works with any CSS framework (Tailwind, Bootstrap, your own) |
|
|
17
|
+
| `handy-uploader/vuetify` | Vue 3 + Vuetify 3 | Vuetify components |
|
|
18
|
+
|
|
19
|
+
## ✨ Features
|
|
20
|
+
|
|
21
|
+
- **Video thumbnails:** a frame is captured automatically for MP4, WebM, MOV and other formats the browser can play.
|
|
22
|
+
- **Image compression:** optional; JPEG, PNG and WebP are re-encoded as JPEG, and the smaller result is kept.
|
|
23
|
+
- **Three views:** `thumbnail` (preview cards), `simple` (compact cards) and `table`.
|
|
24
|
+
- **File details:** rename files, and add descriptions and tags before or after upload.
|
|
25
|
+
- **Validation:** file size, file count and accepted types, including for drag-and-dropped files.
|
|
26
|
+
- **Permissions:** turn insert, edit and delete on or off.
|
|
27
|
+
- **Languages:** English, Persian, French, Chinese and Arabic, with right-to-left layout for Persian and Arabic. You can also add your own translations.
|
|
28
|
+
- **TypeScript:** full type declarations.
|
|
38
29
|
|
|
39
30
|
## 📦 Installation
|
|
40
31
|
|
|
@@ -42,362 +33,257 @@ A comprehensive Vue 3 file uploader component library with advanced features inc
|
|
|
42
33
|
npm install handy-uploader
|
|
43
34
|
```
|
|
44
35
|
|
|
45
|
-
|
|
46
|
-
yarn add handy-uploader
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
pnpm add handy-uploader
|
|
51
|
-
```
|
|
36
|
+
For the Vuetify flavour, also install `vuetify@^3` (and `@mdi/font` for its icons).
|
|
52
37
|
|
|
53
38
|
## 🚀 Quick Start
|
|
54
39
|
|
|
55
|
-
###
|
|
56
|
-
|
|
57
|
-
Make sure you have the required peer dependencies:
|
|
58
|
-
|
|
59
|
-
```bash
|
|
60
|
-
npm install vue@^3.0.0 vuetify@^3.0.0
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
### 2. Import and Use
|
|
40
|
+
### Without Vuetify (any CSS framework)
|
|
64
41
|
|
|
65
42
|
```vue
|
|
66
|
-
<template>
|
|
67
|
-
<div>
|
|
68
|
-
<!-- Thumbnail Uploader with Video Support -->
|
|
69
|
-
<ThumbnailUploader
|
|
70
|
-
:max-file-size="10485760"
|
|
71
|
-
:max-file-count="5"
|
|
72
|
-
:accepted-file-types="['image/*', 'video/*']"
|
|
73
|
-
:language="'en'"
|
|
74
|
-
@files-selected="handleFilesSelected"
|
|
75
|
-
/>
|
|
76
|
-
</div>
|
|
77
|
-
</template>
|
|
78
|
-
|
|
79
43
|
<script setup lang="ts">
|
|
80
|
-
import {
|
|
81
|
-
import type
|
|
44
|
+
import { ref } from 'vue'
|
|
45
|
+
import { HandyUploader, type DocumentAttachment } from 'handy-uploader'
|
|
46
|
+
import 'handy-uploader/style.css'
|
|
82
47
|
|
|
83
|
-
const
|
|
84
|
-
console.log('Selected files:', files)
|
|
85
|
-
// Each file includes base64 data and video thumbnails are auto-generated
|
|
86
|
-
}
|
|
48
|
+
const files = ref<DocumentAttachment[]>([])
|
|
87
49
|
</script>
|
|
50
|
+
|
|
51
|
+
<template>
|
|
52
|
+
<HandyUploader
|
|
53
|
+
v-model:document-attachment="files"
|
|
54
|
+
file-uploader-type="thumbnail"
|
|
55
|
+
file-accept="image/*,video/*,.pdf"
|
|
56
|
+
:max-file-size="10 * 1024 * 1024"
|
|
57
|
+
:max-file-count="10"
|
|
58
|
+
change-file-name
|
|
59
|
+
add-file-description
|
|
60
|
+
add-file-tag
|
|
61
|
+
:tags="['invoice', 'contract', 'photo']"
|
|
62
|
+
/>
|
|
63
|
+
</template>
|
|
88
64
|
```
|
|
89
65
|
|
|
90
|
-
###
|
|
66
|
+
### With Vuetify
|
|
91
67
|
|
|
92
|
-
```
|
|
68
|
+
```ts
|
|
93
69
|
// main.ts
|
|
94
70
|
import { createApp } from 'vue'
|
|
95
71
|
import { createVuetify } from 'vuetify'
|
|
96
72
|
import 'vuetify/styles'
|
|
97
73
|
import '@mdi/font/css/materialdesignicons.css'
|
|
74
|
+
import App from './App.vue'
|
|
98
75
|
|
|
99
|
-
|
|
100
|
-
const app = createApp(App)
|
|
101
|
-
|
|
102
|
-
app.use(vuetify)
|
|
103
|
-
app.mount('#app')
|
|
76
|
+
createApp(App).use(createVuetify()).mount('#app')
|
|
104
77
|
```
|
|
105
78
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
79
|
+
```vue
|
|
80
|
+
<script setup lang="ts">
|
|
81
|
+
import { ref } from 'vue'
|
|
82
|
+
import { HandyUploader } from 'handy-uploader/vuetify'
|
|
83
|
+
import type { DocumentAttachment } from 'handy-uploader/vuetify'
|
|
109
84
|
|
|
110
|
-
|
|
85
|
+
const files = ref<DocumentAttachment[]>([])
|
|
86
|
+
</script>
|
|
111
87
|
|
|
112
|
-
```vue
|
|
113
88
|
<template>
|
|
114
|
-
<
|
|
115
|
-
:max-file-size="52428800"
|
|
116
|
-
:max-file-count="10"
|
|
117
|
-
:accepted-file-types="['image/*', 'video/*', 'application/pdf']"
|
|
118
|
-
:language="'en'"
|
|
119
|
-
:theme="'light'"
|
|
120
|
-
@files-selected="onFilesSelected"
|
|
121
|
-
@file-removed="onFileRemoved"
|
|
122
|
-
@error="onError"
|
|
123
|
-
/>
|
|
89
|
+
<HandyUploader v-model:document-attachment="files" file-uploader-type="table" />
|
|
124
90
|
</template>
|
|
125
|
-
|
|
126
|
-
<script setup>
|
|
127
|
-
import { ThumbnailUploader } from 'handy-uploader'
|
|
128
|
-
|
|
129
|
-
const onFilesSelected = (files) => {
|
|
130
|
-
// Video files will have thumbnails automatically generated
|
|
131
|
-
files.forEach(file => {
|
|
132
|
-
if (file.type === 'video') {
|
|
133
|
-
console.log('Video thumbnail:', file.thumbnail) // Base64 thumbnail
|
|
134
|
-
}
|
|
135
|
-
})
|
|
136
|
-
}
|
|
137
|
-
</script>
|
|
138
91
|
```
|
|
139
92
|
|
|
140
|
-
|
|
93
|
+
Switching between the two is a one-line change, because the props are the same.
|
|
141
94
|
|
|
142
|
-
|
|
95
|
+
## 🧭 Framework Support
|
|
143
96
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
:language="'en'"
|
|
150
|
-
@files-selected="handleFiles"
|
|
151
|
-
/>
|
|
152
|
-
</template>
|
|
153
|
-
```
|
|
97
|
+
| Framework | Status |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| **Vue 3** (any CSS) | ✅ `handy-uploader` |
|
|
100
|
+
| **Vue 3 + Vuetify 3** | ✅ `handy-uploader/vuetify` |
|
|
101
|
+
| **React, Svelte, Angular, plain HTML** | 🛠️ Planned as a Web Component (`<handy-uploader>`) in a 3.x release |
|
|
154
102
|
|
|
155
|
-
|
|
103
|
+
The upload logic (reading files, validation, compression, video thumbnails) lives in a framework-free core that is already exported; see [Building your own UI](#-building-your-own-ui).
|
|
156
104
|
|
|
157
|
-
|
|
105
|
+
## 📚 Documentation
|
|
158
106
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
</template>
|
|
167
|
-
```
|
|
107
|
+
The [live demo](https://illustrious-griffin-257b43.netlify.app) is a Storybook with guides and an interactive example of every feature:
|
|
108
|
+
|
|
109
|
+
- [Getting Started](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-getting-started--docs)
|
|
110
|
+
- [Feature Tour](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-feature-tour--docs): every feature, with a link to try it
|
|
111
|
+
- [Styling & Theming](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-styling-theming--docs)
|
|
112
|
+
- [Build Your Own UI](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-build-your-own-ui--docs)
|
|
113
|
+
- [Upgrading from 2.x](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-upgrading-from-2-x--docs)
|
|
168
114
|
|
|
169
115
|
## ⚙️ API Reference
|
|
170
116
|
|
|
171
|
-
###
|
|
117
|
+
### `HandyUploader` props
|
|
172
118
|
|
|
173
119
|
| Prop | Type | Default | Description |
|
|
174
|
-
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
120
|
+
| --- | --- | --- | --- |
|
|
121
|
+
| `documentAttachment` | `DocumentAttachment[]` | `[]` | The files. Use with `v-model:document-attachment`, or pass an array. The component updates the array you pass in, as the Vuetify version always has. |
|
|
122
|
+
| `fileUploaderType` | `'thumbnail' \| 'simple' \| 'table'` | `'thumbnail'` | Layout. |
|
|
123
|
+
| `maxFileSize` | `number` | `5242880` | Maximum size per file, **in bytes** (5 MB). |
|
|
124
|
+
| `maxFileCount` | `number` | `10` | Maximum number of files. |
|
|
125
|
+
| `fileAccept` | `string` | `''` | Accepted types, in the same format as the HTML `accept` attribute, e.g. `"image/*,.pdf"`. Empty means everything. |
|
|
126
|
+
| `imageCompressor` | `boolean` | `false` | Compress JPEG, PNG and WebP images (re-encoded as JPEG, kept only when smaller). |
|
|
127
|
+
| `imageCompressLevel` | `number` | `0.8` | JPEG quality, from 0 to 1. |
|
|
128
|
+
| `thumb` | `boolean` | `true` | Show image previews and video thumbnails. When off, file-type icons are shown instead. |
|
|
129
|
+
| `cols` | `number` | `3` | Thumbnail view: card width out of 12 columns (3 = four per row, 4 = three per row). |
|
|
130
|
+
| `cardType` | `'default' \| 'outlined' \| 'raised' \| 'shaped' \| 'tile'` | `'default'` | Card style. |
|
|
131
|
+
| `badgeCounter` | `boolean` | `true` | Show the file count on the Insert button. |
|
|
132
|
+
| `btnColor` | `string` | `'info'` | Button colour: a Vuetify colour name (`primary`, `info`, `success`, …) or, without Vuetify, any CSS colour. |
|
|
133
|
+
| `changeFileName` | `boolean` | `false` | Let users rename files. |
|
|
134
|
+
| `addFileDescription` | `boolean` | `false` | Let users add a description. |
|
|
135
|
+
| `addFileTag` | `boolean` | `false` | Let users pick tags from `tags`. |
|
|
136
|
+
| `tags` | `string[]` | `[]` | Tags users can choose from. |
|
|
137
|
+
| `insertPermission` | `boolean` | `true` | Show the Insert button. |
|
|
138
|
+
| `editPermission` | `boolean` | `true` | Show the edit button. |
|
|
139
|
+
| `deletePermission` | `boolean` | `true` | Show the delete button. Deleting always asks for confirmation. |
|
|
140
|
+
| `tableThumbColumn` | `boolean` | `true` | Table view: show the preview column. |
|
|
141
|
+
| `tableFixedHeader` | `boolean` | `true` | Table view: keep the header visible while scrolling. |
|
|
142
|
+
| `tableHeight` | `number` | `400` | Table view: height in pixels when the header is fixed. |
|
|
143
|
+
| `lang` | `string` | `'en'` | Interface language: `en`, `fa`, `fr`, `ch`, `ar`, or a key you add with `customLang`. |
|
|
144
|
+
| `customLang` | `LanguageCollection \| null` | `null` | Your own translations (see [Internationalization](#-internationalization)). |
|
|
145
|
+
| `rtlSupport` | `boolean` | `false` | Right-to-left layout. Without Vuetify it is also turned on automatically for `fa` and `ar`. With Vuetify, use Vuetify's own RTL setting (`createVuetify({ locale: { rtl: … } })`). |
|
|
180
146
|
|
|
181
147
|
### Events
|
|
182
148
|
|
|
183
149
|
| Event | Payload | Description |
|
|
184
|
-
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
150
|
+
| --- | --- | --- |
|
|
151
|
+
| `updateDocumentAttachment` | `DocumentAttachment[]` | The file list changed (added, edited or removed). |
|
|
152
|
+
| `update:documentAttachment` | `DocumentAttachment[]` | Same as above, for `v-model:document-attachment`. *(Not in the Vuetify flavour.)* |
|
|
153
|
+
| `add` | `DocumentAttachment[]` | Files were added. *(Not in the Vuetify flavour.)* |
|
|
154
|
+
| `remove` | `(attachment, index)` | A file was removed. *(Not in the Vuetify flavour.)* |
|
|
155
|
+
| `error` | `AttachmentError[]` | Files were rejected (`fileType`, `maxFileSize`, `maxFileCount`, `invalidFormat`). *(Not in the Vuetify flavour.)* |
|
|
188
156
|
|
|
189
|
-
|
|
157
|
+
When a prop changes, the component also emits a matching `update…` event (e.g. `updateCardType`, `updateLang`), as the 2.x versions did.
|
|
190
158
|
|
|
191
|
-
|
|
192
|
-
interface FileData {
|
|
193
|
-
id: string
|
|
194
|
-
name: string
|
|
195
|
-
size: number
|
|
196
|
-
type: string
|
|
197
|
-
format: string
|
|
198
|
-
base64?: string
|
|
199
|
-
thumbnail?: string // Auto-generated for videos
|
|
200
|
-
lastModified: number
|
|
201
|
-
}
|
|
202
|
-
```
|
|
159
|
+
### Slots (without Vuetify)
|
|
203
160
|
|
|
204
|
-
|
|
161
|
+
| Slot | Props | Use |
|
|
162
|
+
| --- | --- | --- |
|
|
163
|
+
| `item` | `{ attachment, index, remove }` | Replace a whole card. |
|
|
164
|
+
| `actions` | `{ attachment, index }` | Add your own buttons to each card or row. |
|
|
165
|
+
| `empty` | – | Content to show when there are no files. |
|
|
205
166
|
|
|
206
|
-
###
|
|
167
|
+
### Data types
|
|
207
168
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
// Thumbnails are generated automatically
|
|
212
|
-
const videoFile = {
|
|
213
|
-
name: 'video.mp4',
|
|
214
|
-
type: 'video',
|
|
215
|
-
thumbnail: 'data:image/jpeg;base64,/9j/4AAQ...' // Auto-generated
|
|
169
|
+
```ts
|
|
170
|
+
interface DocumentAttachment {
|
|
171
|
+
file: FileData
|
|
216
172
|
}
|
|
217
|
-
```
|
|
218
173
|
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
type: 'document', // Auto-detected
|
|
228
|
-
icon: 'mdi-file-pdf-box', // Auto-assigned
|
|
229
|
-
color: 'red' // Auto-assigned
|
|
174
|
+
interface FileData {
|
|
175
|
+
name: string // with extension, e.g. "report.pdf"
|
|
176
|
+
format: string // extension, e.g. "pdf"; "jpg" after compression
|
|
177
|
+
base64: string // file contents, without the "data:…;base64," prefix
|
|
178
|
+
size: number // bytes
|
|
179
|
+
tags: string[]
|
|
180
|
+
description: string | null
|
|
181
|
+
showDetailState: boolean
|
|
230
182
|
}
|
|
231
183
|
```
|
|
232
184
|
|
|
233
|
-
|
|
185
|
+
## 🎨 Styling (without Vuetify)
|
|
234
186
|
|
|
235
|
-
|
|
187
|
+
Import the default theme once:
|
|
236
188
|
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
:compress-images="true"
|
|
240
|
-
:compression-quality="0.8"
|
|
241
|
-
:max-width="1920"
|
|
242
|
-
:max-height="1080"
|
|
243
|
-
/>
|
|
189
|
+
```ts
|
|
190
|
+
import 'handy-uploader/style.css'
|
|
244
191
|
```
|
|
245
192
|
|
|
246
|
-
|
|
193
|
+
The easiest way to re-theme is with CSS variables, on the component or any parent:
|
|
247
194
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
'ja', // Japanese
|
|
258
|
-
'ko', // Korean
|
|
259
|
-
'ar' // Arabic (RTL)
|
|
260
|
-
]
|
|
195
|
+
```css
|
|
196
|
+
.hu-uploader {
|
|
197
|
+
--hu-primary: #7c3aed; /* links, focus, drop area */
|
|
198
|
+
--hu-button-bg: #7c3aed; /* Insert / Add buttons (or use btnColor) */
|
|
199
|
+
--hu-chip: #7c3aed; /* size chips */
|
|
200
|
+
--hu-radius: 16px; /* card corners */
|
|
201
|
+
--hu-media-height: 160px; /* preview height in the thumbnail view */
|
|
202
|
+
--hu-font: inherit;
|
|
203
|
+
}
|
|
261
204
|
```
|
|
262
205
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
- **Vue**: ^3.0.0
|
|
267
|
-
- **Vuetify**: ^3.0.0
|
|
268
|
-
|
|
269
|
-
### Browser Support
|
|
270
|
-
- Chrome 88+
|
|
271
|
-
- Firefox 85+
|
|
272
|
-
- Safari 14+
|
|
273
|
-
- Edge 88+
|
|
206
|
+
- Add the `hu-dark` class (on the component or a parent) for the dark preset.
|
|
207
|
+
- Built-in styles are single `hu-*` class selectors. They survive global resets such as Tailwind's preflight, and are easy to override with your own classes.
|
|
208
|
+
- Or skip `style.css` entirely and style the `hu-*` classes yourself.
|
|
274
209
|
|
|
275
|
-
|
|
276
|
-
- **Gzipped**: ~45KB
|
|
277
|
-
- **Minified**: ~120KB
|
|
210
|
+
The default theme uses `color-mix()` and `:has()` (Chrome/Edge 111+, Firefox 121+, Safari 16.4+). In older browsers it still works, with simpler focus and badge styling.
|
|
278
211
|
|
|
279
|
-
##
|
|
212
|
+
## 🧱 Building your own UI
|
|
280
213
|
|
|
281
|
-
|
|
214
|
+
Everything `HandyUploader` uses is exported:
|
|
282
215
|
|
|
283
|
-
|
|
216
|
+
- **`useUploader(filesRef, options)`:** the upload logic with no markup. It provides `add`, `stage` + `commit` (read files, let users edit them, then add), `remove`, `update`, `clear`, `errors` and `isProcessing`.
|
|
217
|
+
- **Components:** `HandyDropzone`, `HandyFileList`, `HandyDialog` and `HandyFileIcon`.
|
|
218
|
+
- **Framework-agnostic helpers:** `readFiles`, `prepareAttachments`, `compressDataUrl`, `generateVideoThumbnail`, `matchesAccept`, `formatBytes` and more. These have no Vue dependency.
|
|
284
219
|
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
}
|
|
296
|
-
}
|
|
220
|
+
```ts
|
|
221
|
+
import { ref } from 'vue'
|
|
222
|
+
import { useUploader, type DocumentAttachment } from 'handy-uploader'
|
|
223
|
+
|
|
224
|
+
const files = ref<DocumentAttachment[]>([])
|
|
225
|
+
const { add, remove, errors, isProcessing } = useUploader(files, {
|
|
226
|
+
maxFileSize: 5 * 1024 * 1024,
|
|
227
|
+
maxFileCount: 10,
|
|
228
|
+
accept: 'image/*',
|
|
229
|
+
imageCompressor: true
|
|
297
230
|
})
|
|
231
|
+
// <input type="file" multiple @change="add($event.target.files)">
|
|
298
232
|
```
|
|
299
233
|
|
|
300
|
-
|
|
234
|
+
## 🌍 Internationalization
|
|
235
|
+
|
|
236
|
+
Built-in languages: `en` (English), `fa` (Persian, RTL), `fr` (French), `ch` (Chinese), `ar` (Arabic, RTL).
|
|
301
237
|
|
|
302
|
-
|
|
303
|
-
<style scoped>
|
|
304
|
-
.handy-uploader {
|
|
305
|
-
--uploader-border-radius: 12px;
|
|
306
|
-
--uploader-primary-color: #1976D2;
|
|
307
|
-
--uploader-background: #f5f5f5;
|
|
308
|
-
}
|
|
309
|
-
</style>
|
|
310
|
-
```
|
|
238
|
+
To change texts or add a language, pass `customLang`. Start from the built-in strings:
|
|
311
239
|
|
|
312
|
-
|
|
240
|
+
```ts
|
|
241
|
+
import { languageData } from 'handy-uploader'
|
|
313
242
|
|
|
314
|
-
|
|
243
|
+
const customLang = {
|
|
244
|
+
...languageData,
|
|
245
|
+
de: { ...languageData.en, insertFile: 'Datei hinzufügen', add: 'Hinzufügen' /* … */ }
|
|
246
|
+
}
|
|
247
|
+
```
|
|
315
248
|
|
|
316
249
|
```vue
|
|
317
|
-
<
|
|
318
|
-
|
|
319
|
-
<h2>File Upload with Video Thumbnails</h2>
|
|
320
|
-
|
|
321
|
-
<ThumbnailUploader
|
|
322
|
-
:max-file-size="52428800"
|
|
323
|
-
:max-file-count="10"
|
|
324
|
-
:accepted-file-types="['image/*', 'video/*', 'application/pdf']"
|
|
325
|
-
:language="currentLanguage"
|
|
326
|
-
:theme="isDark ? 'dark' : 'light'"
|
|
327
|
-
:compress-images="true"
|
|
328
|
-
:compression-quality="0.8"
|
|
329
|
-
@files-selected="handleFilesSelected"
|
|
330
|
-
@file-removed="handleFileRemoved"
|
|
331
|
-
@error="handleError"
|
|
332
|
-
/>
|
|
333
|
-
|
|
334
|
-
<!-- Display selected files -->
|
|
335
|
-
<div v-if="selectedFiles.length" class="mt-4">
|
|
336
|
-
<h3>Selected Files:</h3>
|
|
337
|
-
<div v-for="file in selectedFiles" :key="file.id" class="file-item">
|
|
338
|
-
<img v-if="file.thumbnail" :src="file.thumbnail" alt="Thumbnail" width="100" />
|
|
339
|
-
<span>{{ file.name }} ({{ formatFileSize(file.size) }})</span>
|
|
340
|
-
</div>
|
|
341
|
-
</div>
|
|
342
|
-
</div>
|
|
343
|
-
</template>
|
|
250
|
+
<HandyUploader :custom-lang="customLang" lang="de" />
|
|
251
|
+
```
|
|
344
252
|
|
|
345
|
-
|
|
346
|
-
import { ref } from 'vue'
|
|
347
|
-
import { ThumbnailUploader, type FileData } from 'handy-uploader'
|
|
253
|
+
## 🛠️ Requirements
|
|
348
254
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
255
|
+
- **Vue** ^3.0.0
|
|
256
|
+
- **Vuetify** ^3.0.0: optional, only for `handy-uploader/vuetify`
|
|
257
|
+
- Modern browsers (Chrome, Edge, Firefox, Safari). Video thumbnails need a browser that can play the video format.
|
|
352
258
|
|
|
353
|
-
|
|
354
|
-
selectedFiles.value = files
|
|
355
|
-
console.log('Files with thumbnails:', files)
|
|
356
|
-
}
|
|
259
|
+
Bundle size (minified, gzipped): `handy-uploader` about 10 KB JS + 3 KB CSS, plus about 6 KB of translations; `handy-uploader/vuetify` about 14 KB (Vue and Vuetify not included).
|
|
357
260
|
|
|
358
|
-
|
|
359
|
-
console.log('File removed:', file.name)
|
|
360
|
-
}
|
|
261
|
+
## ⬆️ Upgrading from 2.x
|
|
361
262
|
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
263
|
+
- **Vuetify users:** change the import to `handy-uploader/vuetify`. Nothing else changes.
|
|
264
|
+
- **`maxFileSize` is now enforced in bytes**, as documented. 2.x compared it in kilobytes, so limits were about 1000× looser. If you tuned the value to the old behaviour, divide it by 1000.
|
|
265
|
+
- **`file.size` is always a number of bytes.** It used to be a string.
|
|
266
|
+
- **The package ships ES modules and CommonJS.** The UMD build was removed.
|
|
365
267
|
|
|
366
|
-
|
|
367
|
-
return bytes > 1024 * 1024
|
|
368
|
-
? `${(bytes / 1024 / 1024).toFixed(2)} MB`
|
|
369
|
-
: `${(bytes / 1024).toFixed(2)} KB`
|
|
370
|
-
}
|
|
371
|
-
</script>
|
|
372
|
-
```
|
|
268
|
+
See [CHANGELOG.md](CHANGELOG.md) for details.
|
|
373
269
|
|
|
374
270
|
## 🤝 Contributing
|
|
375
271
|
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
381
|
-
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
382
|
-
5. Open a Pull Request
|
|
272
|
+
1. Fork the repository and create a branch.
|
|
273
|
+
2. `npm install`, then `npm run storybook` to work on the components.
|
|
274
|
+
3. Run `npm test`, `npm run type-check` and `npm run lint` before opening a pull request.
|
|
275
|
+
4. Add a changeset (`npx changeset`) describing your change.
|
|
383
276
|
|
|
384
277
|
## 📄 License
|
|
385
278
|
|
|
386
|
-
|
|
279
|
+
MIT. See [LICENSE](LICENSE).
|
|
387
280
|
|
|
388
281
|
## 🔗 Links
|
|
389
282
|
|
|
390
|
-
- [GitHub
|
|
391
|
-
- [npm
|
|
392
|
-
- [
|
|
393
|
-
- [Issues](https://github.com/alijahanpak/
|
|
394
|
-
|
|
395
|
-
## 📊 Stats
|
|
283
|
+
- [GitHub repository](https://github.com/alijahanpak/handy-uploader)
|
|
284
|
+
- [npm package](https://www.npmjs.com/package/handy-uploader)
|
|
285
|
+
- [Live demo (Storybook)](https://illustrious-griffin-257b43.netlify.app)
|
|
286
|
+
- [Issues](https://github.com/alijahanpak/handy-uploader/issues)
|
|
396
287
|
|
|
397
288
|

|
|
398
289
|

|
|
399
|
-

|
|
400
|
-
|
|
401
|
-
---
|
|
402
|
-
|
|
403
|
-
**Made with ❤️ for the Vue.js community**
|
|
@@ -31,6 +31,7 @@ interface Props {
|
|
|
31
31
|
tile?: boolean;
|
|
32
32
|
}
|
|
33
33
|
declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
|
|
34
|
+
updateDocumentAttachment: (...args: any[]) => void;
|
|
34
35
|
updateCardType: (...args: any[]) => void;
|
|
35
36
|
updateBadgeCounter: (...args: any[]) => void;
|
|
36
37
|
updateMaxFileCount: (...args: any[]) => void;
|
|
@@ -45,8 +46,8 @@ declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {},
|
|
|
45
46
|
updateTableFixedHeader: (...args: any[]) => void;
|
|
46
47
|
updateTableHeight: (...args: any[]) => void;
|
|
47
48
|
updateLang: (...args: any[]) => void;
|
|
48
|
-
updateDocumentAttachment: (...args: any[]) => void;
|
|
49
49
|
}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
|
|
50
|
+
onUpdateDocumentAttachment?: (...args: any[]) => any;
|
|
50
51
|
onUpdateCardType?: (...args: any[]) => any;
|
|
51
52
|
onUpdateBadgeCounter?: (...args: any[]) => any;
|
|
52
53
|
onUpdateMaxFileCount?: (...args: any[]) => any;
|
|
@@ -61,7 +62,6 @@ declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {},
|
|
|
61
62
|
onUpdateTableFixedHeader?: (...args: any[]) => any;
|
|
62
63
|
onUpdateTableHeight?: (...args: any[]) => any;
|
|
63
64
|
onUpdateLang?: (...args: any[]) => any;
|
|
64
|
-
onUpdateDocumentAttachment?: (...args: any[]) => any;
|
|
65
65
|
}>, {
|
|
66
66
|
maxFileSize: number;
|
|
67
67
|
fileUploaderType: FileUploaderType;
|
|
@@ -75,7 +75,7 @@ declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {},
|
|
|
75
75
|
changeFileName: boolean;
|
|
76
76
|
addFileDescription: boolean;
|
|
77
77
|
addFileTag: boolean;
|
|
78
|
-
customLang: LanguageCollection
|
|
78
|
+
customLang: LanguageCollection;
|
|
79
79
|
insertPermission: boolean;
|
|
80
80
|
lang: LanguageCode;
|
|
81
81
|
thumb: boolean;
|
|
@@ -14,6 +14,10 @@ export interface ErrorHandlerOptions {
|
|
|
14
14
|
autoRemoveTimeout?: number;
|
|
15
15
|
logToConsole?: boolean;
|
|
16
16
|
}
|
|
17
|
+
/**
|
|
18
|
+
* @deprecated Use the `errors` returned by `useUploader` (or the `error` event of
|
|
19
|
+
* HandyUploader) instead. `useErrorHandler` will be removed in the next major version.
|
|
20
|
+
*/
|
|
17
21
|
export declare function useErrorHandler(options?: ErrorHandlerOptions): {
|
|
18
22
|
errors: unknown;
|
|
19
23
|
isLoading: unknown;
|
|
@@ -7,6 +7,11 @@ export interface UseFileUploadOptions {
|
|
|
7
7
|
imageCompressLevel?: number;
|
|
8
8
|
fileAccept?: string;
|
|
9
9
|
}
|
|
10
|
+
/**
|
|
11
|
+
* @deprecated Use `useUploader` from 'handy-uploader' instead: it validates before reading,
|
|
12
|
+
* supports drag and drop, image compression and editing files before they are added.
|
|
13
|
+
* `useFileUpload` will be removed in the next major version.
|
|
14
|
+
*/
|
|
10
15
|
export declare function useFileUpload(documentAttachment: Ref<DocumentAttachment[]>, options?: UseFileUploadOptions): {
|
|
11
16
|
isUploading: Readonly<Ref<boolean, boolean>>;
|
|
12
17
|
snackbar: Readonly<Ref<SnackbarConfig | {
|