@chenzy-design/svelte 0.3.1 → 0.4.1

package/dist/upload/meta.js

@@ -1,64 +1,106 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
  * See specs/00-foundation/ai-friendly.spec.md.
+ * 严格对齐 Semi Design（fileList/defaultFileList 受控、listType list/picture/none、FileCard 双分支）。
  */
 export const meta = {
     name: 'Upload',
     category: 'input',
-    description: '文件上传，支持点击与拖拽选择、文件列表（名称/大小/状态/移除）。本轮不做真实网络上传。',
+    description: '文件上传，严格对齐 Semi Design：点击/拖拽选择、文件卡片列表（list）与照片墙（picture）、真实 XHR 上传、裁切、目录上传。',
     props: [
-        { name: 'value', type: 'UploadFileItem[]', default: 'undefined', desc: '受控文件列表；提供则为受控' },
-        { name: 'defaultValue', type: 'UploadFileItem[]', default: '[]', desc: '非受控初始文件列表' },
+        { name: 'fileList', type: 'UploadFileItem[]', default: 'undefined', desc: "受控文件列表（对齐 Semi fileList）；提供则受控。UploadFileItem.status：'wait'|'validating'|'uploading'|'success'|'validateFail'|'uploadFail'；preview?:boolean 控制缩略图；file 即 Semi fileInstance；项级 showReplace/showRetry 覆盖组件级；response/event/validateMessage 对齐 Semi FileItem" },
+        { name: 'defaultFileList', type: 'UploadFileItem[]', default: '[]', desc: '非受控初始文件列表（对齐 Semi defaultFileList）' },
         { name: 'accept', type: 'string', default: 'undefined', desc: '接受的文件类型（input accept）' },
         { name: 'multiple', type: 'boolean', default: 'false' },
-        { name: 'directory', type: 'boolean', default: 'false', desc: '上传整个目录（webkitdirectory），递归选择目录下所有文件，保留 relativePath' },
-        { name: 'limit', type: 'number', default: 'undefined', desc: '最大文件数；超出触发 onExceed' },
-        { name: 'maxSize', type: 'number', default: 'undefined', desc: '单文件最大体积（KB）；超限标记 error' },
-        { name: 'minSize', type: 'number', default: 'undefined', desc: '单文件最小体积（KB）；过小标记 error' },
+        { name: 'directory', type: 'boolean', default: 'false', desc: '上传整个目录（webkitdirectory），递归选择目录下所有文件，保留 relativePath（对齐 Semi directory）' },
+        { name: 'limit', type: 'number', default: 'undefined', desc: '最大文件数；超出触发 onExceed；limit=1 替换语义' },
+        { name: 'maxSize', type: 'number', default: 'undefined', desc: '单文件最大体积（KB）；超限标 validateFail（对齐 Semi maxSize）' },
+        { name: 'minSize', type: 'number', default: 'undefined', desc: '单文件最小体积（KB）；过小标 validateFail（对齐 Semi minSize）' },
         { name: 'disabled', type: 'boolean', default: 'false' },
-        { name: 'size', type: "'small'|'default'|'large'", default: "'default'", desc: '组件级尺寸（触发按钮/拖拽区/列表项），区别于文件项的 file.size 体积' },
-        { name: 'status', type: "'default'|'warning'|'error'", default: "'default'", desc: '组件级校验态（表单联动，影响上传区/边框色），区别于文件项的 file.status 上传进度态' },
-        { name: 'listType', type: "'text'|'image'|'picture-card'|'none'", default: 'text', desc: 'image/picture-card 显示缩略图网格' },
-        { name: 'drag', type: 'boolean', default: 'false', desc: 'true 渲染拖拽区，false 渲染按钮' },
+        { name: 'validateStatus', type: "'default'|'error'|'warning'|'success'", default: "'default'", desc: '组件级校验态（表单联动，影响上传区/边框色）。对齐 Semi validateStatus，枚举含 success' },
+        { name: 'listType', type: "'list'|'picture'|'none'", default: "'list'", desc: '文件列表展示类型（对齐 Semi listType）：list 文本卡片、picture 照片墙、none 不渲染列表' },
+        { name: 'draggable', type: 'boolean', default: 'false', desc: 'true 渲染拖拽区，false 渲染按钮（对齐 Semi draggable）' },
         { name: 'action', type: 'string', default: 'undefined', desc: '上传地址；有则选文件后自动 XHR 上传' },
-        { name: 'uploadName', type: 'string', default: "'file'", desc: '表单字段名' },
-        { name: 'headers', type: 'Record<string,string>', default: 'undefined', desc: '额外请求头' },
-        { name: 'uploadData', type: 'Record<string,string>', default: 'undefined', desc: '额外表单字段' },
-        { name: 'concurrency', type: 'number', default: '0', desc: '同时进行的上传数上限；0/不传=不限，超出排队、完成补位' },
-        { name: 'beforeUpload', type: '(file: File, fileList: File[]) => boolean | File | Promise<boolean | File>', default: 'undefined', desc: '上传前异步校验/转换：false/reject 跳过该文件，返回 File 替换，true 正常上传' },
-        { name: 'customRequest', type: '(item: UploadFileItem) => void | Promise<void>', default: 'undefined', desc: '提供则由外部接管上传（优先于 action）；返回 Promise 时受 concurrency 调度' },
-        { name: 'onChange', type: '(list: UploadFileItem[]) => void', default: 'undefined' },
+        { name: 'name', type: 'string', default: "'file'", desc: '表单字段名（对齐 Semi name）' },
+        { name: 'fileName', type: 'string', default: 'undefined', desc: '同 name，避免 Form.Upload 中 props 冲突（对齐 Semi fileName）；优先于 name' },
+        { name: 'headers', type: 'Record<string,string> | ((file: File) => Record<string,string>)', default: 'undefined', desc: '额外请求头；静态对象或按当前 file 求值的函数（对齐 Semi headers）' },
+        { name: 'data', type: 'Record<string,string> | ((file: File) => Record<string,string>)', default: 'undefined', desc: '额外表单字段；静态对象或按当前 file 求值的函数（对齐 Semi data）' },
+        { name: 'beforeUpload', type: '(props: { file, fileList }) => boolean | BeforeUploadObjectResult | Promise<...>', default: 'undefined', desc: '上传前钩子（对齐 Semi beforeUpload）：入参 { file, fileList }。返回 false 拒绝；true/undefined 上传；返回富对象 BeforeUploadObjectResult（shouldUpload/autoRemove/status/validateMessage/fileInstance）精细控制。支持异步' },
+        { name: 'customRequest', type: '(item: UploadFileItem) => void | Promise<void>', default: 'undefined', desc: '自定义上传实现（对齐 Semi customRequest，优先于 action）' },
+        { name: 'afterUpload', type: '(props: { response, file, fileList }) => AfterUploadResult | void', default: 'undefined', desc: '上传成功后钩子（同步返回）：据返回值改该项 status/validateMessage/name/url 或 autoRemove（对齐 Semi afterUpload）' },
+        { name: 'onChange', type: '(props: { fileList, currentFile }) => void', default: 'undefined', desc: '文件列表变化回调（对齐 Semi onChange，入参 { fileList, currentFile }）' },
         { name: 'onExceed', type: '(files: File[]) => void', default: 'undefined' },
-        { name: 'onSuccess', type: '(response: string, item: UploadFileItem) => void', default: 'undefined' },
-        { name: 'onError', type: '(item: UploadFileItem) => void', default: 'undefined' },
-        { name: 'children', type: 'Snippet', default: 'undefined', desc: '自定义触发器内容' },
-        { name: 'showRetry', type: 'boolean', default: 'true', desc: '上传失败是否显示重试按钮' },
-        { name: 'showReplace', type: 'boolean', default: 'false', desc: '是否允许替换已有文件（单文件模式下显示"替换"而不是"添加"）' },
-        { name: 'showClear', type: 'boolean', default: 'false', desc: '是否显示批量清除按钮' },
+        { name: 'onSuccess', type: '(responseBody, file, fileList) => void', default: 'undefined', desc: '上传成功回调（对齐 Semi onSuccess(responseBody, file, fileList)）' },
+        { name: 'onError', type: '(error, file, fileList, xhr) => void', default: 'undefined', desc: '上传失败回调（对齐 Semi onError(error, file, fileList, xhr)）' },
+        { name: 'onProgress', type: '(percent, file, fileList) => void', default: 'undefined', desc: '上传进度回调（仅内置 XHR 上传，对齐 Semi onProgress(percent, file, fileList)）' },
+        { name: 'children', type: 'Snippet', default: 'undefined', desc: '自定义触发器/拖拽区内容' },
+        { name: 'showRetry', type: 'boolean', default: 'true', desc: '上传失败是否显示重试按钮（对齐 Semi showRetry）' },
+        { name: 'showReplace', type: 'boolean', default: 'false', desc: '已上传（success）项显示替换按钮（对齐 Semi showReplace）；list/picture 均支持' },
+        { name: 'showUploadList', type: 'boolean', default: 'true', desc: '是否渲染文件列表（对齐 Semi showUploadList）' },
+        { name: 'showClear', type: 'boolean', default: 'true', desc: '是否显示批量清除按钮（对齐 Semi showClear 默认 true）' },
         { name: 'onClear', type: '() => void', default: 'undefined', desc: '清除按钮点击回调' },
-        { name: 'fileListTitle', type: 'string | false', default: 'undefined', desc: '文件列表标题文字；false 则不渲染' },
-        { name: 'showTooltip', type: 'boolean', default: 'true', desc: '文件名超长是否展示 Tooltip（title 属性）' },
-        { name: 'prompt', type: 'string | Snippet', default: 'undefined', desc: '上传区提示内容（文字或 Snippet）' },
-        { name: 'promptPosition', type: "'left'|'right'|'bottom'", default: "'bottom'", desc: '提示位置：left/right 水平排列，bottom 下方' },
-        { name: 'onDrop', type: '(e: DragEvent, files: File[], rejectFiles: File[]) => void', default: 'undefined', desc: '拖拽放下回调' },
-        { name: 'onOpenFileDialog', type: '() => void', default: 'undefined', desc: '打开文件选择弹窗时回调' },
-        { name: 'onPreviewClick', type: '(fileItem: UploadFileItem) => void', default: 'undefined', desc: '预览图点击回调（image/picture-card listType）' },
-        { name: 'onAcceptInvalid', type: '(files: File[]) => void', default: 'undefined', desc: 'accept 校验失败（文件类型不符）的回调' },
-        { name: 'onRetry', type: '(file: UploadFileItem) => void', default: 'undefined', desc: '重试回调' },
-        { name: 'onSizeError', type: "(file: UploadFileItem, validResult: 'max' | 'min') => void", default: 'undefined', desc: '大小校验失败回调' },
-        { name: 'validateMessage', type: 'string', default: 'undefined', desc: '校验失败统一文案（覆盖 i18n 默认文案）' },
-        { name: 'withCredentials', type: 'boolean', default: 'false', desc: 'XHR withCredentials（跨域凭证）' },
-        { name: 'transformFile', type: '(file: File) => Promise<File>', default: 'undefined', desc: '上传前文件转换（async，返回转换后的 File）' },
-        { name: 'dragIcon', type: 'Snippet', default: 'undefined', desc: '拖拽区自定义图标 Snippet' },
+        { name: 'beforeClear', type: '(fileList) => boolean | Promise<boolean>', default: 'undefined', desc: '批量清除前钩子（对齐 Semi beforeClear）' },
+        { name: 'fileListTitle', type: 'string | false | Snippet<[{ fileList, onClear, clearText }]>', default: 'undefined', desc: '文件列表标题：string=替换标题文字；false=不渲染；Snippet=完全自定义（对齐 Semi fileListTitle）' },
+        { name: 'showTooltip', type: "boolean | { type?: 'tooltip'|'popover'; opts?; renderTooltip? }", default: 'true', desc: '文件名超长提示（对齐 Semi showTooltip），经 Typography.Text ellipsis 消费' },
+        { name: 'prompt', type: 'string | Snippet', default: 'undefined', desc: '上传区提示内容（对齐 Semi prompt）' },
+        { name: 'promptPosition', type: "'left'|'right'|'bottom'", default: "'right'", desc: '提示位置（对齐 Semi promptPosition，默认 right）' },
+        { name: 'onDrop', type: '(e, files, fileList) => void', default: 'undefined', desc: '拖拽放下回调（对齐 Semi onDrop(e, files, fileList)）' },
+        { name: 'onOpenFileDialog', type: '() => void', default: 'undefined' },
+        { name: 'onPreviewClick', type: '(fileItem: UploadFileItem) => void', default: 'undefined', desc: '预览图/卡片点击回调' },
+        { name: 'onAcceptInvalid', type: '(files: File[]) => void', default: 'undefined', desc: 'accept 校验失败回调（对齐 Semi onAcceptInvalid）' },
+        { name: 'onRetry', type: '(fileItem: UploadFileItem) => void', default: 'undefined' },
+        { name: 'onSizeError', type: '(file, fileList) => void', default: 'undefined', desc: '大小校验失败回调（对齐 Semi onSizeError(file, fileList)）' },
+        { name: 'validateMessage', type: 'string', default: 'undefined', desc: '校验失败统一文案（对齐 Semi validateMessage）' },
+        { name: 'withCredentials', type: 'boolean', default: 'false' },
+        { name: 'transformFile', type: '(file: File) => File | Promise<File>', default: 'undefined', desc: '上传前文件转换（对齐 Semi transformFile）' },
+        { name: 'dragIcon', type: 'Snippet', default: 'undefined', desc: '拖拽区自定义图标；未传默认云上传图标' },
         { name: 'dragMainText', type: 'string | Snippet', default: 'undefined', desc: '拖拽区主文案' },
         { name: 'dragSubText', type: 'string | Snippet', default: 'undefined', desc: '拖拽区副文案' },
-        { name: 'addOnPasting', type: 'boolean', default: 'false', desc: '粘贴添加文件（监听 document paste）' },
-        { name: 'hotSpotLocation', type: "'start'|'end'|'none'", default: "'start'", desc: "触发热点位置：'start'=前置，'end'=后置，'none'=隐藏触发器" },
+        { name: 'addOnPasting', type: 'boolean', default: 'false', desc: '粘贴添加文件（对齐 Semi addOnPasting）' },
+        { name: 'onPastingError', type: '(error: unknown) => void', default: 'undefined', desc: '粘贴上传出错回调（对齐 Semi onPastingError）' },
+        { name: 'hotSpotLocation', type: "'start'|'end'", default: "'end'", desc: '照片墙添加瓦片位置（对齐 Semi hotSpotLocation，默认 end）' },
+        { name: 'onFileChange', type: '(files: File[]) => void', default: 'undefined', desc: '选中原始 File 列表变化回调（对齐 Semi onFileChange）' },
+        { name: 'beforeRemove', type: '(file, fileList) => boolean | Promise<boolean>', default: 'undefined', desc: '移除前钩子（对齐 Semi beforeRemove）' },
+        { name: 'onRemove', type: '(currentFile, fileList, currentFileItem) => void', default: 'undefined', desc: '移除后回调（对齐 Semi onRemove）' },
+        { name: 'timeout', type: 'number', default: '0', desc: '单文件上传超时（毫秒），>0 启用' },
+        { name: 'uploadTrigger', type: "'auto' | 'custom'", default: "'auto'", desc: "上传触发时机（对齐 Semi uploadTrigger）：auto 选即传；custom 停 wait 需 upload() 触发" },
+        { name: 'itemStyle', type: 'string | Record<string, string | number>', default: 'undefined', desc: '每个文件卡片自定义 style（对齐 Semi itemStyle）' },
+        { name: 'picWidth', type: 'number | string', default: 'undefined', desc: '照片墙缩略图宽度（对齐 Semi picWidth，number→px）' },
+        { name: 'picHeight', type: 'number | string', default: 'undefined', desc: '照片墙缩略图高度（对齐 Semi picHeight，number→px）' },
+        { name: 'capture', type: "boolean | 'user' | 'environment'", default: 'undefined', desc: '透传给 file input 的 capture 属性（对齐 Semi capture）' },
+        { name: 'crop', type: 'boolean | UploadCropProps', default: 'false', desc: '启用图片裁切：image/* 文件先进裁切弹窗（Modal+Cropper）（对齐 Semi crop）' },
+        { name: 'beforeCrop', type: '(file: File, fileList: File[]) => boolean | Promise<boolean>', default: 'undefined', desc: '裁切前钩子（对齐 Semi beforeCrop(file, fileList)）' },
+        { name: 'onCropError', type: '(err: unknown) => void', default: 'undefined', desc: '裁切失败回调（对齐 Semi onCropError）' },
+        { name: 'cropModalProps', type: 'Record<string, unknown>', default: 'undefined', desc: '透传给裁切 Modal 的额外 props（对齐 Semi cropModalProps）' },
+        { name: 'renderFileItem', type: 'Snippet<[RenderFileItemProps]>', default: 'undefined', desc: '完全自定义单个文件项渲染（替换 FileCard）。入参对齐 Semi RenderFileItemProps（index/listType/onRemove/onRetry/onReplace/onPreviewClick…）' },
+        { name: 'previewFile', type: 'Snippet<[RenderFileItemProps]>', default: 'undefined', desc: '自定义缩略图预览内容（对齐 Semi previewFile）' },
+        { name: 'renderThumbnail', type: 'Snippet<[RenderFileItemProps]>', default: 'undefined', desc: '自定义整个缩略图容器（picture，对齐 Semi renderThumbnail）' },
+        { name: 'showPicInfo', type: 'boolean', default: 'false', desc: '照片墙图片信息浮层（序号，对齐 Semi showPicInfo）' },
+        { name: 'renderPicInfo', type: 'Snippet<[RenderFileItemProps]>', default: 'undefined', desc: '自定义照片墙信息浮层（对齐 Semi renderPicInfo）' },
+        { name: 'renderPicPreviewIcon', type: 'Snippet<[RenderFileItemProps]>', default: 'undefined', desc: '自定义照片墙 hover 预览图标（对齐 Semi renderPicPreviewIcon）' },
+        { name: 'renderPicClose', type: 'Snippet<[{ className, remove }]>', default: 'undefined', desc: '自定义照片墙关闭按钮（对齐 Semi renderPicClose）' },
+        { name: 'renderFileOperation', type: 'Snippet<[RenderFileItemProps]>', default: 'undefined', desc: '自定义文件条操作区（list，对齐 Semi renderFileOperation）' },
+        { name: 'class', type: 'string', default: 'undefined', desc: '根容器额外 class（对齐 Semi className）' },
+        { name: 'style', type: 'string', default: 'undefined', desc: '根容器 style（对齐 Semi style）' },
+    ],
+    subComponents: [
+        {
+            name: 'FileCard',
+            usage: '内部组件，由 Upload 按 listType 渲染（对齐 Semi fileCard.tsx 分层，非独立对外 API）',
+            desc: '单个上传文件项渲染：靠 listType 分 renderPic（picture 照片墙）/renderFile（list 文本卡片）双分支。组件化调用 Button（移除/替换）、Spin（validating）、Progress circle（照片墙上传中）、Typography.Text（文件名 ellipsis）；含三个手写 svg（ErrorSvg/DirectorySvg/ReplaceSvg）。严格对齐 Semi FileCard。',
+            props: [],
+        },
+    ],
+    methods: [
+        { name: 'upload', type: '() => void', desc: '命令式手动触发上传（配合 uploadTrigger="custom"），批量上传所有 wait 文件（对齐 Semi ref.upload）' },
+        { name: 'addFiles', type: '(fileList: FileList | File[]) => void', desc: '命令式添加文件，走完整 accept/limit/校验/上传管线' },
+        { name: 'insert', type: '(files: File[], index?: number) => void', desc: '命令式插入文件到指定 index（对齐 Semi insert）' },
+        { name: 'openFileDialog', type: '() => void', desc: '命令式打开文件选择器（对齐 Semi openFileDialog）' },
     ],
     a11y: {
         role: 'button',
         keyboard: ['Enter', 'Space'],
-        notes: ['隐藏的 file input（visually-hidden）', '触发器为 button', '移除按钮 aria-label「移除」', 'dragger role=button + tabindex + 键盘 Enter/Space'],
+        notes: ['隐藏的 file input', '添加区/拖拽区 role=button + 键盘 Enter/Space', 'FileCard 移除/替换/重试按钮有 aria-label', 'uploading Progress 有可访问名'],
     },
-    tokens: ['--cd-upload-*', '--cd-upload-border-warning', '--cd-upload-border-error', '--cd-button-height-*', '--cd-focus-ring', '--cd-color-warning', '--cd-color-danger', '--cd-spacing-*'],
+    tokens: ['--cd-color-upload-*', '--cd-width-upload-*', '--cd-height-upload-*', '--cd-spacing-upload-*', '--cd-radius-upload-*', '--cd-font-upload-*', '--cd-focus-ring', '--cd-color-warning', '--cd-color-danger', '--cd-spacing-*', '--cd-font-size-*', '--cd-border-radius-*'],
 };

