---
id: "upload"
title: "上传控件与文件状态"
category: "输入组件"
document_type: "component-specification"
spec_status: "local-current-draft"
element_ui: "2.15.6"
vue: "2.6.14"
page: "../index.html#spec-upload"
source_data: "../component-data.json"
official_components: ["upload"]
template_components: ["el-button", "el-upload"]
scenario_count: 12
verification: "scenario-checklist-not-full-test-pass"
---

# 上传控件与文件状态

专题 `upload` · 输入组件 · Element UI 2.15.6

## 适用范围与组件映射

公共色板及字体基线适用于整个运营后台。本库整理基础组件、组件状态和可复用的组合模式；本轮补齐表单整体验证、页面布局和导航组合；具体业务字段与跨页流程仍在业务场景中说明。专题验收清单包含接入要求，不表示当前示例已实现或已验证全部场景。

官方条目映射：`upload`。

本页模板直接使用的 Element UI 标签：`el-button`、`el-upload`。

## 通用基线

- 组件库：Element UI **2.15.6**；运行样例 Vue **2.6.14**。
- 系统中文字体：macOS 优先苹方，Windows 通常微软雅黑；工程顺序固定为 `"PingFang SC", "Microsoft YaHei", sans-serif`。不要求安装或加载网络字体，兼容回退不是另一套可选样式。
- 后续仅采用经验证且固定版本的兼容 Element UI 2.x；Element Plus 属于独立迁移路线。
- 正文、数据值、输入及已选值：`14px / 400 / 21px`，`#303133`。
- 表头及组件分组标题：`14px / 600 / 21px`；弹窗标题：`16px / 600 / 24px`，均使用 `#303133`。
- 辅助说明：`12px / 400 / 18px`，`#595959`；错误、链接、状态、禁用与占位按各自语义处理。
- 适用组件的默认尺寸为 `small / 32px`；不得将这一高度机械应用于表格、文本域、浮层等全部组件。
- 规范正文与场景说明使用 `14px / 400 / 24px`、`#303133`，不降成灰蓝小字。
- 筛选文本输入占位统一“请输入”；未选择下拉统一“请选择”；默认全部的下拉显示“全部”。字段标签保留业务含义；日期保留开始/结束语义。
- 次级文字操作（查看更多、编辑、详情、数据中心、更多）：`12px / 400 / 18px`，`#3377BB`；保留点击热区。
- 本规范库的深色目录、蓝色展示区属于文档排版，不是业务组件颜色或业务导航规范。

## 本页用法与分类

默认用法：当前基础示例使用选择文件按钮和文件列表，列表最多保留3个，仅选择本地文件，不发送上传请求。素材有终端或类型差异时使用下方独立分组。

| 区分什么 | 本页内容 | 选用或触发条件 |
| --- | --- | --- |
| 文件与素材分组（用途） | 普通附件列表与分终端/类型素材管理承载不同内容结构。 | 普通附件保持简单列表；确有终端、规格或媒体类型要求时分组，各组文件独立，不为了美观增加分组。 |
| 类型、大小与数量（业务限制） | 这些参数限制允许选择或上传的文件。 | 按所在业务定义；本页数量上限和本地类型检查只是演示，不能代替正式服务校验。 |
| 选择与上传（功能边界） | 选择文件只是建立本地候选，实际上传是另一段流程。 | 本页演示点击与拖拽建立本地待上传列表，并提供图片列表、图片卡片和预览；自动/手动网络上传未接入，不能把选择完成写成上传成功。 |
| 等待、进度与结果（自动状态） | 状态由具体文件和真实请求结果决定；移除是用户动作。 | 接入上传后逐文件反馈，不把选择完成显示成上传成功；待上传附件移除与撤销按现有危险操作示例执行。 |
| 文件呈现与选择方式 | 列表、图片卡片、拖拽区用于不同素材与选择方式。 | 需要看缩略图用图片卡片；批量本地文件可拖拽；本页只选择和验证，不执行上传。 |

使用边界：不要按颜色挑选上传成功或失败状态，也不要把本地文件名列表冒充上传完成列表。

## 组件规则

