Upload 上传

通过点击或者拖拽上传文件。

基础用法

通过 slot 你可以传入自定义的上传按钮类型和文字提示。可通过设置 limit 和 on-exceed 来限制上传文件的个数和定义超出限制时的行为。可通过设置 before-remove 来阻止文件移除操作。

jpg/png files with a size less than 500KB.

element-plus-logo.svg
element-plus-logo2.svg

export function UploadBasic() {  const [fileList, setFileList] = useState<UploadUserFile[]>(INITIAL_FILES);  const handleRemove: UploadProps["onRemove"] = (file, uploadFiles) => {    console.log(file, uploadFiles);  };  const handlePreview: UploadProps["onPreview"] = (uploadFile) => {    console.log(uploadFile);  };  const handleExceed: UploadProps["onExceed"] = (files, uploadFiles) => {    message.warning(      `The limit is 3, you selected ${files.length} files this time, add up to ${        files.length + uploadFiles.length      } totally`,    );  };  const beforeRemove: UploadProps["beforeRemove"] = (uploadFile) => {    return MessageBox.confirm(`Cancel the transfer of ${uploadFile.name} ?`).then(      () => true,      () => false,    );  };  return (    <ElUpload      fileList={fileList}      onFileListChange={setFileList}      action={ACTION}      multiple      onPreview={handlePreview}      onRemove={handleRemove}      beforeRemove={beforeRemove}      limit={3}      onExceed={handleExceed}      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500KB.        </div>      }    >      <ElButton type="primary">Click to upload</ElButton>    </ElUpload>  );}

覆盖前一个文件

设置 limit 和 on-exceed 可以在选中时自动替换上一个文件。

limit 1 file, new file will cover the old file

export function UploadLimitCover() {  const uploadRef = useRef<UploadExpose>(null);  const handleExceed: UploadProps["onExceed"] = (files) => {    uploadRef.current?.clearFiles();    const file = files[0] as UploadRawFile;    file.uid = genFileId();    uploadRef.current?.handleStart(file);  };  const submitUpload = () => {    uploadRef.current?.submit();  };  return (    <ElUpload      ref={uploadRef}      action={ACTION}      limit={1}      onExceed={handleExceed}      autoUpload={false}      trigger={<ElButton type="primary">select file</ElButton>}      tip={        <div className="el-upload__tip" style={{ color: "#f87171" }}>          limit 1 file, new file will cover the old file        </div>      }    >      <ElButton type="success" style={gapLeftStyle} onClick={submitUpload}>        upload to server      </ElButton>    </ElUpload>  );}

用户头像

在 before-upload 钩子中限制用户上传文件的格式和大小。

export function UploadAvatar() {  const [imageUrl, setImageUrl] = useState("");  const handleAvatarSuccess: UploadProps["onSuccess"] = (_response, uploadFile) => {    if (uploadFile.raw) setImageUrl(URL.createObjectURL(uploadFile.raw));  };  const beforeAvatarUpload: UploadProps["beforeUpload"] = (rawFile) => {    if (rawFile.type !== "image/jpeg") {      message.error("Avatar picture must be JPG format!");      return false;    } else if (rawFile.size / 1024 / 1024 > 2) {      message.error("Avatar picture size can not exceed 2MB!");      return false;    }    return true;  };  return (    <ElUpload      className={`avatar-uploader ${styles.avatarUploader}`}      action={ACTION}      showFileList={false}      onSuccess={handleAvatarSuccess}      beforeUpload={beforeAvatarUpload}    >      {imageUrl ? (        <img src={imageUrl} style={avatarImgStyle} alt="" />      ) : (        <ElIcon className="avatar-uploader-icon" style={avatarIconStyle}>          <Plus />        </ElIcon>      )}    </ElUpload>  );}

照片墙

使用 list-type 属性来设定文件列表的样式。

