企业官网建设流程全解析

接手的管理后台项目越来越多，我发现最容易被“嫌弃”的组件就是上传。ant design vue的Upload组件功能确实全面，但默认文件列表的样式非常克制——一个图标、一个文件名、hover 时冒出两个小按钮，放在表单里勉强能看，放在需要展示业务数据的页面里就太朴素了。要自定义文件列表的样式，不能只靠 CSS 硬改，得先把组件内部渲染机制摸清楚。这篇文章我就从itemRender接管节点、缩略图处理、操作按钮改造、scoped 样式穿透这几个层面，把整个套路讲透，最后给出一份可以直接抄的自定义列表行方案。

1. 先搞懂Upload到底怎么渲染文件列表的

1.1 listType决定骨架，showUploadList决定“显隐”

在动手改样式之前，一定得先明白文件列表的结构是从哪来的。Upload组件里有一个listType属性，它直接决定了列表最外层长什么样。我见过不少人在不换listType的情况下强行覆盖 CSS，改半天还是变扭，本质原因就是没理解这三个模式的区别：

这三个模式下，列表项的 DOM 层级大致都是.ant-upload-list-item包着.ant-upload-list-item-info，里面再放缩略图、文件名、操作按钮和进度条。showUploadList这个属性则控制着列表项里哪些内置按钮显示：比如{ showRemoveIcon: false }就能隐藏删除按钮。这两个配置是“不写代码”的情况下最常用的定制手段。

1.2 为什么纯CSS方案常常陷入泥潭

默认列表的问题不只是不美观，而是 DOM 结构里有太多组件内部的类名，而且这些类名在 Vue 的 scoped 样式里很难直接命中。你可能遇到过这种情况：在 style 里写了.ant-upload-list-item { border-radius: 8px }，结果页面里没生效，因为 scoped 样式会给选择器加上>itemRender(originNode, file, fileList, actions)

• originNode：组件内部默认生成的那个列表项 DOM（VNode），它是你定制的基础，也是你最不需要从零实现的兜底。
• file：当前这一条文件记录，里面有name、size、status、percent、uid、url、response等关键字段。
• fileList：整个文件列表数组，一般在做“根据列表状态批量调整样式”时用得到。
• actions：一个对象，里面对应remove、download、preview三个方法，分别触发组件内置的删除、下载、预览行为。

明白了这四个参数，定制列表就已经成功了一半。你可以完全忽略originNode，也可以拿它来当子节点的一部分，这取决于你想要多彻底的自主权。

2.2 最小心示例：包裹originNode并补充信息

如果只是想微调布局，比如给每个列表项加一个自定义图标或者附加一条提示文字，最简单的方式是返回一个新节点，把originNode塞进去，同时在外面增加内容。下面这个例子是在列表项右侧加了一个显示文件大小的标签：

import { h } from 'vue' const itemRender = (originNode, file, fileList, actions) => { return h('div', { class: 'custom-upload-item' }, [ originNode, h('span', { class: 'custom-upload-size' }, formatFileSize(file.size)) ]) }

这样做的优点是从originNode内部复制出来了默认的进度条、图标、名称、hover 按钮，组件内部对状态的管理依然有效。但是这种方案的缺点也很明显：你只是在默认结构的外面加东西，内部的层级和顺序没变，改的余地有限。真正要设计成一个“信息完整的列表行”，还是得完全自己渲染。

2.3 别犯的低级错误：事件和状态丢失

我一开始直接用originNode包裹时踩过一个坑：想给originNode本身加一个点击事件，直接在h()里给originNode外套一层，但内部节点的事件没有被正确绑定，按钮点了没反应。后来才发现，originNode是一个已经被组件内部处理过的 VNode，你最好不要试图修改它的 props，更不要把它重新传递给另一个组件，否则事件绑定大概率会丢。

如果你真的需要完全自定义列表项，我的建议就是干脆忘掉originNode，用file上的字段自己构建结构和交互，这样状态行为和 UI 完全由你控制。originNode在上传这一层是兜底用的，不是给你做二次加工的。