package/dist/upload/types.d.ts

@@ -1,16 +1,150 @@
-export type UploadStatus = 'ready' | 'uploading' | 'success' | 'error';
+import type { Snippet } from 'svelte';
+/**
+ * 文件项上传状态（严格对齐 Semi FileItemStatus，constants.ts 真值）：
+ * - `wait`：已入列，等待上传。
+ * - `validating`：校验中（异步 beforeUpload/transformFile 进行中的中间态）。
+ * - `uploading`：上传中。
+ * - `success`：上传成功。
+ * - `validateFail`：校验失败（accept/maxSize/minSize 等不符）。不显示重试。
+ * - `uploadFail`：上传失败（网络/超时等）。可重试（retry）。
+ */
+export type UploadStatus = 'wait' | 'validating' | 'uploading' | 'success' | 'validateFail' | 'uploadFail';
+/**
+ * 文件列表展示类型（严格对齐 Semi UploadListType，constants.ts LIST_TYPE 真值）：
+ * - `list`（默认）：文本文件卡片列表。
+ * - `picture`：照片墙缩略图网格。
+ * - `none`：不渲染列表。
+ */
+export type UploadListType = 'list' | 'picture' | 'none';
+/**
+ * 组件级校验态（对齐 Semi validateStatus / ValidateStatus）。
+ * 表单联动，影响上传区/边框色。
+ */
+export type UploadValidateStatus = 'default' | 'error' | 'warning' | 'success';
+/** 提示位置（对齐 Semi PromptPositionType，constants.ts PROMPT_POSITION 真值）。 */
+export type UploadPromptPosition = 'left' | 'right' | 'bottom';
+/** 静态对象或按当前 file 求值的函数（对标 Semi data/headers）。 */
+export type UploadDataOrFn = Record<string, string> | ((file: File) => Record<string, string>);
+/**
+ * 文件名超长提示配置（对标 Semi showTooltip）。
+ * boolean：true=用原生 title 属性；false=不展示。
+ * 对象：type 选 Tooltip/Popover 组件包裹文件名；opts 透传给组件；
+ * renderTooltip 完全接管浮层——与 Semi `(content, children) => ReactNode` 语义一致。
+ */
+export type UploadShowTooltip = boolean | {
+    type?: 'tooltip' | 'popover';
+    opts?: Record<string, unknown>;
+    /** 完全接管浮层，位置参数 (fullText, trigger)，与 Semi `(content, children)` 及 Typography.Text 契约一致。 */
+    renderTooltip?: Snippet<[string, Snippet]>;
+};
+/**
+ * 文件列表标题（对标 Semi fileListTitle）。
+ * string：仅替换标题文字（保留默认清空按钮）；false：不渲染标题区；
+ * Snippet：完全自定义标题区（入参含 fileList / onClear / clearText）。
+ */
+export type UploadFileListTitle = string | false | Snippet<[{
+    fileList: UploadFileItem[];
+    onClear: () => void;
+    clearText: string;
+}]>;
 export interface UploadFileItem {
     uid: string;
     name: string;
     size: number;
     status: UploadStatus;
     percent?: number;
+    /**
+     * 原始 File 对象。对标 Semi `fileInstance`——本仓库统一命名为 `file`，
+     * 二者等价（同一 File 引用）；Semi demo 里读 `fileItem.fileInstance` 的写法请改用 `fileItem.file`。
+     */
     file?: File;
-    /** 远程预览地址（image/picture-card 列表优先用它，否则由 file 生成 objectURL） */
+    /**
+     * 是否为该项启用内置缩略图预览（对标 Semi preview）。
+     * picture 列表中：`preview === true` 或存在 `url` 时读取地址显示缩略图；
+     * 显式 `preview === false` 可禁用缩略图（即便有 url 也不预览）。不传时按有无 url 判定（默认预览）。
+     */
+    preview?: boolean;
+    /** 远程预览地址（picture 列表优先用它，否则由 file 生成 objectURL） */
     url?: string;
-    /** 校验失败时的本地化提示（如大小超限/过小）；status==='error' 时展示 */
+    /** 校验失败时的本地化提示（如大小超限/过小）；status==='validateFail' 时展示 */
     error?: string;
+    /**
+     * 校验/上传信息文案（对标 Semi validateMessage）。与 `error` 等价并存：
+     * 优先展示 `validateMessage`，回退 `error`。供 afterUpload/beforeUpload 回写自定义文案。
+     */
+    validateMessage?: string;
+    /**
+     * 项级：单独控制该文件项在 success 态是否显示"替换"按钮（对标 Semi FileItem.showReplace）。
+     * 覆盖组件级 `showReplace`；不传时跟随组件级。
+     */
+    showReplace?: boolean;
+    /**
+     * 项级：单独控制该文件项在 uploadFail 态是否显示"重试"按钮（对标 Semi FileItem.showRetry）。
+     * 覆盖组件级 `showRetry`；不传时跟随组件级。
+     */
+    showRetry?: boolean;
+    /** 服务端响应体（对标 Semi FileItem.response）。XHR success 后写入 responseText 或解析后的 JSON。 */
+    response?: unknown;
+    /** 关联的 XHR 事件（对标 Semi FileItem.event）。成功/失败时的原始 ProgressEvent，供业务读取。 */
+    event?: Event;
     /** 目录上传时文件相对路径（webkitRelativePath，若可用） */
     relativePath?: string;
 }
