企业官网建设流程全解析

• UI组件
• 前端

在 ng-zorro-antd 的上传组件（Upload）中，nzListType="picture"会在上传列表中以缩略图形式展示图片文件：用户选择本地图片后，浏览器即可通过FileReader.readAsDataURL读取文件内容，在列表里即时渲染出本地预览图；对于历史文件或旧浏览器场景，则可以通过thumbUrl字段直接指定缩略图地址。本文以仓库中 picture-style 示例 及其配套源码为主线，讲解图片列表样式的完整配置、本地缩略图的底层实现原理、thumbUrl的兼容替代方案，以及文件状态与图标渲染的细节，帮助你直接复用到真实业务中。

一、Demo 速览：图片列表样式长什么样

components/upload/demo/picture-style.ts是这一特性的最小可运行示例。核心要点只有两处：

1. 给nz-upload设置nzListType="picture"，让上传列表以"文件名 + 缩略图"的横向行式展示；
2. 通过双向绑定[(nzFileList)]传入初始文件列表，列表项可以混合uploading（上传中）、done（完成）、error（失败）三种状态。

完整示例代码如下（与仓库 demo 一致）：

import { Component, signal } from '@angular/core'; import { NzButtonModule } from 'ng-zorro-antd/button'; import { NzIconModule } from 'ng-zorro-antd/icon'; import { NzUploadFile, NzUploadModule } from 'ng-zorro-antd/upload'; @Component({ selector: 'nz-demo-upload-picture-style', imports: [NzButtonModule, NzIconModule, NzUploadModule], template: ` <nz-upload nzAction="https://660d2bd96ddfa2943b33731c.mockapi.io/api/upload" nzListType="picture" [(nzFileList)]="fileList" > <button nz-button> <nz-icon nzType="upload" /> Upload </button> </nz-upload> ` }) export class NzDemoUploadPictureStyleComponent { readonly fileList = signal<NzUploadFile[]>([ { uid: '0', name: 'xxx.png', status: 'uploading', percent: 33 }, { uid: '-1', name: 'yyy.png', status: 'done', url: 'https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png', thumbUrl: 'https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png' }, { uid: '-2', name: 'zzz.png', status: 'error' } ]); }

demo 展示的三种文件形态，恰好对应了图片列表样式在日常使用中的三类场景：

二、核心配置：nzListType 三种内建列表样式

nzListType是决定上传列表外观的入口参数，类型定义在 interface.ts：

/** Built-in styles of the uploading list. */ export type NzUploadListType = 'text' | 'picture' | 'picture-card';

• text（默认值）：仅展示文件名与状态图标，最简洁；
• picture（本文主角）：每个文件一行，图片文件显示缩略图，非图片文件显示文件类型图标；
• picture-card：卡片式照片墙布局，缩略图占满卡片，上传按钮会在达到数量上限时消失（参见 picture-card 示例）。

从 upload.component.ts 源码可以看到默认值为'text'，组件还会根据该值生成对应的宿主 class（ant-upload-select-text/ant-upload-select-picture/ant-upload-select-picture-card）以及ant-upload-picture-card-wrapper包装类。也就是说，选择哪种列表样式，本质上就是切换 ng-zorro-antd 预置的整条列表渲染管线与样式体系。

三、本地缩略图原理：FileReader 与 Canvas 的配合

demo 文档的核心提示是：当上传的文件是图片时，可以展示本地缩略图。这一能力由上传列表组件 upload-list.component.ts 中的genThumb()与previewImage()实现，机制如下：

1. 列表渲染时（ngOnChanges阶段），genThumb()过滤出"有原始文件对象（originFileObj instanceof File）且尚未设置thumbUrl"的图片项；
2. 对这些项调用previewImage()：先判断文件 MIME 类型是否以image/开头（isImageFileType），随后创建一个 200×200 的隐藏<canvas>，用URL.createObjectURL(file)生成对象 URL 并加载到Image上；
3. 按"cover 式"等比缩放绘制到 canvas（宽高比不一致时自动裁剪居中，MEASURE_SIZE = 200），再通过canvas.toDataURL()得到 dataURL；
4. 将 dataURL 写回file.thumbUrl并触发变更检测，列表即刷新出本地缩略图；绘制完成后会移除 canvas 并URL.revokeObjectURL(objectUrl)释放对象 URL。

这段逻辑依赖浏览器原生能力，与FileReader.readAsDataURL同源——这正是 demo 文档提醒IE8/9 不支持浏览器本地缩略图展示的原因。在旧版本 IE 中，FileReader与canvas.toDataURL均不可用，genThumb()中的能力检测会直接短路返回（源码中对window.FileReader、window.File做了显式存在性判断），此时列表无法自动生成缩略图。

