@fibrae/semi-ui-svelte 0.9.1 → 0.10.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.
Files changed (165) hide show
  1. package/README.md +8 -4
  2. package/README.zh-CN.md +8 -4
  3. package/dist/components/anchor/interface.d.ts +14 -0
  4. package/dist/components/audio-player/interface.d.ts +5 -0
  5. package/dist/components/auto-complete/interface.d.ts +29 -0
  6. package/dist/components/avatar/interface.d.ts +24 -0
  7. package/dist/components/backtop/interface.d.ts +2 -0
  8. package/dist/components/badge/interface.d.ts +7 -0
  9. package/dist/components/banner/interface.d.ts +7 -0
  10. package/dist/components/breadcrumb/interface.d.ts +10 -0
  11. package/dist/components/button/interface.d.ts +18 -0
  12. package/dist/components/calendar/interface.d.ts +16 -0
  13. package/dist/components/card/interface.d.ts +18 -0
  14. package/dist/components/carousel/interface.d.ts +16 -0
  15. package/dist/components/cascader/interface.d.ts +57 -0
  16. package/dist/components/checkbox/interface.d.ts +19 -0
  17. package/dist/components/code-highlight/interface.d.ts +3 -0
  18. package/dist/components/collapse/interface.d.ts +16 -0
  19. package/dist/components/collapsible/interface.d.ts +10 -0
  20. package/dist/components/color-picker/interface.d.ts +10 -0
  21. package/dist/components/config-provider/interface.d.ts +7 -0
  22. package/dist/components/cropper/interface.d.ts +11 -0
  23. package/dist/components/date-picker/interface.d.ts +47 -0
  24. package/dist/components/descriptions/interface.d.ts +6 -0
  25. package/dist/components/divider/interface.d.ts +4 -0
  26. package/dist/components/dropdown/interface.d.ts +8 -0
  27. package/dist/components/empty/interface.d.ts +7 -0
  28. package/dist/components/feedback/interface.d.ts +16 -0
  29. package/dist/components/float-button/interface.d.ts +14 -0
  30. package/dist/components/form/interface.d.ts +47 -0
  31. package/dist/components/grid/interface.d.ts +13 -0
  32. package/dist/components/highlight/interface.d.ts +7 -0
  33. package/dist/components/hot-keys/interface.d.ts +3 -0
  34. package/dist/components/image/interface.d.ts +59 -0
  35. package/dist/components/input/interface.d.ts +67 -0
  36. package/dist/components/input-number/interface.d.ts +24 -0
  37. package/dist/components/json-viewer/interface.d.ts +7 -0
  38. package/dist/components/layout/interface.d.ts +3 -0
  39. package/dist/components/list/interface.d.ts +18 -0
  40. package/dist/components/locale/interface.d.ts +4 -0
  41. package/dist/components/lottie/interface.d.ts +2 -0
  42. package/dist/components/markdown-render/interface.d.ts +5 -0
  43. package/dist/components/modal/interface.d.ts +29 -0
  44. package/dist/components/navigation/interface.d.ts +47 -0
  45. package/dist/components/overflow-list/interface.d.ts +11 -0
  46. package/dist/components/pagination/interface.d.ts +12 -0
  47. package/dist/components/pincode/interface.d.ts +8 -0
  48. package/dist/components/popconfirm/interface.d.ts +12 -0
  49. package/dist/components/popover/interface.d.ts +30 -0
  50. package/dist/components/progress/interface.d.ts +13 -0
  51. package/dist/components/radio/interface.d.ts +22 -0
  52. package/dist/components/rating/interface.d.ts +12 -0
  53. package/dist/components/resizable/interface.d.ts +30 -0
  54. package/dist/components/scroll-list/interface.d.ts +6 -0
  55. package/dist/components/select/interface.d.ts +63 -0
  56. package/dist/components/side-sheet/interface.d.ts +19 -0
  57. package/dist/components/skeleton/interface.d.ts +7 -0
  58. package/dist/components/slider/interface.d.ts +23 -0
  59. package/dist/components/space/interface.d.ts +4 -0
  60. package/dist/components/spin/interface.d.ts +7 -0
  61. package/dist/components/steps/interface.d.ts +9 -0
  62. package/dist/components/switch/interface.d.ts +7 -0
  63. package/dist/components/table/interface.d.ts +48 -0
  64. package/dist/components/tabs/interface.d.ts +29 -0
  65. package/dist/components/tag/interface.d.ts +22 -0
  66. package/dist/components/tag-input/interface.d.ts +29 -0
  67. package/dist/components/time-picker/interface.d.ts +31 -0
  68. package/dist/components/timeline/interface.d.ts +5 -0
  69. package/dist/components/tooltip/interface.d.ts +20 -0
  70. package/dist/components/transfer/interface.d.ts +18 -0
  71. package/dist/components/tree/interface.d.ts +45 -0
  72. package/dist/components/tree-select/interface.d.ts +55 -0
  73. package/dist/components/typography/interface.d.ts +33 -0
  74. package/dist/components/upload/interface.d.ts +64 -0
  75. package/dist/components/user-guide/interface.d.ts +15 -0
  76. package/dist/components/video-player/interface.d.ts +22 -0
  77. package/docs/advanced/dark-mode.md +288 -0
  78. package/docs/basic/button.md +605 -0
  79. package/docs/basic/divider.md +103 -0
  80. package/docs/basic/float-button.md +246 -0
  81. package/docs/basic/grid.md +427 -0
  82. package/docs/basic/layout.md +459 -0
  83. package/docs/basic/resizable.md +584 -0
  84. package/docs/basic/space.md +163 -0
  85. package/docs/basic/tokens.md +425 -0
  86. package/docs/basic/typography.md +615 -0
  87. package/docs/changes-from-semi.md +105 -0
  88. package/docs/ecosystem/tailwind.md +210 -0
  89. package/docs/experience/accessibility.md +82 -0
  90. package/docs/experience/content-guidelines.md +819 -0
  91. package/docs/experience/internationalization.md +7 -0
  92. package/docs/feedback/banner.md +198 -0
  93. package/docs/feedback/feedback.md +294 -0
  94. package/docs/feedback/notification.md +401 -0
  95. package/docs/feedback/popconfirm.md +243 -0
  96. package/docs/feedback/progress.md +389 -0
  97. package/docs/feedback/skeleton.md +388 -0
  98. package/docs/feedback/spin.md +172 -0
  99. package/docs/feedback/toast.md +393 -0
  100. package/docs/input/auto-complete.md +399 -0
  101. package/docs/input/cascader.md +1558 -0
  102. package/docs/input/checkbox.md +408 -0
  103. package/docs/input/color-picker.md +175 -0
  104. package/docs/input/date-picker.md +942 -0
  105. package/docs/input/form.md +2550 -0
  106. package/docs/input/input-number.md +451 -0
  107. package/docs/input/input.md +640 -0
  108. package/docs/input/pincode.md +191 -0
  109. package/docs/input/radio.md +337 -0
  110. package/docs/input/rating.md +214 -0
  111. package/docs/input/select.md +1230 -0
  112. package/docs/input/slider.md +347 -0
  113. package/docs/input/switch.md +206 -0
  114. package/docs/input/tag-input.md +465 -0
  115. package/docs/input/time-picker.md +358 -0
  116. package/docs/input/transfer.md +1061 -0
  117. package/docs/input/tree-select.md +1300 -0
  118. package/docs/input/upload.md +1811 -0
  119. package/docs/llms.txt +147 -0
  120. package/docs/navigation/anchor.md +377 -0
  121. package/docs/navigation/backtop.md +100 -0
  122. package/docs/navigation/breadcrumb.md +284 -0
  123. package/docs/navigation/navigation.md +851 -0
  124. package/docs/navigation/pagination.md +217 -0
  125. package/docs/navigation/steps.md +315 -0
  126. package/docs/navigation/tabs.md +754 -0
  127. package/docs/navigation/tree.md +1956 -0
  128. package/docs/other/config-provider.md +599 -0
  129. package/docs/other/locale.md +353 -0
  130. package/docs/plus/audio-player.md +155 -0
  131. package/docs/plus/code-highlight.md +150 -0
  132. package/docs/plus/drag-move.md +214 -0
  133. package/docs/plus/hot-keys.md +174 -0
  134. package/docs/plus/json-viewer.md +392 -0
  135. package/docs/plus/lottie.md +176 -0
  136. package/docs/plus/markdown-render.md +240 -0
  137. package/docs/plus/video-player.md +325 -0
  138. package/docs/show/avatar.md +475 -0
  139. package/docs/show/badge.md +276 -0
  140. package/docs/show/calendar.md +352 -0
  141. package/docs/show/card.md +485 -0
  142. package/docs/show/carousel.md +592 -0
  143. package/docs/show/collapse.md +289 -0
  144. package/docs/show/collapsible.md +216 -0
  145. package/docs/show/cropper.md +285 -0
  146. package/docs/show/descriptions.md +325 -0
  147. package/docs/show/dropdown.md +466 -0
  148. package/docs/show/empty.md +225 -0
  149. package/docs/show/highlight.md +144 -0
  150. package/docs/show/image.md +433 -0
  151. package/docs/show/list.md +927 -0
  152. package/docs/show/modal.md +517 -0
  153. package/docs/show/overflow-list.md +272 -0
  154. package/docs/show/popover.md +534 -0
  155. package/docs/show/scroll-list.md +156 -0
  156. package/docs/show/side-sheet.md +274 -0
  157. package/docs/show/table.md +5437 -0
  158. package/docs/show/tag.md +428 -0
  159. package/docs/show/timeline.md +277 -0
  160. package/docs/show/tooltip.md +442 -0
  161. package/docs/show/user-guide.md +419 -0
  162. package/docs/start/getting-started.md +234 -0
  163. package/docs/start/introduction.md +57 -0
  164. package/docs/start/overview.md +21 -0
  165. package/package.json +5 -4