export function UploadPhotoWall() {  const [fileList, setFileList] = useState<UploadUserFile[]>(PHOTO_WALL_FILES);  const [dialogImageUrl, setDialogImageUrl] = useState("");  const [dialogVisible, setDialogVisible] = useState(false);  const handleRemove: UploadProps["onRemove"] = (uploadFile, uploadFiles) => {    console.log(uploadFile, uploadFiles);  };  const handlePictureCardPreview: UploadProps["onPreview"] = (uploadFile) => {    setDialogImageUrl(uploadFile.url ?? "");    setDialogVisible(true);  };  return (    <>      <ElUpload        fileList={fileList}        onFileListChange={setFileList}        action={ACTION}        listType="picture-card"        onPreview={handlePictureCardPreview}        onRemove={handleRemove}      >        <ElIcon>          <Plus />        </ElIcon>      </ElUpload>      <ElDialog visible={dialogVisible} onVisibleChange={setDialogVisible}>        <img src={dialogImageUrl} alt="Preview Image" style={{ width: "100%" }} />      </ElDialog>    </>  );}

自定义缩略图

使用 scoped-slot 属性来改变默认的缩略图模板样式。

export function UploadCustomThumbnail() {  const [dialogImageUrl, setDialogImageUrl] = useState("");  const [dialogVisible, setDialogVisible] = useState(false);  const handleRemove = (file: UploadFile) => {    console.log(file);  };  const handlePictureCardPreview = (file: UploadFile) => {    setDialogImageUrl(file.url ?? "");    setDialogVisible(true);  };  const handleDownload = (file: UploadFile) => {    console.log(file);  };  return (    <>      <ElUpload        action="#"        listType="picture-card"        autoUpload={false}        renderFile={(file) => (          <div>            <img className="el-upload-list__item-thumbnail" src={file.url} alt="" />            <span className="el-upload-list__item-actions">              <span                className="el-upload-list__item-preview"                onClick={() => handlePictureCardPreview(file)}              >                <ElIcon>                  <ZoomIn />                </ElIcon>              </span>              <span                className="el-upload-list__item-delete"                onClick={() => handleDownload(file)}              >                <ElIcon>                  <Download />                </ElIcon>              </span>              <span                className="el-upload-list__item-delete"                onClick={() => handleRemove(file)}              >                <ElIcon>                  <Delete />                </ElIcon>              </span>            </span>          </div>        )}      >        <ElIcon>          <Plus />        </ElIcon>      </ElUpload>      <ElDialog visible={dialogVisible} onVisibleChange={setDialogVisible}>        <img src={dialogImageUrl} alt="Preview Image" style={{ width: "100%" }} />      </ElDialog>    </>  );}

图片列表缩略图

jpg/png files with a size less than 500kb

food.jpeg
food2.jpeg

export function UploadFileListWithThumbnail() {  const [fileList, setFileList] = useState<UploadUserFile[]>(PICTURE_FILES);  const handleRemove: UploadProps["onRemove"] = (uploadFile, uploadFiles) => {    console.log(uploadFile, uploadFiles);  };  const handlePreview: UploadProps["onPreview"] = (file) => {    console.log(file);  };  return (    <ElUpload      fileList={fileList}      onFileListChange={setFileList}      action={ACTION}      onPreview={handlePreview}      onRemove={handleRemove}      listType="picture"      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500kb        </div>      }    >      <ElButton type="primary">Click to upload</ElButton>    </ElUpload>  );}

上传文件列表控制

通过 on-change 钩子函数来对上传文件的列表进行控制。

jpg/png files with a size less than 500kb

food.jpeg
food2.jpeg

export function UploadFileList() {  const [fileList, setFileList] = useState<UploadUserFile[]>(PICTURE_FILES);  const handleChange: UploadProps["onChange"] = () => {    setFileList((prev) => prev.slice(-3));  };  return (    <ElUpload      fileList={fileList}      onFileListChange={setFileList}      action={ACTION}      onChange={handleChange}      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500kb        </div>      }    >      <ElButton type="primary">Click to upload</ElButton>    </ElUpload>  );}

拖拽上传

你可以将文件拖拽到特定区域以进行上传。

