Upload上传

文件选择上传和拖拽上传控件。

何时使用#

上传是将信息(网页、文字、图片、视频等)通过网页或者上传工具发布到远程服务器上的过程。

  • 当需要上传一个或一些文件时。
  • 当需要展现上传的进度时。
  • 当需要使用拖拽交互时。
import { NzUploadModule } from 'ng-zorro-antd/upload';

代码演示

经典款式,用户点击按钮弹出文件选择框。

expand codeexpand code
加载中

使用 nzFileList 设置已上传的内容。

expand codeexpand code
加载中

使用 nzFileList 对列表进行完全控制,可以实现各种自定义功能,以下演示二种情况:

  1. 上传列表数量的限制。

  2. 读取远程路径并显示链接。

expand codeexpand code
加载中

支持上传一个文件夹里的所有文件。

expand codeexpand code
加载中
yyy.png


yyy.png

上传文件为图片,可展示本地缩略图。IE8/9 不支持浏览器本地缩略图展示(Ref),可以写 thumbUrl 属性来代替。

expand codeexpand code
加载中

使用 nzTransformFile 转换上传的文件(例如添加水印)。

expand codeexpand code
加载中
Upload

点击上传用户头像,并使用 nzBeforeUpload 限制用户上传的图片格式和大小。

nzBeforeUpload 的返回值可以是一个 Observable 以支持也支持异步检查。

expand codeexpand code
加载中
文件上传中
image.png
image.png
Upload

用户可以上传图片并在列表中显示缩略图。当上传照片数到达限制后,上传按钮消失。

expand codeexpand code
加载中

Click or drag file to this area to upload

Support for a single or bulk upload. Strictly prohibit from uploading company data or other band files

把文件拖入指定区域,完成上传,同样支持点击上传。

设置 nzMultiple 后,在 IE10+ 可以一次上传多个文件。

expand codeexpand code
加载中

nzBeforeUpload 返回 false 后,手动上传文件。

expand codeexpand code
加载中

自定义本地预览,用于处理非图片格式文件(例如视频文件)。

expand codeexpand code
加载中
Photos:

使用阿里云 OSS 上传示例.

expand codeexpand code
加载中

API#

服务端上传接口实现可以参考 jQuery-File-Upload

nz-upload#

参数说明类型默认值
[nzAccept]接受上传的文件类型, 详见 input accept Attributestring-
[nzAction]必选参数, 上传的地址string | ((file: NzUploadFile) => string | Observable<string>)-
[nzDirectory]支持上传文件夹(caniusebooleanfalse
[nzBeforeUpload]上传文件之前的钩子,参数为上传的文件,若返回 false 则停止上传。注意:IE9 不支持该方法;注意:务必使用 => 定义处理方法。(file: NzUploadFile, fileList: NzUploadFile[]) => boolean | Observable<boolean>-
[nzCustomRequest]通过覆盖默认的上传行为,可以自定义自己的上传实现;注意:务必使用 => 定义处理方法。(item) => Subscription-
[nzData]上传所需参数或返回上传参数的方法;注意:务必使用 => 定义处理方法。Object | ((file: NzUploadFile) => Object | Observable<{}>)-
[nzDisabled]是否禁用booleanfalse
[nzFileList]文件列表,双向绑定NzUploadFile[]-
[nzLimit]限制单次最多上传数量,nzMultiple 打开时有效;0 表示不限number0
[nzSize]限制文件大小,单位:KB;0 表示不限number0
[nzFileType]限制文件类型,例如:image/png,image/jpeg,image/gif,image/bmpstring-
[nzFilter]自定义过滤器UploadFilter[]-
[nzHeaders]设置上传的请求头部,IE10 以上有效;注意:务必使用 => 定义处理方法。Object | ((file: NzUploadFile) => Object | Observable<{}>)-
[nzListType]上传列表的内建样式,支持三种基本样式 text, picturepicture-card'text' | 'picture' | 'picture-card''text'
[nzMultiple]是否支持多选文件,ie10+ 支持。开启后按住 ctrl 可选择多个文件。booleanfalse
[nzName]发到后台的文件参数名string'file'
[nzShowUploadList]是否展示 uploadList, 可设为一个对象,用于单独设定 showPreviewIconshowRemoveIconshowDownloadIconboolean | { showPreviewIcon?: boolean, showRemoveIcon?: boolean, showDownloadIcon?: boolean }true
[nzShowButton]是否展示上传按钮booleantrue
[nzWithCredentials]上传请求时是否携带 cookiebooleanfalse
[nzOpenFileDialogOnClick]点击打开文件对话框booleantrue
[nzPreview]点击文件链接或预览图标时的回调;注意:务必使用 => 定义处理方法。(file: NzUploadFile) => void-
[nzPreviewFile]自定义文件预览逻辑;注意:务必使用 => 定义处理方法。(file: NzUploadFile) => Observable<dataURL: string>-
[nzPreviewIsImage]自定义预览文件是否有效图像,一般用于图像 URL 为非标准格式;注意:务必使用 => 定义处理方法。(file: NzUploadFile) => boolean-
[nzRemove]点击移除文件时的回调,返回值为 false 时不移除。支持返回 Observable 对象;注意:务必使用 => 定义处理方法。(file: NzUploadFile) => boolean | Observable<boolean>-
(nzChange)上传文件改变时的状态EventEmitter<NzUploadChangeParam>-
[nzDownload]点击下载文件时的回调,如果没有指定,则默认跳转到文件 url 对应的标签页(file: NzUploadFile) => void跳转新标签页
[nzTransformFile]在上传之前转换文件。支持返回一个 Observable 对象(file: NzUploadFile) => NzUploadTransformFileType-
[nzIconRender]自定义显示 iconTemplateRef<{ $implicit: NzUploadFile }>-
[nzFileListRender]自定义显示整个列表TemplateRef<{ $implicit: NzUploadFile[] }>-

nzChange#

开始、上传进度、完成、失败都会调用这个函数。

文件状态改变的回调,返回为:

{
  file: { /* ... */ },
  fileList: [ /* ... */ ],
  event: { /* ... */ },
}
  1. file 当前操作的文件对象。

    {
       uid: 'uid',      // 文件唯一标识
       name: 'xx.png'   // 文件名
       status: 'done', // 状态有:uploading done error removed
       response: '{"status": "success"}', // 服务端响应内容
       linkProps: '{"download": "image"}', // 下载链接额外的 HTML 属性
    }
  2. fileList 当前的文件列表。

  3. event 上传中的服务端响应内容,包含了上传进度等信息,高级浏览器支持。

nzCustomRequest#

默认使用 HTML5 方式上传(即:使用 HttpClient),允许覆盖默认行为实现定制需求,例如直接与阿里云交互等。

nzCustomRequest 回调传递以下参数:

  • onProgress: (event: { percent: number }): void
  • onError: (event: Error): void
  • onSuccess: (body: Object, xhr?: Object): void
  • data: Object
  • filename: String
  • file: File
  • withCredentials: Boolean
  • action: String
  • headers: Object