四、兼容方案：用 thumbUrl 显式指定缩略图

针对不支持本地缩略图的场景，demo 文档给出的替代方案非常直接：在文件对象上编写thumbUrl属性来代替。

thumbUrl是 NzUploadFile 的可选字段，语义为"缩略图地址"。当列表项带有thumbUrl时，genThumb()会跳过该文件（file.thumbUrl === undefined才处理），直接以你提供的地址渲染缩略图。demo 中已完成文件的写法就是典型范例：

{ uid: '-1', name: 'yyy.png', status: 'done', url: 'https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png', thumbUrl: 'https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png' }

两种取值方式适用场景不同，可按需组合：

• 自动生成（现代浏览器）：不写thumbUrl，由组件用 canvas 把本地文件压缩成 200×200 的 dataURL 缩略图，适合"用户刚选完文件"的即时反馈；
• 手动指定（兼容/历史数据）：显式设置thumbUrl，指向后端返回的缩略图地址（如 CDN 上由服务端生成的缩略图），适合 IE8/9、服务端预生成缩略图、以及从数据库回显历史文件等场景。

五、图片判定逻辑：isImageUrl 如何决定渲染分支

列表对每个文件会先判定"是否为有效图片"，再决定渲染缩略图还是文件图标。判定函数isImageUrl()（upload-list.component.ts）的执行顺序是：

1. 文件 MIME 类型以image/开头 → 直接判定为图片；
2. 否则取thumbUrl || url，按后缀名匹配webp | svg | png | gif | jpg | jpeg | jfif | bmp | dpg，或data:image/前缀的 base64 → 判定为图片；
3. data:开头的其他 base64、带其他后缀名的 URL → 判定为非图片；
4. 无后缀名 → 默认按图片处理。

在实际渲染模板 upload-list.component.html 中，判定为图片的项输出<img class="ant-upload-list-item-image" [src]="file.thumbUrl || file.url">，缩略图优先取thumbUrl；判定为非图片或上传中的文件则走图标分支（picture样式下为 loading 图标或picture/file双色图标）。若你希望干预这一判定（例如图片 URL 是非标准格式），可以传入nzPreviewIsImage回调自定义规则。

六、文件状态与列表交互细节

picture列表样式的状态机与图标、操作按钮的联动，可以从模板中直接看出（以下均为仓库真实行为）：

• 上传中：不渲染缩略图，显示 loading 图标和nz-progress细进度条（nzStrokeWidth=2、隐藏百分比文字），对应file.percent字段；
• 已完成：渲染缩略图；picture样式在行尾提供下载（仅done状态）与删除两个操作图标，下载默认通过window.open(file.url)打开新标签页（可用nzDownload覆盖）；
• 失败：悬停时通过nz-tooltip展示file.response（字符串）或file.error.statusText构成的错误信息；
• 文件名点击：若定义了nzPreview回调则触发预览，否则按href打开链接。

文件状态流转（start → progress → success/error → removed）由 upload.component.ts 内部的onStart/onProgress/onSuccess/onError/onRemove驱动，并通过(nzChange)事件向外抛出{ file, fileList, event, type }，详见 Upload API 文档。

七、延伸：从 picture 到照片墙与其他预览玩法

掌握了picture样式后，可以顺畅地迁移到相邻场景：

• 照片墙（picture-card）：把nzListType换成'picture-card'，布局变为卡片式；缩略图即卡片主体，操作按钮悬停浮层展示，上传按钮在数量达到nzMaxCount后自动消失（见 picture-card 示例）；
• 头像上传：单文件场景下结合nzMaxCount=1与nzShowButton实现"始终以最新文件替换"，见 avatar 示例；
• 自定义预览：通过nzPreviewFile接管缩略图生成逻辑、nzIconRender自定义图标、nzFileListRender整体重写列表，见 preview-file 示例 与 custom-action-icon 示例。

八、小结

图片列表样式（nzListType="picture"）是 ng-zorro-antd Upload 组件中"所见即所得"的典型代表：现代浏览器下由组件内部FileReader+ canvas 管线自动产出 200×200 本地缩略图，无需任何服务端参与；在 IE8/9 等不支持本地缩略图的浏览器中，只需为文件补充thumbUrl字段即可获得一致的展示效果。实际开发中建议结合初始文件列表（[(nzFileList)]）预填历史数据、借助nzChange监听上传状态、并通过nzMaxCount控制数量上限，即可覆盖绝大多数图片上传业务。

• UI组件
• 前端