- **UPLOAD-R01**：基础示例采用选择文件按钮和文件列表，不包含业务资料提交表单。选择和移除属于用户动作；待上传、上传中、成功、失败属于文件流程状态；拖入等入口能力只在实际接入后提供。
- **UPLOAD-R02**：文件类型、大小、数量由宿主配置；accept 不是安全校验，真实服务仍要验证。失败保留文件和原因，可重试。
- **UPLOAD-R03**：下载与预览是不同动作；无文件不显示虚假预览。此例只读取本地文件名，不上传内容。
- **UPLOAD-R04**：【公共用色】颜色仅从公共色值 引用：主色系 3 个基础色值、辅助功能色 3 个、中性色 10 个，共 16 个基础色值。角色可以多个，实际色值复用；不为每个组件、悬停 或不同字段再新增近似颜色。透明效果仅限遮罩 35% 与阴影 12%，从 外壳深色 派生。
- **UPLOAD-R05**：【统一字体】统一系统中文字体：macOS 优先苹方（PingFang SC），Windows 通常使用微软雅黑（Microsoft YaHei）；工程顺序固定为 "PingFang SC", "Microsoft YaHei", sans-serif。使用设备已有字体，不要求安装或加载网络字体；最后一项仅作兼容回退，不是供页面作者任选的另一套样式。正文 14px/400/21px；表头与分组标题 14px/600/21px，弹窗标题 16px/600/24px；次级文字操作和辅助说明 12px/400/18px。正文与标题同用 #303133；不通过额外加粗或透明度改变正文轻重。
- **UPLOAD-R06**：【普通 / 加载】普通内容 正文深灰，说明 辅助深灰；加载图标及进行中进度 主题蓝。
- **UPLOAD-R07**：【成功 / 警告 / 失败】图标、进度或独立短状态提示分别使用成功绿、警告橙、错误红；详细说明使用正文深灰，必须显示状态文案，不只靠颜色。
- **UPLOAD-R08**：【空 / 未开始 / 取消】空提示 空值灰；未开始与取消用 正文深灰 或 辅助深灰；不自动判成失败或警告。
- **UPLOAD-R09**：【背景 / 操作】白底 白色、分隔 分隔灰；重试与关闭按公共 操作蓝；不为每类消息增加彩底和浅色边框。
- **UPLOAD-R10**：【组件边界】上传成功用 成功绿 图标；文件名 正文深灰，预览/重试 操作蓝；移除使用无框无底危险红文字；上传失败单项提示，不把正常文件染红。
- **UPLOAD-R11**：【叠加优先级】状态叠加规则：禁用阻断交互；输入类控件错误边框覆盖蓝色聚焦边框；输入框不叠加外圈或阴影，其他无边框操作保留键盘焦点提示；选中底覆盖悬停底；只读不等于禁用；加载不等于成功；业务启用/停用的文字结果不等于控件是否可点击。
- **UPLOAD-R12**：上传反馈按文件或素材分组显示：文件名保持正文色，类型或上传失败就近显示错误红原因，配置的失败图标同步错误红；不能把所有文件或选择文件按钮画成错误输入框。按钮键盘焦点沿用按钮规则。当前示例仅执行本地选择；补充的图片列表、图片卡片和拖拽示例包含非空、类型、大小与数量检查，真实进度、上传失败与重试由正式接入补齐。
- **UPLOAD-R13**：危险文字操作单独规定样式与交互：用于表单右侧删除、移除待上传附件、列表行删除等。默认红字 #F56C6C、12px/400，无底色、无边框、无水平内边距；点击区域至少24px高。悬停和按下保持同一红色并加下划线，键盘进入时显示红色焦点提示。禁用用 #C0C4CC 且不可执行；处理中显示原位进度并阻止重复点击。
- **UPLOAD-R14**：删除、移除统一先打开居中确认弹窗，明确对象、数量和后果；确认按钮统一写“确认”，取消不改变数据。未保存项、待上传附件、已保存记录和批量删除都沿用这一入口规则；失败保留原内容和重试入口。普通清空输入、取消筛选或关闭弹层不是删除，不自动标红。
- **UPLOAD-R15**：按终端、规格、媒体类型分别管理文件、进度、失败与预览，移除只影响当前组；组名、格式、尺寸、数量与大小上限应就近说明。
- **UPLOAD-R16**：语言分组是基于本项目广告草稿需求的扩展，不是本次参考截图已证实的内容。每种语言也独立保存，不默认回退成另一语言素材。
- **UPLOAD-R17**：本演示仅本地选文件和撤销移除；正式接入必须补充实际上传进度、解码、尺寸/大小检查及失败重试。异步结果按记录与草稿版本归属，关闭或切换后不得误回写。
- **UPLOAD-R18**：文件列表、图片卡片和拖拽区按素材用途选用，不按成功或失败切换样式。新增图片卡片与拖拽样例均仅本地选择，分别校验图片类型/大小或文件大小，不执行远端上传。
- **UPLOAD-R19**：图片列表与图片卡片按查看密度选择，拖拽是选择方式；同样执行类型/大小/数量限制。用户主动移除待上传文件同样打开居中确认框，确认按钮统一“确认”；取消保留列表。校验不通过的文件直接拒绝，不走删除确认。
- **UPLOAD-R20**：补充图片列表与卡片样例允许预览；各文件组独立。图片须非空PNG/JPEG且单张不超过2MB，拖拽文件须非空且单个不超过5MB，每组最多3个；这些是本页样例条件，生产额度由业务定义。拒绝无效文件并保留已选有效项，用户确认移除后释放临时预览资源。

