UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载ng-zorro-antd 的nz-upload组件基于 Ant Design 设计语言为 Angular 应用提供文件选择上传与拖拽上传能力支持上传进度展示、多文件批量上传、文件夹上传、图片预览、上传前拦截/转换以及自定义上传请求如直传阿里云 OSS等完整交互。本文以官方文档 components/upload/doc/index.en-US.md对应中文版 components/upload/doc/index.zh-CN.md为骨架结合仓库内 Demo 与源码实现系统讲解全部输入输出属性、状态回调与进阶定制方案读完即可在真实项目中落地可运行的完整上传功能。何时使用 Upload上传是将信息网页、文字、图片、视频等通过网页或上传工具发布到远程服务器的过程。nz-upload适用于以下典型场景需要上传一个或多个文件时需要向用户展示上传进度时需要拖拽文件到指定区域完成上传时。nz-upload API 全览服务端上传接口的具体实现方案可参考 jQuery-File-Upload 的 Wiki 文档社区资源仓库文档原链接指向该外部项目。本文默认你已具备一个可接收 multipart/form-data 的 POST 接口。组件在仓库中的入口为components/upload/index.ts核心实现位于components/upload/upload.component.ts。使用前需在模块中引入NzUploadModule见 components/upload/upload.module.ts并可从ng-zorro-antd/upload导出NzUploadFile、NzUploadChangeParam等类型见 components/upload/interface.ts。输入属性Input属性说明类型默认值[nzId]组件内部 input 的 id 值string-[nzAccept]接受上传的文件类型详见 HTML input 的 accept Attribute 规范string-[nzAction]必选参数上传的地址string \| ((file: NzUploadFile) string \| Observablestring)-[nzDirectory]是否支持上传整个文件夹依赖浏览器对input[typefile]目录选择的支持booleanfalse[nzBeforeUpload]上传文件之前的钩子返回false或Observable则停止上传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-card三种text \| picture \| picture-cardtext[nzMultiple]是否支持多选文件IE10支持开启后按住 Ctrl 可选择多个文件booleanfalse[nzName]发到后台的文件参数字段名stringfile[nzShowUploadList]是否展示默认上传列表可传对象单独控制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或Observablefalse时不移除务必使用定义方法(file: NzUploadFile) boolean \| Observableboolean-[nzDownload]点击下载文件时的回调不传则默认跳转到文件 URL 对应新标签页(file: NzUploadFile) void跳转新标签页[nzIconRender]自定义显示图标TemplateRef{ $implicit: NzUploadFile }-[nzFileListRender]自定义显示整个文件列表TemplateRef{ $implicit: NzUploadFile[] }-输出事件Output事件说明类型(nzChange)上传文件状态改变时的回调EventEmitterNzUploadChangeParam关于「务必使用定义方法」的源码依据文档对nzBeforeUpload、nzCustomRequest、nzData、nzHeaders、nzPreview、nzPreviewFile、nzPreviewIsImage、nzRemove等均强调必须使用箭头函数。这并非文档笔误而是组件内部会将这些回调作为普通属性读取见 components/upload/upload.component.ts 中对应Input()字段同时组件自身也通过事件订阅把状态回传如upload-btn.component.ts中的onStart、onProgress、onSuccess、onError。若使用非箭头函数回调中的this将指向调用上下文而非你的组件实例无法正确访问组件状态。这一点在编写任何回调时都必须遵守。nzChange上传状态变化回调nzChange在上传进行中、完成或失败时都会被调用返回值结构如下{ file: { /* ... */ }, fileList: [ /* ... */ ], event: { /* ... */ }, }三个字段的含义与内部类型定义见 components/upload/interface.ts 中的NzUploadChangeParam对应如下file当前操作的文件对象其核心字段与对应NzUploadFile接口成员{ uid: uid, // 文件唯一标识必填 name: xx.png, // 文件名必填 status: done, // 状态uploading / done / error / removed / success response: {status: success}, // 服务端响应内容 linkProps: {download: image}, // 文件链接额外的 HTML 属性如强制下载 }从源码NzUploadFile接口components/upload/interface.ts可见文件对象还包含size字节、url、thumbUrl缩略图地址、percent进度百分比、originFileObj原始File对象、error、type等可选字段且通过索引签名[key: string]: NzSafeAny允许携带任意自定义扩展字段——例如 OSS 场景中在nzBeforeUpload里为文件附加的url即属于此类自定义用法。fileList当前的文件列表NzUploadFile[]。event上传过程中的服务端响应内容包含上传进度等仅在高级浏览器中可用对应NzUploadChangeParam.event?: { percent: number }。实战示例基于状态的进度反馈仓库 components/upload/demo/basic.ts 演示了最经典的点击上传与状态处理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 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注意nzAction为必选参数示例使用 mocky.io 的测试接口nzHeaders可用于携带鉴权头。文件状态常量uploading | done | error | removed | success定义于 components/upload/interface.ts 的UploadFileStatus类型success与done在组件内部均视为成功终态。nzCustomRequest完全自定义上传请求默认情况下组件使用 AngularHttpClient以 HTML5 方式完成 multipart 上传。当需要对接自定义后端流程、直传阿里云 OSS通过aws-sdk等 SDK 签名或实现自有 XHR 逻辑时可通过nzCustomRequest覆盖默认行为。nzCustomRequest回调接收一个包含以下字段的对象即源码中的NzUploadXHRArgs见 components/upload/interface.tsonProgress: (event: { percent: number }): void—— 汇报上传进度0-100onError: (event: Error): void—— 上报失败onSuccess: (body: Object, xhr?: Object): void—— 上报成功与响应体data: Object—— 由nzData生成的附加参数filename: String—— 发到后台的文件参数名对应nzNamefile: File—— 原始文件withCredentials: Boolean—— 是否携带 Cookieaction: String—— 上传地址由nzAction解析得到headers: Object—— 请求头。回调返回值类型为Subscription见 components/upload/upload.component.ts 中nzCustomRequest?: (item: NzUploadXHRArgs) Subscription组件通过取消订阅来中断上传。自定义实现内部必须正确调用onProgress/onSuccess/onError三个钩子组件才能驱动文件状态机与 UI 更新。从 Demo 看完整使用场景拖拽上传nzTypedragnz-upload额外支持nzType属性类型为NzUploadType select | drag见 components/upload/interface.ts。仓库 components/upload/demo/drag.ts 展示了拖拽区域写法nz-upload nzTypedrag [nzMultiple]true nzActionhttps://www.mocky.io/v2/5cc8019d300000980a055e76 (nzChange)handleChange($event) p classant-upload-drag-icon nz-icon nzTypeinbox / /p p classant-upload-textClick or drag file to this area to upload/p p classant-upload-hint Support for a single or bulk upload. Strictly prohibit from uploading company data or other band files /p /nz-upload拖拽区域同时保留点击选择能力设置nzMultiple后在IE10浏览器中可一次选择/拖入多个文件。照片墙picture-card与预览nzListTypepicture-card提供照片墙样式上传后列表展示缩略图数量达到限制后上传按钮自动消失。仓库 components/upload/demo/picture-card.ts 是完整可运行的实现关键点包括通过[(nzFileList)]fileList双向绑定维护列表并用[nzShowButton]fileList().length 8控制按钮显隐通过[nzPreview]handlePreview自定义预览逻辑当文件既无url也无preview时用FileReader将originFileObj转成 Base64 dataURL 存入file.preview再弹出nz-modal展示大图预置的fileList覆盖了done、uploading含percent: 50、error三种状态可直接观察各状态的 UI 表现。上传前转换文件nzBeforeUploadnzBeforeUpload不仅能拦截上传还能异步返回新文件对象以实现在请求前转换文件如加水印、压缩。仓库 components/upload/demo/transform-file.ts 演示了用 Canvas 给图片绘制文字水印后返回ObservableBlobtransformFile (file: NzUploadFile): ObservableBlob new Observable(observer { const reader new FileReader(); reader.readAsDataURL(file as NzSafeAny); reader.onload () { const canvas document.createElement(canvas); const img document.createElement(img); img.src reader.result as string; img.onload () { const ctx canvas.getContext(2d)!; ctx.drawImage(img, 0, 0); ctx.fillStyle red; ctx.textBaseline middle; ctx.fillText(Ant Design, 20, 20); canvas.toBlob(blob { observer.next(blob!); observer.complete(); }); }; }; });源码中nzBeforeUpload的完整返回类型为NzBeforeUploadFileType见 components/upload/interface.ts支持boolean、Observable、Promise且 Observable/Promise 的解析结果可以是boolean | NzUploadFile | Blob | File——也就是说你既可以用它做校验拦截也可以异步返回被替换后的文件Blob/File/NzUploadFile继续上传这正是「上传前转换」的原理。手动触发上传upload-manually如果不想选中文件后立即上传可以在nzBeforeUpload中返回false阻止自动上传自行收集文件后调用任意 AJAX 库发送。仓库 components/upload/demo/upload-manually.ts 展示了完整流程beforeUpload (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); }); this.uploading.set(true); // 可以使用任意 AJAX 库 const req new HttpRequest(POST, https://www.mocky.io/v2/5cc8019d300000980a055e76, formData, { // reportProgress: true }); this.http.request(req).pipe(filter(e e instanceof HttpResponse)).subscribe({ ... }); }模板侧在nz-upload上只声明[(nzFileList)]与[nzBeforeUpload]不传nzAction由独立按钮触发批量上传上传成功/失败时清空列表并给出消息提示。直传阿里云 OSS仓库 components/upload/demo/upload-with-aliyun-oss.ts 演示了通过nzBeforeUploadnzDatanzAction组合实现 OSS 直传的关键套路beforeUpload (file: NzUploadFile): boolean { const suffix file.name.slice(file.name.lastIndexOf(.)); const filename Date.now() suffix; file.url this.mockOSSData.dir filename; // 计算对象存储 key return true; }; getExtraData (file: NzUploadFile): {} { const { accessId, policy, signature } this.mockOSSData; return { key: file.url, OSSAccessKeyId: accessId, policy, Signature: signature }; };模板上通过nzNamefile、[nzData]getExtraData、[nzAction]mockOSSData.host将签名参数随 multipart 表单提交到 OSS。实际生产环境中的policy与signature应由服务端动态签发前端仅透传。核心源码实现速览组件主体components/upload/upload.component.ts声明全部nz*输入与nzChange输出注意nzLimit/nzSize使用numberAttribute转换、nzDisabled/nzMultiple等使用booleanAttribute转换模板中可直接写nzDisabled而不必[nzDisabled]true。组件内部组合了上传按钮NzUploadBtnComponent与文件列表NzUploadListComponent。上传按钮components/upload/upload-btn.component.ts负责文件对话框、目录选择、拖拽事件绑定以及beforeUpload过滤链nzFilter与默认HttpClient请求的执行与onStart/onProgress/onSuccess/onError状态上报。文件列表components/upload/upload-list.component.ts渲染text/picture/picture-card三种列表样式处理预览、移除、下载图标交互。类型定义components/upload/interface.ts集中定义了NzUploadFile、NzUploadChangeParam、NzShowUploadList、UploadFilter、NzUploadXHRArgs等全部公共类型是查阅字段细节的第一手资料。测试用例components/upload/upload.spec.ts 与 components/upload/upload-list.spec.ts覆盖状态机切换、nzMaxCount替换、列表图标显隐等行为可作为理解组件边界行为的补充参考。小结nz-upload的 API 设计围绕「选择文件 → 过滤校验nzFilter/nzBeforeUpload/nzSize/nzFileType→ 请求上传nzAction/nzData/nzHeaders/nzCustomRequest→ 状态反馈nzChange→ 列表呈现nzListType/nzShowUploadList/预览/下载/移除」的完整链路展开。掌握本文覆盖的 28 个输入属性、1 个输出事件以及nzCustomRequest的自定义协议配合仓库 components/upload/demo 目录下的 14 个开箱即用示例点击上传、拖拽上传、照片墙、上传前转换、手动上传、OSS 直传等足以应对绝大多数业务上传需求。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐Hermes Agent技术融合重构云原生AI架构的新范式Hermes Agent技术融合重构云原生AI架构的新范式 在AI驱动的数字化转型浪潮中技术架构师面临着一个核心挑战如何在保持系统弹性的同时实现AI能力UI组件前端ng-zorro-antd Upload 组件实战使用 nzBeforeUpload 实现只上传 PNG 文件ng zorro antd Upload 组件实战使用 nzBeforeUpload 实现只上传 PNG 文件 nzBeforeUpload 是 ng zorUI组件前端ng-zorro-antd QRCode 组件自定义填充nzPadding完全指南从 Demo 到源码实现ng zorro antd QRCode 组件自定义填充nzPadding完全指南从 Demo 到源码实现 导读 本文围绕 ng zorro antdAUI组件前端上一篇QQ空间说说导出3条命令完成全量历史本地备份下一篇OpenWebRX 项目推荐创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考