Drop file here or click to upload

jpg/png files with a size less than 500kb

export function UploadDragAndDrop() {  return (    <ElUpload      action={ACTION}      drag      multiple      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500kb        </div>      }    >      <ElIcon className="el-icon--upload">        <UploadFilled />      </ElIcon>      <div className="el-upload__text">        Drop file here or <em>click to upload</em>      </div>    </ElUpload>  );}

上传目录 2.13.1

通过 directory 属性启用文件夹上传。

启用后，只能选择文件夹；选择文件夹后，文件夹内的文件将被扁平化处理。

Drop directory here or click to upload

export function UploadDirectory() {  const handleChange = (uploadFile: UploadFile, uploadFiles: UploadFile[]) => {    console.log(uploadFile, uploadFiles);  };  return (    <ElUpload      action={ACTION}      drag      directory      multiple      onChange={handleChange}    >      <ElIcon className="el-icon--upload">        <UploadFilled />      </ElIcon>      <div className="el-upload__text">        Drop directory here or <em>click to upload</em>      </div>    </ElUpload>  );}

手动上传

jpg/png files with a size less than 500kb

export function UploadManual() {  const uploadRef = useRef<UploadExpose>(null);  const submitUpload = () => {    uploadRef.current?.submit();  };  return (    <ElUpload      ref={uploadRef}      action={ACTION}      autoUpload={false}      trigger={<ElButton type="primary">select file</ElButton>}      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500kb        </div>      }    >      <ElButton type="success" style={gapLeftStyle} onClick={submitUpload}>        upload to server      </ElButton>    </ElUpload>  );}

Upload API

Attributes

属性名	说明	类型	默认值
action	请求 URL	`string`	'#'
headers	请求头	`object`	—
method	请求方法	`string`	post
data	附加请求参数，支持对象 / Promise / `(rawFile) => Awaitable`	`object` / `Function`	{}
multiple	是否允许多选	`boolean`	false
name	上传字段名	`string`	file
withCredentials	是否携带 cookie	`boolean`	false
showFileList	是否展示文件列表	`boolean`	true
drag	是否开启拖拽上传	`boolean`	false
accept	接受的文件类型	`string`	''
crossorigin	原生 crossorigin	`enum`	—
directory	是否支持选择目录（选中后扁平化）	`boolean`	false
autoUpload	是否自动上传	`boolean`	true
listType	文件列表类型	`enum`	text
httpRequest	覆盖默认 xhr 行为	`Function`	ajaxUpload
disabled	是否禁用	`boolean`	false
limit	最大上传数量	`number`	—
fileList	默认文件列表	`array`	[]
beforeUpload	上传前钩子，返回 false 或 reject 会中断	`Function`	—
beforeRemove	移除前钩子，返回 false 或 reject 会中断	`Function`	—
className / style	根元素类名与样式	`string` / `object`	—

Events

事件名	说明	参数
onFileListChange	文件列表变化，对应官方 v-model:file-list	`Function`
onRemove	移除文件时触发	`Function`
onChange	选择文件 / 上传成功 / 上传失败时触发	`Function`
onPreview	点击已上传文件时触发	`Function`
onSuccess	上传成功	`Function`
onProgress	上传进度变化	`Function`
onError	上传出错	`Function`
onExceed	超出 limit 时触发	`Function`

Slots（以 props 表达）

属性名	说明	类型
children	默认内容，无 trigger 时作为触发器	`ReactNode`
trigger	触发器内容，对应官方 trigger 插槽	`ReactNode`
tip	提示文案，对应官方 tip 插槽	`ReactNode`
renderFile	自定义缩略图模板，对应官方 file 插槽	`Function`

Exposes（通过 ref 访问）

名称	说明
abort	取消上传请求，传 file 只取消对应文件，省略则取消全部
submit	手动上传列表中 ready 状态的文件
clearFiles	清空文件列表，可按状态过滤
handleStart	手动把原始文件加入列表
handleRemove	手动移除文件