Upload
选择并上传文件。中文惯用名：上传。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.upload |
| 名称 | Upload |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 选择并上传文件 |
| 描述 | 中文惯用名：上传。 |
预览
静态结构：Upload 根节点 data-slot="upload"，内含隐藏 file input（data-slot="upload-input"）与选择区——按钮形态 data-slot="upload-button"（图标 + 「选择文件」）或 drag 形态 data-slot="upload-dragger"（虚线拖拽区，「点击或拖拽文件到此区域」，支持拖入）；选择区下方依次渲染 data-slot="upload-tip" 辅助说明、data-slot="upload-rejected" 拒绝计数（「已忽略 N 个不符合要求的文件」）与 data-slot="upload-list" 文件列表（每行：文件名 + 格式化大小 + 移除按钮）。选择时按 accept / maxSize / maxCount 校验，不合规文件不进列表。Form 内声明 name 时外层包 FieldShell（label + 校验错误）。
DSL 结构
{
"type": "Upload",
"props": {
"name": "attachments",
"multiple": true,
"accept": "image/*,.pdf",
"maxSize": 5242880,
"maxCount": 3,
"drag": true,
"tip": "支持图片与 PDF，单文件不超过 5MB"
}
}何时用
何时使用
- 表单中采集文件：头像、附件、合同、导入数据文件。
- 单文件用按钮形态（缺省），批量或多文件用 drag 拖拽区 + multiple。
何时不用
- 需要组件直接上传到服务端：Upload 是纯 UI 组件，不发起任何网络请求；上传动作由调用方在 onChange 后自行实现。
- 展示 / 预览已上传文件：使用数据展示或文件预览类组件。
- 仅需文件下载入口：使用 Link / Button。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 按钮形态（缺省） | 描边按钮「选择文件」+ 下方文件列表 | 单文件或低频上传，如头像、单个附件 |
| drag 拖拽区 | 虚线大区域，点击或拖入文件 | 多文件批量上传，配合 multiple 使用 |
| multiple 多选 | 列表累积追加，直至 maxCount | 附件集合、批量导入 |
| tip 辅助说明 | 选择区下方弱提示文案 | 说明类型与大小限制（如「仅 PNG/JPG，不超过 2MB」） |
| disabled 禁用 | 选择区与移除按钮均禁用 | 只读回显、流程未就绪 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（FieldShell 呈现） |
rules | FieldRule[] | — | 校验规则 |
value | UploadFileMeta[] | — | 受控值（文件元数据数组）；Form 内作为字段初始值 |
multiple | boolean | false | 允许多选；开启后新文件追加进列表，否则替换 |
accept | string | — | 接受的文件类型（同原生 input accept：扩展名 / MIME / image/* 等，逗号分隔） |
maxSize | number | — | 单文件大小上限（字节），超出不进列表 |
maxCount | number | — | 文件总数上限，超出不进列表 |
drag | boolean | false | 拖拽区形态（点击或拖入文件选择） |
tip | string | — | 选择区下方的辅助说明文案 |
disabled | boolean | false | 禁用选择与移除 |
onChange | (value: UploadFileMeta[]) => void | — | 文件列表变化事件，传出可序列化元数据数组 Array<{ name, size, type }>（DSL 语义值，不携带 File 本体） |
className | string | — | 根节点 class（Form 内为 form-item 容器，独立渲染时为控件根节点） |
style | CSSProperties | — | 根节点内联样式（同 className 的挂载规则） |
使用规范
- Upload 是纯 UI 组件：只产出元数据数组，不发起网络上传；实际上传、进度与失败重试由调用方在 onChange 后实现。
- 客户端校验只做体验层拦截：accept 按扩展名 / MIME 前缀 / 完整 MIME 匹配，maxSize / maxCount 超限文件不进列表并计数提示；扩展名与 MIME 均可伪造，服务端必须复检扩展名、MIME、文件头与大小。
- 用 tip 明示限制（类型、大小、数量），与 accept / maxSize / maxCount 配置保持一致，减少被拒绝的挫败感。
- multiple 缺省 false：单文件场景新选择替换旧文件；需要累积才开启并配 maxCount。
- onChange 传出的 UploadFileMeta 可序列化（name / size / type），适合进表单值与 DSL 状态；不要试图从中取 File 对象。
正例
- ✓ 头像上传：按钮形态 + accept="image/*" + maxSize 2MB，tip 写明限制，onChange 后由调用方上传。
- ✓ 批量附件：drag + multiple + maxCount 5，拖拽区收集，列表逐项可移除。
- ✓ Form 内声明 name + 必填 rules，未选文件提交时提示「请上传附件」。
反例
- ✕ 以为配置 accept 就完成安全校验，服务端不再复检（扩展名 / MIME 均可伪造）。
- ✕ 期望组件自动上传到服务器（Upload 不发起任何网络请求，需调用方实现）。
- ✕ 限制条件只写代码不写 tip，用户反复选择被拒却不知道为什么。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。