Upload
文件上传，严格对齐 Semi Design：点击/拖拽选择、文件卡片列表（list）与照片墙（picture）、真实 XHR 上传、裁切、目录上传。
如何引入
import { Upload, FileCard } from '@chenzy-design/svelte';基础用法
children 内放 Button（点按钮激活文件选择）与 picture 照片墙加号瓦片两种触发方式（对齐 Semi）。
list（点击按钮选择文件） picture-card（缩略图网格） 
拖拽上传
通过 draggable 开启拖拽区，自定义主/副文案。
点击或拖拽文件到此处上传
支持任意类型，可一次拖入多个文件
照片墙
listType="picture" 缩略图网格，受控管理图片列表。
限制数量与类型
用 limit 限制数量、accept 限制类型，超限/不符触发回调提示。
最多 3 个文件，仅接受 .png/.jpg/.jpeg
超出数量或类型不符的文件会被忽略
手动上传
uploadTrigger="custom" 选文件不自动上传，外部按钮调 ref.upload() 才统一触发（对齐 Semi）。
选择文件后不会自动上传，点击「开始上传」才真正上传（uploadTrigger="custom"）。
失败态与重试
list 红底失败卡片、picture 失败角标/描边，hover 显示重试按钮（对齐 Semi 状态态）。
文本列表失败态：红底卡片 + 失败信息文本，hover 显示重试按钮。
选择文件
已选择文件 清空
report.pdf 200.0KB
重试
photo.png 50.0KB
图片卡片失败态：失败描边 + 右下失败角标，hover 显示居中重试按钮与移除。
图片裁切
crop 开启后图片先进裁切弹窗（Modal + Cropper），确认后用裁切结果替换原文件再上传；传对象自定义圆形/宽高比。
自定义列表操作区与预览
renderFileOperation 自绘预览/下载/删除操作按钮（删除调 file.onRemove）、previewFile 按 uid 返回 IconFile 或缩略图（对齐 Semi）。
自定义列表操作区（renderFileOperation）：list 模式下自绘操作按钮组，删除调 file.onRemove()（对齐 Semi）。 
自定义预览逻辑（previewFile）：uid==='1' 恒返回 IconFile，其余按缩略图预览（对齐 Semi）。
已选择文件 清空
dyBag.png 130.0KB
已选择文件 清空
dyBag.png 130.0KB
dyBag2.png 130.0KB
头像触发上传
以 Avatar 作为触发器（showUploadList=false + hoverMask 遮罩），点击头像换图的完整观感。
自定义上传属性
data 函数式按当前文件生成附加字段，headers 附加请求头，name 自定义字段名。
附加请求参数与请求头：data 用函数式按当前文件动态生成字段，headers 传静态对象，name 自定义字段名。
受控组件
fileList + onChange 完全受控，外部按钮直接增删列表证明受控。
受控模式：fileList 绑定外部 state，onChange 回写；外部按钮可直接增删证明列表受控。 当前列表共 1 项
已选择文件 清空
readme.txt 1.0KB
图片墙放大预览
renderPicPreviewIcon 自绘 hover 眼睛图标 + onPreviewClick 触发 ImagePreview 放大预览（对齐 Semi）。
照片墙放大预览（对齐 Semi）：renderPicPreviewIcon 自绘 hover 眼睛图标，onPreviewClick 监听单张容器点击，弹出 ImagePreview 放大预览，可缩放/旋转/翻页。 
1
2
3
默认文件列表
defaultFileList 传入已上传项（成功项与 uploadFail 失败项混合态），非受控（对齐 Semi）。
默认文件列表：defaultFileList 传入已上传项（含成功项与失败项混合态），非受控。 picture-card 默认已上传图片：
已选择文件 清空
contract.pdf 100.0KB
invoice.xlsx 50.0KB
重试
禁用
disabled 下 list 与 picture 两态：触发器不可点、列表项（含 validateFail 混合态）不可移除。
禁用（text）：触发器不可点，已有列表项也不可移除。 禁用（picture-card）： 
已选择文件
locked.pdf 4.0KB
rejected.exe 8.0KB
自定义请求
customRequest 完全接管上传，模拟 onProgress 进度后置成功/失败。
自定义请求 customRequest：外部接管上传，模拟进度回调后置成功/失败（文件名含 fail 则失败）。
选择文件
替换与隐藏列表
showReplace 已上传项替换按钮（list/picture），showUploadList=false 隐藏列表。
showReplace：已上传项显示"替换"按钮，点击重选文件替换该项（list）。 showReplace（picture 照片墙）：hover 卡片显示替换。 showUploadList=false：不渲染文件列表，仅保留触发器（列表交由外部呈现）。
选择文件
已选择文件 清空
avatar.png 50.0KB
选择文件
自定义列表标题
fileListTitle 的 string 形式与 Snippet 形式（入参 onClear/clearText 自绘清空）。
fileListTitle 为 string：仅替换标题文字，保留默认清空按钮。 fileListTitle 为 Snippet：完全自定义标题区，用入参 onClear / clearText 自绘清空按钮。
选择文件
附件列表 清空
doc-a.pdf 4.0KB
doc-b.pdf 8.0KB
选择文件
已选 2 个文件
doc-a.pdf 4.0KB
doc-b.pdf 8.0KB
文件名省略提示
超长文件名省略，showTooltip 对象式（type:tooltip）hover 展示完整名称。
文件名超长时省略，showTooltip 对象式（type: 'tooltip'）：hover 用 Tooltip 展示完整文件名。
选择文件
已选择文件 清空
这是一个超级超级超级长的文件名用于演示省略号与悬浮提示效果的示例文档.pdf 4.0KB
annual-financial-report-2025-final-v2-approved.xlsx 8.0KB
进度回调
onProgress 回调把每个文件的 percent 回传外部展示。
onProgress 进度回调：外部拿到每个文件的 percent 并展示数值。
选择文件
命令式操作
bind:this 拿 ref，insert(files, index) 指定位置插入、openFileDialog() 打开选择器。
命令式 API：bind:this 拿到 ref，insert(files, index) 指定位置插入、openFileDialog() 打开选择器。
选择文件
已选择文件 清空
first.txt 1.0KB
批量清空确认
showClear 批量清空按钮 + beforeClear 二次确认拦截。
showClear 批量清空 + beforeClear 二次确认：点击清空按钮先弹确认，取消则保留列表。
选择文件
待处理文件 清空
file-a.log 1.0KB
file-b.log 2.0KB
file-c.log 3.0KB
照片墙热区位置
hotSpotLocation 切换加号瓦片位置：start 前置 / end 后置（对齐 Semi）。
hotSpotLocation 控制照片墙加号瓦片的位置：start 前置、end 后置（对齐 Semi，默认 end）。 
添加提示文本
prompt 提示文本 + promptPosition 位置（left / right / bottom，对齐 Semi 默认 right）。
prompt + promptPosition（对齐 Semi）：提示文本随位置在触发器 左 / 右 / 下 排列。 promptPosition="right"（默认） promptPosition="left" promptPosition="bottom"
支持 jpg / png，单个不超过 2MB
点击右侧按钮选择文件
提示文本位于上传区下方
上传文件夹
directory 递归选择整个目录下所有文件，保留相对路径（对齐 Semi）。
directory（对齐 Semi）：传 directory 后可选择整个文件夹，递归收集其下所有文件并保留相对路径（relativePath）。
照片墙宽高
picWidth / picHeight 统一定制照片墙缩略图与添加瓦片宽高（对齐 Semi v2.42+）。
picWidth / picHeight（对齐 Semi，v2.42+）：统一定制照片墙缩略图与添加瓦片的宽高（number 视为 px）。 
点击添加图片
上传后更新信息
afterUpload 上传成功后据返回对象更新文件项状态 / 校验信息 / 文件名（对齐 Semi）。
afterUpload（对齐 Semi）：上传完成后根据返回对象更新文件项状态 / 校验信息 / 文件名（同步返回，不支持异步）。
上传前校验
beforeUpload 异步校验（validating 中间态）返回富对象拦截大文件 + transformFile 转换（对齐 Semi）。
beforeUpload 校验（对齐 Semi）：异步校验（validating 中间态），返回富对象拒绝大文件并回写校验信息；
配合 transformFile 上传前转换文件。
自定义拖拽区
draggable + children 完全自定义拖拽区外观（对齐 Semi）。
children 自定义拖拽区（对齐 Semi）：draggable + children 时，拖拽区外观完全由 children 决定（无默认虚线框/文案）。
点击或拖拽文件到此处 完全自定义的上传区域
限制文件大小
maxSize / minSize 限制单文件体积（KB），超限标 validateFail 并触发 onSizeError（对齐 Semi）。
maxSize / minSize（对齐 Semi，单位 KB）：过大或过小的文件标记 validateFail 并触发 onSizeError。
完全自定义列表项
renderFileItem 完全自定义文本列表项、showPicInfo + renderPicInfo 图片信息浮层（对齐 Semi）。
renderFileItem：完全自定义文本列表项结构。 showPicInfo + renderPicInfo：picture 照片墙图片信息浮层。 cover.svg · 2.0KB
已选择文件 清空
📄 report.pdf
cover.svg · 2.0KB 完整示例
照片墙、校验态、beforeUpload 异步拦截、目录上传等高级用法。
点击或拖拽文件到此处上传
选择文件
点击或拖拽文件到此处上传
点击或拖拽文件到此处上传
选择文件
选择文件
API 参考
Upload
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
fileList | 受控文件列表（对齐 Semi fileList）；提供则受控。UploadFileItem.status：'wait'|'validating'|'uploading'|'success'|'validateFail'|'uploadFail'；preview?:boolean 控制缩略图；file 即 Semi fileInstance；项级 showReplace/showRetry 覆盖组件级；response/event/validateMessage 对齐 Semi FileItem | UploadFileItem[] | undefined |
defaultFileList | 非受控初始文件列表（对齐 Semi defaultFileList） | UploadFileItem[] | [] |
accept | 接受的文件类型（input accept） | string | undefined |
multiple | — | boolean | false |
directory | 上传整个目录（webkitdirectory），递归选择目录下所有文件，保留 relativePath（对齐 Semi directory） | boolean | false |
limit | 最大文件数；超出触发 onExceed；limit=1 替换语义 | number | undefined |
maxSize | 单文件最大体积（KB）；超限标 validateFail（对齐 Semi maxSize） | number | undefined |
minSize | 单文件最小体积（KB）；过小标 validateFail（对齐 Semi minSize） | number | undefined |
disabled | — | boolean | false |
validateStatus | 组件级校验态（表单联动，影响上传区/边框色）。对齐 Semi validateStatus，枚举含 success | 'default'|'error'|'warning'|'success' | 'default' |
listType | 文件列表展示类型（对齐 Semi listType）：list 文本卡片、picture 照片墙、none 不渲染列表 | 'list'|'picture'|'none' | 'list' |
draggable | true 渲染拖拽区，false 渲染按钮（对齐 Semi draggable） | boolean | false |
action | 上传地址；有则选文件后自动 XHR 上传 | string | undefined |
name | 表单字段名（对齐 Semi name） | string | 'file' |
fileName | 同 name，避免 Form.Upload 中 props 冲突（对齐 Semi fileName）；优先于 name | string | undefined |
headers | 额外请求头；静态对象或按当前 file 求值的函数（对齐 Semi headers） | Record<string,string> | ((file: File) => Record<string,string>) | undefined |
data | 额外表单字段；静态对象或按当前 file 求值的函数（对齐 Semi data） | Record<string,string> | ((file: File) => Record<string,string>) | undefined |
beforeUpload | 上传前钩子（对齐 Semi beforeUpload）：入参 { file, fileList }。返回 false 拒绝；true/undefined 上传；返回富对象 BeforeUploadObjectResult（shouldUpload/autoRemove/status/validateMessage/fileInstance）精细控制。支持异步 | (props: { file, fileList }) => boolean | BeforeUploadObjectResult | Promise<...> | undefined |
customRequest | 自定义上传实现（对齐 Semi customRequest，优先于 action） | (item: UploadFileItem) => void | Promise<void> | undefined |
afterUpload | 上传成功后钩子（同步返回）：据返回值改该项 status/validateMessage/name/url 或 autoRemove（对齐 Semi afterUpload） | (props: { response, file, fileList }) => AfterUploadResult | void | undefined |
onChange | 文件列表变化回调（对齐 Semi onChange，入参 { fileList, currentFile }） | (props: { fileList, currentFile }) => void | undefined |
onExceed | — | (files: File[]) => void | undefined |
onSuccess | 上传成功回调（对齐 Semi onSuccess(responseBody, file, fileList)） | (responseBody, file, fileList) => void | undefined |
onError | 上传失败回调（对齐 Semi onError(error, file, fileList, xhr)） | (error, file, fileList, xhr) => void | undefined |
onProgress | 上传进度回调（仅内置 XHR 上传，对齐 Semi onProgress(percent, file, fileList)） | (percent, file, fileList) => void | undefined |
children | 自定义触发器/拖拽区内容 | Snippet | undefined |
showRetry | 上传失败是否显示重试按钮（对齐 Semi showRetry） | boolean | true |
showReplace | 已上传（success）项显示替换按钮（对齐 Semi showReplace）；list/picture 均支持 | boolean | false |
showUploadList | 是否渲染文件列表（对齐 Semi showUploadList） | boolean | true |
showClear | 是否显示批量清除按钮（对齐 Semi showClear 默认 true） | boolean | true |
onClear | 清除按钮点击回调 | () => void | undefined |
beforeClear | 批量清除前钩子（对齐 Semi beforeClear） | (fileList) => boolean | Promise<boolean> | undefined |
fileListTitle | 文件列表标题：string=替换标题文字；false=不渲染；Snippet=完全自定义（对齐 Semi fileListTitle） | string | false | Snippet<[{ fileList, onClear, clearText }]> | undefined |
showTooltip | 文件名超长提示（对齐 Semi showTooltip），经 Typography.Text ellipsis 消费 | boolean | { type?: 'tooltip'|'popover'; opts?; renderTooltip? } | true |
prompt | 上传区提示内容（对齐 Semi prompt） | string | Snippet | undefined |
promptPosition | 提示位置（对齐 Semi promptPosition，默认 right） | 'left'|'right'|'bottom' | 'right' |
onDrop | 拖拽放下回调（对齐 Semi onDrop(e, files, fileList)） | (e, files, fileList) => void | undefined |
onOpenFileDialog | — | () => void | undefined |
onPreviewClick | 预览图/卡片点击回调 | (fileItem: UploadFileItem) => void | undefined |
onAcceptInvalid | accept 校验失败回调（对齐 Semi onAcceptInvalid） | (files: File[]) => void | undefined |
onRetry | — | (fileItem: UploadFileItem) => void | undefined |
onSizeError | 大小校验失败回调（对齐 Semi onSizeError(file, fileList)） | (file, fileList) => void | undefined |
validateMessage | 校验失败统一文案（对齐 Semi validateMessage） | string | undefined |
withCredentials | — | boolean | false |
transformFile | 上传前文件转换（对齐 Semi transformFile） | (file: File) => File | Promise<File> | undefined |
dragIcon | 拖拽区自定义图标；未传默认云上传图标 | Snippet | undefined |
dragMainText | 拖拽区主文案 | string | Snippet | undefined |
dragSubText | 拖拽区副文案 | string | Snippet | undefined |
addOnPasting | 粘贴添加文件（对齐 Semi addOnPasting） | boolean | false |
onPastingError | 粘贴上传出错回调（对齐 Semi onPastingError） | (error: unknown) => void | undefined |
hotSpotLocation | 照片墙添加瓦片位置（对齐 Semi hotSpotLocation，默认 end） | 'start'|'end' | 'end' |
onFileChange | 选中原始 File 列表变化回调（对齐 Semi onFileChange） | (files: File[]) => void | undefined |
beforeRemove | 移除前钩子（对齐 Semi beforeRemove） | (file, fileList) => boolean | Promise<boolean> | undefined |
onRemove | 移除后回调（对齐 Semi onRemove） | (currentFile, fileList, currentFileItem) => void | undefined |
timeout | 单文件上传超时（毫秒），>0 启用 | number | 0 |
uploadTrigger | 上传触发时机（对齐 Semi uploadTrigger）：auto 选即传；custom 停 wait 需 upload() 触发 | 'auto' | 'custom' | 'auto' |
itemStyle | 每个文件卡片自定义 style（对齐 Semi itemStyle） | string | Record<string, string | number> | undefined |
picWidth | 照片墙缩略图宽度（对齐 Semi picWidth，number→px） | number | string | undefined |
picHeight | 照片墙缩略图高度（对齐 Semi picHeight，number→px） | number | string | undefined |
capture | 透传给 file input 的 capture 属性（对齐 Semi capture） | boolean | 'user' | 'environment' | undefined |
crop | 启用图片裁切：image/* 文件先进裁切弹窗（Modal+Cropper）（对齐 Semi crop） | boolean | UploadCropProps | false |
beforeCrop | 裁切前钩子（对齐 Semi beforeCrop(file, fileList)） | (file: File, fileList: File[]) => boolean | Promise<boolean> | undefined |
onCropError | 裁切失败回调（对齐 Semi onCropError） | (err: unknown) => void | undefined |
cropModalProps | 透传给裁切 Modal 的额外 props（对齐 Semi cropModalProps） | Record<string, unknown> | undefined |
renderFileItem | 完全自定义单个文件项渲染（替换 FileCard）。入参对齐 Semi RenderFileItemProps（index/listType/onRemove/onRetry/onReplace/onPreviewClick…） | Snippet<[RenderFileItemProps]> | undefined |
previewFile | 自定义缩略图预览内容（对齐 Semi previewFile） | Snippet<[RenderFileItemProps]> | undefined |
renderThumbnail | 自定义整个缩略图容器（picture，对齐 Semi renderThumbnail） | Snippet<[RenderFileItemProps]> | undefined |
showPicInfo | 照片墙图片信息浮层（序号，对齐 Semi showPicInfo） | boolean | false |
renderPicInfo | 自定义照片墙信息浮层（对齐 Semi renderPicInfo） | Snippet<[RenderFileItemProps]> | undefined |
renderPicPreviewIcon | 自定义照片墙 hover 预览图标（对齐 Semi renderPicPreviewIcon） | Snippet<[RenderFileItemProps]> | undefined |
renderPicClose | 自定义照片墙关闭按钮（对齐 Semi renderPicClose） | Snippet<[{ className, remove }]> | undefined |
renderFileOperation | 自定义文件条操作区（list，对齐 Semi renderFileOperation） | Snippet<[RenderFileItemProps]> | undefined |
class | 根容器额外 class（对齐 Semi className） | string | undefined |
style | 根容器 style（对齐 Semi style） | string | undefined |
FileCard
单个上传文件项渲染：靠 listType 分 renderPic（picture 照片墙）/renderFile（list 文本卡片）双分支。组件化调用 Button（移除/替换）、Spin（validating）、Progress circle（照片墙上传中）、Typography.Text（文件名 ellipsis）；含三个手写 svg（ErrorSvg/DirectorySvg/ReplaceSvg）。严格对齐 Semi FileCard。
Methods
| 属性 | 类型 | 说明 |
|---|---|---|
upload | () => void | 命令式手动触发上传（配合 uploadTrigger="custom"），批量上传所有 wait 文件（对齐 Semi ref.upload） |
addFiles | (fileList: FileList | File[]) => void | 命令式添加文件，走完整 accept/limit/校验/上传管线 |
insert | (files: File[], index?: number) => void | 命令式插入文件到指定 index（对齐 Semi insert） |
openFileDialog | () => void | 命令式打开文件选择器（对齐 Semi openFileDialog） |
Accessibility
| ARIA role | button |
| 键盘交互 | EnterSpace |
- 隐藏的 file input
- 添加区/拖拽区 role=button + 键盘 Enter/Space
- FileCard 移除/替换/重试按钮有 aria-label
- uploading Progress 有可访问名
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--cd-color-upload-assist-text | var(--cd-color-text-2) | 上传文件列表标题及文件大小文本颜色 |
--cd-color-upload-border | var(--cd-color-border) | 图片墙添加按钮及拖拽区域描边颜色 |
--cd-color-upload-card-bg | var(--cd-color-fill-0) | 上传文件卡片背景色 - 默认 |
--cd-color-upload-card-bg-hover | var(--cd-color-fill-1) | 上传文件卡片背景色 - 悬浮 |
--cd-color-upload-card-fail-bg | var(--cd-color-danger-light-default) | 上传失败文件卡片背景色 - 默认 |
--cd-color-upload-card-fail-bg-hover | var(--cd-color-danger-light-hover) | 上传失败文件卡片背景色 - 悬浮 |
--cd-color-upload-clear-text | var(--cd-color-primary) | 上传清空按钮文本颜色 |
--cd-color-upload-drag-area-bg | var(--cd-color-tertiary-light-default) | 上传可拖拽区域背景颜色 - 默认 |
--cd-color-upload-drag-area-bg-hover | var(--cd-color-primary-light-default) | 上传可拖拽区域背景颜色 - 悬浮 |
--cd-color-upload-drag-area-border-hover | var(--cd-color-primary) | 上传可拖拽区域描边颜色 - 悬浮 |