3. 逐块重写：文件名、状态、进度、缩略图一个不落

3.1 一个完整的自定义列表行长什么样

完全重写列表项的思路并不难，难的是把组件内部那些细节补齐，比如上传进度、状态颜色、失败重试。来做一个可用的自定义行组件。先看模板部分：

<template> <a-upload v-model:file-list="fileList" :item-render="itemRender" action="/api/upload" name="file" > <a-button type="primary">选择文件</a-button> </a-upload> </template>

然后定义itemRender，返回我们自己设计的节点结构。我习惯把“一行文件”拆成四个区域：缩略图/图标、文件信息区（名称、大小、状态）、进度条、操作按钮。

import { h } from 'vue' const itemRender = (originNode, file, fileList, actions) => { return h('div', { class: ['custom-file-row', `custom-file-row-${file.status}`] }, [ // 缩略图区域 h('div', { class: 'custom-file-thumb' }, renderThumb(file)), // 信息区域 h('div', { class: 'custom-file-info' }, [ h('div', { class: 'custom-file-name' }, [file.name]), h('div', { class: 'custom-file-meta' }, [ formatFileSize(file.size), renderStatusText(file.status) ]) ]), // 进度条区域 file.status === 'uploading' ? h('div', { class: 'custom-file-progress' }, [ h('div', { class: 'custom-file-progress-inner', style: { width: (file.percent || 0) + '%' } }) ]) : null, // 操作按钮区域 h('div', { class: 'custom-file-actions' }, [ renderActions(file, actions) ]) ]) }

这里最核心的一点是，我完全靠file.status来判断状态，自己渲染状态文案和颜色。这样做的好处是 UI 是你自己的，不会被组件内置样式“绑架”。

3.2 状态文案与进度百分比处理

file.status只有几个取值：uploading、done、error、removed。对于done和error这种终态，渲染对应用的颜色和文案即可；对于uploading状态，则要读取file.percent，它会在上传过程中被组件自动更新。进度条宽度直接绑file.percent，刷新率很稳定，不需要额外做节流。

function renderStatusText(status) { const map = { uploading: '上传中', done: '已完成', error: '上传失败', removed: '已删除' } return map[status] || '待处理' }

这里要留意一个细节：如果上传接口用的是action属性，组件内部会自动更新percent；如果用的是customRequest自定义上传请求，那你就得自己在上传过程中调用onProgress去更新。

// customRequest 场景 const customRequest = ({ file, onSuccess, onError, onProgress }) => { // 假上传演示 let percent = 0 const timer = setInterval(() => { percent += 10 onProgress({ percent }) if (percent >= 100) { clearInterval(timer) onSuccess({ url: URL.createObjectURL(file) }) } }, 100) }

3.3 不同文件类型的图标/缩略图逻辑

不是所有文件都是图片，所以缩略图区域要分类型处理。我的做法是：有可预览 URL 的图片就显示图片，没有图片资源就显示一个带扩展名的小徽章。比如.pdf显示红色 PDF 徽章，.docx显示蓝色 DOCX 徽章，压缩包显示橙色 ZIP 徽章。这样列表在视觉上比纯内置图标清晰得多。

function getFileExt(name = '') { return name.includes('.') ? name.split('.').pop().toLowerCase() : 'file' } function renderThumb(file) { const thumbUrl = file.thumbUrl || file.url if (thumbUrl) { return h('img', { src: thumbUrl, alt: file.name, class: 'custom-thumb-img' }) } const ext = getFileExt(file.name) return h('span', { class: ['custom-file-ext', `ext-${ext}`] }, ext.toUpperCase()) }

在渲染图片时候，我通常会给图片加一个onError兜底，确保某些后端返回了损坏的链接时，不会显示一个裂图，而是自动换成文件扩展名徽章。

4. 操作按钮改造：删除前二次确认、自定义预览

4.1 actions方法绑定与默认行为

在上面的自定义行里，操作按钮不是组件内置的，所以默认的 hover 图标不会出现。我们需要通过actions对象手动绑定行为：

function renderActions(file, actions) { const buttons = [] if (file.status === 'done' && (file.url || file.thumbUrl)) { buttons.push(h('a', { onClick: () => actions.preview() }, '预览')) } if (file.status === 'done') { buttons.push(h('a', { onClick: () => actions.download() }, '下载')) } buttons.push(h('a', { onClick: () => handleRemove(file, actions) }, '删除')) return buttons }

actions.preview()和actions.download()会触发组件内部的默认逻辑，比如调起默认预览层。如果你有自定义的预览弹窗需求，更稳的做法是在Upload上监听@preview事件，在事件里自己打开 Modal。

4.2 删除前二次确认的一种干净写法

默认删除是直接调actions.remove()，这个动作会立刻从fileList里移除文件。但业务上删除前通常要一个确认弹窗。直接在itemRender里写Modal.confirm是最直观的，注意一定在确认回调里调用actions.remove()，否则取消时会留下一个处理一半的文件项。

const handleRemove = (file, actions) => { Modal.confirm({ title: '删除确认', content: `确定要删除 ${file.name} 吗？`, okText: '删除', cancelText: '取消', onOk() { actions.remove() } }) }

这里有个容易忽略的细节：上传接口返回 200 但业务失败了，file.status可能会不正确。这种情况下最好在后端接口里用约定好的code字段判断业务成功失败，再手动把file.status改为error。否则你看到的列表是绿的，但其实文件没传上去，用户也会懵。

4.3 预览不仅要能看，还要能下载

预览功能要同时兼容图片和非图片文件。图片直接弹窗口展示；PDF 可以让浏览器新开标签页去展示；Office 文档和压缩包则只能引导下载。所以在预览按钮的实现里，我会区分处理：

const handlePreview = (file) => { const url = file.url || file.thumbUrl || '' if (!url) return const ext = getFileExt(file.name) if (['jpg', 'jpeg', 'png', 'gif', 'webp'].includes(ext)) { previewVisible.value = true previewImage.value = url } else { window.open(url, '_blank') } }

如果你维护的是纯前端预览场景，没有真实后端地址，那本地图片预览就要靠URL.createObjectURL生成本地链接，这个放到下一节单独讲。

5. 缩略图细节：本地预览与内存释放

5.1 thumbUrl、url、本地文件的优先级

在itemRender里拿缩略图时，file对象上有几个字段很容易混淆：

• file.url：后端返回的远程地址，通常上传完成后才有。
• file.thumbUrl：缩略图地址，有时候后端会单独返回压缩图；没有的话，可以手动设置成file.url。
• file.originFileObj：浏览器原生的 File 对象，在本地尚未上传成功时，它就是唯一能拿到图片内容的数据源。

我的取值策略是：thumbUrl优先，其次url，最后才用originFileObj生成临时 URL。

function getPreviewUrl(file) { if (file.thumbUrl) return file.thumbUrl if (file.url) return file.url if (file.originFileObj) { if (!localUrlMap.has(file.uid)) { localUrlMap.set(file.uid, URL.createObjectURL(file.originFileObj)) } return localUrlMap.get(file.uid) } return '' }

用 Map 以file.uid为 key 缓存生成的 URL，可以避免同一个文件反复调用createObjectURL，产生大量临时内存。

5.2 内存释放不能忘

URL.createObjectURL生成的链接如果不去释放，会一直占着内存。完整页面一次上传几十张大图，内存就可能暴涨。最简单的方式是监听文件移除和组件卸载这两个时机，统一释放。

const localUrlMap = new Map() const releaseLocalUrl = (uid) => { const url = localUrlMap.get(uid) if (url) { URL.revokeObjectURL(url) localUrlMap.delete(uid) } } // 在 Upload 的 remove 回调中释放 const handleRemoveFile = (file) => { releaseLocalUrl(file.uid) }

如果你的组件是关在弹窗里的，千万别忘了在弹窗关闭时把 Map 里所有 URL 全revoke掉，否则弹窗开开关关几次，浏览器内存会明显上涨。这个坑我是真踩过，线上弹窗频繁开关导致页面卡顿，定位到就是本地缩略图 URL 没释放。

5.3 圆角、遮罩与hover效果

缩略图区域的视觉可以很灵活。比如图片缩略图我在外层套一个固定尺寸的正方形容器，配border-radius和悬停遮罩。这个在picture-card模式下尤其常见。

.custom-file-thumb { width: 48px; height: 48px; border-radius: 8px; overflow: hidden; position: relative; background: #f5f5f5; flex-shrink: 0; display: flex; align-items: center; justify-content: center; } .custom-file-thumb img { width: 100%; height: 100%; object-fit: cover; } .custom-file-thumb:hover::after { content: ''; position: absolute; inset: 0; background: rgba(0, 0, 0, 0.2); }

6. scoped样式与antd类名冲突的最终解法

6.1 深层穿透与命名空间

到了样式落地的环节，最让人头疼的就是 scoped 样式。你在组件里写的.custom-file-row是自己的类名，能正常命中，没问题。但当你偶尔想动组件内部的默认类时，比如隐藏某些情况下的.ant-upload-list-item或者调整列表间距，就必须用 Vue 3 的:deep()。

<style lang="less" scoped> .upload-custom-wrapper { :deep(.ant-upload-list) { margin-top: 16px; display: flex; flex-direction: column; gap: 12px; } :deep(.ant-upload-list-item) { border: none; padding: 0; } } </style>

给Upload最外层套一个自己的类名（比如upload-custom-wrapper），所有深层选择器都基于它去写，能有效防止样式泄漏到页面其他Upload实例上。这是一个很重要的规范：不要直接用:deep(.ant-upload-list)，那会误伤同一个页面里其他上传组件。

6.2 隐藏默认动作，保留自定义动作

当你在itemRender里完全自绘了操作按钮后，要注意内置的 hover 图标可能还会出来捣乱，因为默认结构里的.ant-upload-list-item-actions还存在于 DOM 上，或者某些状态下 hover 遮罩仍然生效。这时候有两个做法：

• 在showUploadList配置里把内置图标全关掉：{ showRemoveIcon: false, showPreviewIcon: false, showDownloadIcon: false }
• 用:deep(.ant-upload-list-item-actions) { display: none; }强制隐藏。

我建议优先用第一种，从配置层面关掉内置动作更干净。完全自绘的时候，这些内置按钮对你来说就是多余的，留着只会造成点击冲突。

6.3 一个完整的组装示例

把上面的所有内容组合起来，就是一个可以直接用的自定义上传列表组件雏形。模板部分：

<template> <div class="upload-custom-wrapper"> <a-upload v-model:file-list="fileList" list-type="text" :item-render="itemRender" :show-upload-list="{ showRemoveIcon: false, showPreviewIcon: false, showDownloadIcon: false }" action="/api/upload" name="file" @remove="handleRemoveFile" > <a-button type="primary">上传附件</a-button> </a-upload> </div> </template>

逻辑部分集中定义itemRender、renderThumb、renderActions、formatFileSize这些辅助函数即可。整个方案的核心思路是：不去对抗默认 CSS，而是用itemRender把列表项的 DOM 结构彻底换成自己的，然后配合一套独立的类名写样式。这样做有几个明显的好处——文件状态、缩进、间距、缩略图形状都能完全掌控，代码也不散。

最后再分享一个我在实际项目里总结的小窍门：完全自绘列表项时，最好把itemRender抽成一个独立的渲染模块，文件行里的数据展示、状态判断、操作逻辑全放进去，不要在Upload主组件里堆一堆条件渲染。这样后面要加“重试上传”“批量下载”“拖拽排序”这些需求时，只需要改文件行一个地方，比在模板里撕扯舒服得多。