Ant Design Upload 图片列表样式listTypepicture实战本地缩略图、IE8/9 兼容与平铺布局定制【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-design图片文件上传是后台管理、内容发布等场景的高频需求。本指南以 Ant Design 中 Upload 组件的图片列表样式listTypepicture为核心讲解如何让上传列表直接展示本地图片缩略图、如何在 IE8/9 下用thumbUrl兜底以及如何通过少量 CSS 将默认的纵向列表改造成平铺inline展示。阅读完本文你将掌握图片型上传列表的完整配置方法、底层渲染原理与可落地的定制方案。一、什么是「图片列表样式」Ant Design 的 Upload 组件 内置了两种基础列表样式通过listType属性切换取值说明默认值text文本样式仅展示文件名如回形针图标 文件名默认picture图片样式每个上传项显示缩略图 文件名非默认picture-card图片卡片样式96px 方形容器平铺展示见 picture-card 示例非默认从 Upload 组件 API 文档 可以看到listType的官方定义是上传列表的内建样式支持两种基本样式textorpicture其默认值为text。当上传的文件本身就是图片时picture样式会在列表中渲染出图片缩略图让用户无需点开文件即可预览内容这也是本文要重点讲解的「图片列表样式」。需要说明的是本仓库对应早期版本实现在 uploadList.jsx 的默认属性中同样声明了listType: text同时在渲染逻辑中同时处理了picture与picture-card两种图片型列表二者共享一套缩略图渲染逻辑只是布局样式不同。二、核心示例完整的图片列表配置picture样式最直接的使用方式是像 picture-style 示例 中那样通过props对象一次配置action上传地址、listType列表样式与defaultFileList初始文件列表然后渲染两个 Upload 实例一个使用默认的纵向列表另一个附加upload-list-inline类名以展示平铺效果。import { Upload, Button, Icon } from antd; const props { action: /upload.do, listType: picture, defaultFileList: [{ uid: -1, name: xxx.png, status: done, url: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, thumbUrl: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, }, { uid: -2, name: yyy.png, status: done, url: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, thumbUrl: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, }] }; ReactDOM.render( div Upload {...props} Button typeghost Icon typeupload / 点击上传 /Button /Upload br / br / Upload {...props} classNameupload-list-inline Button typeghost Icon typeupload / 点击上传 /Button /Upload /div , mountNode);配套样式将第二个列表的上传项改为内联平铺每个 200px 宽、右间距 8px/* 加几行样式将上传项变成平铺样式 */ .upload-list-inline .ant-upload-list-item { display: inline-block; width: 200px; margin-right: 8px; }关键配置项解读action必选参数上传的地址即请求发送到服务端的 URL此处示例为/upload.do。listType: picture开启图片列表样式。设置后列表中的每个文件项会显示缩略图与文件名而非默认的纯文本项。defaultFileList初始展示的文件列表。示例中为每个文件指定了uid、name、status、url和thumbUrl用于在组件挂载时立即渲染出已完成上传的图片项。三、源码级原理本地缩略图是如何生成的图片列表样式最核心的能力是展示本地缩略图——即用户刚选择图片、尚未上传完成时列表中就已经能看到该图片的预览。这一能力在 uploadList.jsx 中通过FileReader实现// https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL const previewFile function (file, callback) { const reader new FileReader(); reader.onloadend function () { callback(reader.result); }; reader.readAsDataURL(file); };previewFile接收本地文件对象通过FileReader.readAsDataURL将文件读取为 Data URLdata:image/png;base64,...形式随后由componentDidUpdate生命周期钩子在满足条件时逐个为列表项生成缩略图componentDidUpdate() { if (this.props.listType ! picture this.props.listType ! picture-card) { return; } this.props.items.forEach(file { if (typeof document undefined || typeof window undefined || !window.FileReader || !window.File || !(file.originFileObj instanceof File) || file.thumbUrl ! undefined) { return; } file.thumbUrl ; previewFile(file.originFileObj, (previewDataUrl) { file.thumbUrl previewDataUrl; this.forceUpdate(); }); }); }这一段代码透露了三个关键事实只有图片型列表picture/picture-card才触发本地预览text列表直接跳过。本地预览依赖window.FileReader与window.File且文件对象必须是File实例originFileObj由 index.jsx 中的fileToObject从原生文件对象包装而来保留了originFileObj引用。若文件已有thumbUrl则跳过自动预览——这就是手动指定缩略图的优先级所在显式提供的thumbUrl优先于浏览器本地生成。渲染分支什么情况下显示图片什么情况下显示占位图标在render()中图片型列表的每个文件项会依据文件状态决定显示内容if (this.props.listType picture || this.props.listType picture-card) { if (file.status uploading || (!file.thumbUrl !file.url)) { // picture-card 显示文件上传中文字picture 显示 picture 图标占位 icon Icon className{${prefixCls}-list-item-thumbnail} typepicture /; } else { icon (a className{${prefixCls}-list-item-thumbnail} href{file.url} target_blankimg src{file.thumbUrl || file.url} alt{file.name} //a ); } }可以看出缩略图的取值优先级是thumbUrl || url优先使用缩略图地址没有缩略图时回退到原图地址。在status uploading上传中或既无thumbUrl也无url本地预览尚未完成时则渲染占位图标picture样式的回形针/图片图标。此外上传中的文件还会在列表项底部渲染一个进度条ant-upload-list-item-progress复用 Progress 组件 的Line类型进度数据来自 index.jsx 的onProgress回调。四、IE8/9 兼容用thumbUrl手动兜底本地缩略图依赖FileReader.readAsDataURL将文件读取为 Data URL。IE8/9 并不支持浏览器本地缩略图展示即不支持该 API因此在这些环境下自动预览会静默失败列表项只能显示占位图标。官方给出的解决方案是在文件对象上手动写入thumbUrl属性由开发者或服务端提供一个可访问的缩略图地址作为替代defaultFileList: [{ uid: -1, name: xxx.png, status: done, url: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, thumbUrl: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, }]当thumbUrl已存在时componentDidUpdate中的预览逻辑会直接return跳过本地生成见上文file.thumbUrl ! undefined的判断转而使用手动提供的地址渲染img。这一机制同时适用于picture与picture-card两种样式也是旧版 IE 下保证图片列表可用性的标准做法。需要注意的是该方案要求服务端在上传完成后能返回缩略图 URL例如通过onChange回调中的file.response或file.url回填或者由前端在上传前就预先约定缩略图地址。五、文件对象与defaultFileList的字段约定无论是defaultFileList初始列表还是 onChange 回调中返回的file对象图片列表样式相关的关键字段如下字段说明是否必填uid文件唯一标识建议设置为负数防止和组件内部产生的 id 冲突建议必填name文件名如xxx.png是status文件状态uploading/done/error/removed是url文件地址点击文件名/缩略图时的跳转链接推荐thumbUrl缩略图地址优先于url展示IE8/9 下必须手动指定IE8/9 必填response服务端响应内容上传成功后回填否originFileObj原始本地文件对象本地预览的数据来源上传时自动生成其中uid的负数约定在 Upload API 文档 中有明确说明组件内部查找目标文件时会优先按uid匹配、无uid时按name匹配相关逻辑见 getFileItem.js。六、定制平铺布局从纵向列表到 inline 排列picture样式的默认布局是纵向堆叠每个文件项占一行默认样式为display: block、overflow: hidden、margin-top: 8px见 upload.less。示例通过给 Upload 容器加classNameupload-list-inline再用三段 CSS 将列表项改为内联平铺display: inline-block让每个文件项横向排列width: 200px固定每个文件项宽度形成规整的平铺网格margin-right: 8px拉开文件项之间的水平间距。/* 加几行样式将上传项变成平铺样式 */ .upload-list-inline .ant-upload-list-item { display: inline-block; width: 200px; margin-right: 8px; }该选择器直接命中 Upload 列表项的基础类名ant-upload-list-item由 uploadList.jsx 中prefixCls ant-upload拼装而来最终类名为ant-upload-list-item 状态后缀如ant-upload-list-item-done。由于 CSS 层叠规则自定义类名下的这些覆盖样式会生效于默认样式之上因此无需改动组件源码即可实现布局定制。默认样式参考便于定制时覆盖picture列表的内建样式集中在 style/components/upload.less 的-picture规则块中要点如下文件项padding: 8px、圆角边框、高度固定 66px、相对定位缩略图ant-upload-list-item-thumbnail48px × 48px绝对定位于左上角top: 8px; left: 8px文件名ant-upload-list-item-nameline-height: 42px、padding-left: 48px为缩略图让位、超长省略号截断text-overflow: ellipsis上传进度条ant-upload-list-item-progresspadding-left: 56px避开缩略图区域删除按钮.anticon-cross默认透明鼠标悬停列表项时淡入显示。了解这些默认尺寸可以在编写平铺等自定义样式时准确估算每项占位、缩略图偏移与间距。七、picture与picture-card的选择当文件列表需要更紧凑、更醒目的图片展示时可参考同目录下的 图片卡片样式示例 将listType切换为picture-card。二者在渲染逻辑上共用同一套缩略图生成与展示分支区别主要在于picture-card的每个文件项为96px 的正方形卡片由 upload.less 中pictrue-card-size: 96px定义默认即display: inline-block平铺无需额外 CSS卡片左上角是带虚线边框的上传按钮ant-upload-select-picture-card悬停时边框变为主色悬停卡片时出现遮罩层与查看eye-o、删除delete两个操作图标上传中状态下隐藏操作图标并显示文件上传中占位文字。若你的场景只需要带缩略图的纵向文件列表使用picture即可若追求图片墙/相册式的视觉密度则picture-card是更合适的内建方案。八、相关 API 速查以下是 Upload 组件文档 中与本示例直接相关的属性速查参数说明类型默认值name上传的文件字段名Stringfileaction必选上传的地址String无data上传所需附加参数Object无headers设置上传的请求头部IE10 以上有效Object无showUploadList是否展示 uploadList默认开启Booleantruemultiple是否支持多选文件ie10支持开启后按住 Ctrl 可选择多个文件Booleanfalseaccept接受上传的文件类型详见 input accept 属性String无beforeUpload上传文件之前的钩子参数为上传的文件若返回false或 Promise 则停止上传不支持老 IEFunction无onChange上传文件状态改变时的回调Function无listType上传列表的内建样式支持text或pictureStringtextclassName自定义类名平铺定制正是通过它接入String无onChange回调返回{ file, fileList, event }结构file为当前操作的文件对象multiple 模式下为对象数组fileList为当前完整文件列表event为上传中的服务端响应内容含进度信息高级浏览器支持。若需要展示下载链接请使用fileList数组项的url属性进行控制。上述默认值均可在 index.jsx 的getDefaultProps中验证如multiple: false、action: 、listType: text、showUploadList: true。九、小结通过listType: pictureAnt Design Upload 组件可以为图片文件自动生成并展示本地缩略图现代浏览器借助FileReader.readAsDataURL在 uploadList.jsx 中实现本地预览IE8/9 则通过手动指定thumbUrl兜底在此基础上借助className与少量覆盖样式如示例中的upload-list-inline即可把默认纵向列表改造成 200px 宽的平铺网格。掌握thumbUrl的优先级规则、ant-upload-list-item的类名体系与 upload.less 中的默认尺寸你就能根据业务需要自由定制图片上传列表的展示形态。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ant Design Upload 图片列表样式（listType=“picture“）实战：本地缩略图、IE8/9 兼容与平铺布局定制
Ant Design Upload 图片列表样式listTypepicture实战本地缩略图、IE8/9 兼容与平铺布局定制【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-design图片文件上传是后台管理、内容发布等场景的高频需求。本指南以 Ant Design 中 Upload 组件的图片列表样式listTypepicture为核心讲解如何让上传列表直接展示本地图片缩略图、如何在 IE8/9 下用thumbUrl兜底以及如何通过少量 CSS 将默认的纵向列表改造成平铺inline展示。阅读完本文你将掌握图片型上传列表的完整配置方法、底层渲染原理与可落地的定制方案。一、什么是「图片列表样式」Ant Design 的 Upload 组件 内置了两种基础列表样式通过listType属性切换取值说明默认值text文本样式仅展示文件名如回形针图标 文件名默认picture图片样式每个上传项显示缩略图 文件名非默认picture-card图片卡片样式96px 方形容器平铺展示见 picture-card 示例非默认从 Upload 组件 API 文档 可以看到listType的官方定义是上传列表的内建样式支持两种基本样式textorpicture其默认值为text。当上传的文件本身就是图片时picture样式会在列表中渲染出图片缩略图让用户无需点开文件即可预览内容这也是本文要重点讲解的「图片列表样式」。需要说明的是本仓库对应早期版本实现在 uploadList.jsx 的默认属性中同样声明了listType: text同时在渲染逻辑中同时处理了picture与picture-card两种图片型列表二者共享一套缩略图渲染逻辑只是布局样式不同。二、核心示例完整的图片列表配置picture样式最直接的使用方式是像 picture-style 示例 中那样通过props对象一次配置action上传地址、listType列表样式与defaultFileList初始文件列表然后渲染两个 Upload 实例一个使用默认的纵向列表另一个附加upload-list-inline类名以展示平铺效果。import { Upload, Button, Icon } from antd; const props { action: /upload.do, listType: picture, defaultFileList: [{ uid: -1, name: xxx.png, status: done, url: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, thumbUrl: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, }, { uid: -2, name: yyy.png, status: done, url: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, thumbUrl: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, }] }; ReactDOM.render( div Upload {...props} Button typeghost Icon typeupload / 点击上传 /Button /Upload br / br / Upload {...props} classNameupload-list-inline Button typeghost Icon typeupload / 点击上传 /Button /Upload /div , mountNode);配套样式将第二个列表的上传项改为内联平铺每个 200px 宽、右间距 8px/* 加几行样式将上传项变成平铺样式 */ .upload-list-inline .ant-upload-list-item { display: inline-block; width: 200px; margin-right: 8px; }关键配置项解读action必选参数上传的地址即请求发送到服务端的 URL此处示例为/upload.do。listType: picture开启图片列表样式。设置后列表中的每个文件项会显示缩略图与文件名而非默认的纯文本项。defaultFileList初始展示的文件列表。示例中为每个文件指定了uid、name、status、url和thumbUrl用于在组件挂载时立即渲染出已完成上传的图片项。三、源码级原理本地缩略图是如何生成的图片列表样式最核心的能力是展示本地缩略图——即用户刚选择图片、尚未上传完成时列表中就已经能看到该图片的预览。这一能力在 uploadList.jsx 中通过FileReader实现// https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL const previewFile function (file, callback) { const reader new FileReader(); reader.onloadend function () { callback(reader.result); }; reader.readAsDataURL(file); };previewFile接收本地文件对象通过FileReader.readAsDataURL将文件读取为 Data URLdata:image/png;base64,...形式随后由componentDidUpdate生命周期钩子在满足条件时逐个为列表项生成缩略图componentDidUpdate() { if (this.props.listType ! picture this.props.listType ! picture-card) { return; } this.props.items.forEach(file { if (typeof document undefined || typeof window undefined || !window.FileReader || !window.File || !(file.originFileObj instanceof File) || file.thumbUrl ! undefined) { return; } file.thumbUrl ; previewFile(file.originFileObj, (previewDataUrl) { file.thumbUrl previewDataUrl; this.forceUpdate(); }); }); }这一段代码透露了三个关键事实只有图片型列表picture/picture-card才触发本地预览text列表直接跳过。本地预览依赖window.FileReader与window.File且文件对象必须是File实例originFileObj由 index.jsx 中的fileToObject从原生文件对象包装而来保留了originFileObj引用。若文件已有thumbUrl则跳过自动预览——这就是手动指定缩略图的优先级所在显式提供的thumbUrl优先于浏览器本地生成。渲染分支什么情况下显示图片什么情况下显示占位图标在render()中图片型列表的每个文件项会依据文件状态决定显示内容if (this.props.listType picture || this.props.listType picture-card) { if (file.status uploading || (!file.thumbUrl !file.url)) { // picture-card 显示文件上传中文字picture 显示 picture 图标占位 icon Icon className{${prefixCls}-list-item-thumbnail} typepicture /; } else { icon (a className{${prefixCls}-list-item-thumbnail} href{file.url} target_blankimg src{file.thumbUrl || file.url} alt{file.name} //a ); } }可以看出缩略图的取值优先级是thumbUrl || url优先使用缩略图地址没有缩略图时回退到原图地址。在status uploading上传中或既无thumbUrl也无url本地预览尚未完成时则渲染占位图标picture样式的回形针/图片图标。此外上传中的文件还会在列表项底部渲染一个进度条ant-upload-list-item-progress复用 Progress 组件 的Line类型进度数据来自 index.jsx 的onProgress回调。四、IE8/9 兼容用thumbUrl手动兜底本地缩略图依赖FileReader.readAsDataURL将文件读取为 Data URL。IE8/9 并不支持浏览器本地缩略图展示即不支持该 API因此在这些环境下自动预览会静默失败列表项只能显示占位图标。官方给出的解决方案是在文件对象上手动写入thumbUrl属性由开发者或服务端提供一个可访问的缩略图地址作为替代defaultFileList: [{ uid: -1, name: xxx.png, status: done, url: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, thumbUrl: https://os.alipayobjects.com/rmsportal/NDbkJhpzmLxtPhB.png, }]当thumbUrl已存在时componentDidUpdate中的预览逻辑会直接return跳过本地生成见上文file.thumbUrl ! undefined的判断转而使用手动提供的地址渲染img。这一机制同时适用于picture与picture-card两种样式也是旧版 IE 下保证图片列表可用性的标准做法。需要注意的是该方案要求服务端在上传完成后能返回缩略图 URL例如通过onChange回调中的file.response或file.url回填或者由前端在上传前就预先约定缩略图地址。五、文件对象与defaultFileList的字段约定无论是defaultFileList初始列表还是 onChange 回调中返回的file对象图片列表样式相关的关键字段如下字段说明是否必填uid文件唯一标识建议设置为负数防止和组件内部产生的 id 冲突建议必填name文件名如xxx.png是status文件状态uploading/done/error/removed是url文件地址点击文件名/缩略图时的跳转链接推荐thumbUrl缩略图地址优先于url展示IE8/9 下必须手动指定IE8/9 必填response服务端响应内容上传成功后回填否originFileObj原始本地文件对象本地预览的数据来源上传时自动生成其中uid的负数约定在 Upload API 文档 中有明确说明组件内部查找目标文件时会优先按uid匹配、无uid时按name匹配相关逻辑见 getFileItem.js。六、定制平铺布局从纵向列表到 inline 排列picture样式的默认布局是纵向堆叠每个文件项占一行默认样式为display: block、overflow: hidden、margin-top: 8px见 upload.less。示例通过给 Upload 容器加classNameupload-list-inline再用三段 CSS 将列表项改为内联平铺display: inline-block让每个文件项横向排列width: 200px固定每个文件项宽度形成规整的平铺网格margin-right: 8px拉开文件项之间的水平间距。/* 加几行样式将上传项变成平铺样式 */ .upload-list-inline .ant-upload-list-item { display: inline-block; width: 200px; margin-right: 8px; }该选择器直接命中 Upload 列表项的基础类名ant-upload-list-item由 uploadList.jsx 中prefixCls ant-upload拼装而来最终类名为ant-upload-list-item 状态后缀如ant-upload-list-item-done。由于 CSS 层叠规则自定义类名下的这些覆盖样式会生效于默认样式之上因此无需改动组件源码即可实现布局定制。默认样式参考便于定制时覆盖picture列表的内建样式集中在 style/components/upload.less 的-picture规则块中要点如下文件项padding: 8px、圆角边框、高度固定 66px、相对定位缩略图ant-upload-list-item-thumbnail48px × 48px绝对定位于左上角top: 8px; left: 8px文件名ant-upload-list-item-nameline-height: 42px、padding-left: 48px为缩略图让位、超长省略号截断text-overflow: ellipsis上传进度条ant-upload-list-item-progresspadding-left: 56px避开缩略图区域删除按钮.anticon-cross默认透明鼠标悬停列表项时淡入显示。了解这些默认尺寸可以在编写平铺等自定义样式时准确估算每项占位、缩略图偏移与间距。七、picture与picture-card的选择当文件列表需要更紧凑、更醒目的图片展示时可参考同目录下的 图片卡片样式示例 将listType切换为picture-card。二者在渲染逻辑上共用同一套缩略图生成与展示分支区别主要在于picture-card的每个文件项为96px 的正方形卡片由 upload.less 中pictrue-card-size: 96px定义默认即display: inline-block平铺无需额外 CSS卡片左上角是带虚线边框的上传按钮ant-upload-select-picture-card悬停时边框变为主色悬停卡片时出现遮罩层与查看eye-o、删除delete两个操作图标上传中状态下隐藏操作图标并显示文件上传中占位文字。若你的场景只需要带缩略图的纵向文件列表使用picture即可若追求图片墙/相册式的视觉密度则picture-card是更合适的内建方案。八、相关 API 速查以下是 Upload 组件文档 中与本示例直接相关的属性速查参数说明类型默认值name上传的文件字段名Stringfileaction必选上传的地址String无data上传所需附加参数Object无headers设置上传的请求头部IE10 以上有效Object无showUploadList是否展示 uploadList默认开启Booleantruemultiple是否支持多选文件ie10支持开启后按住 Ctrl 可选择多个文件Booleanfalseaccept接受上传的文件类型详见 input accept 属性String无beforeUpload上传文件之前的钩子参数为上传的文件若返回false或 Promise 则停止上传不支持老 IEFunction无onChange上传文件状态改变时的回调Function无listType上传列表的内建样式支持text或pictureStringtextclassName自定义类名平铺定制正是通过它接入String无onChange回调返回{ file, fileList, event }结构file为当前操作的文件对象multiple 模式下为对象数组fileList为当前完整文件列表event为上传中的服务端响应内容含进度信息高级浏览器支持。若需要展示下载链接请使用fileList数组项的url属性进行控制。上述默认值均可在 index.jsx 的getDefaultProps中验证如multiple: false、action: 、listType: text、showUploadList: true。九、小结通过listType: pictureAnt Design Upload 组件可以为图片文件自动生成并展示本地缩略图现代浏览器借助FileReader.readAsDataURL在 uploadList.jsx 中实现本地预览IE8/9 则通过手动指定thumbUrl兜底在此基础上借助className与少量覆盖样式如示例中的upload-list-inline即可把默认纵向列表改造成 200px 宽的平铺网格。掌握thumbUrl的优先级规则、ant-upload-list-item的类名体系与 upload.less 中的默认尺寸你就能根据业务需要自由定制图片上传列表的展示形态。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
