跳到主要内容
Termlib

UI 组件 · 表单输入

上传

Upload

也叫：文件上传、图片上传、拖拽上传、Uploader

让用户从电脑或手机里选择文件、图片并传到服务器的控件，可以点按钮选择，也可以把文件拖进来。

点「标注」看每个部分叫什么。

怎么跟 AI 说

改成你的业务内容再发

「附件」用拖拽上传区域：虚线边框的方框，中间是上传图标和「点击或将文件拖到此处」，下方灰色小字「支持 PDF、Word，单个不超过 10MB，最多 5 个」。文件拖入时边框加深，上传后在下方列出文件名、进度条和删除按钮，失败的显示重试。

发给

01判断

你的内容是这样吗？

对照两列，确认上传是不是你要找的。

符合这些情况，用上传

  • 表单里需要提交附件、证件照、合同扫描件等文件
  • 上传头像、商品图片这类需要马上看到缩略图预览的图片
  • 一次上传多个文件或大文件，需要看到每个文件的进度和结果

是这些情况，换成别的

  • 用户只需要粘贴一个图片或文件的网址时，用普通输入框即可

    改用输入框

  • 需要在页面上边写文字边插图排版时，应该用富文本编辑器自带的插图功能

    改用富文本编辑器

  • 批量导入几千条表格数据并需要逐行校验时，应该做成专门的分步导入流程

拿不准？上传页面截图，页面分析会逐块判断该用什么布局。

02避坑

常见坏用法

看起来能用，其实会给用户添麻烦。

  1. 01

    不提前说明格式和大小限制，用户传完才看到「文件过大」

  2. 02

    上传过程中没有进度和状态，用户不知道是卡住了还是成功了

  3. 03

    图片上传后不显示缩略图，用户无法确认传对了没有

03识别

怎么认出它

先看整体结构，再对照几个一眼能认出的特征。

结构

由触发选择的按钮或拖拽区域、限制说明文字和已上传文件列表组成，列表每项含文件名、进度和操作按钮。

组成部分点一下，在上面的线框里标出来

识别特征

  1. 1虚线边框的大方框，中间有向上箭头或云朵图标和「拖到此处」的文字
  2. 2带上传图标的按钮，下方列出文件名和细进度条
  3. 3一排方形缩略图，最后一个格子是虚线框加「+」

04解释

详细解释

上传组件最常见三种样子：一个「上传文件」按钮，点了打开系统的文件选择窗口；一块虚线边框的 拖拽区域，写着「点击或将文件拖到此处上传」；一排方形的 图片墙，每格显示缩略图，最后一格是「+」。选完文件后，下方会列出文件名、进度条、成功或失败状态，以及删除、重新上传按钮。

写需求时要讲清限制：允许的文件类型（比如只要 jpg、png）、单个文件大小上限、最多几个文件。这些要在选择前就用灰色小字提示，而不是上传失败了才告诉用户。上传头像这类场景还常在选图后弹出裁剪框。大文件要显示真实进度，并允许取消。

开发者信息
术语 ID
component-upload
DOM 选择器

插件在本地识别时匹配这些 CSS 选择器（标签、ARIA role、常见组件库 class）。

  • input[type="file"]
  • .ant-upload-wrapper
  • .ant-upload-drag
  • .el-upload
  • .arco-upload
  • .t-upload
  • .n-upload
类名关键词

类名、id、data-testid 拆成单词后连续匹配，例如 page-header、PageHeader_root__x7a、pageHeader 都拆成 page、header。

  • upload
  • uploader
  • dropzone
  • drop-zone
  • file-upload
  • file-input
  • upload-area
  • upload-box
  • file-drop
组件名

React / Vue 开发模式下读到的组件名，不区分大小写，会去掉 El、Ant、Mui 这类组件库前缀。

  • Upload
  • Dropzone
  • FileUpload
  • Uploader
  • FileInput
优先级
1 · 同一层有多条命中时，优先级高的胜出
版本
v2 · 更新于 2026/09/30