UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本指南以 ng-zorro-antd 的 Upload上传组件为核心系统讲解文件选择上传、拖拽上传的完整用法、nz-upload全部 API 参数、状态回调与自定义上传实现并结合仓库源码components/upload剖析其底层上传链路、过滤器机制与nzCustomRequest扩展点。读完本文你将能在一个 Angular 应用中从零搭建支持进度展示、图片预览、手动上传、阿里云 OSS 直传等场景的完整上传方案。何时使用 Upload 组件上传是将信息网页、文字、图片、视频等通过网页或者上传工具发布到远程服务器上的过程。以下场景适合使用本组件当需要上传一个或一些文件时。当需要展现上传的进度时。当需要使用拖拽交互时。组件支持两种交互形态nzTypeselect点击选择与drag拖拽区域列表展示支持text、picture、picture-card三种内建样式。快速上手第一个上传示例引入NzUploadModule后在模板中使用nz-upload标签并传入必选的nzAction上传地址。参考仓库示例 components/upload/demo/basic.tsimport { Component, inject } from angular/core; import { NzButtonModule } from ng-zorro-antd/button; import { NzIconModule } from ng-zorro-antd/icon; import { NzMessageService } from ng-zorro-antd/message; import { NzUploadChangeParam, NzUploadModule } from ng-zorro-antd/upload; Component({ selector: nz-demo-upload-basic, imports: [NzButtonModule, NzIconModule, NzUploadModule], template: nz-upload nzActionhttps://www.mocky.io/v2/5cc8019d300000980a055e76 [nzHeaders]{ authorization: authorization-text } (nzChange)handleChange($event) button nz-button nz-icon nzTypeupload / Click to Upload /button /nz-upload }) export class NzDemoUploadBasicComponent { private readonly messageService inject(NzMessageService); handleChange(info: NzUploadChangeParam): void { if (info.file.status ! uploading) { console.log(info.file, info.fileList); } if (info.file.status done) { this.messageService.success(${info.file.name} file uploaded successfully); } else if (info.file.status error) { this.messageService.error(${info.file.name} file upload failed.); } } }nz-upload的默认实现基于 HTML5 方式上传内部使用 Angular 的HttpClient因此你的应用需要配置HttpClient如根模块中使用provideHttpClient()。若未提供组件构造函数会直接抛出错误相关校验见 components/upload/upload-btn.component.ts。nz-upload API 全参数详解服务端上传接口实现可参考 jQuery-File-Upload 的思路Multipart/form-data 表单提交 进度回调。参数总表参数说明类型默认值[nzId]组件内部 input 的 id 值string-[nzAccept]接受上传的文件类型详见 HTMLinput accept属性规范string-[nzAction]必选参数上传的地址string \| ((file: NzUploadFile) string \| Observablestring)-[nzDirectory]支持上传文件夹booleanfalse[nzBeforeUpload]上传文件之前的钩子参数为上传的文件若返回false则停止上传。注意IE9 不支持该方法务必使用定义处理方法(file: NzUploadFile, fileList: NzUploadFile[]) boolean \| Observableboolean-[nzCustomRequest]通过覆盖默认的上传行为可以自定义自己的上传实现务必使用定义处理方法(item) Subscription-[nzData]上传所需参数或返回上传参数的方法务必使用定义处理方法Object \| ((file: NzUploadFile) Object \| Observable{})-[nzDisabled]是否禁用booleanfalse[nzFileList]文件列表双向绑定NzUploadFile[]-[nzLimit]限制单次最多上传数量nzMultiple打开时有效0表示不限number0[nzMaxCount]限制上传数量。当为 1 时始终用最新上传的文件代替当前文件number\|undefinedundefined[nzSize]限制文件大小单位KB0表示不限number0[nzFileType]限制文件类型例如image/png,image/jpeg,image/gif,image/bmpstring-[nzFilter]自定义过滤器UploadFilter[]-[nzHeaders]设置上传的请求头部IE10 以上有效务必使用定义处理方法Object \| ((file: NzUploadFile) Object \| Observable{})-[nzListType]上传列表的内建样式支持三种基本样式text、picture和picture-cardtext \| picture \| picture-cardtext[nzMultiple]是否支持多选文件ie10支持。开启后按住 ctrl 可选择多个文件booleanfalse[nzName]发到后台的文件参数名stringfile[nzShowUploadList]是否展示 uploadList可设为一个对象用于单独设定extra、showPreviewIcon、showRemoveIcon、showDownloadIcon、previewIcon、removeIcon和downloadIconboolean \| NzShowUploadListtrue[nzShowButton]是否展示上传按钮booleantrue[nzWithCredentials]上传请求时是否携带 cookiebooleanfalse[nzOpenFileDialogOnClick]点击打开文件对话框booleantrue[nzPreview]点击文件链接或预览图标时的回调务必使用定义处理方法(file: NzUploadFile) void-[nzPreviewFile]自定义文件预览逻辑务必使用定义处理方法(file: NzUploadFile) ObservabledataURL: string-[nzPreviewIsImage]自定义预览文件是否有效图像一般用于图像 URL 为非标准格式务必使用定义处理方法(file: NzUploadFile) boolean-[nzRemove]点击移除文件时的回调返回值为 false 时不移除。支持返回Observable对象务必使用定义处理方法(file: NzUploadFile) boolean \| Observableboolean-(nzChange)上传文件改变时的状态EventEmitterNzUploadChangeParam-[nzDownload]点击下载文件时的回调如果没有指定则默认跳转到文件 url 对应的标签页(file: NzUploadFile) void跳转新标签页[nzIconRender]自定义显示 iconTemplateRef{ $implicit: NzUploadFile }-[nzFileListRender]自定义显示整个列表TemplateRef{ $implicit: NzUploadFile[] }-上述参数在组件源码 components/upload/upload.component.ts 中均有对应Input()定义其中nzId、nzMaxCount采用新式input()信号写法nzLimit、nzSize通过numberAttribute转换nzDirectory、nzMultiple、nzDisabled、nzWithCredentials、nzShowButton、nzOpenFileDialogOnClick等布尔参数通过booleanAttribute自动转换因此模板中可直接写nzMultiple而不必传值。文件选择与限制类参数nzAccept对应原生input typefile的accept属性浏览器据此过滤文件选择器中的可选项。值得留意的是源码中attrAccept方法components/upload/upload-btn.component.ts对拖拽drop进入的文件也会做类型校验支持以.开头的扩展名匹配、image/*通配的 MIME 前缀匹配以及精确 MIME 类型匹配。nzMultiple开启多选ie10支持按住 ctrl 可一次选择多个文件。nzLimit与nzMultiple配合使用限制单次最多上传数量0表示不限。nzMaxCount限制文件列表总数。当设为1时新上传的文件会直接替换当前文件。源码中的实现位于 components/upload/upload.component.tsmaxCount 1时文件列表重置为[targetItem]否则仅在当前列表长度小于maxCount时才追加。nzSize文件大小上限单位 KB0表示不限。nzFileType文件 MIME 类型白名单如image/png,image/jpeg,image/gif,image/bmp。nzDirectory开启文件夹上传能力依赖浏览器对input-file-directory的支持。请求配置类参数nzAction必选上传地址可以是静态字符串也可以是根据文件动态返回地址的函数甚至返回Observablestring异步解析地址。nzName表单字段名默认file即FormData中携带文件的 key。nzData随请求携带的额外参数可以是对象、返回对象的函数或返回Observable{}的异步函数。nzHeaders上传请求的自定义请求头IE10 以上有效。nzWithCredentials请求是否携带 cookie对应XMLHttpRequest的withCredentials。列表展示与交互类参数nzListType列表样式text文本列表、picture带缩略图列表、picture-card卡片式网格常用于头像/图片上传。nzShowUploadListboolean或NzShowUploadList对象对象可单独控制showPreviewIcon、showRemoveIcon、showDownloadIcon三个布尔开关以及通过extra、previewIcon、removeIcon、downloadIcon传入自定义TemplateRef渲染图标。其类型定义见 components/upload/interface.ts。nzShowButton控制是否渲染上传按钮本身picture-card场景常结合文件数量动态隐藏。nzPreview/nzPreviewFile/nzPreviewIsImage预览相关回调分别处理点击预览、自定义预览逻辑返回 dataURL 的 Observable、自定义图片判定。nzRemove移除文件前的回调返回false或 Observable 发出false时不真正移除。nzDownload点击下载回调缺省时打开文件 url 新标签页。nzIconRender/nzFileListRender分别自定义单项图标与整个文件列表模板。nzChange 文件状态回调nzChange是 Upload 组件最核心的事件输出开始、上传进度、完成、失败都会调用这个函数。回调参数NzUploadChangeParam结构如下{ file: { /* ... */ }, fileList: [ /* ... */ ], event: { /* ... */ }, }file当前操作的文件对象{ uid: uid, // 文件唯一标识 name: xx.png // 文件名 status: done, // 状态有uploading done error removed response: {status: success}, // 服务端响应内容 linkProps: {download: image}, // 下载链接额外的 HTML 属性 }fileList当前的文件列表。event上传中的服务端响应内容包含了上传进度等信息高级浏览器支持。类型层面UploadFileStatus定义为error | success | done | uploading | removed完整文件对象NzUploadFile还包含size、type、url、percent、thumbUrl、originFileObj等字段且支持索引签名扩展任意自定义字段见 components/upload/interface.ts。结合源码可知nzChange每次触发都会携带type字段start/progress/success/error/removedonStart文件加入列表、状态置为uploading时触发upload.component.ts。onProgressHttpEventType.UploadProgress事件到达时按loaded / total * 100计算百分比并更新file.percent后触发upload-btn.component.ts。onSuccess收到HttpResponse后将file.status置为done、写入file.response后触发。onError请求出错时将file.status置为error、写入file.error后触发。onRemove移除确认后置为removed并从列表删除后触发。nzCustomRequest 自定义上传请求默认使用 HTML5 方式上传即使用HttpClientnzCustomRequest允许覆盖默认行为实现定制需求例如直接与阿里云 OSS 等第三方存储交互。nzCustomRequest回调传递以下参数onProgress: (event: { percent: number }): voidonError: (event: Error): voidonSuccess: (body: Object, xhr?: Object): voiddata: Objectfilename: Stringfile: FilewithCredentials: Booleanaction: Stringheaders: Object这些参数被归纳为NzUploadXHRArgs类型components/upload/interface.ts。注意nzCustomRequest的返回值必须是Subscription否则源码会输出警告Must return Subscription type in [nzCustomRequest] propertyupload-btn.component.ts组件据此统一管理请求的生命周期this.reqs[uid]并在组件销毁或文件移除时通过abort()取消对应订阅。源码级剖析上传内部链路内建过滤器机制nzSize、nzFileType、nzLimit三个限制参数在内部并非独立处理而是被转换为统一的UploadFilter管道。UploadFilter类型为{ name: string; fn(fileList: NzUploadFile[]): NzUploadFile[] | ObservableNzUploadFile[] }interface.ts。在 upload.component.ts 的zipOptions()中当nzMultiple nzLimit 0且不存在名为limit的过滤器时追加fn: list list.slice(-this.nzLimit)取最后 N 个文件当nzSize 0时追加fn: list list.filter(w w.size! / 1024 this.nzSize)KB 换算后过滤当nzFileType非空时按逗号切分并追加 MIME 类型匹配过滤器。同时你也可以通过nzFilter传入自定义过滤器数组。执行时 upload-btn.component.ts 会用switchMap将这些过滤器串成一条 RxJS 管道逐级过滤后再进入上传流程过滤异常会通过warn记录日志而不会中断程序。beforeUpload 钩子与文件转换nzBeforeUpload是上传前拦截点返回false停止上传。但它不止能拦截还能转换文件源码中successBeforeLoadHook会判断处理结果upload-btn.component.ts返回File或Blob时会把原始文件的uid赋给转换后的文件然后以转换结果作为上传实体返回true时按原文件上传返回false时放弃本次上传支持同步返回值、Observable与Promise三种形式。这也是 components/upload/demo/transform-file.ts 中用 canvas 给图片加水印后再上传这一能力的底层支撑先用FileReader读为 dataURL绘制到 canvascanvas.toBlob生成新Blob并通过 Observable 返回。默认 XHR 实现若未提供nzCustomRequest组件走内置xhr()方法upload-btn.component.ts构造FormData将nzData的每个 key 依次append以nzName默认file为字段名 append 文件本体默认注入X-Requested-With: XMLHttpRequest头除非显式置null删除创建HttpRequest(POST, action, formData)开启reportProgress: true以接收上传进度事件订阅请求UploadProgress事件换算percent后回调onProgressHttpResponse触发onSuccess错误则先abort再回调onError。可见进度条、成功/失败状态全部由这条 HttpClient 链路驱动与nzChange的回调紧密联动。实战场景示例拖拽上传设置nzTypedrag并在标签内提供拖拽提示文案见 components/upload/demo/drag.ts。组件对dragover/drop事件做了兼容处理源码中还针对 Firefox 修复了拖拽后打开新标签页的浏览器缺陷upload.component.ts。nz-upload nzTypedrag [nzMultiple]true nzActionhttps://www.mocky.io/v2/5cc8019d300000980a055e76 (nzChange)handleChange($event) p classant-upload-drag-iconnz-icon nzTypeinbox //p p classant-upload-textClick or drag file to this area to upload/p p classant-upload-hintSupport for a single or bulk upload./p /nz-upload图片卡片上传与预览nzListTypepicture-card以卡片网格展示图片常配合nzPreview弹窗预览。参考 components/upload/demo/picture-card.ts预览时若文件没有url或preview先用FileReader.readAsDataURL生成 base64 缩略图再结合nz-modal全屏展示同时用[nzShowButton]fileList().length 8控制上传按钮是否继续显示。手动控制上传让nzBeforeUpload返回false即可阻止自动上传文件仅进入列表由业务自行触发上传。参考 components/upload/demo/upload-manually.tsbeforeUpload (file: NzUploadFile): boolean { this.fileList.update(fileList fileList.concat(file)); return false; }; handleUpload(): void { const formData new FormData(); this.fileList().forEach((file: any) formData.append(files[], file)); // 使用 HttpClient 或其他任意 AJAX 库发起请求 }阿里云 OSS 直传组合nzActionOSS host、nzData签名参数、nzBeforeUpload生成对象 key即可绕过业务服务器直传 OSS完整示例见 components/upload/demo/upload-with-aliyun-oss.tsbeforeUpload (file: NzUploadFile): boolean { const suffix file.name.slice(file.name.lastIndexOf(.)); const filename Date.now() suffix; file.url this.mockOSSData.dir filename; return true; }; getExtraData (file: NzUploadFile): {} { const { accessId, policy, signature } this.mockOSSData; return { key: file.url, OSSAccessKeyId: accessId, policy, Signature: signature }; };默认文件列表与自定义错误文案通过[nzFileList]传入已存在的文件status: done、url等即可回显服务端已有文件当status: error且response为字符串时该字符串会作为错误提示展示。参考 components/upload/demo/default-file-list.ts。数量上限控制nzMaxCount限制列表总量1表示始终以最新文件替换旧文件3表示最多保留 3 个配合nzChange在done/error状态弹出 message 提示参考 components/upload/demo/max-count.ts。常见问题与注意事项nzBeforeUpload等方法务必用箭头函数定义确保this指向组件实例否则回调中访问不到业务状态。nzCustomRequest必须返回Subscription用于组件统一管理取消与销毁清理。nzFileList为双向绑定组件通过nzFileListChange输出变更模板中可用[(nzFileList)]fileList语法或配合signalNzUploadFile[]使用。nzWithCredentials默认false跨域携带 Cookie 场景需显式开启且服务端需配合Access-Control-Allow-Credentials。IE 兼容边界nzBeforeUpload在 IE9 不支持nzHeaders在 IE10 以上有效nzMultiple依赖ie10文件夹上传依赖浏览器对 directory 的支持。Firefox 拖拽缺陷已内置修复组件会在document.body上监听drop并preventDefault避免拖拽文件到页面时误打开新标签页。必须提供HttpClient默认上传链路依赖provideHttpClient()注入缺失时组件构造直接抛错这是最常见的初始化报错原因。完整源码与全部 13 个官方示例位于仓库 components/upload 目录示例在demo/子目录组件实现为upload.component.ts、upload-btn.component.ts、upload-list.component.ts类型定义在interface.ts可结合阅读以获得对上传链路的整体把握。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd Upload 组件实战使用 nzBeforeUpload 实现只上传 PNG 文件ng zorro antd Upload 组件实战使用 nzBeforeUpload 实现只上传 PNG 文件 nzBeforeUpload 是 ng zorUI组件前端ng-zorro-antd Upload 组件完全指南从 API 配置到自定义上传实现ng zorro antd Upload 组件完全指南从 API 配置到自定义上传实现 ng zorro antd 的 nz upload 组件基于 AntUI组件前端ng-zorro-antd Upload 文件夹上传nzDirectory实战指南从目录选择到递归上传全解析ng zorro antd Upload 文件夹上传nzDirectory实战指南从目录选择到递归上传全解析 本篇技术指南聚焦 ng zorro antdUI组件前端上一篇PaySharp 项目推荐下一篇Go接口设计终极指南5分钟掌握多态与鸭子类型精髓创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考