Input · Upload
Upload
File selection upload
Demos
How to import
Basic usage
The most basic usage is to place a Button in children, click on the children content (the placed Button) to activate the file selection box, and the upload will start automatically after the selection is completed
Add prompt text
Set a custom prompt text through the
prompt
slot
Set the slot position by promptPosition
, optional left
, right
, bottom
, the default is right
When listType is picture, the reference object at promptPosition is the whole picture wall list
Click on the avatar to trigger upload
Custom upload attributes
Custom upload attributes can be added by setting
data
, headers
Upload file type
The type of files uploaded can be restricted through the
accept
attribute (the native html
attribute of input
).accept
supports the following two types of strings:- A collection of file extensions (recommended), such as .jpg, .png, etc.;
- MIME types collection of file types, please refer to MDN document
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 ,
).Upload folder
By passing in
directory
as true
, all files in the folder can be uploadedSelect multiple files at once
You can select multiple files to upload at the same time by setting the
multiple
attribute.Limit the total number of files
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 will not trigger the onExceed callback v1.5.0 takes effectIn the photo wall mode, when the number of uploaded files is equal to the limit, the upload entry will be automatically hidden
Limit upload file size
The upload file size limit can be customized through the
maxSize
and minSize
properties, and the callback when the limit is exceeded can be set by setting onSizeError
.Custom list operation area
When
listType
is list
, you can customize the list operation area by passing in renderFileOperation
Custom preview logic
When
For example, when you don't need thumbnail preview for image types, you can constantly return a
If you want to enlarge and preview the image when clicked, you can use the
Or if you want to use an additional operation area to achieve enlarged preview when clicked, you can also combine
listType
is list, the preview logic can be implemented by passing in previewFile
.For example, when you don't need thumbnail preview for image types, you can constantly return a
<IconFile />
in previewFile.If you want to enlarge and preview the image when clicked, you can use the
Image
component in previewFile
.Or if you want to use an additional operation area to achieve enlarged preview when clicked, you can also combine
renderFileOperation
to place some custom elements such as Icon to achieve enlarged preview when clicked.The following is an example of combining
renderFileOperation
and ImagePreview
. In this example, clicking the first Icon on the right can enlarge the image for preview.Default file list
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
Controlled component
When
fileList
is passed in, it is used as a controlled component. Need to listen to the onChange callback, and pass the fileList back to Upload (note that a new array object needs to be passed in)Photo Wall
Set
listType ='picture'
, users can upload pictures and display thumbnails in the listSet
showPicInfo
, you can view the basic information of the pictureYou can customize the preview icon through
When you need to customize the preview/replacement function, you need to turn off the replacement function and use
renderPicPreviewIcon
, 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
renderPicPreviewIcon
to listen for icon click events. onPreviewClick
listens for the click event of the single image containerSet
hotSpotLocation
to customize the order of click hotspots, the default is at the end of the photo wall listPhoto Wall With Preview
With the Image component, through the renderThumbnail API, you can click on the image to enlarge the preview
Photo Wall Width/Height
By setting picHeight, picWidth (provided after v2.42), the width and height of picture wall elements can be uniformly set
Disabled
Manually trigger upload
uploadTrigger='custom'
, the upload will not be triggered automatically after the file is selected. Need to manually call the upload method on the ref to triggerDrag and drop upload
draggable='true'
, you can use the drag and drop functionYou can quickly set the content of the drag area through
dragIcon
, dragMainText
, dragSubText
You can also pass in ReactNode through
children
to completely customize the display of the drag areaThe scss style is as follows
Custom check before upload
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 followsIn 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)
Update file information after upload
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 followsCustom request
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
API Reference
Property | Description | Type | Default Value | Version |
---|---|---|---|---|
accept | html Native attribute, accept uploaded file type. The value of accept is the MIME types string or file that you allow to select the file Suffix (.jpg, etc.) | string | ||
action | File upload address, required | string | ||
afterUpload | Hook after the file upload, update the file status according to the returned object | function(auProps) => afterUploadResult | 1.0.0 | |
beforeClear | Call back before clearing the file, judge whether to continue removing according to the return value, return false, Promise.resolve(false), Promise.reject() will prevent removal | (fileList: Array<FileItem >) => boolean | Promise | 1.31.0 | |
beforeRemove | Callback before removing the file, judge whether to continue removing according to the return value, return false, Promise.resolve(false), Promise.reject() will prevent removal | (file: <FileItem>, fileList: Array<FileItem >) => boolean | Promise | 1.31.0 | |
beforeUpload | The hook before uploading the file, according to the return object to update the file status, control whether to upload | function(buProps) => beforeUploadResult | Promise | boolean | 1.0.0 | |
capture | The way of media shooting in the file upload control | boolean | string | undefined | ||
className | class name | string | ||
customRequest | Asynchronous request method for custom upload | (object: customRequestArgs) => void | 1.5.0 | |
data | Additional parameters attached to the upload or the method to return the uploaded additional parameters | object|(file: File) => object | {} | |
defaultFileList | List of uploaded files | Array<FileItem> | [] | |
directory | Folder type upload | boolean | false | 1.20.0 |
disabled | Whether to disable | boolean | false | |
dragIcon | Icon on the left side of the drag area | ReactNode | <IconUpload /> | 0.22.0 |
dragMainText | Main text of the drag area | ReactNode | 'Click to upload the file or drag and drop the file here' | 0.22.0 |
dragSubText | Drag area help text | ReactNode | '' | 0.22.0 |
draggable | Whether to support drag and drop upload | boolean | false | 0.22.0 |
fileList | A list of uploaded files. When this value is passed in, upload is a controlled component | Array<FileItem> | 1.0.0 | |
fileName | has the same function as name and is mainly used in Form.Upload. In order to avoid conflicts with the props.name of Field, a renamed props is provided here | string | 1.0.0 | |
headers | The headers attached to the upload or the method to return the uploaded additional headers | object|(file: File) = > object | {} | |
hotSpotLocation | 照片墙点击热区的放置位置,可选值 start , end | string | 'end' | 2.5.0 |
itemStyle | Inline style of fileCard | CSSProperties | 1.0.0 | |
limit | Maximum number of files allowed to be uploaded | number | ||
listType | File list display type, optional picture , list | string | 'list' | |
maxSize | Maximum file size limit, in KB | number | ||
minSize | Minimum file size limit, unit KB | number | ||
multiple | Whether to allow multiple files to be selected at a time | boolean | false | |
name | File name used when uploading | string | '' | |
onAcceptInvalid | Triggered when the received file does not conform to the accept specification (generally because the folder selects all types of files / drags and drops files that do not conform to the format) | (files: File[]) => void | 1.24 .0 | |
onChange | Called when the file status changes, including upload success, failure, upload, the callback input parameter is Object, including fileList, currentFile, etc. | ({fileList: Array<FileItem>, currentFile?: FileItem}) = > void | 1.0.0 | |
onClear | Callback when click to clear | () => void | 1.1.0 | |
onDrop | Triggered when the dragged element is released on the drag area | (e, files: Array<File>, fileList: Array<FileItem>) => void | 1.9.0 | |
onError | Callback when uploading error | (error: Error, file: File, fileList: Array<FileItem> , xhr: XMLHttpRequest) => void | ||
onExceed | Callback when the total number of uploaded files exceeds limit | (fileList:Array<FileItem>) => void | ||
onFileChange | Callback after file selection | (Array<File>) => void | ||
onOpenFileDialog | Triggered when opening the system file system file selection pop-up window | () => void | 1.18.0 | |
onPreviewClick | Callback when the file card is clicked | (fileItem: FileItem) => void | 1.8.0 | |
onProgress | Callback when uploading files | (percent: number, file: File, fileList: Array<FileItem> ) => void | ||
onRemove | Callback for removing files | (currentFile: File, fileList:Array<FileItem>, currentFileItem: FileItem ) => void | ||
onRetry | Upload retry callback | (file: <FileItem>) => void | 1.18.0 | |
onSizeError | File size invalid callback | (file:File, fileList:Array<FileItem>) => void | ||
onSuccess | Callback after successful upload | (responseBody: object, file: File, fileList:Array<FileItem> ) => void | ||
picHeight | Set picture display height when listType='picture' | string|number | 2.42.0 | |
picWidth | Set picture display width when listType='picture' | string|number | 2.42.0 | |
previewFile | Customize the preview logic, the content returned by this function will replace the original thumbnail | (fileItem: FileItem) => ReactNode | ||
prompt | Custom slot, which can be used to insert prompt text. Different from writing directly in children , the content of prompt will not trigger upload when clicked.(In the picture wall mode, the incoming prompt is only supported after v1.3.0) | ReactNode | ||
promptPosition | The position of the prompt text. When the listType is list, the reference object is the children element; when the listType is picture, the reference object is the picture list. Optional values left , right , bottom (In picture wall mode, promptPosition is only supported after v1.3.0) | string | 'right' | |
renderFileItem | Custom rendering of fileCard | (renderProps: RenderFileItemProps) => ReactNode | 1.0.0 | |
renderFileOperation | Custom list item operation area | (renderProps: RenderFileItemProps)=>ReactNode | 2.5.0 | |
renderPicInfo | Custom photo wall information, only valid in photo wall mode | (renderProps: RenderFileItemProps)=>ReactNode | 2.2.0 | |
renderPicPreviewIcon | The preview icon displayed when customizing the photo wall hover, only valid in photo wall mode | (renderProps: RenderFileItemProps)=>ReactNode | 2.5.0 | |
renderThumbnail | Custom picture wall thumb, only valid in photo wall mode | (renderProps: RenderFileItemProps)=>ReactNode | 2.2.0 | |
showClear | When limit is not 1 and the current number of uploaded files is greater than 1, whether to show the clear button | boolean | true | 1.0.0 |
showPicInfo | Whether to display picture information, only valid in photo wall mode | boolean | false | 2.2.0 |
showReplace | When the upload is successful, whether to display the replace button inside the fileCard | boolean | false | 1.21.0 |
showRetry | When uploading fails, whether to display the retry button inside the fileCard | boolean | true | 1.0.0 |
showUploadList | Whether to display the file list | boolean | true | |
style | Style | CSSProperties | ||
transformFile | After selecting the file, the callback function before uploading the file can be used to customize the conversion processing of the file | (file:File) => FileItem | 1.0.0 | |
uploadTrigger | Trigger upload timing, optional values auto , custom | string | 'auto' | |
validateMessage | Upload the overall error message | ReactNode | 1.0.0 | |
withCredentials | Whether to bring cookie information | boolean | false |
Accessibility
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.
ARIA
- Add
role="button"
to clickable elements - Add
role="list"
to the file list and describe it witharia-label
Interfaces
FileItem Interface
Methods
Some internal methods provided by Upload can be accessed through ref:
Name | Description | Type | Version |
---|---|---|---|
insert | Upload file, when index is passed, it will be inserted at the specified position, if not passed, it will be inserted at the end | (files: Array<File>, index?: number) => void | 2.2.0 |
upload | Start upload manually, use with uploadTrigger="custom" | () => void | |
openFileDialog | open file select Dialog | () => void | 2.21.0 |
Content Guidelines
- Upload button
- For the copywriting specification of the form button, refer to The content Guidelines of the Button component
- Help text
- The help text is written in sentences, the first letter is capitalized, and periods may not be required
- Error message
- Clearly tell the user why the file cannot be uploaded, and tell the user how to upload it successfully
- Help texts are written using sentences, capitalized
- 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
Design Tokens
FAQ
- When will the retry button appear?
- 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.
- When
- When will the replace button appear?
- When
showReplace
is true and the current file status is uploaded, the replace button will be displayed.
- When
- Where did Semi save the pictures?
- 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.
- Didn’t call the XXX method after uploading the picture?
- 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.
- If you set