## 场景与验收清单

以下为需核对的场景组；`[ ]` 不代表已经测试通过。

- [ ] **UPLOAD-S01**：当前示例包含文字文件列表、图片列表、图片卡片、拖拽选择及分组素材管理。按各示例实际限制核对本地选择、非空/类型/大小/数量校验、预览和移除；这些能力不代表已接入网络上传。
- [ ] **UPLOAD-S02**：接入验收按实际配置核对自动或手动上传、上传前的文件类型与大小校验，以及移除前的检查和拦截。
- [ ] **UPLOAD-S03**：选择 / 等待 / 进度 / 成功 / 失败 / 超时 / 取消 / 重试 / 移除 / 超限
- [ ] **UPLOAD-S04**：文件名安全文本 / 同名不同文件 / 大文件 / 返回错误 / 预览失败；服务器校验独立
- [ ] **UPLOAD-S05**：本页核对本地选择入口、文件列表、无效文件错误、预览与移除入口的适用颜色；网络等待、上传进度、成功及失败仅在真实上传接入后验收，不把文件列表当选择行套选中色。
- [ ] **UPLOAD-S06**：核对正文14/400、次级操作12/400、标题600及同色深正文；检查实际弹出层和子 span，不能只检查父元素。
- [ ] **UPLOAD-S07**：本地演示检查取消文件选择、无效类型、切换素材分组、移除与撤销；正式上传接入后再验等待、进度、成功、失败和重试，每次反馈归属正确文件。
- [ ] **UPLOAD-S08**：核对红色文字删除：无框无底、12px/400、悬停、键盘、禁用、处理中；子文字不能被普通蓝链接样式覆盖。
- [ ] **UPLOAD-S09**：本页核对待上传附件的居中确认、取消保留与确认移除；带撤销的本地示例另验撤销。图片列表/卡片的临时资源移除后不承诺撤销；已保存记录与失败重试到确认框专题检查。
- [ ] **UPLOAD-S10**：图片/视频与终端/语言来回切换保持独立列表；无效类型失败；移除后撤销；不触发真实上传。
- [ ] **UPLOAD-S11**：核对文字列表、图片列表、图片卡片和拖拽入口的适用条件；选择文件仅更新本地列表，不伪报远端成功。
- [ ] **UPLOAD-S12**：上传样例核对非空/类型/大小/数量限制、连续选择后非法项不回流、分组错误独立、预览关闭回焦、取消移除保留与确认移除释放临时资源。

### 专题验收重点

取消选择不报错，文件名安全渲染；核对文字列表、图片列表、图片卡片和拖拽入口的本地限制、分组独立、图片预览及移除确认。普通附件、图片和分组素材按各自示例规则检查，不把本地选择宣称为上传成功。

## 当前示例模板

以下来自本专题的结构化示例，使用 Vue 2 模板语法。`v-model`、事件方法、数据列表等依赖 [components.js](../components.js)；完整样式文件及加载顺序见 [通用基线](FOUNDATIONS.md)。自定义组合标签的内部实现由下方依赖文件提供，不能仅复制标签作为完整组件。