+/**
+ * beforeUpload 返回的富对象（对标 Semi BeforeUploadObjectResult）。
+ * 除返回 boolean（true 通过/false 拒绝）外，可返回该对象精细控制：
+ * - `shouldUpload`：是否继续上传（false 停在 validateFail/自定义 status）。
+ * - `autoRemove`：true 则自动移除该文件项。
+ * - `status`：直接改该项状态（如标 validateFail）。
+ * - `validateMessage`：校验文案。
+ * - `fileInstance`：替换上传的 File（如压缩后）。
+ */
+export interface BeforeUploadObjectResult {
+    shouldUpload?: boolean;
+    autoRemove?: boolean;
+    status?: UploadStatus;
+    validateMessage?: string;
+    fileInstance?: File;
+}
+/** beforeUpload 入参（对标 Semi BeforeUploadProps）。 */
+export interface BeforeUploadProps {
+    file: UploadFileItem;
+    fileList: UploadFileItem[];
+}
+/** afterUpload 入参（对标 Semi AfterUploadProps）。 */
+export interface AfterUploadProps {
+    response: unknown;
+    file: UploadFileItem;
+    fileList: UploadFileItem[];
+}
+/** afterUpload 返回（对标 Semi AfterUploadResult）。 */
+export interface AfterUploadResult {
+    autoRemove?: boolean;
+    status?: UploadStatus;
+    validateMessage?: string;
+    name?: string;
+    url?: string;
+}
+/**
+ * render 家族入参（对标 Semi RenderFileItemProps）。
+ * 在 UploadFileItem 基础上挂 index/listType/操作回调等全量字段，
+ * 供 renderFileItem / renderFileOperation / renderPicInfo / renderPicPreviewIcon / previewFile 消费。
+ */
+export interface RenderFileItemProps extends UploadFileItem {
+    index: number;
+    listType: UploadListType;
+    disabled: boolean;
+    showRetry?: boolean;
+    showReplace?: boolean;
+    showPicInfo?: boolean;
+    onRemove: () => void;
+    onRetry: () => void;
+    onReplace: () => void;
+    onPreviewClick?: () => void;
+}
+/** renderPicClose 入参（对标 Semi RenderPictureCloseProps）。 */
+export interface RenderPictureCloseProps {
+    className: string;
+    remove: () => void;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/upload/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/upload/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/upload/types.ts"],"names":[],"mappings":"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"}