@@ -0,0 +1,1811 @@
1
+ # Upload
2
+
3
+ > File selection upload
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/input/upload/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Upload } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic usage
18
+
19
+ The most basic usage is to place a Button in the trigger area; clicking it opens the file selection box, and the upload starts automatically after the selection is completed
20
+
21
+ ```svelte
22
+ <script lang="ts">
23
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
24
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
25
+ import { mockUpload } from '#/lib/mock-upload';
26
+ </script>
27
+
28
+ <Upload action="/upload" customRequest={mockUpload}>
29
+ <Button theme="light">
30
+ {#snippet icon()}<IconUpload />{/snippet}
31
+ 点击上传
32
+ </Button>
33
+ </Upload>
34
+ ```
35
+
36
+ ### File name too long ellipsis
37
+
38
+ Customize the file name tooltip using the `showTooltip` property
39
+
40
+ When the type is `boolean`, control whether to show the tooltip
41
+
42
+ ```svelte
43
+ <script lang="ts">
44
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
45
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
46
+ import { mockUpload } from '#/lib/mock-upload';
47
+ </script>
48
+
49
+ <Upload action="/upload" customRequest={mockUpload} showTooltip={false}>
50
+ <Button theme="light">
51
+ {#snippet icon()}<IconUpload />{/snippet}
52
+ 点击上传
53
+ </Button>
54
+ </Upload>
55
+ ```
56
+
57
+ Customize the popup through the `ellipsisTooltip` snippet, which receives `content` (the full file name) and `trigger` (the file name element, placed in the popup with `{@render trigger()}`); an object `showTooltip` configures the tooltip type and the props passed to it.
58
+
59
+ ```svelte
60
+ <script lang="ts">
61
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
62
+ import { Button, Tooltip, Upload } from '@fibrae/semi-ui-svelte';
63
+ import { mockUpload } from '#/lib/mock-upload';
64
+ </script>
65
+
66
+ <Upload action="/upload" customRequest={mockUpload} showTooltip>
67
+ {#snippet ellipsisTooltip({ content: text, trigger })}
68
+ <Tooltip position="bottom">
69
+ {#snippet content()}{text}{/snippet}
70
+ {@render trigger()}
71
+ </Tooltip>
72
+ {/snippet}
73
+ <Button theme="light">
74
+ {#snippet icon()}<IconUpload />{/snippet}
75
+ 点击上传
76
+ </Button>
77
+ </Upload>
78
+ ```
79
+
80
+ ### Add prompt text
81
+
82
+ Set a custom prompt text through the `prompt` slot. Set the slot position by `promptPosition`, optional `left`, `right`, `bottom`, the default is `right`
83
+
84
+ ```svelte
85
+ <script lang="ts">
86
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
87
+ import { Button, Upload, type PromptPositionType } from '@fibrae/semi-ui-svelte';
88
+ import { mockUpload } from '#/lib/mock-upload';
89
+
90
+ const action = '/upload';
91
+ const marginStyle: Partial<Record<PromptPositionType, string>> = {
92
+ left: 'margin-inline-end: 10px',
93
+ right: 'margin-inline-start: 10px',
94
+ };
95
+ const promptStyle = (pos: PromptPositionType) => `display: flex; align-items: center; color: var(--semi-color-text-2); height: 32px; ${marginStyle[pos] ?? ''}`;
96
+ const positions: PromptPositionType[] = ['right', 'left', 'bottom'];
97
+ </script>
98
+
99
+ {#each positions as pos, index (pos)}
100
+ {#if index}
101
+ <div style="margin-block-end: 12px; margin-block-start: 12px; border-block-end: 1px solid var(--semi-color-border)"></div>
102
+ {/if}
103
+ <Upload {action} customRequest={mockUpload} promptPosition={pos}>
104
+ {#snippet prompt()}
105
+ <div style={promptStyle(pos)}>请上传资格认证材料</div>
106
+ {/snippet}
107
+ <Button theme="light">
108
+ {#snippet icon()}<IconUpload />{/snippet}
109
+ 点击上传
110
+ </Button>
111
+ </Upload>
112
+ {/each}
113
+ ```
114
+
115
+ When listType is picture, the reference object at promptPosition is the whole picture wall list
116
+
117
+ ```svelte
118
+ <script lang="ts">
119
+ import { IconPlus } from '@fibrae/semi-icons-svelte';
120
+ import { Upload, type FileItem, type PromptPositionType } from '@fibrae/semi-ui-svelte';
121
+ import { mockUpload } from '#/lib/mock-upload';
122
+
123
+ const action = '/upload';
124
+ const marginStyle: Partial<Record<PromptPositionType, string>> = {
125
+ right: 'margin-inline-start: 10px',
126
+ };
127
+ const promptStyle = (pos: PromptPositionType) => `display: flex; align-items: center; color: var(--semi-color-text-2); height: 100%; ${marginStyle[pos] ?? ''}`;
128
+ const defaultFileList: FileItem[] = [
129
+ {
130
+ uid: '1',
131
+ name: 'dy.jpeg',
132
+ status: 'success',
133
+ size: '130kb',
134
+ url: '/assets/placeholder/avatar-a.svg',
135
+ },
136
+ {
137
+ uid: '5',
138
+ name: 'resso.jpeg',
139
+ status: 'wait',
140
+ percent: 50,
141
+ size: '222kb',
142
+ url: '/assets/placeholder/avatar-b.svg',
143
+ },
144
+ ];
145
+ const positions: PromptPositionType[] = ['right', 'bottom'];
146
+ </script>
147
+
148
+ {#each positions as pos, index (pos)}
149
+ {#if index}
150
+ <div style="margin-block-end: 12px; margin-block-start: 12px; border-block-end: 1px solid var(--semi-color-border)"></div>
151
+ {/if}
152
+ <Upload {action} customRequest={mockUpload} fileList={defaultFileList} listType="picture" promptPosition={pos}>
153
+ {#snippet prompt()}
154
+ <div style={promptStyle(pos)}>请上传认证材料</div>
155
+ {/snippet}
156
+ <IconPlus aria-label="上传图片" size="extra-large" />
157
+ </Upload>
158
+ {/each}
159
+ ```
160
+
161
+ ### Click on the avatar to trigger upload
162
+
163
+ ```svelte
164
+ <script lang="ts">
165
+ import { IconCamera } from '@fibrae/semi-icons-svelte';
166
+ import { Avatar, Toast, Upload } from '@fibrae/semi-ui-svelte';
167
+ import { mockUpload } from '#/lib/mock-upload';
168
+
169
+ const api = '/upload';
170
+ const imageOnly = 'image/*';
171
+
172
+ let url = $state('/assets/placeholder/avatar-a.svg');
173
+
174
+ const onSuccess = () => {
175
+ Toast.success('头像更新成功');
176
+ url = '/assets/ttmoment.jpeg';
177
+ };
178
+
179
+ const maskStyle = 'background-color: var(--semi-color-overlay-bg); height: 100%; width: 100%; display: flex; align-items: center; justify-content: center; color: var(--semi-color-white)';
180
+ </script>
181
+
182
+ <Upload accept={imageOnly} action={api} class="avatar-upload" customRequest={mockUpload} onError={() => Toast.error('上传失败')} {onSuccess} showUploadList={false}>
183
+ <!-- the avatar is the whole content of the upload button, so its alt names the button -->
184
+ <Avatar alt="上传头像" src={url} style="margin: 4px">
185
+ {#snippet hoverMask()}
186
+ <div style={maskStyle}>
187
+ <IconCamera />
188
+ </div>
189
+ {/snippet}
190
+ </Avatar>
191
+ </Upload>
192
+ ```
193
+
194
+ ```css
195
+ .avatar-upload .semi-upload-add {
196
+ border-radius: 50%; // Make sure that only the circle is clicked on the hot zone
197
+ }
198
+ ```
199
+
200
+ ### Custom upload attributes
201
+
202
+ Custom upload attributes can be added by setting `data`, `headers`
203
+
204
+ ```svelte
205
+ <script lang="ts">
206
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
207
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
208
+ import { mockUpload } from '#/lib/mock-upload';
209
+
210
+ const action = '/upload';
211
+ // A data function is evaluated per upload, so time is the upload moment
212
+ const data = () => ({
213
+ role: 'ies',
214
+ time: new Date().getTime(),
215
+ });
216
+ const headers = {
217
+ 'x-tt-semi': 'semi-upload',
218
+ };
219
+ </script>
220
+
221
+ <Upload {action} customRequest={mockUpload} {data} {headers}>
222
+ <Button theme="light">
223
+ {#snippet icon()}<IconUpload />{/snippet}
224
+ 点击上传
225
+ </Button>
226
+ </Upload>
227
+ ```
228
+
229
+ ### Upload file type
230
+
231
+ The type of files uploaded can be restricted through the `accept` attribute (the native `html` attribute of `input`).
232
+
233
+ `accept` supports the following two types of strings:
234
+
235
+ - A collection of file extensions (recommended), such as .jpg, .png, etc.;
236
+ - MIME types collection of file types, please refer to [MDN document](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types)
237
+
238
+ For example, only allowing users to upload PNG and PDF files, `accept` can be written like this: `accept ='.pdf,.png'` or `accept ='application/pdf,image/png'` (the MIME type of PNG and PDF Connect through `,`).
239
+
240
+ > **Notes**
241
+ >
242
+ > Upload will intercept files that do not meet the accept format internally. When files that do not meet the format requirements are intercepted, onAcceptInvalid will be called;
243
+ > accept uses the suffix to avoid the incompatibility between file.type and MIME due to different browsers or operating systems.&#x20;
244
+
245
+ ```svelte
246
+ <script lang="ts">
247
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
248
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
249
+ import { mockUpload } from '#/lib/mock-upload';
250
+
251
+ const action = '/upload';
252
+ const imageOnly = 'image/*';
253
+ const videoOnly = 'video/*';
254
+ const fileLimit = '.pdf,.png,.jpeg';
255
+ </script>
256
+
257
+ <Upload accept={imageOnly} {action} customRequest={mockUpload} style="margin-bottom: 12px">
258
+ <Button theme="light">
259
+ {#snippet icon()}<IconUpload />{/snippet}
260
+ 上传图片
261
+ </Button>
262
+ </Upload>
263
+ <Upload accept={videoOnly} {action} customRequest={mockUpload} style="margin-bottom: 12px">
264
+ <Button theme="light">
265
+ {#snippet icon()}<IconUpload />{/snippet}
266
+ 上传视频
267
+ </Button>
268
+ </Upload>
269
+ <Upload accept={fileLimit} {action} customRequest={mockUpload}>
270
+ <Button theme="light">
271
+ {#snippet icon()}<IconUpload />{/snippet}
272
+ 上传 PDF, PNG, JPEG
273
+ </Button>
274
+ </Upload>
275
+ ```
276
+
277
+ ### Upload folder
278
+
279
+ By passing in `directory` as `true`, all files in the folder can be uploaded
280
+
281
+ ```svelte
282
+ <script lang="ts">
283
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
284
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
285
+ import { mockUpload } from '#/lib/mock-upload';
286
+ </script>
287
+
288
+ <Upload action="/upload" customRequest={mockUpload} directory>
289
+ <Button theme="light">
290
+ {#snippet icon()}<IconUpload />{/snippet}
291
+ 上传文件夹
292
+ </Button>
293
+ </Upload>
294
+ ```
295
+
296
+ ### Select multiple files at once
297
+
298
+ You can select multiple files to upload at the same time by setting the `multiple` attribute.
299
+
300
+ ```svelte
301
+ <script lang="ts">
302
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
303
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
304
+ import { mockUpload } from '#/lib/mock-upload';
305
+ </script>
306
+
307
+ <Upload action="/upload" customRequest={mockUpload} multiple>
308
+ <Button theme="light">
309
+ {#snippet icon()}<IconUpload />{/snippet}
310
+ 点击上传
311
+ </Button>
312
+ </Upload>
313
+ ```
314
+
315
+ ### Limit the total number of files
316
+
317
+ You can limit the maximum number of files that can be uploaded by setting the `limit` property. When `limit` is 1, always replace the current one with the latest upload, and `onExceed` will not be called
318
+
319
+ ```svelte
320
+ <script lang="ts">
321
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
322
+ import { Button, Upload, type UploadOnChangeProps } from '@fibrae/semi-ui-svelte';
323
+ import { mockUpload } from '#/lib/mock-upload';
324
+
325
+ const limit = 1;
326
+ const onChange = (props: UploadOnChangeProps) => {
327
+ console.log(props.fileList);
328
+ };
329
+ </script>
330
+
331
+ <Upload action="/upload" customRequest={mockUpload} {limit} {onChange}>
332
+ <Button theme="light">
333
+ {#snippet icon()}<IconUpload />{/snippet}
334
+ 点击上传(最多{limit}项)
335
+ </Button>
336
+ </Upload>
337
+ ```
338
+
339
+ When the limit is reached, disable the trigger control rather than Upload, so uploaded files can still be removed.
340
+
341
+ ```svelte
342
+ <script lang="ts">
343
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
344
+ import { Button, Toast, Upload, type UploadOnChangeProps } from '@fibrae/semi-ui-svelte';
345
+ import { mockUpload } from '#/lib/mock-upload';
346
+
347
+ const limit = 2;
348
+ // Only the trigger button is disabled; Upload itself stays enabled so files can still be removed.
349
+ let disabled = $state(false);
350
+ const onChange = (props: UploadOnChangeProps) => {
351
+ disabled = props.fileList.length === limit;
352
+ };
353
+ </script>
354
+
355
+ <Upload action="/upload" customRequest={mockUpload} {limit} {onChange} onExceed={() => Toast.warning(`最多只允许上传${limit}个文件`)}>
356
+ <Button {disabled} theme="light">
357
+ {#snippet icon()}<IconUpload />{/snippet}
358
+ 点击上传(最多{limit}项)
359
+ </Button>
360
+ </Upload>
361
+ ```
362
+
363
+ In the photo wall mode, when the number of uploaded files is equal to the limit, the upload entry will be automatically hidden
364
+
365
+ ```svelte
366
+ <script lang="ts">
367
+ import { IconPlus } from '@fibrae/semi-icons-svelte';
368
+ import { Toast, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
369
+ import { mockUpload } from '#/lib/mock-upload';
370
+
371
+ const defaultFileList: FileItem[] = [
372
+ {
373
+ uid: '1',
374
+ name: 'dyBag.png',
375
+ status: 'success',
376
+ size: '130KB',
377
+ preview: true,
378
+ url: '/assets/root-web-sites/edit-bag.jpeg',
379
+ },
380
+ {
381
+ uid: '2',
382
+ name: 'dyBag2.jpeg',
383
+ status: 'success',
384
+ size: '222KB',
385
+ preview: true,
386
+ fileInstance: new File([new ArrayBuffer(2048)], 'dyBag2.jpeg', { type: 'image/png' }),
387
+ url: '/assets/root-web-sites/edit-bag.jpeg',
388
+ },
389
+ ];
390
+ </script>
391
+
392
+ <Upload accept="image/*" action="/upload" customRequest={mockUpload} fileList={defaultFileList} limit={2} listType="picture" onExceed={() => Toast.warning('最多只允许上传2个文件')}>
393
+ <IconPlus aria-label="上传图片" size="extra-large" />
394
+ </Upload>
395
+ ```
396
+
397
+ ### Limit upload file size
398
+
399
+ The upload file size limit can be customized through the `maxSize` and `minSize` properties, and you can pass `onSizeError` to be notified when the limit is exceeded.
400
+
401
+ ```svelte
402
+ <script lang="ts">
403
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
404
+ import { Button, Toast, Upload } from '@fibrae/semi-ui-svelte';
405
+ import { mockUpload } from '#/lib/mock-upload';
406
+ </script>
407
+
408
+ <Upload action="/upload" customRequest={mockUpload} maxSize={1024} minSize={200} onSizeError={(file) => Toast.error(`${file.name} size invalid`)}>
409
+ <Button theme="light">
410
+ {#snippet icon()}<IconUpload />{/snippet}
411
+ 点击上传(最小 200KB,最大 1MB)
412
+ </Button>
413
+ </Upload>
414
+ ```
415
+
416
+ ### Custom list operation area
417
+
418
+ When `listType` is `list`, you can customize the list operation area through the `fileOperation` snippet, which receives `UploadFileItemSlotProps`
419
+
420
+ ```svelte
421
+ <script lang="ts">
422
+ import { IconDelete, IconDownload, IconEyeOpened, IconUpload } from '@fibrae/semi-icons-svelte';
423
+ import { Button, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
424
+ import { mockUpload } from '#/lib/mock-upload';
425
+
426
+ const action = '/upload';
427
+ const defaultFileList: FileItem[] = [
428
+ {
429
+ uid: '1',
430
+ name: 'dyBag.png',
431
+ status: 'success',
432
+ size: '130KB',
433
+ preview: true,
434
+ url: '/assets/root-web-sites/edit-bag.jpeg',
435
+ },
436
+ ];
437
+ </script>
438
+
439
+ <Upload {action} customRequest={mockUpload} fileList={defaultFileList} styles={{ item: 'width: 300px' }}>
440
+ {#snippet fileOperation(fileItem)}
441
+ <div style="display: flex; column-gap: 8px; padding: 0 8px">
442
+ <Button aria-label="预览" size="small" theme="borderless" type="tertiary">
443
+ {#snippet icon()}<IconEyeOpened />{/snippet}
444
+ </Button>
445
+ <Button aria-label="下载" size="small" theme="borderless" type="tertiary">
446
+ {#snippet icon()}<IconDownload />{/snippet}
447
+ </Button>
448
+ <Button aria-label="删除" size="small" theme="borderless" type="tertiary" onclick={() => fileItem.onRemove()}>
449
+ {#snippet icon()}<IconDelete />{/snippet}
450
+ </Button>
451
+ </div>
452
+ {/snippet}
453
+ <Button theme="light">
454
+ {#snippet icon()}<IconUpload />{/snippet}
455
+ 点击上传
456
+ </Button>
457
+ </Upload>
458
+ ```
459
+
460
+ ### Custom file list title
461
+
462
+ When `listType` is `list`, you can customize the title area at the top of the file list through two snippets:
463
+
464
+ #### Replace only the title text
465
+
466
+ `fileListTitle` replaces only the title text, and the clear button retains its default style:
467
+
468
+ ```svelte
469
+ <script lang="ts">
470
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
471
+ import { Button, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
472
+ import { mockUpload } from '#/lib/mock-upload';
473
+
474
+ const action = '/upload';
475
+
476
+ const initialList = (): FileItem[] => [
477
+ {
478
+ uid: '1',
479
+ name: 'document.pdf',
480
+ status: 'success',
481
+ size: '130KB',
482
+ },
483
+ {
484
+ uid: '2',
485
+ name: 'report.xlsx',
486
+ status: 'success',
487
+ size: '222KB',
488
+ },
489
+ ];
490
+ </script>
491
+
492
+ <Upload {action} customRequest={mockUpload} fileList={initialList()} style="margin-bottom: 20px">
493
+ {#snippet fileListTitle()}已上传文件{/snippet}
494
+ <Button theme="light">
495
+ {#snippet icon()}<IconUpload />{/snippet}
496
+ 自定义标题文字
497
+ </Button>
498
+ </Upload>
499
+ <Upload {action} customRequest={mockUpload} fileList={initialList()}>
500
+ {#snippet fileListTitle()}
501
+ <span style="color: var(--semi-color-primary); font-weight: 600">📁 重要文件</span>
502
+ {/snippet}
503
+ <Button theme="light">
504
+ {#snippet icon()}<IconUpload />{/snippet}
505
+ 带样式的标题
506
+ </Button>
507
+ </Upload>
508
+ ```
509
+
510
+ #### Replace the whole title area
511
+
512
+ `fileListHeader` replaces the whole title area, including the clear button. Once the snippet is provided, the default title does not come back even when it renders nothing. The snippet receives the following parameters:
513
+
514
+ - `fileList`: Current file list
515
+ - `onClear`: Function to clear files
516
+ - `clearText`: Default text for the clear button (based on current locale)
517
+
518
+ ```svelte
519
+ <script lang="ts">
520
+ import { IconClose, IconUpload } from '@fibrae/semi-icons-svelte';
521
+ import { Button, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
522
+ import { mockUpload } from '#/lib/mock-upload';
523
+
524
+ const action = '/upload';
525
+
526
+ const defaultFileList: FileItem[] = [
527
+ {
528
+ uid: '1',
529
+ name: 'document.pdf',
530
+ status: 'success',
531
+ size: '130KB',
532
+ },
533
+ {
534
+ uid: '2',
535
+ name: 'report.xlsx',
536
+ status: 'success',
537
+ size: '222KB',
538
+ },
539
+ ];
540
+ </script>
541
+
542
+ <Upload {action} customRequest={mockUpload} fileList={defaultFileList} style="margin-bottom: 20px">
543
+ {#snippet fileListHeader(title)}
544
+ <div style="display: flex; align-items: center; justify-content: space-between; width: 100%">
545
+ <span style="color: var(--semi-color-primary)">📂 共 {title.fileList.length} 个文件</span>
546
+ <Button size="small" type="danger" onclick={title.onClear}>
547
+ {#snippet icon()}<IconClose />{/snippet}
548
+ {title.clearText}
549
+ </Button>
550
+ </div>
551
+ {/snippet}
552
+ <Button theme="light">
553
+ {#snippet icon()}<IconUpload />{/snippet}
554
+ 自定义清空按钮样式
555
+ </Button>
556
+ </Upload>
557
+ <Upload {action} customRequest={mockUpload} fileList={defaultFileList}>
558
+ {#snippet fileListHeader(title)}
559
+ <div style="display: flex; align-items: center; justify-content: space-between; width: 100%">
560
+ <span>
561
+ 已选择
562
+ <strong style="color: var(--semi-color-danger)">{title.fileList.length}</strong>
563
+ 个文件
564
+ </span>
565
+ <button style="padding: 0; border: none; background: none; font: inherit; cursor: pointer; color: var(--semi-color-link); font-size: 12px" type="button" onclick={title.onClear}>全部移除</button>
566
+ </div>
567
+ {/snippet}
568
+ <Button theme="light">
569
+ {#snippet icon()}<IconUpload />{/snippet}
570
+ 完全自定义标题区域
571
+ </Button>
572
+ </Upload>
573
+ ```
574
+
575
+ ### Custom preview logic
576
+
577
+ When `listType` is list, the preview logic can be implemented through the `previewFile` snippet. Its content replaces the thumbnail, and the default thumbnail does not come back even when the snippet renders nothing.\
578
+ For example, when you don't need thumbnail preview for image types, you can constantly render a `<IconFile />` in `previewFile`.\
579
+ If you want to enlarge and preview the image when clicked, you can use the `Image` component in `previewFile`.\
580
+ Or if you want to use an additional operation area to achieve enlarged preview when clicked, you can also combine `fileOperation` to place some custom elements such as Icon to achieve enlarged preview when clicked.
581
+
582
+ ```svelte
583
+ <script lang="ts">
584
+ import { IconFile, IconUpload } from '@fibrae/semi-icons-svelte';
585
+ import { Button, Image, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
586
+ import { mockUpload } from '#/lib/mock-upload';
587
+
588
+ const defaultFileList: FileItem[] = [
589
+ {
590
+ uid: '1',
591
+ name: 'dyBag.png',
592
+ status: 'success',
593
+ size: '130KB',
594
+ url: '/assets/root-web-sites/edit-bag.jpeg',
595
+ },
596
+ {
597
+ uid: '2',
598
+ name: 'dyBag2.png',
599
+ status: 'success',
600
+ size: '130KB',
601
+ url: '/assets/root-web-sites/edit-bag.jpeg',
602
+ },
603
+ ];
604
+ </script>
605
+
606
+ <Upload action="/upload" customRequest={mockUpload} fileList={defaultFileList}>
607
+ {#snippet previewFile({ file })}
608
+ {#if file.uid === '1'}
609
+ <IconFile size="large" />
610
+ {:else}
611
+ <Image alt="" src={file.url} />
612
+ {/if}
613
+ {/snippet}
614
+ <Button theme="light">
615
+ {#snippet icon()}<IconUpload />{/snippet}
616
+ 点击上传
617
+ </Button>
618
+ </Upload>
619
+ ```
620
+
621
+ The following is an example of combining the `fileOperation` snippet and `ImagePreview`. In this example, clicking the first Icon on the right can enlarge the image for preview.
622
+
623
+ ```svelte
624
+ <script lang="ts">
625
+ import { IconDelete, IconDownload, IconExpand, IconUpload } from '@fibrae/semi-icons-svelte';
626
+ import { Button, ImagePreview, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
627
+ import { mockUpload } from '#/lib/mock-upload';
628
+
629
+ let visible = $state(false);
630
+ const defaultFileList: FileItem[] = [
631
+ {
632
+ uid: '1',
633
+ name: 'dyBag.png',
634
+ status: 'success',
635
+ size: '130KB',
636
+ preview: true,
637
+ url: '/assets/root-web-sites/edit-bag.jpeg',
638
+ },
639
+ ];
640
+ </script>
641
+
642
+ <Upload action="/upload" customRequest={mockUpload} fileList={defaultFileList} styles={{ item: 'width: 300px' }}>
643
+ {#snippet fileOperation(fileItem)}
644
+ <div style="display: flex; column-gap: 8px; padding: 0 8px">
645
+ <Button aria-label="预览" size="small" theme="borderless" type="tertiary" onclick={() => (visible = true)}>
646
+ {#snippet icon()}<IconExpand />{/snippet}
647
+ </Button>
648
+ <Button aria-label="下载" size="small" theme="borderless" type="tertiary">
649
+ {#snippet icon()}<IconDownload />{/snippet}
650
+ </Button>
651
+ <Button aria-label="删除" size="small" theme="borderless" type="tertiary" onclick={() => fileItem.onRemove()}>
652
+ {#snippet icon()}<IconDelete />{/snippet}
653
+ </Button>
654
+ <ImagePreview bind:visible src={fileItem.file.url} />
655
+ </div>
656
+ {/snippet}
657
+ <Button theme="light">
658
+ {#snippet icon()}<IconUpload />{/snippet}
659
+ 点击上传
660
+ </Button>
661
+ </Upload>
662
+ ```
663
+
664
+ ### Default file list
665
+
666
+ The uploaded files can be displayed through `defaultFileList`. When you need to preview the thumbnail of the default file, you can set the `preview` attribute of the corresponding `item` in `defaultFileList` to `true`
667
+
668
+ > **Notice**
669
+ >
670
+ > The uid of every item in defaultFileList must be unique
671
+
672
+ ```svelte
673
+ <script lang="ts">
674
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
675
+ import { Button, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
676
+ import { mockUpload } from '#/lib/mock-upload';
677
+
678
+ const action = '/upload';
679
+
680
+ const fileList: FileItem[] = [
681
+ {
682
+ uid: '1',
683
+ name: 'dyBag.jpeg',
684
+ status: 'success',
685
+ size: '130KB',
686
+ preview: true,
687
+ url: '/assets/root-web-sites/edit-bag.jpeg',
688
+ },
689
+ {
690
+ uid: '2',
691
+ name: 'dyBag2.jpeg',
692
+ status: 'uploadFail',
693
+ size: '222KB',
694
+ preview: true,
695
+ fileInstance: new File([new ArrayBuffer(2048)], 'dyBag2.jpeg', { type: 'image/png' }),
696
+ url: '/assets/root-web-sites/edit-bag.jpeg',
697
+ },
698
+ ];
699
+ </script>
700
+
701
+ <Upload {action} customRequest={mockUpload} {fileList}>
702
+ <Button theme="light">
703
+ {#snippet icon()}<IconUpload />{/snippet}
704
+ 点击上传
705
+ </Button>
706
+ </Upload>
707
+ ```
708
+
709
+ ### Replace file
710
+
711
+ With `showReplace`, a successfully uploaded file card shows a replace button. Clicking it opens the file picker, and the chosen file replaces the original one and is uploaded again.
712
+
713
+ ```svelte
714
+ <script lang="ts">
715
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
716
+ import { Button, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
717
+ import { mockUpload } from '#/lib/mock-upload';
718
+
719
+ const action = '/upload';
720
+
721
+ const fileList: FileItem[] = [
722
+ {
723
+ uid: '1',
724
+ name: 'dyBag.jpeg',
725
+ status: 'success',
726
+ size: '130KB',
727
+ preview: true,
728
+ url: '/assets/root-web-sites/edit-bag.jpeg',
729
+ },
730
+ ];
731
+ </script>
732
+
733
+ <Upload {action} customRequest={mockUpload} {fileList} showReplace>
734
+ <Button theme="light">
735
+ {#snippet icon()}<IconUpload />{/snippet}
736
+ 点击上传
737
+ </Button>
738
+ </Upload>
739
+ ```
740
+
741
+ ### Controlled component
742
+
743
+ Bind the file list with `bind:fileList`; Upload writes it back whenever the list changes. A plain `fileList` value that is not bound is the initial list, which Upload then maintains itself. `onChange` still receives `{ fileList, currentFile }`, where `currentFile` is `null` after files are added with the `insert` method.
744
+
745
+ ```svelte
746
+ <script lang="ts">
747
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
748
+ import { Button, Upload, type FileItem, type UploadOnChangeProps } from '@fibrae/semi-ui-svelte';
749
+ import { mockUpload } from '#/lib/mock-upload';
750
+
751
+ const initList: FileItem[] = [
752
+ {
753
+ uid: '1',
754
+ name: 'dyBag.jpeg',
755
+ status: 'success',
756
+ size: '130KB',
757
+ preview: true,
758
+ url: '/assets/root-web-sites/edit-bag.jpeg',
759
+ },
760
+ {
761
+ uid: '2',
762
+ name: 'dy.jpeg',
763
+ status: 'uploading',
764
+ size: '222KB',
765
+ percent: 50,
766
+ preview: true,
767
+ fileInstance: new File([new ArrayBuffer(2048)], 'dy.jpeg', { type: 'image/jpeg' }),
768
+ url: '/assets/placeholder/avatar-a.svg',
769
+ },
770
+ ];
771
+
772
+ let list = $state(initList);
773
+
774
+ const onChange = ({ fileList, currentFile }: UploadOnChangeProps) => {
775
+ console.log('onChange');
776
+ console.log(fileList);
777
+ console.log(currentFile);
778
+ };
779
+ </script>
780
+
781
+ <Upload action="/upload" bind:fileList={list} customRequest={mockUpload} {onChange} showRetry={false}>
782
+ <Button theme="light">
783
+ {#snippet icon()}<IconUpload />{/snippet}
784
+ 点击上传
785
+ </Button>
786
+ </Upload>
787
+ ```
788
+
789
+ ### Photo Wall
790
+
791
+ Set `listType ='picture'`, users can upload pictures and display thumbnails in the list\
792
+ When the uploaded file list is set through defaultFileList or fileList, the url property of the objects in the array is read automatically to display the pictures
793
+
794
+ ```svelte
795
+ <script lang="ts">
796
+ import { IconPlus } from '@fibrae/semi-icons-svelte';
797
+ import { Upload, type FileItem } from '@fibrae/semi-ui-svelte';
798
+ import { mockUpload } from '#/lib/mock-upload';
799
+
800
+ const defaultFileList: FileItem[] = [
801
+ {
802
+ uid: '1',
803
+ name: 'dy.png',
804
+ status: 'success',
805
+ size: '130KB',
806
+ preview: true,
807
+ url: '/assets/placeholder/avatar-a.svg',
808
+ },
809
+ ];
810
+ </script>
811
+
812
+ <Upload accept="image/*" action="/upload" customRequest={mockUpload} fileList={defaultFileList} listType="picture" multiple>
813
+ <IconPlus aria-label="上传图片" size="extra-large" />
814
+ </Upload>
815
+ ```
816
+
817
+ Set `showPicInfo`, you can view the basic information of the picture
818
+
819
+ ```svelte
820
+ <script lang="ts">
821
+ import { IconPlus } from '@fibrae/semi-icons-svelte';
822
+ import { Upload, type FileItem } from '@fibrae/semi-ui-svelte';
823
+ import { mockUpload } from '#/lib/mock-upload';
824
+
825
+ const defaultFileList: FileItem[] = [
826
+ {
827
+ uid: '1',
828
+ name: 'music.png',
829
+ status: 'success',
830
+ size: '130KB',
831
+ preview: true,
832
+ url: '/assets/placeholder/avatar-b.svg',
833
+ },
834
+ {
835
+ uid: '2',
836
+ name: 'brand.png',
837
+ status: 'success',
838
+ size: '130KB',
839
+ preview: true,
840
+ url: '/assets/placeholder/avatar-b.svg',
841
+ },
842
+ ];
843
+ </script>
844
+
845
+ <Upload accept="image/*" action="/upload" customRequest={mockUpload} fileList={defaultFileList} listType="picture" multiple showPicInfo>
846
+ <IconPlus aria-label="上传图片" size="extra-large" />
847
+ </Upload>
848
+ ```
849
+
850
+ ### Photo Wall With Preview
851
+
852
+ With the Image component, through the `thumbnail` snippet, you can click on the image to enlarge the preview
853
+
854
+ ```svelte
855
+ <script lang="ts">
856
+ import { IconPlus } from '@fibrae/semi-icons-svelte';
857
+ import { Image, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
858
+ import { mockUpload } from '#/lib/mock-upload';
859
+
860
+ const action = '/upload';
861
+ const defaultFileList: FileItem[] = [
862
+ {
863
+ uid: '1',
864
+ name: 'music.png',
865
+ status: 'success',
866
+ size: '130KB',
867
+ preview: true,
868
+ url: '/assets/placeholder/avatar-b.svg',
869
+ },
870
+ ];
871
+ </script>
872
+
873
+ <Upload accept="image/*" {action} customRequest={mockUpload} fileList={defaultFileList} listType="picture" multiple>
874
+ {#snippet thumbnail({ file })}
875
+ <Image alt={file.name} src={file.url} />
876
+ {/snippet}
877
+ <IconPlus aria-label="Upload picture" size="extra-large" />
878
+ </Upload>
879
+ ```
880
+
881
+ You can customize the preview icon through the `picPreviewIcon` snippet and `onPreviewClick`, when the replacement icon `showReplace` is displayed, the preview icon will no longer be displayed. When you need to customize the preview/replacement function, you need to turn off the replacement function and use `onPreviewClick` to listen for clicks. `onPreviewClick` listens for the click event of the single image container. Passing it also makes the file cards clickable and shows a preview button
882
+
883
+ ```svelte
884
+ <script lang="ts">
885
+ import { IconEyeOpened, IconPlus } from '@fibrae/semi-icons-svelte';
886
+ import { Upload, type FileItem } from '@fibrae/semi-ui-svelte';
887
+ import { mockUpload } from '#/lib/mock-upload';
888
+
889
+ const defaultFileList: FileItem[] = [
890
+ {
891
+ uid: '1',
892
+ name: 'resso.png',
893
+ status: 'success',
894
+ size: '130KB',
895
+ preview: true,
896
+ url: '/assets/placeholder/avatar-b.svg',
897
+ },
898
+ ];
899
+
900
+ const handlePreview = (file: FileItem) => {
901
+ window.open(file.url, 'imagePreview', 'width=300,height=300');
902
+ };
903
+ </script>
904
+
905
+ <Upload accept="image/*" action="/upload" customRequest={mockUpload} fileList={defaultFileList} listType="picture" multiple onPreviewClick={handlePreview} showPicInfo>
906
+ {#snippet picPreviewIcon()}
907
+ <IconEyeOpened style="color: var(--semi-color-white); font-size: 24px" />
908
+ {/snippet}
909
+ <IconPlus aria-label="上传图片" size="extra-large" />
910
+ </Upload>
911
+ ```
912
+
913
+ ### Photo Wall Width/Height
914
+
915
+ By setting picHeight, picWidth, the width and height of picture wall elements can be uniformly set. If you also render an Image component in the `thumbnail` snippet for click-to-enlarge preview, you need to specify both the width and height of the Image component
916
+
917
+ ```svelte
918
+ <script lang="ts">
919
+ import { IconPlus } from '@fibrae/semi-icons-svelte';
920
+ import { Image, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
921
+ import { mockUpload } from '#/lib/mock-upload';
922
+
923
+ const defaultFileList: FileItem[] = [
924
+ {
925
+ uid: '1',
926
+ name: 'image-1.jpg',
927
+ status: 'success',
928
+ size: '130KB',
929
+ preview: true,
930
+ url: '/assets/root-web-sites/abstract.jpg',
931
+ },
932
+ ];
933
+ </script>
934
+
935
+ <Upload accept="image/*" action="/upload" customRequest={mockUpload} fileList={defaultFileList} listType="picture" multiple picHeight={110} picWidth={200}>
936
+ {#snippet thumbnail({ file })}
937
+ <Image alt={file.name} height={110} src={file.url} width={200} />
938
+ {/snippet}
939
+ <IconPlus aria-label="上传图片" size="extra-large" style="margin: 4px" />
940
+ 点击添加图片
941
+ </Upload>
942
+ ```
943
+
944
+ Set `hotSpotLocation` to customize the order of click hotspots, the default is at the end of the photo wall list
945
+
946
+ ```svelte
947
+ <script lang="ts">
948
+ import { IconPlus } from '@fibrae/semi-icons-svelte';
949
+ import { Radio, RadioGroup, Upload, type FileItem, type UploadProps } from '@fibrae/semi-ui-svelte';
950
+ import { mockUpload } from '#/lib/mock-upload';
951
+
952
+ const action = '/upload';
953
+ const defaultFileList: FileItem[] = [
954
+ {
955
+ uid: '1',
956
+ name: 'resso.png',
957
+ status: 'success',
958
+ size: '130KB',
959
+ preview: true,
960
+ url: '/assets/placeholder/avatar-b.svg',
961
+ },
962
+ ];
963
+ const handlePreview = (file: FileItem) => {
964
+ window.open(file.url, 'imagePreview', 'width=300,height=300');
965
+ };
966
+ let hotSpotLocation = $state<UploadProps['hotSpotLocation']>('end');
967
+ </script>
968
+
969
+ <RadioGroup aria-label="添加按钮位置" bind:value={hotSpotLocation} type="button">
970
+ <Radio value="start">start</Radio>
971
+ <Radio value="end">end</Radio>
972
+ </RadioGroup>
973
+ <hr />
974
+ <Upload accept="image/*" {action} customRequest={mockUpload} fileList={defaultFileList} {hotSpotLocation} listType="picture" multiple onPreviewClick={handlePreview} showPicInfo>
975
+ <IconPlus aria-label="上传图片" size="extra-large" />
976
+ </Upload>
977
+ ```
978
+
979
+ ### Disabled
980
+
981
+ ```svelte
982
+ <script lang="ts">
983
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
984
+ import { Button, Upload, type FileItem } from '@fibrae/semi-ui-svelte';
985
+ import { mockUpload } from '#/lib/mock-upload';
986
+
987
+ const fileList: FileItem[] = [
988
+ {
989
+ uid: '1',
990
+ name: 'first.png',
991
+ status: 'success',
992
+ size: '130KB',
993
+ preview: true,
994
+ url: '/assets/placeholder/avatar-a.svg',
995
+ },
996
+ {
997
+ uid: '2',
998
+ name: 'second.png',
999
+ status: 'validateFail',
1000
+ size: '222KB',
1001
+ preview: true,
1002
+ url: '/assets/placeholder/avatar-a.svg',
1003
+ },
1004
+ ];
1005
+ </script>
1006
+
1007
+ <Upload action="/upload" customRequest={mockUpload} disabled {fileList}>
1008
+ <Button disabled theme="light">
1009
+ {#snippet icon()}<IconUpload />{/snippet}
1010
+ 点击上传
1011
+ </Button>
1012
+ </Upload>
1013
+ ```
1014
+
1015
+ ### Manually trigger upload
1016
+
1017
+ `uploadTrigger="custom"`, the upload will not be triggered automatically after the file is selected. Get the instance with `bind:this` and call its `upload` method to trigger it
1018
+
1019
+ ```svelte
1020
+ <script lang="ts">
1021
+ import { IconPlus, IconUpload } from '@fibrae/semi-icons-svelte';
1022
+ import { Button, Upload, type UploadHandle } from '@fibrae/semi-ui-svelte';
1023
+ import { mockUpload } from '#/lib/mock-upload';
1024
+
1025
+ const action = '/upload';
1026
+ let uploadRef = $state<UploadHandle>();
1027
+ const manualUpload = () => {
1028
+ uploadRef?.upload();
1029
+ };
1030
+ </script>
1031
+
1032
+ <div>
1033
+ <Upload accept="image/gif, image/png, image/jpeg, image/bmp, image/webp" {action} bind:this={uploadRef} customRequest={mockUpload} onError={(...v) => console.log(...v)} onSuccess={(...v) => console.log(...v)} uploadTrigger="custom">
1034
+ <Button style="margin-inline-end: 8px" theme="light">
1035
+ {#snippet icon()}<IconPlus />{/snippet}
1036
+ 选择文件
1037
+ </Button>
1038
+ </Upload>
1039
+ <Button theme="light" onclick={manualUpload}>
1040
+ {#snippet icon()}<IconUpload />{/snippet}
1041
+ 开始上传
1042
+ </Button>
1043
+ </div>
1044
+ ```
1045
+
1046
+ ### Drag and drop upload
1047
+
1048
+ `draggable='true'`, you can use the drag and drop function
1049
+
1050
+ > **Notice**
1051
+ >
1052
+ > When the directory is true, because the browser automatically imposes restrictions, it is not allowed to select a single file when clicking upload. When dragging, we think it is more reasonable to allow folders and files to be dragged, so no additional interception processing is performed.
1053
+
1054
+ ```svelte
1055
+ <script lang="ts">
1056
+ import { Upload } from '@fibrae/semi-ui-svelte';
1057
+ import { mockUpload } from '#/lib/mock-upload';
1058
+ </script>
1059
+
1060
+ <Upload action="/upload" customRequest={mockUpload} draggable>
1061
+ {#snippet dragMainText()}点击上传文件或拖拽文件到这里{/snippet}
1062
+ {#snippet dragSubText()}支持任意类型文件{/snippet}
1063
+ </Upload>
1064
+ ```
1065
+
1066
+ You can quickly set the content of the drag area through the `dragIcon`, `dragMainText`, `dragSubText` snippets. `dragIcon` and `dragMainText` fall back to the default icon and text when they render nothing
1067
+
1068
+ ```svelte
1069
+ <script lang="ts">
1070
+ import { IconBolt } from '@fibrae/semi-icons-svelte';
1071
+ import { Upload } from '@fibrae/semi-ui-svelte';
1072
+ import { mockUpload } from '#/lib/mock-upload';
1073
+ </script>
1074
+
1075
+ <Upload accept="application/pdf,.jpeg" action="/upload" customRequest={mockUpload} draggable style="margin-top: 10px">
1076
+ {#snippet dragIcon()}
1077
+ <IconBolt />
1078
+ {/snippet}
1079
+ {#snippet dragMainText()}点击上传文件或拖拽文件到这里{/snippet}
1080
+ {#snippet dragSubText()}仅支持jpeg、pdf{/snippet}
1081
+ </Upload>
1082
+ ```
1083
+
1084
+ You can also pass content through `children` to completely customize the display of the drag area
1085
+
1086
+ ```svelte
1087
+ <script lang="ts">
1088
+ import { IconBolt } from '@fibrae/semi-icons-svelte';
1089
+ import { Upload } from '@fibrae/semi-ui-svelte';
1090
+ import { mockUpload } from '#/lib/mock-upload';
1091
+ </script>
1092
+
1093
+ <Upload accept="application/pdf,.jpeg" action="/upload" customRequest={mockUpload} draggable style="margin-top: 10px">
1094
+ {#snippet dragIcon()}
1095
+ <IconBolt />
1096
+ {/snippet}
1097
+ <div class="components-upload-demo-drag-area">
1098
+ <img alt="demo img" height="96" src="/assets/placeholder/avatar-a.svg" style="border-radius: 4px" />
1099
+ <div style="font-size: 14px; margin-top: 8px; flex-basis: 100%; text-align: center; color: var(--semi-color-tertiary)">Wow, you can really dance.</div>
1100
+ </div>
1101
+ </Upload>
1102
+ ```
1103
+
1104
+ The scss style is as follows
1105
+
1106
+ ```scss
1107
+ .components-upload-demo-drag-area {
1108
+ border-radius: var(--semi-border-radius-small);
1109
+ border: 2px dashed var(--semi-color-border);
1110
+ width: 100%;
1111
+ padding: 12px;
1112
+ background-color: var(--semi-color-tertiary-light-default);
1113
+ display: flex;
1114
+ cursor: pointer;
1115
+ flex-wrap: wrap;
1116
+ justify-content: center;
1117
+ &:hover {
1118
+ background-color: var(--semi-color-primary-light-default);
1119
+ border-color: var(--semi-color-primary);
1120
+ }
1121
+ }
1122
+ ```
1123
+
1124
+ ### Paste upload
1125
+
1126
+ With `addOnPasting`, files pasted anywhere on the page (the `paste` event) are added to the file list, with no clipboard permission prompt. `onPastingError` is called when a pasted file cannot be read.
1127
+
1128
+ ```svelte
1129
+ <script lang="ts">
1130
+ import { Toast, Upload } from '@fibrae/semi-ui-svelte';
1131
+ import { mockUpload } from '#/lib/mock-upload';
1132
+ </script>
1133
+
1134
+ <Upload action="/upload" addOnPasting customRequest={mockUpload} draggable onPastingError={() => Toast.error('读取剪贴板中的文件失败')}>
1135
+ {#snippet dragMainText()}复制截图或文件后,在页面上按 Ctrl/Cmd + V{/snippet}
1136
+ {#snippet dragSubText()}也可以点击或拖拽上传{/snippet}
1137
+ </Upload>
1138
+ ```
1139
+
1140
+ ### Custom check before upload
1141
+
1142
+ The file status can be updated through the `beforeUpload` hook, which is to verify the file after selecting the file before uploading online, `({ file: FileItem, fileList: Array<FileItem> }) => beforeUploadResult | Promise | boolean` During synchronization verification, a boolean (true means the verification passed, false means the verification failed, and the verification failure will prevent the file from uploading online) or an Object object. The specific structure is as follows
1143
+
1144
+ ```ts
1145
+ // beforeUploadResult:
1146
+ {
1147
+ fileInstance?: File,
1148
+ status?:'success' |'uploadFail' |'validateFail' |'validating' |'uploading' |'wait',
1149
+ validateMessage?: string, // file validation information; use the fileValidateMessage snippet for a node
1150
+ shouldUpload: boolean, // Whether to upload. The default is true, if it is false, the fileItem will only be displayed in the list, and the upload operation will not be triggered
1151
+ autoRemove: boolean, // Whether to remove the file from the fileList, the default is false
1152
+ }
1153
+ ```
1154
+
1155
+ ```svelte
1156
+ <script lang="ts">
1157
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1158
+ import { Button, Upload, type BeforeUploadObjectResult, type BeforeUploadProps } from '@fibrae/semi-ui-svelte';
1159
+ import { mockUpload } from '#/lib/mock-upload';
1160
+
1161
+ let count = 0;
1162
+
1163
+ const transformFile = (fileInstance: File) => {
1164
+ if (count === 0) {
1165
+ return new File([fileInstance], 'newFileName', { type: 'image/png' });
1166
+ }
1167
+ return fileInstance;
1168
+ };
1169
+
1170
+ const beforeUpload = ({ file }: BeforeUploadProps) => {
1171
+ let result: BeforeUploadObjectResult;
1172
+ if (count > 0) {
1173
+ result = {
1174
+ autoRemove: false,
1175
+ fileInstance: file.fileInstance,
1176
+ shouldUpload: true,
1177
+ };
1178
+ } else {
1179
+ result = {
1180
+ autoRemove: false,
1181
+ fileInstance: file.fileInstance,
1182
+ status: 'validateFail',
1183
+ shouldUpload: false,
1184
+ };
1185
+ }
1186
+ count = count + 1;
1187
+ return result;
1188
+ };
1189
+ </script>
1190
+
1191
+ <Upload action="/upload" {beforeUpload} customRequest={mockUpload} {transformFile}>
1192
+ <Button theme="light">
1193
+ {#snippet icon()}<IconUpload />{/snippet}
1194
+ 点击上传(上传前同步校验)
1195
+ </Button>
1196
+ </Upload>
1197
+ ```
1198
+
1199
+ In the case of asynchronous verification, a Promise must be returned. Promise resolve means that the verification is passed, and reject means that the verification fails and the upload will not be triggered. Object can be passed in when resolve/reject (the structure is the same as beforeUploadResult)
1200
+
1201
+ ```svelte
1202
+ <script lang="ts">
1203
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1204
+ import { Button, Upload, type BeforeUploadObjectResult, type BeforeUploadProps } from '@fibrae/semi-ui-svelte';
1205
+ import { mockUpload } from '#/lib/mock-upload';
1206
+
1207
+ let count = 0;
1208
+
1209
+ const beforeUpload = ({ file }: BeforeUploadProps) => {
1210
+ return new Promise<BeforeUploadObjectResult>((resolve, reject) => {
1211
+ if (count > 1) {
1212
+ const result = {
1213
+ autoRemove: false,
1214
+ shouldUpload: true,
1215
+ };
1216
+ count = count + 1;
1217
+ resolve(result);
1218
+ } else {
1219
+ const result = {
1220
+ autoRemove: false,
1221
+ fileInstance: file.fileInstance,
1222
+ status: 'validateFail',
1223
+ shouldUpload: false,
1224
+ validateMessage: `第${count + 1}个注定失败`,
1225
+ };
1226
+ count = count + 1;
1227
+ reject(result);
1228
+ }
1229
+ });
1230
+ };
1231
+ </script>
1232
+
1233
+ <Upload action="/upload" {beforeUpload} customRequest={mockUpload}>
1234
+ <Button theme="light">
1235
+ {#snippet icon()}<IconUpload />{/snippet}
1236
+ 点击上传(上传前异步校验)
1237
+ </Button>
1238
+ </Upload>
1239
+ ```
1240
+
1241
+ ### Update file information after upload
1242
+
1243
+ The file status, verification information, and file name can be updated through the `afterUpload` hook. `({ response: any, file: FileItem, fileList: Array<FileItem> }) => afterUploadResult` afterUpload is triggered when the upload is completed (xhr.onload) and no error occurs, it needs to return an Object object (asynchronous return is not supported), the specific structure is as follows
1244
+
1245
+ ```ts
1246
+ // afterUploadResult:
1247
+ {
1248
+ status?:'success' |'uploadFail' |'validateFail' |'validating' |'uploading' |'wait',
1249
+ validateMessage?: string, // file validation information; use the fileValidateMessage snippet for a node
1250
+ autoRemove?: boolean, // Whether to remove the file from the fileList, the default is false
1251
+ name?: string;
1252
+ // The URL for previewing image file, usually the storage address returned by the Server after receiving response
1253
+ url?: string;
1254
+ }
1255
+ ```
1256
+
1257
+ ```svelte
1258
+ <script lang="ts">
1259
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1260
+ import { Button, Upload, type AfterUploadProps, type AfterUploadResult } from '@fibrae/semi-ui-svelte';
1261
+ import { mockUpload } from '#/lib/mock-upload';
1262
+
1263
+ const afterUpload = ({ response }: AfterUploadProps): AfterUploadResult => {
1264
+ if (response.status_code === 200) {
1265
+ return {
1266
+ autoRemove: false,
1267
+ status: 'uploadFail',
1268
+ validateMessage: '内容不合法',
1269
+ name: 'RenameByServer.jpg',
1270
+ url: '/assets/root-web-sites/edit-bag.jpeg',
1271
+ };
1272
+ }
1273
+ return {};
1274
+ };
1275
+ </script>
1276
+
1277
+ <Upload action="/upload" {afterUpload} customRequest={mockUpload}>
1278
+ <Button theme="light">
1279
+ {#snippet icon()}<IconUpload />{/snippet}
1280
+ 点击上传
1281
+ </Button>
1282
+ </Upload>
1283
+ ```
1284
+
1285
+ ### Custom request
1286
+
1287
+ When customRequest is passed in, it is equivalent to using the custom request method to replace the upload built-in xhr request, and the user needs to take over the upload behavior by himself. The file object of the current operation can be obtained in the input parameters, and the user implements the upload process by himself, and calls onProgress, onError, and onSuccess in the customRequest input parameters when appropriate to update the internal state of the Upload component customRequest contains the following input parameters
1288
+
1289
+ ```ts
1290
+ {
1291
+ // current file name
1292
+ fileName: string,
1293
+ // props.data set by the user
1294
+ data: object,
1295
+ // FileItem, refer to the following document for the specific structure
1296
+ file: FileItem,
1297
+ // original File Object which extends Blob, the file object actually obtained by the browser (https://developer.mozilla.org/zh-CN/docs/Web/API/File)
1298
+ fileInstance: File,
1299
+ // Function that should be called during upload, event needs to include total and loaded attributes
1300
+ onProgress: (event: {total: number, loaded: number }) => any,
1301
+ // Function to be called when upload error
1302
+ onError: (userXhr: { status?: number }, e?: Event) => any,
1303
+ // The function that should be called after the upload is successful, response is the request result after the upload is successful
1304
+ onSuccess: (response: any, e?: Event) => any,
1305
+ // props.withCredentials set by the user
1306
+ withCredentials: boolean,
1307
+ // props.action set by the user
1308
+ action: string,
1309
+ }
1310
+ ```
1311
+
1312
+ ```svelte
1313
+ <script lang="ts">
1314
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1315
+ import { Button, Upload, type UploadCustomRequestArgs } from '@fibrae/semi-ui-svelte';
1316
+
1317
+ const mockRequest = ({ onProgress, onSuccess }: UploadCustomRequestArgs) => {
1318
+ let count = 0;
1319
+ const interval = setInterval(() => {
1320
+ if (count === 100) {
1321
+ clearInterval(interval);
1322
+ onSuccess({});
1323
+ return;
1324
+ }
1325
+ onProgress({ total: 100, loaded: count });
1326
+ count += 20;
1327
+ }, 500);
1328
+ };
1329
+ </script>
1330
+
1331
+ <Upload action="/upload" customRequest={mockRequest}>
1332
+ <Button theme="light">
1333
+ {#snippet icon()}<IconUpload />{/snippet}
1334
+ 点击上传
1335
+ </Button>
1336
+ </Upload>
1337
+ ```
1338
+
1339
+ ### Image Cropping
1340
+
1341
+ Enable image cropping functionality through the `crop` property. Supports cropping when clicking to select, dragging, pasting, and replacing files.
1342
+
1343
+ #### Basic Usage
1344
+
1345
+ Set `crop` to enable default cropping configuration (`crop={true}` or the boolean shorthand `crop`).
1346
+
1347
+ `accept` and `limit` are applied before cropping, so images that are rejected or exceed the limit are never cropped. Browsers encode only PNG, JPEG and WebP; the cropped result of any other format (GIF, BMP, SVG) is a PNG, and the file's `type` and extension become `image/png` and `.png`.
1348
+
1349
+ ```svelte
1350
+ <script lang="ts">
1351
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1352
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
1353
+ import { mockUpload } from '#/lib/mock-upload';
1354
+ </script>
1355
+
1356
+ <Upload action="/upload" crop customRequest={mockUpload} onSuccess={(response, file) => console.log('上传成功:', response, file)}>
1357
+ <Button theme="light">
1358
+ {#snippet icon()}<IconUpload />{/snippet}
1359
+ 点击上传(启用裁切)
1360
+ </Button>
1361
+ </Upload>
1362
+ ```
1363
+
1364
+ #### Custom Cropping Configuration
1365
+
1366
+ Configure cropping parameters through object form, including aspect ratio, shape, quality, etc.
1367
+
1368
+ ```svelte
1369
+ <script lang="ts">
1370
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1371
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
1372
+ import { mockUpload } from '#/lib/mock-upload';
1373
+ </script>
1374
+
1375
+ <Upload
1376
+ action="/upload"
1377
+ crop={{
1378
+ aspectRatio: 16 / 9,
1379
+ shape: 'rect',
1380
+ quality: 0.8,
1381
+ modalTitle: '裁切图片',
1382
+ modalOkText: '确认裁切',
1383
+ modalCancelText: '取消',
1384
+ }}
1385
+ customRequest={mockUpload}
1386
+ onSuccess={(response, file) => console.log('上传成功:', response, file)}
1387
+ >
1388
+ <Button theme="light">
1389
+ {#snippet icon()}<IconUpload />{/snippet}
1390
+ 点击上传(16:9 裁切)
1391
+ </Button>
1392
+ </Upload>
1393
+ ```
1394
+
1395
+ #### Round Cropping
1396
+
1397
+ Suitable for avatar upload scenarios, set `shape: 'round'` to enable round cropping.
1398
+
1399
+ ```svelte
1400
+ <script lang="ts">
1401
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1402
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
1403
+ import { mockUpload } from '#/lib/mock-upload';
1404
+ </script>
1405
+
1406
+ <Upload
1407
+ action="/upload"
1408
+ crop={{
1409
+ aspectRatio: 1,
1410
+ shape: 'round',
1411
+ quality: 0.9,
1412
+ modalTitle: '裁切头像',
1413
+ }}
1414
+ customRequest={mockUpload}
1415
+ onSuccess={(response, file) => console.log('上传成功:', response, file)}
1416
+ >
1417
+ <Button theme="light">
1418
+ {#snippet icon()}<IconUpload />{/snippet}
1419
+ 点击上传(圆形裁切)
1420
+ </Button>
1421
+ </Upload>
1422
+ ```
1423
+
1424
+ #### Confirm Before Cropping
1425
+
1426
+ Use the `beforeCrop` callback to confirm or perform other processing before cropping. Return `false` to skip cropping and upload directly.
1427
+
1428
+ ```svelte
1429
+ <script lang="ts">
1430
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1431
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
1432
+ import { mockUpload } from '#/lib/mock-upload';
1433
+ </script>
1434
+
1435
+ <Upload
1436
+ action="/upload"
1437
+ beforeCrop={(file, fileList) => {
1438
+ console.log('beforeCrop:', file, fileList);
1439
+ // true continues cropping; false skips it and uploads directly
1440
+ return window.confirm('是否裁切图片?');
1441
+ }}
1442
+ crop={{ aspectRatio: 1, shape: 'round' }}
1443
+ customRequest={mockUpload}
1444
+ onCropError={(error) => console.error('裁切失败:', error)}
1445
+ onSuccess={(response, file) => console.log('上传成功:', response, file)}
1446
+ >
1447
+ <Button theme="light">
1448
+ {#snippet icon()}<IconUpload />{/snippet}
1449
+ 点击上传(裁切前确认)
1450
+ </Button>
1451
+ </Upload>
1452
+ ```
1453
+
1454
+ #### Drag and Drop Upload with Cropping
1455
+
1456
+ Cropping is also triggered when uploading via drag and drop.
1457
+
1458
+ ```svelte
1459
+ <script lang="ts">
1460
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1461
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
1462
+ import { mockUpload } from '#/lib/mock-upload';
1463
+ </script>
1464
+
1465
+ <Upload
1466
+ action="/upload"
1467
+ crop={{
1468
+ aspectRatio: 1,
1469
+ shape: 'rect',
1470
+ }}
1471
+ customRequest={mockUpload}
1472
+ draggable
1473
+ onDrop={(_e, files) => console.log('拖拽文件:', files)}
1474
+ onSuccess={(response, file) => console.log('上传成功:', response, file)}
1475
+ >
1476
+ <Button theme="light">
1477
+ {#snippet icon()}<IconUpload />{/snippet}
1478
+ 拖拽上传(启用裁切)
1479
+ </Button>
1480
+ </Upload>
1481
+ ```
1482
+
1483
+ #### Custom Cropping Modal Style
1484
+
1485
+ Customize the style and properties of the cropping modal through `cropModalProps`. The `width` of the modal defaults to 600, and the value passed in wins.
1486
+
1487
+ `cropModalProps` is typed as `UploadCropModalProps`, which leaves out `visible`, `title`, `okText`, `cancelText`, `onOk` and `onCancel`: set the title and button texts with `modalTitle`, `modalOkText` and `modalCancelText` of `crop`, and the rest belongs to Upload.
1488
+
1489
+ ```svelte
1490
+ <script lang="ts">
1491
+ import { IconUpload } from '@fibrae/semi-icons-svelte';
1492
+ import { Button, Upload } from '@fibrae/semi-ui-svelte';
1493
+ import { mockUpload } from '#/lib/mock-upload';
1494
+ </script>
1495
+
1496
+ <Upload
1497
+ action="/upload"
1498
+ crop={{
1499
+ aspectRatio: 1,
1500
+ shape: 'rect',
1501
+ }}
1502
+ cropModalProps={{
1503
+ width: 800,
1504
+ style: 'height: 600px',
1505
+ styles: { body: 'height: 500px; background-color: #f5f5f5' },
1506
+ }}
1507
+ customRequest={mockUpload}
1508
+ onSuccess={(response, file) => console.log('上传成功:', response, file)}
1509
+ >
1510
+ <Button theme="light">
1511
+ {#snippet icon()}<IconUpload />{/snippet}
1512
+ 自定义弹窗样式
1513
+ </Button>
1514
+ </Upload>
1515
+ ```
1516
+
1517
+ ## API Reference
1518
+
1519
+ ---
1520
+
1521
+ ### Upload
1522
+
1523
+ **Props**
1524
+
1525
+ | Property | Description | Type | Default |
1526
+ | - | - | - | - |
1527
+ | accept | Accepted file types, written like the accept attribute of input: file extensions such as `.jpg` or MIME types, separated by commas. | `string` | - |
1528
+ | action | Upload URL. Required. | `string` | - |
1529
+ | addOnPasting | Whether files in the clipboard are added to the file list on paste, without extra permission. | `boolean` | `false` |
1530
+ | afterUpload | Hook after an upload completes without error. The returned object updates the file status, validate message, name and preview URL. Async results are not supported. | `(object: AfterUploadProps) => AfterUploadResult` | - |
1531
+ | beforeClear | Called before the list is cleared. Returning false, or a Promise that resolves to false or rejects, blocks the clear. | `(fileList: FileItem[]) => boolean \| Promise<boolean>` | - |
1532
+ | beforeCrop | Called before the crop modal opens, once with the first selected image; the result decides cropping for the whole batch. Return false to upload without cropping. May return a Promise. | `(file: File, fileList: File[]) => boolean \| Promise<boolean>` | - |
1533
+ | beforeRemove | Called before a file is removed. Returning false, or a Promise that resolves to false or rejects, blocks the removal. | `(file: FileItem, fileList: FileItem[]) => boolean \| Promise<boolean>` | - |
1534
+ | beforeUpload | Hook before a file is uploaded. The returned object updates the file status and decides whether to upload. A boolean means pass or fail; for a Promise, resolve passes and reject fails. | `(object: BeforeUploadProps) => BeforeUploadObjectResult \| Promise<BeforeUploadObjectResult> \| boolean` | - |
1535
+ | capture | How media is captured: user or environment. true renders the attribute with an empty value, false omits it. | `boolean \| 'environment' \| 'user'` | - |
1536
+ | children | Trigger content. In draggable mode it replaces the whole default drag area content. | `Snippet` | - |
1537
+ | classNames | Class names of the inner parts, keyed by `item` (each file card); merged with the built-in classes. | `Partial<Record<UploadPart, ClassValue>>` | - |
1538
+ | crop | Enables image cropping. true uses the defaults, an object configures the cropper. Selecting, dragging, pasting and replacing all crop. | `boolean \| UploadCropProps` | `false` |
1539
+ | cropModalProps | Props of the crop Modal. visible, title, okText, cancelText, onOk, onCancel and children belong to Upload; style and every value of styles are style strings. | `UploadCropModalProps` | - |
1540
+ | customRequest | Replaces the built-in XMLHttpRequest. It must call the onProgress, onError and onSuccess it receives to update the state. | `(object: UploadCustomRequestArgs) => void` | - |
1541
+ | data | Extra parameters sent with the upload, or a function that returns them for a file. | `Record<string, any> \| ((file: File) => Record<string, unknown>)` | - |
1542
+ | directory | Whether to upload a folder. | `boolean` | `false` |
1543
+ | disabled | Whether Upload is disabled. A disabled Upload no longer shows the remove, retry, replace and clear actions. | `boolean` | `false` |
1544
+ | draggable | Whether dragging files to upload is supported. | `boolean` | `false` |
1545
+ | dragIcon | Icon of the drag area. Falls back to the default icon when empty. | `Snippet` | - |
1546
+ | dragMainText | Main text of the drag area. Falls back to the locale text when empty. | `Snippet` | - |
1547
+ | dragSubText | Help text of the drag area. | `Snippet` | - |
1548
+ | ellipsisTooltip | Custom popup content for a truncated file name, with content and trigger; trigger is the file name element to place in the popup. | `Snippet<[TypographyEllipsisTooltipProps]>` | - |
1549
+ | fileItem | Replaces each file card, with UploadFileItemSlotProps. Render `<UploadFileCard {...props} />` for the default card. A file it renders nothing for is not shown. | `Snippet<[UploadFileItemSlotProps]>` | - |
1550
+ | fileList | The file list, two-way bindable with bind:fileList. A plain value is the initial list, which Upload then maintains itself. The uid of every item is required and must be unique. | `FileItem[]` | - |
1551
+ | fileListHeader | Replaces the whole title area, clear button included, with fileList, onClear and clearText. | `Snippet<[UploadFileListHeaderSlotProps]>` | - |
1552
+ | fileListTitle | Replaces only the title text of the file list; the clear button stays. | `Snippet` | - |
1553
+ | fileName | Same as name. Mainly used in FormUpload to avoid clashing with the name of Field. | `string` | - |
1554
+ | fileOperation | Custom operation area of a list item. | `Snippet<[UploadFileItemSlotProps]>` | - |
1555
+ | fileValidateMessage | Custom validate message of a file card, which receives validateMessage. | `Snippet<[UploadFileItemSlotProps]>` | - |
1556
+ | headers | Headers sent with the upload, or a function that returns them for a file. | `Record<string, any> \| ((file: File) => Record<string, string>)` | - |
1557
+ | hotSpotLocation | Position of the picture wall add button: start or end. | `'end' \| 'start'` | `"end"` |
1558
+ | limit | Maximum number of files. With 1, the newest file always replaces the current one and onExceed is not called. | `number` | - |
1559
+ | listType | How the file list is displayed: list, picture or none. none renders no file list, only the trigger area. | `UploadListType` | `"list"` |
1560
+ | maxSize | Maximum file size in KB. | `number` | - |
1561
+ | minSize | Minimum file size in KB. | `number` | - |
1562
+ | multiple | Whether several files can be selected at once. | `boolean` | `false` |
1563
+ | name | Field name used for the file when uploading. | `string` | - |
1564
+ | onAcceptInvalid | Called when received files do not match accept, with those files. | `(files: File[]) => void` | - |
1565
+ | onChange | Called when a file status changes, including uploading, success and failure. currentFile is null after insert and absent after a clear. This is the callback of Upload, not the native change of the hidden input. | `(object: UploadOnChangeProps) => void` | - |
1566
+ | onClear | Called after the list is cleared. | `() => void` | - |
1567
+ | onCropError | Called when cropping an image fails. | `(error: Error) => void` | - |
1568
+ | onDrop | Called when a dragged element is released on the drag area, with the native drop event, the dropped files and the current file list. | `(e: DragEvent, files: File[], fileList: FileItem[]) => void` | - |
1569
+ | onError | Called when an upload fails. With customRequest, xhr is the object passed to its onError. | `(e: UploadCustomError, file: CustomFile, fileList: FileItem[], xhr: XMLHttpRequest \| { status?: number }) => void` | - |
1570
+ | onExceed | Called when the total number of files exceeds limit, with the originally selected files before truncation. | `(fileList: File[]) => void` | - |
1571
+ | onFileChange | Called after files are selected. | `(files: File[]) => void` | - |
1572
+ | onOpenFileDialog | Called when the system file dialog opens. | `() => void` | - |
1573
+ | onPastingError | Called when addOnPasting is true and a clipboard file cannot be read. | `(error: Error) => void` | - |
1574
+ | onPreviewClick | While present the file cards are clickable and show a preview button; its presence changes the rendering. | `(fileItem: FileItem) => void` | - |
1575
+ | onProgress | Called while uploading, with the percentage, the file and the current file list. | `(percent: number, file: CustomFile, fileList: FileItem[]) => void` | - |
1576
+ | onRemove | Called after a file is removed. currentFile is undefined for an item without a File object, such as one from the initial list. | `(currentFile: CustomFile \| undefined, fileList: FileItem[], currentFileItem: FileItem) => void` | - |
1577
+ | onRetry | Called when retry is clicked. | `(fileItem: FileItem) => void` | - |
1578
+ | onSizeError | Called when a file size violates maxSize or minSize. | `(file: CustomFile, fileList: FileItem[]) => void` | - |
1579
+ | onSuccess | Called after a successful upload, with the server response, the file and the current file list. | `(responseBody: any, file: CustomFile, fileList: FileItem[]) => void` | - |
1580
+ | picClose | Custom close button of the picture wall, with class and onRemove. Only applies in picture mode. | `Snippet<[UploadPicCloseSlotProps]>` | - |
1581
+ | picHeight | Display height of the pictures in picture mode. | `string \| number` | - |
1582
+ | picInfo | Custom picture wall information. Only applies in picture mode with showPicInfo set to true. | `Snippet<[UploadFileItemSlotProps]>` | - |
1583
+ | picPreviewIcon | Custom preview icon shown on hover in the picture wall. Only applies in picture mode. | `Snippet<[UploadFileItemSlotProps]>` | - |
1584
+ | picWidth | Display width of the pictures in picture mode. | `string \| number` | - |
1585
+ | previewFile | Custom preview that replaces the thumbnail. Only applies in list mode. It does not fall back to the default thumbnail when empty. | `Snippet<[UploadFileItemSlotProps]>` | - |
1586
+ | prompt | Prompt text. Unlike content in children, clicking it does not trigger an upload. | `Snippet` | - |
1587
+ | promptPosition | Position of the prompt: left, right or bottom. In list mode it is relative to the trigger, in picture mode to the picture list. | `PromptPositionType` | `"right"` |
1588
+ | showClear | In list mode, whether to show the clear button when limit is not 1 and there is at least one file. | `boolean` | `true` |
1589
+ | showPicInfo | Whether to show picture information. Only applies in picture mode. | `boolean` | `false` |
1590
+ | showReplace | Whether the file card shows a replace button after a successful upload. | `boolean` | `false` |
1591
+ | showRetry | Whether the file card shows a retry button when the upload fails. | `boolean` | `true` |
1592
+ | showTooltip | Whether a truncated file name shows a tooltip, or the tooltip type (tooltip or popover) and the props passed to it. Use the ellipsisTooltip snippet for custom popup content. | `boolean \| ShowTooltip` | `true` |
1593
+ | showUploadList | Whether to show the file list. | `boolean` | `true` |
1594
+ | styles | Style strings of the inner parts, keyed like classNames; in the picture wall `item` is merged with picWidth and picHeight, and the latter win. | `Partial<Record<UploadPart, string>>` | - |
1595
+ | thumbnail | Custom picture wall thumbnail. Only applies in picture mode. | `Snippet<[UploadFileItemSlotProps]>` | - |
1596
+ | transformFile | Called after a file is selected and before it is uploaded; returns the File to upload. | `(file: File) => File` | - |
1597
+ | uploadTrigger | When uploading starts: auto uploads on selection, custom waits for the upload method. | `'auto' \| 'custom'` | `"auto"` |
1598
+ | validateMessage | Validate message of the whole Upload. | `Snippet` | - |
1599
+ | validateStatus | Validation status, which styles the root element: default, error, warning or success. | `ValidateStatus` | - |
1600
+ | withCredentials | Whether the upload request carries cookies. | `boolean` | `false` |
1601
+
1602
+ **Methods**
1603
+
1604
+ | Method | Description | Type |
1605
+ | - | - | - |
1606
+ | insert | Adds files at index, or at the end without one. | `(files: CustomFile[], index?: number) => void` |
1607
+ | openFileDialog | Opens the file dialog. | `() => void` |
1608
+ | upload | Uploads the waiting files. Use it with uploadTrigger set to custom. | `() => void` |
1609
+
1610
+ Undeclared attributes such as `class`, `style` and `aria-*` land on the root element, which gets `role="group"` automatically when it has `aria-label` or `aria-labelledby`.
1611
+
1612
+ ### Upload.FileCard
1613
+
1614
+ `Upload.FileCard` (also importable on its own as `UploadFileCard`) is the default file card, used to keep the default look inside snippets such as `fileItem`: `<Upload.FileCard {...props} />`. `class`, `style`, `data-*` and `aria-*` land on its root element.
1615
+
1616
+ **Props**
1617
+
1618
+ | Property | Description | Type | Default |
1619
+ | - | - | - | - |
1620
+ | disabled | Whether the card is disabled. A disabled card shows no remove, retry or replace button. | `boolean` | - |
1621
+ | ellipsisTooltip | Custom popup content for a truncated file name, with content and trigger. | `Snippet<[TypographyEllipsisTooltipProps]>` | - |
1622
+ | file | The file to show. Required. | `FileItem` | - |
1623
+ | fileOperation | Custom operation area of a list item. | `Snippet<[UploadFileItemSlotProps]>` | - |
1624
+ | fileValidateMessage | Custom validate message, which receives validateMessage. | `Snippet<[UploadFileItemSlotProps]>` | - |
1625
+ | index | Position of the file in the list. | `number` | - |
1626
+ | listType | Display type of the card: list, picture or none. none renders no card. | `UploadListType` | `"list"` |
1627
+ | onPreviewClick | While present the card is clickable and shows a preview button; its presence changes the rendering. | `() => void` | - |
1628
+ | onRemove | Called when remove is clicked. | `() => void` | - |
1629
+ | onReplace | Called when replace is clicked. | `() => void` | - |
1630
+ | onRetry | Called when retry is clicked. | `() => void` | - |
1631
+ | picClose | Custom close button of the picture wall, with class and onRemove. Only applies in picture mode. | `Snippet<[UploadPicCloseSlotProps]>` | - |
1632
+ | picHeight | Height of the picture in picture mode. | `string \| number` | - |
1633
+ | picInfo | Custom picture wall information. Only applies in picture mode with showPicInfo set to true. | `Snippet<[UploadFileItemSlotProps]>` | - |
1634
+ | picPreviewIcon | Custom preview icon shown on hover in the picture wall. Only applies in picture mode. | `Snippet<[UploadFileItemSlotProps]>` | - |
1635
+ | picWidth | Width of the picture in picture mode. | `string \| number` | - |
1636
+ | previewFile | Custom preview that replaces the thumbnail. Only applies in list mode. | `Snippet<[UploadFileItemSlotProps]>` | - |
1637
+ | showPicInfo | Whether to show picture information. Only applies in picture mode. | `boolean` | - |
1638
+ | showReplace | Whether to show a replace button after success. The showReplace of the file wins. | `boolean` | - |
1639
+ | showRetry | Whether to show a retry button on failure. The showRetry of the file wins. | `boolean` | - |
1640
+ | showTooltip | Whether a truncated file name shows a tooltip, or the tooltip type and the props passed to it. | `boolean \| ShowTooltip` | `true` |
1641
+ | thumbnail | Custom picture wall thumbnail. Only applies in picture mode. | `Snippet<[UploadFileItemSlotProps]>` | - |
1642
+ | validateMessage | Validate message. Wins over the validateMessage of the file. | `string` | - |
1643
+
1644
+ ## Interfaces
1645
+
1646
+ ### FileItem Interface
1647
+
1648
+ > **Notice**
1649
+ >
1650
+ > uid is the unique identifier of the file, and upload update and delete logic strongly relies on this value. If the current file is selected and added by upload, uid will be automatically generated. If it is passed in by props.defaultFileList or props.fileList, it must be passed, and you need to ensure that it will
1651
+ > not be repeated
1652
+
1653
+ ```ts
1654
+ interface FileItem {
1655
+ event?: Event; // xhr event
1656
+ fileInstance?: File; // original File Object which extends Blob, the file object actually obtained by the browser (https://developer.mozilla.org/zh-CN/docs/Web/API/File)
1657
+ name: string;
1658
+ percent?: number; // upload progress percentage
1659
+ preview?: boolean; // Whether to preview according to url
1660
+ response?: any; // xhr's response, response body when the request is successful, and corresponding error when the request fails
1661
+ shouldUpload?: boolean; // Should you continue to upload
1662
+ showReplace?: boolean; // Separately control whether the file displays the replace button
1663
+ showRetry?: boolean; // Separately control whether the file displays the retry button
1664
+ size: string; // file size, unit kb
1665
+ status: 'success' | 'uploadFail' | 'validateFail' | 'validating' | 'uploading' | 'wait';
1666
+ uid: string; // The unique identifier of the file. If the current file is selected and added by upload, the uid will be automatically generated. If it is the initial list, you need to ensure that it will not be repeated
1667
+ url?: string;
1668
+ validateMessage?: string; // a string only; use the fileValidateMessage snippet for a node
1669
+ }
1670
+ ```
1671
+
1672
+ FileItem has only the fields above; writing an undeclared field is a type error.
1673
+
1674
+ ### UploadFileItemSlotProps Interface
1675
+
1676
+ The parameter that the `fileItem`, `thumbnail`, `picInfo`, `picPreviewIcon`, `fileOperation`, `previewFile` and `fileValidateMessage` snippets receive. The file data sits in the `file` field, next to the file card's props. `<Upload.FileCard {...props} />` renders the default card.
1677
+
1678
+ ```ts
1679
+ interface UploadFileItemSlotProps {
1680
+ file: FileItem;
1681
+ index?: number; // position of the file in the list
1682
+ listType: 'picture' | 'list' | 'none';
1683
+ disabled?: boolean;
1684
+ showRetry?: boolean;
1685
+ showReplace?: boolean;
1686
+ showPicInfo?: boolean;
1687
+ showTooltip?: boolean | ShowTooltip;
1688
+ picWidth?: string | number;
1689
+ picHeight?: string | number;
1690
+ validateMessage?: string;
1691
+ class?: ClassValue; // from classNames.item
1692
+ style?: string; // from styles.item
1693
+ onRemove: () => void; // removes this file
1694
+ onRetry: () => void; // uploads this file again
1695
+ onReplace: () => void; // replaces this file
1696
+ onPreviewClick?: () => void; // present only when Upload has an onPreviewClick
1697
+ }
1698
+ ```
1699
+
1700
+ ### UploadPicCloseSlotProps Interface
1701
+
1702
+ The parameter that `picClose` receives:
1703
+
1704
+ ```ts
1705
+ interface UploadPicCloseSlotProps {
1706
+ class: string;
1707
+ onRemove: (e: MouseEvent) => void;
1708
+ }
1709
+ ```
1710
+
1711
+ ### UploadFileListHeaderSlotProps Interface
1712
+
1713
+ The parameter that `fileListHeader` receives:
1714
+
1715
+ ```ts
1716
+ interface UploadFileListHeaderSlotProps {
1717
+ fileList: FileItem[]; // Current file list
1718
+ onClear: () => void; // Function to clear files
1719
+ clearText: string; // Default text for the clear button (based on current locale)
1720
+ }
1721
+ ```
1722
+
1723
+ ### CropProps Interface
1724
+
1725
+ Configuration object accepted by the `crop` prop:
1726
+
1727
+ In Svelte the type is exported as `UploadCropProps`.
1728
+
1729
+ ```ts
1730
+ interface CropProps {
1731
+ aspectRatio?: number; // Crop box aspect ratio, e.g. 16/9, 1, 4/3
1732
+ shape?: 'rect' | 'round' | 'roundRect'; // Crop box shape, default 'rect'
1733
+ minZoom?: number; // Minimum zoom ratio
1734
+ maxZoom?: number; // Maximum zoom ratio
1735
+ zoomStep?: number; // Zoom step size
1736
+ quality?: number; // Output image quality, range 0 - 1, default 0.92
1737
+ fill?: string; // Fill color of the area outside the cropped region, default transparent 'rgba(0, 0, 0, 0)'
1738
+ modalTitle?: string; // Title text of the crop modal
1739
+ modalOkText?: string; // Confirm button text of the crop modal
1740
+ modalCancelText?: string; // Cancel button text of the crop modal
1741
+ }
1742
+ ```
1743
+
1744
+ ## Methods
1745
+
1746
+ Upload exposes `insert`, `upload` and `openFileDialog` as `export function`s. Get the instance with `bind:this`, typed as `UploadHandle`; see the Methods table of Upload above.
1747
+
1748
+ ## Accessibility
1749
+
1750
+ The Upload component is an interactive control that can trigger file selection when clicking or dragging. After the file is selected, the status will be displayed in the file list.
1751
+
1752
+ ### ARIA
1753
+
1754
+ - The trigger area is a `role="button"` that Enter and Space activate. When the trigger content holds its own control, such as a Button, the area takes no role and that control is the button; its click opens the file dialog. A disabled control (native `disabled` or `aria-disabled="true"`) still counts as your own control: the area does not become a button, and Enter and Space do not open the file dialog
1755
+ - When Upload is disabled, pass `disabled` to that control as well. When `limit` is reached, disable only that control and not Upload, so users can still remove uploaded files
1756
+ - When the root element has `aria-label` or `aria-labelledby`, it gets `role="group"` automatically; a `role` you pass yourself wins
1757
+ - Add `role="list"` to the file list and describe it with `aria-label`; in the picture wall the add button sits beside the list
1758
+ - In list mode the replace button is the trigger of its Tooltip, so Tab stops on it once
1759
+
1760
+ ## Content Guidelines
1761
+
1762
+ - Upload button
1763
+ - For the copywriting specification of the form button, refer to [The content Guidelines of the Button component](../basic/button.md#content-guidelines)
1764
+ - Help text
1765
+ - The help text is written in sentences, the first letter is capitalized, and periods may not be required
1766
+ - Error message
1767
+ - Clearly tell the user why the file cannot be uploaded, and tell the user how to upload it successfully
1768
+ - Help texts are written using sentences, capitalized
1769
+ - Concise language that users can read at a glance, such as `File size must be less than 20MB`, `File type must be .gif, .jpg, .png or .svg`
1770
+
1771
+ ## Design Tokens
1772
+
1773
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/input/upload/>
1774
+
1775
+ ## FAQ
1776
+
1777
+ - When will the retry button appear?
1778
+ - When `showRetry` is true and the upload of the current file fails due to a network error, the retry button will be displayed. Other statuses such as verification failed, upload successful, etc. will not display the retry button.
1779
+ - When will the replace button appear?
1780
+ - When `showReplace` is true and the current file status is uploaded, the replace button will be displayed.
1781
+ - Where did Semi save the pictures?
1782
+ - Semi is not responsible for the preservation of the image, you need to customize the action when you use the Upload component. You can choose to set action as your own server address or image service address.
1783
+ - FormUpload props.name does not work?
1784
+ - Field components have props.name and so does Upload, so the two clash. With FormUpload, use props.fileName instead to avoid the clash
1785
+ - Didn't call the XXX method after uploading the picture?
1786
+ - If you set `accept`, you can try to remove the accept attribute, and then see if the modified method is called. After removing it, the method is called to explain that the file type obtained by accept in the current environment does not match the set accept, and the upload behavior is terminated early. You can make a breakpoint to upload/foundation.js checkFileFormat function to see if the actual value of file.type obtained meets expectations.
1787
+
1788
+ > **About the progress bar**
1789
+ >
1790
+ > The progress bar indicates the upload progress. The upload progress is divided into two parts: data upload and server return. If all the data has been sent, but the server does not return a response, the progress bar will stay at 95%. The user upload is not completed. At this time, the request in the developer tool
1791
+ > will be pending, which is normal.
1792
+
1793
+ ## Changes from Semi Design
1794
+
1795
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
1796
+
1797
+ - 破坏性:删除 `itemStyle`,改用 `classNames.item`、`styles.item`,落在每个文件卡片上,图片墙里宽高以 `picWidth`、`picHeight` 为准;`Upload.FileCard` 与 `renderFileItem`、`fileItem` 插槽的参数新增类名(React 为 `className`,其余为 `class`),来自 `classNames.item`。`cropModalProps` 删除 `bodyStyle`,改用 `styles.body`,与内置的 400px 高度合并,使用方的值优先。
1798
+ - 破坏性:`limit` 为 1 时选择文件不再调用 `onExceed`;`onDrop` 第一个参数改为原生 `DragEvent`;`accept` 中点开头的扩展名按完整后缀匹配(`.tar.gz` 要求以其结尾);`addOnPasting` 只响应原生 `paste` 事件,`onPastingError` 改为粘贴文件读取失败时触发,参数收窄为 `Error`。
1799
+ - 破坏性(类型):`FileItem`、`BaseFileItem` 删除 `[key: string]: any`(Chat 的 `attachment`、AIChatInput 的 `Attachment` 随之变化);`RenderFileItemProps` 不再含 `key`;`transformFile` 改为 `(file: File) => File`;`cropModalProps` 收窄为 `UploadCropModalProps`;ref 为 `UploadHandle { insert, upload, openFileDialog }`。
1800
+ - React、Solid 破坏性(类型):`upload` 深路径导出的 `customRequestArgs` 改名 `UploadCustomRequestArgs`,与包根导出同名。
1801
+ - 上传事件不再原地改写文件项,每次生成新对象,用 `===` 比较旧文件项需改为比较 `uid`;卸载、隐藏或缓存时进行中的上传不再中止(需要中止的用 `customRequest`),卸载后请求结果仍会回调 `onChange`、`onSuccess`、`onError` 等(Vue 的事件卸载后不再发出)。
1802
+ - 选择文件后清空隐藏文件输入框的值而不重新挂载它,同一文件可再次选择;React 的 `UploadState` 删除 `inputKey`、`replaceInputKey`。
1803
+ - React、Vue、Solid:服务端渲染的文件卡片缩略图在 hydration 前已加载失败时,hydration 后切到回退图标(原来保留破图)。
1804
+ - DOM 变化:图片墙空列表也渲染 `.semi-upload-file-list`(依赖 `.semi-upload > .semi-upload-add` 的样式需调整);`tabIndex` 落在添加按钮上,根元素不再输出 `aria-required`、`tabIndex`;列表缩略图 `alt` 为空,卡片操作与「清空」改为原生 `button`。
1805
+ - `aria-required` 为真时(FormUpload 必填),添加按钮的 `aria-describedby` 指向一段隐藏的「必填」说明(文案取语言包 `Form.required`);添加区内容自带可聚焦控件时说明落不到该控件上,改挂在根元素的 `aria-describedby`。
1806
+ - 不带事件对象调用 `onProgress` 不再抛错;进度事件只重渲染对应的文件卡片(React;Solid、Svelte 原本按卡片细粒度更新)。
1807
+ - 添加区挂载后子元素增删 `aria-label`、`aria-labelledby`、`alt` 时重新判断是否已有名称;foundation 的 `addAreaControlAttributes` 改名为 `addAreaObservedAttributes` 并包含这三个属性。
1808
+ - Solid 破坏性(类型):`FileItem`、`BeforeUploadObjectResult`、`AfterUploadResult` 的 `validateMessage` 只收字符串(原为 `JSX.Element`),节点用 `renderValidateMessage(fileItem)`,参数同其他渲染函数为 `RenderFileItemProps`,渲染为空时回落到文字;照片墙只为带 `validateMessage` 的文件显示校验图标,`renderValidateMessage` 替换图标提示中的文字(Vue 的 `#fileValidateMessage` 为该文件渲染出内容时即使没有文字也显示图标)。
1809
+ - Svelte:`fileList` 可绑定(`bind:`、函数绑定、单向、不传四种写法),没有 `defaultFileList`,绑定成 `undefined` 时清空(表单重置);事件是 `onX` 回调;插槽改为同名 snippet:`dragIcon`、`dragMainText`、`dragSubText`、`prompt`、`validateMessage`、`fileListTitle`、`fileListHeader`、`fileItem`、`previewFile`、`thumbnail`、`picInfo`、`picPreviewIcon`、`picClose`、`fileOperation`、`fileValidateMessage`、`ellipsisTooltip`,空 snippet 不回落默认内容。
1810
+ - Svelte:`styles` 的值与 `cropModalProps` 的 `style`、`styles` 的值只接受字符串;图片墙的校验图标只在 `validateMessage` 为字符串时出现;经 `bind:this` 调用 `insert`、`upload`、`openFileDialog`(类型 `UploadHandle`);`Upload.FileCard` 与 `UploadFileCard` 两种导出都有。
1811
+ - Svelte:没有 KeepAlive 行为;有 `aria-label` 时根元素为 `role="group"`;`tabindex` 交给上传区域,`onblur` 只在焦点离开整个组件时触发。