```html
<el-upload action="#" :auto-upload="false" :limit="3" :on-exceed="uploadExceeded" :file-list="uploadFiles" :before-remove="confirmUploadRemove">
<el-button icon="el-icon-upload2">选择本地文件</el-button>
<div slot="tip" class="el-upload__tip">最多选择 3 个文件</div>
</el-upload>
<h4>待上传附件的文字移除</h4>
<danger-action-demo mode="file">
</danger-action-demo>
<!-- reference-pattern-media-slots-pattern -->
<section class="reference-supplement">
<h4>多终端素材独立管理</h4>
<media-slots-pattern>
</media-slots-pattern>
<p class="reference-note">参考截图用于提取场景结构；切换、校验、撤销等演示行为按本规范定义。<a href="https://ztqpvr.axshare.com/#id=fzzrfh&amp;p=app闪屏页广告a&amp;g=1" target="_blank" rel="noopener noreferrer">查看参考页</a>
</p>
</section>
<official-upload-types>
</official-upload-types>
```

## 交付与使用边界

- 规范条款、示例代码与待验收场景分开理解；有示例不等于已覆盖所有样式、交互状态和使用场景。
- 业务接口、权限、时区、金额精度、数据规模等依赖应从实际项目读取，不使用演示值代替生产约定。
- 发生样式或文案变更时，同步专题数据、页面与 Markdown，避免规范和样例分离。

## 来源与关联

- 来源线索：历史样板规范 72；2026-09-15 参考抽样：https://ztqpvr.axshare.com/#id=fzzrfh&p=app闪屏页广告a&g=1。
- [打开本专题页面](../index.html#spec-upload)
- [通用基线](FOUNDATIONS.md)
- [规范总索引](README.md)
- [结构化规范数据](../component-data.json)（记录 id：`upload`）
- [原始历史样板](../original-20260621.html)
- [历史规范条目](../spec-notes.json)

自定义示例 `danger-action-demo` 的实现：[danger-actions.js](../danger-actions.js)。

自定义示例 `official-upload-types` 的实现：[official-types.js](../official-types.js)。

自定义示例 `media-slots-pattern` 的实现：[reference-patterns.js](../reference-patterns.js)。

组合样式见 [reference-patterns.css](../reference-patterns.css)；来源及扩展范围见 [参考补充记录](../reference-supplements.md)。

危险操作样式见 [action-contract.css](../action-contract.css)；示例使用本地演示数据。

## 本组件颜色状态表

| 状态 / 条件 | 统一规则 |
| --- | --- |
| 普通 / 加载 | 普通内容 正文深灰，说明 辅助深灰；加载图标及进行中进度 主题蓝。 |
| 成功 / 警告 / 失败 | 图标、进度或独立短状态提示分别使用成功绿、警告橙、错误红；详细说明使用正文深灰，必须显示状态文案，不只靠颜色。 |
| 空 / 未开始 / 取消 | 空提示 空值灰；未开始与取消用 正文深灰 或 辅助深灰；不自动判成失败或警告。 |
| 背景 / 操作 | 白底 白色、分隔 分隔灰；重试与关闭按公共 操作蓝；不为每类消息增加彩底和浅色边框。 |
| 危险文字操作 | 查看、编辑、查看更多使用操作蓝；删除、移除使用危险红。字号同为12px/400，颜色表达动作类型，不通过加粗或更大字号表达危险。 |

本页只演示本地选择和移除，不触发上传成功/失败。正式接入后按文件实际结果使用状态图标；文件名保持正文色，预览/重试用操作蓝，危险移除用无框无底红字。

[公共颜色与字体 token](../color-tokens.json) · [公共组件样式](../color-contract.css) · [系统字体合同（最后加载）](../font-contract.css)

## 业务落地场景

- [广告管理 · 编辑广告 · 各语言图片素材](../../showcase/index.html#adverts) · [场景文档](../../showcase/docs/adverts.md)
- [客服工单管理 · 新增工单或处理补充 · 本地附件](../../showcase/index.html?example=ticket-create#tickets) · [场景文档](../../showcase/docs/tickets.md)

[竞品组件拆解](../../reference-review/竞品组件反推规范.html) · [业务场景分类](../../业务场景分类清单.md)