@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/upload/Upload.svelte

@@ -1,14 +1,11 @@
 <!--
-  Upload — see specs/components/input/Upload.spec.md
-  Basic subset: file selection (click + drag) + file list (name/size/status/remove).
-  Controlled / uncontrolled `value`. 真实上传：有 action 且无 customRequest 时，
-  选文件后自动 XHR 上传（uploading→进度→success/error），customRequest 优先；
-  XHR 句柄存 Map，remove/卸载时 abort。uploading 时渲染 Progress（line）。
-  listType=image/picture-card：缩略图预览（item.url 优先，否则 file → objectURL，移除/卸载 revoke）。
-  concurrency 并发上限（0=不限，超出排队、完成补位，core createUploadQueue 调度）；
-  beforeUpload 异步校验/转换（false/reject 跳过该文件，返回 File 替换，true 正常上传）。
-  directory：input 命令式加 webkitdirectory，可递归选择整个目录（保留 relativePath）。
-  minSize/maxSize：core validateFileSize 纯函数校验（单位 KB），超限标 error + i18n 提示。
+  Upload — 严格对齐 Semi Design（破坏性重写，无向后兼容）。
+  受控 prop：fileList / defaultFileList（对齐 Semi）。文件卡片渲染拆到 FileCard.svelte
+  （renderPic/renderFile 双分支）。class 命名走 Semi 连字符体系 cd-upload-*。
+  真实上传：有 action 且无 customRequest 时选文件后自动 XHR 上传；customRequest 优先。
+  listType=picture：照片墙缩略图网格；list：文本卡片列表；none：不渲染列表。
+  crop：image/* 文件先进裁切弹窗（Modal + Cropper）。directory：input 加 webkitdirectory。
+  minSize/maxSize：core validateFileSize 校验（KB）；beforeUpload 支持返回富对象控制上传。
 -->
 <script lang="ts">
   import type { Snippet } from 'svelte';
@@ -17,111 +14,177 @@
     useLiveAnnouncer,
     computeUploadPercent,
     isUploadOk,
-    createUploadQueue,
-    resolveBeforeUpload,
     validateFileSize,
-    type BeforeUploadResult,
   } from '@chenzy-design/core';
   import { useLocale } from '../locale-provider/index.js';
-  import { Progress } from '../progress/index.js';
-  import type { UploadFileItem } from './types.js';
+  import { Modal } from '../modal/index.js';
+  import { Cropper } from '../cropper/index.js';
+  import FileCard from './FileCard.svelte';
+  import { IconUpload } from '@chenzy-design/icons';
+  import type { CropperShape } from '../cropper/index.js';
+  import type {
+    UploadFileItem,
+    UploadListType,
+    UploadValidateStatus,
+    UploadPromptPosition,
+    UploadDataOrFn,
+    UploadShowTooltip,
+    UploadFileListTitle,
+    BeforeUploadObjectResult,
+    BeforeUploadProps,
+    AfterUploadProps,
+    AfterUploadResult,
+    RenderFileItemProps,
+    RenderPictureCloseProps,
+  } from './types.js';
+
+  /**
+   * 裁剪配置（对标 Semi CropProps）。crop=true 时用默认配置；传对象覆盖。
+   */
+  export interface UploadCropProps {
+    aspectRatio?: number;
+    shape?: CropperShape;
+    minZoom?: number;
+    maxZoom?: number;
+    zoomStep?: number;
+    quality?: number;
+    fill?: string;
+    modalTitle?: string;
+    modalOkText?: string;
+    modalCancelText?: string;
+  }
 
   interface Props {
-    value?: UploadFileItem[];
-    defaultValue?: UploadFileItem[];
+    /** 受控文件列表（对齐 Semi fileList）；提供则受控。 */
+    fileList?: UploadFileItem[];
+    /** 非受控初始文件列表（对齐 Semi defaultFileList）。 */
+    defaultFileList?: UploadFileItem[];
     accept?: string;
     multiple?: boolean;
-    /** 上传整个目录（input 加 webkitdirectory，递归选择目录下所有文件）。 */
+    /** 上传整个目录（对齐 Semi directory；input 加 webkitdirectory）。 */
     directory?: boolean;
     limit?: number;
-    /** Max size per file, in KB. */
+    /** 单文件最大体积，单位 KB（对齐 Semi maxSize）。 */
     maxSize?: number;
-    /** Min size per file, in KB. 小于此值的文件校验失败（error）。 */
+    /** 单文件最小体积，单位 KB（对齐 Semi minSize）。 */
     minSize?: number;
     disabled?: boolean;
-    /**
-     * 组件级尺寸（触发按钮/列表项），与其它表单控件一致。
-     * 注意：区别于每个文件项的 file.size（字节体积）。
-     */
-    size?: 'small' | 'default' | 'large';
-    /**
-     * 组件级校验态（表单联动），影响上传区/边框色。
-     * 注意：区别于每个文件项的 file.status（ready/uploading/error 上传进度态）。
-     */
-    status?: 'default' | 'warning' | 'error';
-    listType?: 'text' | 'image' | 'picture-card' | 'none';
-    drag?: boolean;
-    /** 上传地址；提供且无 customRequest 时选文件后自动 XHR 上传 */
+    /** 组件级校验态（对齐 Semi validateStatus）。 */
+    validateStatus?: UploadValidateStatus;
+    /** 文件列表展示类型（对齐 Semi listType）：list（默认）/picture/none。 */
+    listType?: UploadListType;
+    /** 拖拽上传（对齐 Semi draggable）。 */
+    draggable?: boolean;
+    /** 上传地址（对齐 Semi action）；提供且无 customRequest 时自动 XHR 上传。 */
     action?: string;
-    /** 表单字段名，默认 'file' */
-    uploadName?: string;
-    /** 额外请求头 */
-    headers?: Record<string, string>;
-    /** 随文件一起提交的额外字段 */
-    uploadData?: Record<string, string>;
-    /** 同时进行的上传数上限；0/不传=不限（受控调度，超出排队，完成补位） */
-    concurrency?: number;
+    /** 表单字段名（对齐 Semi name），默认 'file'。 */
+    name?: string;
+    /** 同 name，避免 Form.Upload 中 props 冲突（对齐 Semi fileName）。优先于 name。 */
+    fileName?: string;
+    /** 额外请求头（对齐 Semi headers）。静态对象或按当前 file 求值的函数。 */
+    headers?: UploadDataOrFn;
+    /** 随文件一起提交的额外字段（对齐 Semi data）。静态对象或按当前 file 求值的函数。 */
+    data?: UploadDataOrFn;
     /**
-     * 每个文件上传前调用：返回 false / reject 跳过该文件（移除）；
-     * 返回 File 替换为该文件（如压缩后）；返回 true / resolve 正常上传。异步会被 await。
+     * 上传前钩子（对齐 Semi beforeUpload）：入参 { file, fileList }。
+     * 返回 false 拒绝该文件；true/undefined 正常上传；返回富对象 BeforeUploadObjectResult
+     * 精细控制（shouldUpload/autoRemove/status/validateMessage/fileInstance）。支持异步。
      */
-    beforeUpload?: (file: File, fileList: File[]) => BeforeUploadResult | Promise<BeforeUploadResult>;
-    /** 自定义上传实现（优先于 action）。返回 Promise 时受 concurrency 调度（完成才释放槽位）。 */
+    beforeUpload?: (
+      props: BeforeUploadProps,
+    ) => boolean | BeforeUploadObjectResult | Promise<boolean | BeforeUploadObjectResult>;
+    /** 自定义上传实现（对齐 Semi customRequest，优先于 action）。 */
     customRequest?: (item: UploadFileItem) => void | Promise<void>;
-    onChange?: (list: UploadFileItem[]) => void;
+    /** 上传成功后钩子（对齐 Semi afterUpload），同步返回。 */
+    afterUpload?: (props: AfterUploadProps) => AfterUploadResult | void;
+    onChange?: (props: { fileList: UploadFileItem[]; currentFile: UploadFileItem }) => void;
     onExceed?: (files: File[]) => void;
-    onSuccess?: (response: string, item: UploadFileItem) => void;
-    onError?: (item: UploadFileItem) => void;
+    /** 上传成功（对齐 Semi onSuccess(responseBody, file, fileList)）。 */
+    onSuccess?: (responseBody: unknown, file: UploadFileItem, fileList: UploadFileItem[]) => void;
+    /** 上传失败（对齐 Semi onError(error, file, fileList, xhr)）。 */
+    onError?: (error: Error, file: UploadFileItem, fileList: UploadFileItem[], xhr?: XMLHttpRequest) => void;
+    /** 上传进度（对齐 Semi onProgress(percent, file, fileList)）。 */
+    onProgress?: (percent: number, file: UploadFileItem, fileList: UploadFileItem[]) => void;
     children?: Snippet;
-    /** 上传失败是否显示重试按钮。默认 true */
+    /** 上传失败是否显示重试按钮（对齐 Semi showRetry）。默认 true。 */
     showRetry?: boolean;
-    /** 是否允许替换已有文件（单文件模式下显示"替换"而不是"添加"）。默认 false */
+    /** success 项显示替换按钮（对齐 Semi showReplace）。默认 false。 */
     showReplace?: boolean;
-    /** 是否显示批量清除按钮。默认 false */
+    /** 是否渲染文件列表（对齐 Semi showUploadList）。默认 true。 */
+    showUploadList?: boolean;
+    /** 是否显示批量清除按钮（对齐 Semi showClear）。默认 true。 */
     showClear?: boolean;
-    /** 清除按钮点击回调 */
     onClear?: () => void;
-    /** 文件列表标题文字；false 则不渲染。默认 undefined（不渲染） */
-    fileListTitle?: string | false;
-    /** 文件名超长是否展示 Tooltip（简单实现：title 属性）。true=展示 title；false=不展示。默认 true */
-    showTooltip?: boolean;
-    /** 上传区提示内容（文字或 Snippet） */
+    /** 批量清除前钩子（对齐 Semi beforeClear）。 */
+    beforeClear?: (fileList: UploadFileItem[]) => boolean | Promise<boolean>;
+    /** 文件列表标题（对齐 Semi fileListTitle）。 */
+    fileListTitle?: UploadFileListTitle;
+    /** 文件名超长提示（对齐 Semi showTooltip）。默认 true。 */
+    showTooltip?: UploadShowTooltip;
+    /** 上传区提示内容（对齐 Semi prompt）。 */
     prompt?: string | Snippet;
-    /** 提示位置：left/right 为水平排列，bottom 为下方。默认 'bottom' */
-    promptPosition?: 'left' | 'right' | 'bottom';
-    /** 拖拽放下回调 */
-    onDrop?: (e: DragEvent, files: File[], rejectFiles: File[]) => void;
-    /** 打开文件选择弹窗时回调 */
+    /** 提示位置（对齐 Semi promptPosition）。默认 'right'。 */
+    promptPosition?: UploadPromptPosition;
+    onDrop?: (e: DragEvent, files: File[], fileList: UploadFileItem[]) => void;
     onOpenFileDialog?: () => void;
-    /** 预览图点击回调（image/picture-card listType） */
     onPreviewClick?: (fileItem: UploadFileItem) => void;
-    /** accept 校验失败（文件类型不符）的回调 */
     onAcceptInvalid?: (files: File[]) => void;
-    /** 重试回调 */
-    onRetry?: (file: UploadFileItem) => void;
-    /** 大小校验失败回调 */
-    onSizeError?: (file: UploadFileItem, validResult: 'max' | 'min') => void;
-    /** 校验失败统一文案（覆盖 i18n 默认文案） */
+    onRetry?: (fileItem: UploadFileItem) => void;
+    onSizeError?: (file: UploadFileItem, fileList: UploadFileItem[]) => void;
+    /** 校验失败统一文案（对齐 Semi validateMessage）。 */
     validateMessage?: string;
-    /** XHR withCredentials（跨域凭证） */
     withCredentials?: boolean;
-    /** 上传前文件转换（async，返回转换后的 File） */
-    transformFile?: (file: File) => Promise<File>;
-    /** 拖拽区自定义图标 Snippet */
+    transformFile?: (file: File) => File | Promise<File>;
     dragIcon?: Snippet;
-    /** 拖拽区主文案（Snippet 或 string） */
     dragMainText?: string | Snippet;
-    /** 拖拽区副文案（Snippet 或 string） */
     dragSubText?: string | Snippet;
-    /** 粘贴添加文件（监听 document paste） */
     addOnPasting?: boolean;
-    /** 触发热点位置（拖拽区时无效）。'start'=前置，'end'=后置，'none'=隐藏触发器。默认 'start' */
-    hotSpotLocation?: 'start' | 'end' | 'none';
+    onPastingError?: (error: unknown) => void;
+    /** 触发热点位置（对齐 Semi hotSpotLocation）。默认 'end'。 */
+    hotSpotLocation?: 'start' | 'end';
+    /** 选中原始 File 列表变化回调（对齐 Semi onFileChange）。 */
+    onFileChange?: (files: File[]) => void;
+    /** 移除前钩子（对齐 Semi beforeRemove）。 */
+    beforeRemove?: (file: UploadFileItem, fileList: UploadFileItem[]) => boolean | Promise<boolean>;
+    /** 移除后回调（对齐 Semi onRemove(currentFile, fileList, currentFileItem)）。 */
+    onRemove?: (currentFile: File | undefined, fileList: UploadFileItem[], currentFileItem: UploadFileItem) => void;
+    /** 单文件上传超时（毫秒）。 */
+    timeout?: number;
+    /** 上传触发时机（对齐 Semi uploadTrigger）。默认 'auto'。 */
+    uploadTrigger?: 'auto' | 'custom';
+    /** 每项卡片自定义 style（对齐 Semi itemStyle）。 */
+    itemStyle?: string | Record<string, string | number>;
+    /** 照片墙缩略图宽度（对齐 Semi picWidth）。 */
+    picWidth?: number | string;
+    /** 照片墙缩略图高度（对齐 Semi picHeight）。 */
+    picHeight?: number | string;
+    capture?: boolean | 'user' | 'environment';
+
+    // ——— 裁剪集成（对标 Semi crop 家族）———
+    crop?: boolean | UploadCropProps;
+    /** 裁切前钩子（对齐 Semi beforeCrop(file, fileList)）。 */
+    beforeCrop?: (file: File, fileList: File[]) => boolean | Promise<boolean>;
+    onCropError?: (err: unknown) => void;
+    cropModalProps?: Record<string, unknown>;
+
+    // ——— render 家族（对齐 Semi，用 Svelte Snippet，入参 RenderFileItemProps）———
+    renderFileItem?: Snippet<[RenderFileItemProps]>;
+    previewFile?: Snippet<[RenderFileItemProps]>;
+    renderThumbnail?: Snippet<[RenderFileItemProps]>;
+    showPicInfo?: boolean;
+    renderPicInfo?: Snippet<[RenderFileItemProps]>;
+    renderPicPreviewIcon?: Snippet<[RenderFileItemProps]>;
+    renderPicClose?: Snippet<[RenderPictureCloseProps]>;
+    renderFileOperation?: Snippet<[RenderFileItemProps]>;
+    /** 根容器额外 class（对齐 Semi className）。 */
+    class?: string;
+    /** 根容器 style（对齐 Semi style）。 */
+    style?: string;
   }
 
   let {
-    value,
-    defaultValue = [],
+    fileList,
+    defaultFileList = [],
     accept,
     multiple = false,
     directory = false,
@@ -129,30 +192,33 @@
     maxSize,
     minSize,
     disabled = false,
-    size = 'default',
-    status = 'default',
-    listType = 'text',
-    drag = false,
+    validateStatus = 'default',
+    listType = 'list',
+    draggable = false,
     action,
-    uploadName = 'file',
+    name = 'file',
+    fileName,
     headers,
-    uploadData,
-    concurrency = 0,
+    data,
     beforeUpload,
     customRequest,
+    afterUpload,
     onChange,
     onExceed,
     onSuccess,
     onError,
+    onProgress,
     children,
     showRetry = true,
     showReplace = false,
-    showClear = false,
+    showUploadList = true,
+    showClear = true,
     onClear,
+    beforeClear,
     fileListTitle,
     showTooltip = true,
     prompt,
-    promptPosition = 'bottom',
+    promptPosition = 'right',
     onDrop,
     onOpenFileDialog,
     onPreviewClick,
@@ -166,42 +232,61 @@
     dragMainText,
     dragSubText,
     addOnPasting = false,
-    hotSpotLocation = 'start',
+    onPastingError,
+    hotSpotLocation = 'end',
+    onFileChange,
+    beforeRemove,
+    onRemove,
+    timeout = 0,
+    uploadTrigger = 'auto',
+    itemStyle,
+    picWidth,
+    picHeight,
+    capture,
+    crop = false,
+    beforeCrop,
+    onCropError,
+    cropModalProps,
+    renderFileItem,
+    previewFile,
+    renderThumbnail,
+    showPicInfo = false,
+    renderPicInfo,
+    renderPicPreviewIcon,
+    renderPicClose,
+    renderFileOperation,
+    class: className,
+    style: styleProp,
   }: Props = $props();
 
   const loc = useLocale();
-  // 屏幕阅读器播报（spec §6）：进度 polite（节流，避免每 1% 刷屏），成功 polite、失败 assertive。
-  // 命令式调用在 XHR 事件回调里（非 render 期），符合红线 #3。
   const announcer = useLiveAnnouncer();
-  // 每个文件上次播报的进度档（每 25% 一档），避免逐 % 重复播报。
   const announcedBucket = new Map<string, number>();
 
-  const isControlled = $derived(value !== undefined);
-  let inner = $state<UploadFileItem[]>(getInitialValue());
-  // Controlled (`value=`): parent owns the list; we never write the prop, only
-  // propagate via `onChange`. Uncontrolled: keep our own state in sync.
-  const current = $derived(isControlled ? (value ?? []) : inner);
+  // 表单字段名：fileName 优先于 name（对齐 Semi 在 FormData 中 fileName || name）。
+  const fieldName = $derived(fileName ?? name);
 
-  function getInitialValue(): UploadFileItem[] {
-    return [...defaultValue];
+  const isControlled = $derived(fileList !== undefined);
+  // 非受控初始值（仅取初始 defaultFileList，后续由内部状态管理）。
+  function getInitial(): UploadFileItem[] {
+    return [...defaultFileList];
   }
+  let inner = $state<UploadFileItem[]>(getInitial());
+  const current = $derived(isControlled ? (fileList ?? []) : inner);
 
   let inputEl: HTMLInputElement | null = null;
 
-  // 进行中的 XHR 句柄（uid → xhr），remove/卸载时 abort。
-  const xhrMap = new Map<string, XMLHttpRequest>();
+  let dragOver = $state(false);
+  let dragEnterTarget: EventTarget | null = null;
 
-  // 并发调度队列：concurrency 变化时重建（新文件用新上限，进行中的 XHR 不受影响）。
-  // concurrency<=0 时不限，行为与未接入队列前一致。
-  const queue = $derived(createUploadQueue(concurrency));
-
-  // 卸载标记：避免卸载后仍向已 abort 的 XHR/已移除项回写状态。
+  const xhrMap = new Map<string, XMLHttpRequest>();
   let mounted = true;
 
-  // image/picture-card 预览：本地缓存 file → objectURL（uid → url），移除/卸载 revoke。
   const objectUrls = new Map<string, string>();
-  const isImageList = $derived(listType === 'image' || listType === 'picture-card');
+  const isPicture = $derived(listType === 'picture');
+
   function previewUrl(item: UploadFileItem): string | undefined {
+    if (item.preview === false) return undefined;
     if (item.url) return item.url;
     if (!item.file) return undefined;
     let u = objectUrls.get(item.uid);
@@ -211,6 +296,17 @@
     }
     return u;
   }
+  // list 文本卡片预览：仅图片项返回缩略图地址，否则 undefined → 占位。
+  function itemThumbUrl(item: UploadFileItem): string | undefined {
+    if (item.preview === false) return undefined;
+    const isImage = item.file ? item.file.type.startsWith('image/') : Boolean(item.url);
+    if (!isImage) return undefined;
+    return previewUrl(item);
+  }
+  function itemPreviewEnabled(item: UploadFileItem): boolean {
+    if (item.preview === false) return false;
+    return item.file ? item.file.type.startsWith('image/') : Boolean(item.url);
+  }
   function revokeUrl(uid: string) {
     const u = objectUrls.get(uid);
     if (u !== undefined) {
@@ -219,19 +315,50 @@
     }
   }
 
-  // 按 uid 局部更新某个文件项（不破坏受控/非受控约定，走 commit）。
   function patchItem(uid: string, patch: Partial<UploadFileItem>) {
     commit(current.map((it) => (it.uid === uid ? { ...it, ...patch } : it)));
   }
 
-  // directory 是非标准 input 属性（webkitdirectory），Svelte 模板不直接支持，
-  // 故命令式 toggle（红线 #3）。directory 变化时同步增删。
+  // afterUpload（对齐 Semi notifyAfterUpload）：成功后据返回值改该项或自动移除。
+  function applyAfterUpload(uid: string, responseText: string) {
+    if (!afterUpload) return;
+    const item = current.find((it) => it.uid === uid);
+    if (!item) return;
+    let response: unknown = responseText;
+    try {
+      response = JSON.parse(responseText);
+    } catch {
+      response = responseText;
+    }
+    const result = afterUpload({ response, file: item, fileList: current });
+    if (!result) return;
+    if (result.autoRemove) {
+      removeInternal(uid);
+      return;
+    }
+    const patch: Partial<UploadFileItem> = {};
+    if (result.status) patch.status = result.status;
+    if (result.validateMessage !== undefined) patch.validateMessage = result.validateMessage;
+    if (result.name !== undefined) patch.name = result.name;
+    if (result.url !== undefined) {
+      revokeUrl(uid);
+      patch.url = result.url;
+    }
+    if (Object.keys(patch).length > 0) patchItem(uid, patch);
+  }
+
+  // directory/capture 是非标准 input 属性，命令式 toggle。
   $effect(() => {
     if (!inputEl) return;
     inputEl.toggleAttribute('webkitdirectory', directory);
+    if (capture === undefined || capture === false) {
+      inputEl.removeAttribute('capture');
+    } else {
+      inputEl.setAttribute('capture', capture === true ? '' : capture);
+    }
   });
 
-  // 卸载时中止所有进行中的上传 + 释放预览 objectURL。
+  // 卸载：中止上传 + 释放 objectURL + 收尾裁切。
   $effect(() => {
     return () => {
       mounted = false;
@@ -240,30 +367,35 @@
       for (const u of objectUrls.values()) URL.revokeObjectURL(u);
       objectUrls.clear();
       announcedBucket.clear();
+      if (cropSrc) URL.revokeObjectURL(cropSrc);
+      cropResolve?.(null);
+      cropResolve = null;
     };
   });
 
-  // 粘贴监听：addOnPasting 时挂载 document paste。
+  // 粘贴监听（addOnPasting）。
   $effect(() => {
     if (!addOnPasting || disabled) return;
     function handlePaste(e: ClipboardEvent) {
-      const items = e.clipboardData?.items;
-      if (!items) return;
-      const files: File[] = [];
-      for (const item of Array.from(items)) {
-        if (item.kind === 'file') {
-          const f = item.getAsFile();
-          if (f) files.push(f);
+      try {
+        const items = e.clipboardData?.items;
+        if (!items) return;
+        const files: File[] = [];
+        for (const item of Array.from(items)) {
+          if (item.kind === 'file') {
+            const f = item.getAsFile();
+            if (f) files.push(f);
+          }
         }
+        if (files.length > 0) addFiles(files);
+      } catch (error) {
+        onPastingError?.(error);
       }
-      if (files.length > 0) addFiles(files);
     }
     document.addEventListener('paste', handlePaste);
     return () => document.removeEventListener('paste', handlePaste);
   });
 
-  // 进度播报节流：每跨过一个 25% 档位才播一次（25/50/75），避免逐 % 刷屏。
-  // 0% 与 100% 不在此播报（开始无意义、完成走 success 文案）。
   function announceProgress(item: UploadFileItem, percent: number) {
     const bucket = Math.floor(percent / 25);
     if (bucket <= 0 || bucket >= 4) return;
@@ -272,10 +404,14 @@
     announcer.announce(loc().t('Upload.announceUploading', { name: item.name, percent }));
   }
 
-  // XHR 上传单个文件项：uploading → onprogress 更新 percent → success/error。
-  // 返回 Promise，在 load/error/abort 任一终态 resolve，供并发队列释放槽位。
+  // XHR 上传单个文件项。
   function uploadItem(item: UploadFileItem, file: File): Promise<void> {
     return new Promise<void>((resolve) => {
+      if (customRequest) {
+        void customRequest({ ...item, file });
+        resolve();
+        return;
+      }
       if (!action) {
         resolve();
         return;
@@ -296,66 +432,77 @@
           const percent = computeUploadPercent(e.loaded, e.total);
           patchItem(item.uid, { percent });
           announceProgress(item, percent);
+          onProgress?.(percent, { ...item, percent }, current);
         }
       };
       xhr.onload = () => {
         xhrMap.delete(item.uid);
         announcedBucket.delete(item.uid);
         if (isUploadOk(xhr.status)) {
-          patchItem(item.uid, { status: 'success', percent: 100 });
-          // 完成必播（polite，不抢断）。
+          let response: unknown = xhr.responseText;
+          try {
+            response = JSON.parse(xhr.responseText);
+          } catch {
+            response = xhr.responseText;
+          }
+          patchItem(item.uid, { status: 'success', percent: 100, response });
+          applyAfterUpload(item.uid, xhr.responseText);
           announcer.announce(loc().t('Upload.announceSuccess', { name: item.name }));
-          onSuccess?.(xhr.responseText, item);
+          onSuccess?.(response, item, current);
         } else {
-          patchItem(item.uid, { status: 'error' });
-          // 失败必播（assertive，立即打断）。
+          patchItem(item.uid, { status: 'uploadFail' });
           announcer.announce(loc().t('Upload.announceError', { name: item.name }), 'assertive');
-          onError?.(item);
+          onError?.(new Error('Upload failed'), item, current, xhr);
         }
         done();
       };
-      xhr.onerror = () => {
+      xhr.onerror = (e) => {
         xhrMap.delete(item.uid);
         announcedBucket.delete(item.uid);
-        patchItem(item.uid, { status: 'error' });
+        patchItem(item.uid, { status: 'uploadFail', event: e as Event });
         announcer.announce(loc().t('Upload.announceError', { name: item.name }), 'assertive');
-        onError?.(item);
+        onError?.(new Error('Upload failed'), item, current, xhr);
         done();
       };
-      // abort（remove/卸载）也要释放槽位，否则队列卡死。
       xhr.onabort = () => {
         xhrMap.delete(item.uid);
         announcedBucket.delete(item.uid);
         done();
       };
+      xhr.ontimeout = () => {
+        xhrMap.delete(item.uid);
+        announcedBucket.delete(item.uid);
+        patchItem(item.uid, { status: 'uploadFail', error: loc().t('Upload.timeoutError') });
+        announcer.announce(loc().t('Upload.timeoutError', { name: item.name }), 'assertive');
+        onError?.(new Error(loc().t('Upload.timeoutError') ?? 'Upload timed out'), item, current, xhr);
+        done();
+      };
 
       const form = new FormData();
-      form.append(uploadName, file, item.name);
-      if (uploadData) {
-        for (const [k, v] of Object.entries(uploadData)) form.append(k, v);
+      form.append(fieldName, file, item.name);
+      const resolvedData = typeof data === 'function' ? data(file) : data;
+      if (resolvedData) {
+        for (const [k, v] of Object.entries(resolvedData)) form.append(k, v);
       }
       xhr.open('POST', action);
+      if (timeout > 0) xhr.timeout = timeout;
       if (withCredentials) xhr.withCredentials = true;
-      if (headers) {
-        for (const [k, v] of Object.entries(headers)) xhr.setRequestHeader(k, v);
+      const resolvedHeaders = typeof headers === 'function' ? headers(file) : headers;
+      if (resolvedHeaders) {
+        for (const [k, v] of Object.entries(resolvedHeaders)) xhr.setRequestHeader(k, v);
       }
       xhr.send(form);
     });
   }
 
-  /** Format a byte count: <1KiB → B, <1MiB → KB, else MB (1 decimal). */
-  function formatSize(bytes: number): string {
-    if (bytes < 1024) return `${bytes} B`;
-    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-  }
-
-  function commit(next: UploadFileItem[]) {
+  function commit(next: UploadFileItem[], currentFile?: UploadFileItem) {
     if (!isControlled) inner = next;
-    onChange?.(next);
+    onChange?.({
+      fileList: next,
+      currentFile: currentFile ?? next[next.length - 1] ?? ({} as UploadFileItem),
+    });
   }
 
-  /** accept 过滤：返回通过和拒绝两组文件。 */
   function filterByAccept(files: File[]): { accepted: File[]; rejected: File[] } {
     if (!accept) return { accepted: files, rejected: [] };
     const acceptList = accept.split(',').map((s) => s.trim().toLowerCase());
@@ -376,115 +523,207 @@
   }
 
   function buildItem(file: File): UploadFileItem {
-    // 纯函数校验大小（KB），min/max 同源；超限 → error + 本地化提示。
     const sizeError = validateFileSize(file.size, { minSize, maxSize });
-    // 目录上传时浏览器在 webkitRelativePath 上保留相对路径（如 dir/sub/a.txt）。
     const relativePath = (file as File & { webkitRelativePath?: string }).webkitRelativePath;
     const item: UploadFileItem = {
       uid: useId('cd-upload'),
       name: file.name,
       size: file.size,
-      status: sizeError ? 'error' : 'ready',
+      status: sizeError ? 'validateFail' : 'wait',
       file,
     };
     if (relativePath) item.relativePath = relativePath;
     if (sizeError) {
       const limitKB = sizeError === 'max' ? maxSize! : minSize!;
-      item.error = validateMessage ?? loc().t(sizeError === 'max' ? 'Upload.sizeError' : 'Upload.minSizeError', {
-        size: formatSize(limitKB * 1024),
-      });
+      item.error =
+        validateMessage ??
+        loc().t(sizeError === 'max' ? 'Upload.sizeError' : 'Upload.minSizeError', {
+          size: formatKB(limitKB),
+        });
     }
     return item;
   }
 
-  function addFiles(fileList: FileList | File[]) {
+  function formatKB(kb: number): string {
+    if (kb >= 1024) return `${(kb / 1024).toFixed(1)}MB`;
+    return `${kb}KB`;
+  }
+
+  export function addFiles(fileListInput: FileList | File[]) {
     if (disabled) return;
-    const allFiles = Array.from(fileList);
+    const allFiles = Array.from(fileListInput);
     if (allFiles.length === 0) return;
+    if (crop) {
+      void runCropPipeline(allFiles);
+      return;
+    }
+    addFilesInternal(allFiles);
+  }
 
-    // accept 校验
-    const { accepted: afterAccept, rejected } = filterByAccept(allFiles);
+  function filterSelected(files: File[], insertLen = 0): { accepted: File[]; replaceOne: boolean } {
+    const { accepted: afterAccept, rejected } = filterByAccept(files);
     if (rejected.length > 0) onAcceptInvalid?.(rejected);
-    if (afterAccept.length === 0) return;
+    if (afterAccept.length === 0) return { accepted: [], replaceOne: false };
+
+    if (limit === 1) {
+      return { accepted: [afterAccept[afterAccept.length - 1]!], replaceOne: true };
+    }
 
     let accepted = afterAccept;
     if (limit !== undefined) {
-      const room = limit - current.length;
+      const room = limit - current.length - insertLen;
       if (room <= 0) {
         onExceed?.(accepted);
-        return;
+        return { accepted: [], replaceOne: false };
       }
       if (accepted.length > room) {
         onExceed?.(accepted.slice(room));
         accepted = accepted.slice(0, room);
       }
     }
+    return { accepted, replaceOne: false };
+  }
 
-    const newItems = accepted.map(buildItem);
-    commit([...current, ...newItems]);
-
-    // onSizeError 回调：大小校验失败项通知外部
+  function dispatchNewItems(newItems: UploadFileItem[], accepted: File[]) {
     for (const item of newItems) {
-      if (item.status === 'error' && item.file) {
+      if (item.status === 'validateFail' && item.file) {
         const result = validateFileSize(item.file.size, { minSize, maxSize });
-        if (result) onSizeError?.(item, result);
+        if (result) onSizeError?.(item, current);
       }
     }
-
-    // beforeUpload 通过的项才进队列受 concurrency 调度。
-    // customRequest 完全接管；否则有 action 时自动 XHR 上传。仅处理无尺寸错误的项。
     for (const item of newItems) {
-      if (item.status === 'error' || !item.file) continue;
-      dispatch(item, item.file, accepted);
+      if (item.status === 'validateFail' || !item.file) continue;
+      void dispatch(item, item.file, accepted);
     }
   }
 
-  // 单个文件的上传派发：先跑（可能异步的）beforeUpload，通过后入队受并发调度。
-  async function dispatch(item: UploadFileItem, original: File, fileList: File[]) {
+  function addFilesInternal(fileListInput: FileList | File[]) {
+    if (disabled) return;
+    const allFiles = Array.from(fileListInput);
+    if (allFiles.length === 0) return;
+
+    const { accepted, replaceOne } = filterSelected(allFiles);
+    if (accepted.length === 0) return;
+
+    onFileChange?.(accepted);
+
+    const newItems = accepted.map(buildItem);
+    if (replaceOne) {
+      for (const it of current) removeInternalResources(it.uid);
+      commit(newItems, newItems[0]);
+    } else {
+      commit([...current, ...newItems], newItems[0]);
+    }
+
+    dispatchNewItems(newItems, accepted);
+  }
+
+  // 命令式插入（对齐 Semi insert）。
+  export function insert(files: File[], index?: number) {
+    if (disabled) return;
+    const allFiles = Array.from(files);
+    if (allFiles.length === 0) return;
+
+    const { accepted, replaceOne } = filterSelected(allFiles);
+    if (accepted.length === 0) return;
+
+    onFileChange?.(accepted);
+
+    const newItems = accepted.map(buildItem);
+    if (replaceOne) {
+      for (const it of current) removeInternalResources(it.uid);
+      commit(newItems, newItems[0]);
+    } else {
+      const at = index === undefined ? current.length : Math.max(0, Math.min(index, current.length));
+      const next = [...current];
+      next.splice(at, 0, ...newItems);
+      commit(next, newItems[0]);
+    }
+
+    dispatchNewItems(newItems, accepted);
+  }
+
+  const pendingFiles = new Map<string, File>();
+
+  // beforeUpload 支持返回富对象（对齐 Semi BeforeUploadObjectResult）。
+  async function dispatch(item: UploadFileItem, original: File, _fileListForHook: File[]) {
     let file = original;
     if (beforeUpload) {
-      let result: BeforeUploadResult;
+      let result: boolean | BeforeUploadObjectResult;
+      // 中间态 validating（对齐 Semi）。
+      patchItem(item.uid, { status: 'validating' });
       try {
-        result = await beforeUpload(original, fileList);
-      } catch {
-        // reject 视为拒绝该文件。
-        result = false;
+        result = await beforeUpload({ file: item, fileList: current });
+      } catch (err) {
+        // reject 支持传富对象（对齐 Semi）。
+        if (err && typeof err === 'object') {
+          result = err as BeforeUploadObjectResult;
+          if (result.shouldUpload === undefined) result.shouldUpload = false;
+        } else {
+          result = false;
+        }
       }
       if (!mounted) return;
-      // 上传开始前可能已被手动移除。
       if (!current.some((it) => it.uid === item.uid)) return;
-      const decision = resolveBeforeUpload(original, result);
-      if (!decision.upload) {
-        // 跳过该文件：从列表移除（受控仅 onChange，不回写）。
-        remove(item.uid);
+
+      if (result === false) {
+        // 拒绝：标 validateFail（不移除，对齐 Semi 默认 shouldUpload=false 且无 autoRemove）。
+        patchItem(item.uid, { status: 'validateFail' });
         return;
       }
-      file = decision.file ?? original;
-      if (file !== original) patchItem(item.uid, { name: file.name, size: file.size, file });
+      if (result !== true && typeof result === 'object') {
+        const obj = result;
+        if (obj.autoRemove) {
+          removeInternal(item.uid);
+          return;
+        }
+        const patch: Partial<UploadFileItem> = {};
+        if (obj.status) patch.status = obj.status;
+        if (obj.validateMessage !== undefined) patch.validateMessage = obj.validateMessage;
+        if (obj.fileInstance) {
+          file = obj.fileInstance;
+          patch.name = file.name;
+          patch.size = file.size;
+          patch.file = file;
+        }
+        const shouldUpload = obj.shouldUpload !== false;
+        if (!shouldUpload) {
+          if (!patch.status) patch.status = 'validateFail';
+          patchItem(item.uid, patch);
+          return;
+        }
+        if (Object.keys(patch).length > 0) patchItem(item.uid, patch);
+      }
     }
     if (!mounted) return;
 
-    // transformFile：上传前文件转换
     if (transformFile) {
       file = await transformFile(file);
       if (!mounted) return;
       patchItem(item.uid, { name: file.name, size: file.size, file });
     }
 
-    // 入队受 concurrency 调度：customRequest 返回 Promise 时队列会 await 其完成
-    // 来释放槽位（同步返回则立即释放，由其自管生命周期）；否则由队列 await XHR。
-    queue.add(() => {
-      if (!mounted) return;
-      if (!current.some((it) => it.uid === item.uid)) return;
-      if (customRequest) {
-        return customRequest({ ...item, file });
-      }
-      if (action) return uploadItem(item, file);
-    });
+    if (uploadTrigger === 'custom') {
+      patchItem(item.uid, { status: 'wait' });
+      pendingFiles.set(item.uid, file);
+      return;
+    }
+
+    void uploadItem(item, file);
   }
 
-  function remove(uid: string) {
+  export function upload() {
     if (disabled) return;
+    for (const it of current) {
+      if (it.status !== 'wait') continue;
+      const file = pendingFiles.get(it.uid) ?? it.file;
+      if (!file) continue;
+      pendingFiles.delete(it.uid);
+      void uploadItem(it, file);
+    }
+  }
+
+  function removeInternalResources(uid: string) {
     const xhr = xhrMap.get(uid);
     if (xhr) {
       xhr.abort();
@@ -492,26 +731,60 @@
     }
     revokeUrl(uid);
     announcedBucket.delete(uid);
+    pendingFiles.delete(uid);
+  }
+
+  function removeInternal(uid: string) {
+    removeInternalResources(uid);
     commit(current.filter((item) => item.uid !== uid));
   }
 
-  /** 重试失败项：重置状态后重新派发上传。 */
+  async function remove(uid: string) {
+    if (disabled) return;
+    const item = current.find((it) => it.uid === uid);
+    if (!item) return;
+    if (beforeRemove) {
+      let allow: boolean;
+      try {
+        allow = await beforeRemove(item, current);
+      } catch {
+        allow = false;
+      }
+      if (allow === false) return;
+      if (!mounted) return;
+      if (!current.some((it) => it.uid === uid)) return;
+    }
+    const nextList = current.filter((it) => it.uid !== uid);
+    removeInternalResources(uid);
+    commit(nextList, item);
+    onRemove?.(item.file, nextList, item);
+  }
+
   function retryItem(item: UploadFileItem) {
     onRetry?.(item);
     if (!item.file) return;
-    // Drop `percent` and `error` keys entirely (exactOptionalPropertyTypes: true requires
-    // omission rather than explicit undefined assignment).
-    commit(current.map((it) => {
-      if (it.uid !== item.uid) return it;
-      const { percent: _p, error: _e, ...rest } = it;
-      return { ...rest, status: 'ready' };
-    }));
-    dispatch(item, item.file, [item.file]);
-  }
-
-  /** 清除所有文件：中止进行中的上传，释放 objectURL，清空列表。 */
-  function clearAll() {
+    commit(
+      current.map((it) => {
+        if (it.uid !== item.uid) return it;
+        const { percent: _p, error: _e, ...rest } = it;
+        return { ...rest, status: 'wait' };
+      }),
+    );
+    void dispatch(item, item.file, [item.file]);
+  }
+
+  async function clearAll() {
     if (disabled) return;
+    if (beforeClear) {
+      let allow: boolean;
+      try {
+        allow = await beforeClear(current);
+      } catch {
+        allow = false;
+      }
+      if (allow === false) return;
+      if (!mounted) return;
+    }
     for (const xhr of xhrMap.values()) xhr.abort();
     xhrMap.clear();
     for (const u of objectUrls.values()) URL.revokeObjectURL(u);
@@ -527,22 +800,99 @@
     inputEl?.click();
   }
 
+  export function openFileDialog() {
+    openPicker();
+  }
+
   function handleInputChange(e: Event & { currentTarget: HTMLInputElement }) {
     const fl = e.currentTarget.files;
     if (fl) addFiles(fl);
-    // Reset so selecting the same file again re-fires change.
     e.currentTarget.value = '';
   }
 
+  // ——— showReplace：替换已上传文件 ———
+  let replaceInputEl = $state<HTMLInputElement | null>(null);
+  let replaceTargetUid: string | null = null;
+
+  function openReplace(uid: string) {
+    if (disabled) return;
+    replaceTargetUid = uid;
+    replaceInputEl?.click();
+  }
+
+  function handleReplaceChange(e: Event & { currentTarget: HTMLInputElement }) {
+    const fl = e.currentTarget.files;
+    const target = replaceTargetUid;
+    replaceTargetUid = null;
+    e.currentTarget.value = '';
+    if (!fl || fl.length === 0 || !target) return;
+    const file = fl[0]!;
+    if (disabled) return;
+    if (crop && file.type.startsWith('image/')) {
+      void runReplacePipeline(target, file);
+      return;
+    }
+    doReplace(target, file);
+  }
+
+  function doReplace(target: string, file: File) {
+    const { accepted, rejected } = filterByAccept([file]);
+    if (rejected.length > 0) onAcceptInvalid?.(rejected);
+    if (accepted.length === 0) return;
+    const chosen = accepted[0]!;
+    removeInternalResources(target);
+    const built = buildItem(chosen);
+    const replaced: UploadFileItem = { ...built, uid: target };
+    commit(current.map((it) => (it.uid === target ? replaced : it)), replaced);
+    onFileChange?.([chosen]);
+    dispatchNewItems([replaced], [chosen]);
+  }
+
+  async function runReplacePipeline(target: string, file: File) {
+    let out: File | null = file;
+    let skip = false;
+    if (beforeCrop) {
+      try {
+        skip = (await beforeCrop(file, [file])) === false;
+      } catch {
+        skip = false;
+      }
+      if (!mounted) return;
+    }
+    if (!skip) {
+      try {
+        out = await cropOne(file);
+      } catch (err) {
+        onCropError?.(err);
+        out = file;
+      }
+    }
+    if (!mounted || !out) return;
+    doReplace(target, out);
+  }
+
+  function handleDragEnter(e: DragEvent) {
+    e.preventDefault();
+    e.stopPropagation();
+    dragEnterTarget = e.currentTarget;
+    if (!disabled) dragOver = true;
+  }
+
+  function handleDragLeave(e: DragEvent) {
+    e.preventDefault();
+    e.stopPropagation();
+    if (dragEnterTarget === e.target) dragOver = false;
+  }
+
   function handleDrop(e: DragEvent) {
     e.preventDefault();
+    dragOver = false;
     if (disabled) return;
     const dt = e.dataTransfer;
     if (dt?.files && dt.files.length > 0) {
       const files = Array.from(dt.files);
-      // accept 过滤
-      const { accepted, rejected } = filterByAccept(files);
-      onDrop?.(e, files, rejected);
+      onDrop?.(e, files, current);
+      const { accepted } = filterByAccept(files);
       if (accepted.length > 0) addFiles(accepted);
     }
   }
@@ -554,544 +904,656 @@
     }
   }
 
-  // 是否水平布局 prompt（left 或 right）
-  const promptRow = $derived(promptPosition === 'left' || promptPosition === 'right');
+  const clearText = $derived(loc().t('Upload.clear'));
+  const titleSnippet = $derived(
+    typeof fileListTitle === 'function'
+      ? (fileListTitle as Snippet<[{ fileList: UploadFileItem[]; onClear: () => void; clearText: string }]>)
+      : undefined,
+  );
+  const titleText = $derived(typeof fileListTitle === 'string' ? fileListTitle : undefined);
+
+  // itemStyle → 字符串。
+  const itemStyleStr = $derived.by<string | undefined>(() => {
+    if (itemStyle === undefined) return undefined;
+    if (typeof itemStyle === 'string') return itemStyle;
+    const parts = Object.entries(itemStyle).map(
+      ([k, v]) => `${k}: ${typeof v === 'number' ? `${v}px` : v}`,
+    );
+    return parts.length > 0 ? parts.join('; ') : undefined;
+  });
+
+  // 卡片 style：picWidth/picHeight（number→px）+ itemStyle。
+  const cardStyleStr = $derived.by<string | undefined>(() => {
+    const parts: string[] = [];
+    if (picHeight !== undefined) parts.push(`height: ${typeof picHeight === 'number' ? `${picHeight}px` : picHeight}`);
+    if (picWidth !== undefined) parts.push(`width: ${typeof picWidth === 'number' ? `${picWidth}px` : picWidth}`);
+    if (itemStyleStr) parts.push(itemStyleStr);
+    return parts.length > 0 ? parts.join('; ') : undefined;
+  });
+
+  const addTileStyle = $derived.by<string | undefined>(() => {
+    const parts: string[] = [];
+    if (picHeight !== undefined) parts.push(`height: ${typeof picHeight === 'number' ? `${picHeight}px` : picHeight}`);
+    if (picWidth !== undefined) parts.push(`width: ${typeof picWidth === 'number' ? `${picWidth}px` : picWidth}`);
+    return parts.length > 0 ? parts.join('; ') : undefined;
+  });
+
+  // 图片墙添加瓦片是否显示（对齐 Semi showAddTriggerInList）。
+  const showAddTrigger = $derived(limit ? limit > current.length : true);
+  const showListTitle = $derived(limit !== 1 && current.length > 0);
+
+  // ——— 裁剪流程 ———
+  const cropConfig = $derived<UploadCropProps>(
+    crop === true ? {} : crop && typeof crop === 'object' ? crop : {},
+  );
+
+  let cropOpen = $state(false);
+  let cropSrc = $state<string | undefined>(undefined);
+  let cropperRef = $state<{ getCropperCanvas: () => HTMLCanvasElement } | null>(null);
+  let cropConfirming = $state(false);
+  let cropCurrentFile: File | null = null;
+  let cropResolve: ((file: File | null) => void) | null = null;
+
+  const isImageFile = (f: File) => f.type.startsWith('image/');
+
+  const cropModalTextProps = $derived({
+    ...(cropConfig.modalOkText !== undefined ? { okText: cropConfig.modalOkText } : {}),
+    ...(cropConfig.modalCancelText !== undefined ? { cancelText: cropConfig.modalCancelText } : {}),
+  });
+  const cropperNumProps = $derived({
+    ...(cropConfig.aspectRatio !== undefined ? { aspectRatio: cropConfig.aspectRatio } : {}),
+    ...(cropConfig.minZoom !== undefined ? { minZoom: cropConfig.minZoom } : {}),
+    ...(cropConfig.maxZoom !== undefined ? { maxZoom: cropConfig.maxZoom } : {}),
+    ...(cropConfig.zoomStep !== undefined ? { zoomStep: cropConfig.zoomStep } : {}),
+  });
+
+  async function runCropPipeline(files: File[]) {
+    const out: File[] = [];
+    for (const file of files) {
+      if (!mounted) return;
+      if (!isImageFile(file)) {
+        out.push(file);
+        continue;
+      }
+      if (beforeCrop) {
+        let skip = false;
+        try {
+          skip = (await beforeCrop(file, files)) === false;
+        } catch {
+          skip = false;
+        }
+        if (!mounted) return;
+        if (skip) {
+          out.push(file);
+          continue;
+        }
+      }
+      try {
+        const cropped = await cropOne(file);
+        if (!mounted) return;
+        if (cropped) out.push(cropped);
+      } catch (err) {
+        onCropError?.(err);
+        out.push(file);
+      }
+    }
+    if (!mounted) return;
+    if (out.length > 0) addFilesInternal(out);
+  }
+
+  function cropOne(file: File): Promise<File | null> {
+    return new Promise<File | null>((resolve) => {
+      cropCurrentFile = file;
+      cropResolve = resolve;
+      cropSrc = URL.createObjectURL(file);
+      cropOpen = true;
+    });
+  }
+
+  function confirmCrop() {
+    const canvas = cropperRef?.getCropperCanvas();
+    const original = cropCurrentFile;
+    if (!canvas || !original) {
+      settleCrop(null);
+      return;
+    }
+    cropConfirming = true;
+    const type = original.type || 'image/png';
+    const quality = cropConfig.quality ?? 0.92;
+    try {
+      canvas.toBlob(
+        (blob) => {
+          cropConfirming = false;
+          if (!blob) {
+            onCropError?.(new Error('Cropper toBlob returned null'));
+            settleCrop(original);
+            return;
+          }
+          const cropped = new File([blob], original.name, { type, lastModified: Date.now() });
+          settleCrop(cropped);
+        },
+        type,
+        quality,
+      );
+    } catch (err) {
+      cropConfirming = false;
+      onCropError?.(err);
+      settleCrop(original);
+    }
+  }
+
+  function cancelCrop() {
+    settleCrop(null);
+  }
+
+  function settleCrop(result: File | null) {
+    cropOpen = false;
+    if (cropSrc) {
+      URL.revokeObjectURL(cropSrc);
+      cropSrc = undefined;
+    }
+    const resolve = cropResolve;
+    cropResolve = null;
+    cropCurrentFile = null;
+    resolve?.(result);
+  }
+
+  // 组装单项传给 FileCard 的公共 props。url/style 仅在有值时带上（exactOptionalPropertyTypes）。
+  function cardProps(item: UploadFileItem, index: number, url: string | undefined, style: string | undefined) {
+    return {
+      item,
+      index,
+      listType,
+      disabled,
+      showRetry,
+      showReplace,
+      showPicInfo,
+      preview: itemPreviewEnabled(item),
+      showTooltip,
+      ...(url !== undefined ? { url } : {}),
+      ...(style !== undefined ? { style } : {}),
+      ...(picWidth !== undefined ? { picWidth } : {}),
+      ...(picHeight !== undefined ? { picHeight } : {}),
+      onRemove: () => remove(item.uid),
+      onRetry: () => retryItem(item),
+      onReplace: () => openReplace(item.uid),
+      ...(onPreviewClick ? { onPreviewClick: () => onPreviewClick(item) } : {}),
+    };
+  }
+
+  function renderProps(item: UploadFileItem, index: number): RenderFileItemProps {
+    return {
+      ...item,
+      index,
+      listType,
+      disabled,
+      showRetry,
+      showReplace,
+      showPicInfo,
+      onRemove: () => remove(item.uid),
+      onRetry: () => retryItem(item),
+      onReplace: () => openReplace(item.uid),
+      ...(onPreviewClick ? { onPreviewClick: () => onPreviewClick(item) } : {}),
+    };
+  }
 </script>
 
 <div
-  class="cd-upload cd-upload--{size} cd-upload--{status}"
-  class:cd-upload--disabled={disabled}
-  data-status={status !== 'default' ? status : undefined}
+  class={['cd-upload', isPicture && 'cd-upload-picture', disabled && 'cd-upload-disabled', validateStatus === 'default' && 'cd-upload-default', validateStatus === 'error' && 'cd-upload-error', validateStatus === 'warning' && 'cd-upload-warning', validateStatus === 'success' && 'cd-upload-success', className]
+    .filter(Boolean)
+    .join(' ')}
+  style={styleProp}
+  {...{ 'x-prompt-pos': promptPosition }}
 >
   <input
     bind:this={inputEl}
-    class="cd-upload__input"
+    class="cd-upload-hidden-input"
     type="file"
     {accept}
     {multiple}
     {disabled}
     tabindex="-1"
+    autocomplete="off"
     aria-hidden="true"
     onchange={handleInputChange}
   />
+  <input
+    bind:this={replaceInputEl}
+    class="cd-upload-hidden-input-replace"
+    type="file"
+    {accept}
+    {disabled}
+    tabindex="-1"
+    autocomplete="off"
+    aria-hidden="true"
+    onchange={handleReplaceChange}
+  />
 
-  {#snippet triggerArea()}
+  <!-- ============ 添加区（对齐 Semi renderAddContent / renderDragArea） ============ -->
+  {#snippet dragArea()}
     <div
-      class="cd-upload__trigger-wrap"
-      class:cd-upload__trigger-wrap--row={promptRow}
-      class:cd-upload__trigger-wrap--row-reverse={promptPosition === 'left'}
+      class={['cd-upload-drag-area', dragOver && 'cd-upload-drag-area-legal', children && 'cd-upload-drag-area-custom']
+        .filter(Boolean)
+        .join(' ')}
+      role="button"
+      tabindex={disabled ? -1 : 0}
+      aria-disabled={disabled || undefined}
+      ondragover={(e) => e.preventDefault()}
+      ondragenter={handleDragEnter}
+      ondragleave={handleDragLeave}
+      ondrop={handleDrop}
+      onclick={openPicker}
+      onkeydown={handleDragKeydown}
     >
-      {#if drag}
-        <div
-          class="cd-upload__dragger"
-          role="button"
-          tabindex={disabled ? -1 : 0}
-          aria-disabled={disabled || undefined}
-          ondragover={(e) => e.preventDefault()}
-          ondrop={handleDrop}
-          onclick={openPicker}
-          onkeydown={handleDragKeydown}
-        >
-          {#if children}
-            {@render children()}
-          {:else}
-            {#if dragIcon}{@render dragIcon()}{/if}
+      {#if children}
+        {@render children()}
+      {:else}
+        <div class="cd-upload-drag-area-icon">
+          {#if dragIcon}{@render dragIcon()}{:else}<IconUpload size="extra-large" />{/if}
+        </div>
+        <div class="cd-upload-drag-area-text">
+          <div class="cd-upload-drag-area-main-text">
             {#if dragMainText}
-              <span class="cd-upload__dragger-main">
-                {#if typeof dragMainText === 'string'}{dragMainText}{:else}{@render dragMainText()}{/if}
-              </span>
-            {:else}
-              <span class="cd-upload__dragger-text">{loc().t('Upload.draggerText')}</span>
-            {/if}
-            {#if dragSubText}
-              <span class="cd-upload__dragger-sub">
-                {#if typeof dragSubText === 'string'}{dragSubText}{:else}{@render dragSubText()}{/if}
-              </span>
-            {/if}
+              {#if typeof dragMainText === 'string'}{dragMainText}{:else}{@render dragMainText()}{/if}
+            {:else}{loc().t('Upload.draggerText')}{/if}
+          </div>
+          {#if dragSubText}
+            <div class="cd-upload-drag-area-sub-text">
+              {#if typeof dragSubText === 'string'}{dragSubText}{:else}{@render dragSubText()}{/if}
+            </div>
           {/if}
+          <div class="cd-upload-drag-area-tips">
+            {#if dragOver}
+              <span class="cd-upload-drag-area-tips-legal">{loc().t('Upload.legalTips')}</span>
+            {/if}
+          </div>
         </div>
-      {:else}
-        <button type="button" class="cd-upload__trigger" {disabled} onclick={openPicker}>
-          {#if children}
-            {@render children()}
-          {:else}
-            {loc().t('Upload.trigger')}
-          {/if}
-        </button>
       {/if}
+    </div>
+  {/snippet}
 
-      {#if prompt}
-        <div class="cd-upload__prompt">
-          {#if typeof prompt === 'string'}{prompt}{:else}{@render prompt()}{/if}
-        </div>
-      {/if}
+  {#snippet addContent()}
+    {#if draggable}
+      {@render dragArea()}
+    {:else}
+      <div
+        role="button"
+        tabindex="0"
+        aria-disabled={disabled || undefined}
+        class="cd-upload-add"
+        onclick={openPicker}
+        onkeydown={handleDragKeydown}
+      >
+        {#if children}
+          {@render children()}
+        {:else}
+          {loc().t('Upload.trigger')}
+        {/if}
+      </div>
+    {/if}
+  {/snippet}
+
+  <!-- picture 添加瓦片（对齐 Semi picture renderFileListPic 的 addContent）。 -->
+  {#snippet pictureAddContent()}
+    <div
+      role="button"
+      tabindex="0"
+      class={['cd-upload-add', 'cd-upload-picture-add', disabled && 'cd-upload-picture-add-disabled', draggable && dragOver && 'cd-upload-drag-area-legal']
+        .filter(Boolean)
+        .join(' ')}
+      style={addTileStyle}
+      onclick={openPicker}
+      onkeydown={handleDragKeydown}
+      ondragover={draggable ? (e) => e.preventDefault() : undefined}
+      ondragenter={draggable ? handleDragEnter : undefined}
+      ondragleave={draggable ? handleDragLeave : undefined}
+      ondrop={draggable ? handleDrop : undefined}
+    >
+      {@render children?.()}
     </div>
   {/snippet}
 
-  {#if hotSpotLocation !== 'none' && hotSpotLocation !== 'end'}
-    {@render triggerArea()}
+  <!-- 非 picture：添加区在文件列表前渲染（对齐 Semi render() 顺序）。 -->
+  {#if !isPicture}
+    {@render addContent()}
   {/if}
 
-  {#if showClear && current.length > 0}
-    <button
-      type="button"
-      class="cd-upload__clear-btn"
-      {disabled}
-      onclick={clearAll}
-    >清除全部</button>
+  {#if prompt}
+    <div class="cd-upload-prompt">
+      {#if typeof prompt === 'string'}{prompt}{:else}{@render prompt()}{/if}
+    </div>
   {/if}
 
-  {#if listType === 'text' && current.length > 0}
-    {#if fileListTitle !== false && fileListTitle}
-      <div class="cd-upload__list-title">{fileListTitle}</div>
-    {/if}
-    <ul class="cd-upload__list">
-      {#each current as item (item.uid)}
-        <li class="cd-upload__item" class:cd-upload__item--error={item.status === 'error'}>
-          <div class="cd-upload__item-main">
-            <span
-              class="cd-upload__item-name"
-              title={showTooltip !== false ? item.name : undefined}
-            >{item.name}</span>
-            <span class="cd-upload__item-size">{formatSize(item.size)}</span>
-            {#if item.status !== 'uploading'}
-              <span class="cd-upload__item-status">{item.error ?? item.status}</span>
-            {/if}
-            {#if item.status === 'error' && showRetry !== false}
-              <button
-                type="button"
-                class="cd-upload__retry-btn"
-                {disabled}
-                onclick={() => retryItem(item)}
-              >重试</button>
+  {#if validateMessage && current.length === 0}
+    <div class="cd-upload-validate-message">{validateMessage}</div>
+  {/if}
+
+  <!-- ============ 文件列表（对齐 Semi renderFileList） ============ -->
+  {#if listType === 'list' && showUploadList && current.length > 0}
+    <div class="cd-upload-file-list">
+      {#if showListTitle}
+        <div class="cd-upload-file-list-title">
+          {#if titleSnippet}
+            {@render titleSnippet({ fileList: current, onClear: clearAll, clearText })}
+          {:else}
+            <span class="cd-upload-file-list-title-choosen">{titleText ?? loc().t('Upload.selectedFiles')}</span>
+            {#if showClear && !disabled}
+              <span role="button" tabindex="0" class="cd-upload-file-list-title-clear" onclick={clearAll} onkeydown={null}>{clearText}</span>
             {/if}
-            <button
-              type="button"
-              class="cd-upload__item-remove"
-              aria-label={loc().t('Upload.remove')}
-              {disabled}
-              onclick={() => remove(item.uid)}
-            >
-              &times;
-            </button>
-          </div>
-          {#if item.status === 'uploading'}
-            <Progress
-              percent={item.percent ?? 0}
-              size="small"
-              ariaLabel={loc().t('Upload.uploadingProgress', { name: item.name })}
+          {/if}
+        </div>
+      {/if}
+      <div class="cd-upload-file-list-main" role="list" aria-label="file list">
+        {#each current as item, index (item.uid)}
+          {#if renderFileItem}
+            {@render renderFileItem(renderProps(item, index))}
+          {:else}
+            <FileCard
+              {...cardProps(item, index, itemThumbUrl(item), itemStyleStr)}
+              {...(previewFile ? { previewFile } : {})}
+              {...(renderFileOperation ? { renderFileOperation } : {})}
             />
           {/if}
-        </li>
-      {/each}
-    </ul>
+        {/each}
+      </div>
+    </div>
   {/if}
 
-  {#if isImageList && current.length > 0}
-    <ul
-      class="cd-upload__grid"
-      class:cd-upload__grid--card={listType === 'picture-card'}
-    >
-      {#each current as item (item.uid)}
-        {@const url = previewUrl(item)}
-        <li
-          class="cd-upload__card"
-          class:cd-upload__card--error={item.status === 'error'}
-          class:cd-upload__card--uploading={item.status === 'uploading'}
-        >
-          {#if url}
-            {#if onPreviewClick}
-              <button
-                type="button"
-                class="cd-upload__thumb-btn"
-                aria-label={item.name}
-                onclick={() => onPreviewClick(item)}
-              >
-                <img class="cd-upload__thumb" src={url} alt="" aria-hidden="true" />
-              </button>
-            {:else}
-              <img class="cd-upload__thumb" src={url} alt={item.name} />
-            {/if}
-          {:else}
-            <span class="cd-upload__thumb cd-upload__thumb--placeholder" aria-hidden="true"></span>
+  {#if isPicture && ((showUploadList && current.length > 0) || (!current.length && showAddTrigger))}
+    {#if !showUploadList || !current.length}
+      <!-- 空列表：仅渲染添加瓦片（对齐 Semi renderFileListPic 空态返回 addContent）。 -->
+      {#if showAddTrigger}
+        {@render pictureAddContent()}
+      {/if}
+    {:else}
+      <div class="cd-upload-file-list cd-upload-picture-file-list">
+        <div class="cd-upload-file-list-main" role="list" aria-label="picture list">
+          {#if showAddTrigger && hotSpotLocation === 'start'}
+            {@render pictureAddContent()}
           {/if}
-          {#if item.status === 'uploading'}
-            <div class="cd-upload__card-progress">
-              <Progress
-                percent={item.percent ?? 0}
-                size="small"
-                ariaLabel={loc().t('Upload.uploadingProgress', { name: item.name })}
+          {#each current as item, index (item.uid)}
+            {#if renderFileItem}
+              {@render renderFileItem(renderProps(item, index))}
+            {:else}
+              <FileCard
+                {...cardProps(item, index, previewUrl(item), cardStyleStr)}
+                {...(renderThumbnail ? { renderThumbnail } : {})}
+                {...(previewFile ? { previewFile } : {})}
+                {...(renderPicInfo ? { renderPicInfo } : {})}
+                {...(renderPicPreviewIcon ? { renderPicPreviewIcon } : {})}
+                {...(renderPicClose ? { renderPicClose } : {})}
               />
-            </div>
+            {/if}
+          {/each}
+          {#if showAddTrigger && hotSpotLocation !== 'start'}
+            {@render pictureAddContent()}
           {/if}
-          <div class="cd-upload__card-overlay">
-            <span class="cd-upload__card-name">{item.name}</span>
-            <button
-              type="button"
-              class="cd-upload__card-remove"
-              aria-label={loc().t('Upload.remove')}
-              {disabled}
-              onclick={() => remove(item.uid)}
-            >
-              &times;
-            </button>
-          </div>
-        </li>
-      {/each}
-    </ul>
-  {/if}
-
-  {#if hotSpotLocation === 'end'}
-    {@render triggerArea()}
+        </div>
+      </div>
+    {/if}
   {/if}
 </div>
 
+{#if crop}
+  <Modal
+    visible={cropOpen}
+    title={cropConfig.modalTitle ?? loc().t('Upload.cropTitle')}
+    confirmLoading={cropConfirming}
+    onOk={confirmCrop}
+    onCancel={cancelCrop}
+    onVisibleChange={(o) => {
+      if (!o && cropOpen) cancelCrop();
+    }}
+    {...cropModalTextProps}
+    {...cropModalProps}
+  >
+    {#if cropSrc}
+      <div class="cd-upload-crop-body">
+        <Cropper
+          bind:this={cropperRef}
+          src={cropSrc}
+          shape={cropConfig.shape ?? 'rect'}
+          fill={cropConfig.fill ?? '#fff'}
+          style="width: 100%; height: 320px;"
+          {...cropperNumProps}
+        />
+      </div>
+    {/if}
+  </Modal>
+{/if}
+
 <style>
+  /* ============ 根容器（对齐 Semi upload.scss .semi-upload） ============ */
   .cd-upload {
     display: flex;
-    flex-direction: column;
-    gap: var(--cd-spacing-base-tight);
-    color: var(--cd-color-text-0);
+    flex-wrap: wrap;
+    color: var(--cd-color-upload-text);
   }
-  .cd-upload__input {
-    position: absolute;
-    inline-size: 1px;
-    block-size: 1px;
-    padding: 0;
-    margin: 0;
-    overflow: hidden;
-    clip-path: inset(50%);
-    white-space: nowrap;
-    border: 0;
+  .cd-upload-hidden-input,
+  .cd-upload-hidden-input-replace {
+    display: none;
   }
-  .cd-upload__trigger-wrap {
+  .cd-upload-add {
     display: flex;
-    flex-direction: column;
-    gap: var(--cd-spacing-tight);
-  }
-  .cd-upload__trigger-wrap--row {
-    flex-direction: row;
     align-items: center;
   }
-  .cd-upload__trigger-wrap--row-reverse {
-    flex-direction: row-reverse;
+  /* prompt-pos（对齐 Semi x-prompt-pos） */
+  .cd-upload[x-prompt-pos='right'] .cd-upload-add,
+  .cd-upload[x-prompt-pos='right'] .cd-upload-prompt {
+    display: inline-flex;
   }
-  .cd-upload__prompt {
-    color: var(--cd-color-text-2);
-    font-size: var(--cd-font-size-small);
+  .cd-upload[x-prompt-pos='bottom'] .cd-upload-add {
+    display: flex;
+  }
+  .cd-upload[x-prompt-pos='bottom'] .cd-upload-prompt {
+    display: flex;
+    flex-basis: 100%;
+  }
+  .cd-upload[x-prompt-pos='bottom'] .cd-upload-file-list {
+    flex-basis: 100%;
   }
-  .cd-upload__trigger {
-    align-self: flex-start;
+  .cd-upload[x-prompt-pos='left'] .cd-upload-add,
+  .cd-upload[x-prompt-pos='left'] .cd-upload-prompt {
     display: inline-flex;
-    align-items: center;
-    gap: var(--cd-spacing-tight);
-    height: var(--cd-button-height-default);
-    padding-inline: var(--cd-button-padding-x);
-    background: var(--cd-color-fill-0);
-    color: var(--cd-color-text-0);
-    border: 1px solid var(--cd-color-border);
-    border-radius: var(--cd-button-radius);
-    font-size: var(--cd-button-font-size);
-    cursor: pointer;
   }
-  .cd-upload__trigger:focus-visible {
-    outline: none;
-    box-shadow: var(--cd-focus-ring);
+  .cd-upload[x-prompt-pos='left'] .cd-upload-prompt {
+    order: -1;
   }
-  /* 组件级 size：触发按钮高度/字号档（区别于 file.size 体积）。 */
-  .cd-upload--small .cd-upload__trigger {
-    height: var(--cd-button-height-small);
-    font-size: var(--cd-font-size-small);
+  .cd-upload[x-prompt-pos='left'] .cd-upload-file-list {
+    order: 2;
   }
-  .cd-upload--large .cd-upload__trigger {
-    height: var(--cd-button-height-large);
-    font-size: var(--cd-font-size-header-6);
+  .cd-upload-prompt {
+    color: var(--cd-color-upload-assist-text);
   }
-  .cd-upload__trigger:disabled {
-    cursor: not-allowed;
-    opacity: 0.5;
+
+  /* ============ 文件列表（对齐 Semi file-list 段） ============ */
+  .cd-upload-file-list {
+    flex-basis: 100%;
+    flex-shrink: 0;
+    display: block;
+    margin-block: var(--cd-spacing-tight);
   }
-  .cd-upload__dragger {
+  .cd-upload-file-list-main {
     display: flex;
+    flex-wrap: wrap;
+    flex-shrink: 0;
+    gap: var(--cd-spacing-upload-picture-file-card-gap);
+    margin-block-end: var(--cd-spacing-upload-picture-file-card-marginbottom);
+  }
+  .cd-upload-file-list-title {
+    font-size: var(--cd-font-size-small);
+    color: var(--cd-color-upload-assist-text);
+    margin-block-end: var(--cd-spacing-upload-title-marginbottom);
+  }
+  .cd-upload-file-list-title-choosen {
+    margin-inline-end: var(--cd-spacing-upload-title-choosen-marginright);
+  }
+  .cd-upload-file-list-title-clear {
+    cursor: pointer;
+    color: var(--cd-color-upload-clear-text);
+  }
+
+  /* list 卡片纵向堆叠（Semi file-list-main flex-wrap 下逐个换行）。 */
+  .cd-upload-file-list:not(.cd-upload-picture-file-list) .cd-upload-file-list-main {
     flex-direction: column;
+    gap: var(--cd-spacing-extra-tight);
+  }
+
+  /* ============ 拖拽区（对齐 Semi drag-area 段） ============ */
+  .cd-upload-drag-area {
+    border-radius: var(--cd-radius-upload-drag-area);
+    border: var(--cd-width-upload-drag-area-border) dashed var(--cd-color-upload-border);
+    width: 100%;
+    padding: var(--cd-spacing-upload-drag-area-padding);
+    background-color: var(--cd-color-upload-drag-area-bg);
+    display: flex;
     align-items: center;
     justify-content: center;
-    padding-block: var(--cd-spacing-loose);
-    padding-inline: var(--cd-spacing-base);
-    background: var(--cd-upload-dragger-bg);
-    border: 1px dashed var(--cd-upload-dragger-border);
-    border-radius: var(--cd-upload-dragger-radius);
-    color: var(--cd-color-text-2);
+    flex-direction: column;
     cursor: pointer;
-    transition:
-      border-color var(--cd-motion-duration-fast) var(--cd-motion-ease-standard),
-      background-color var(--cd-motion-duration-fast) var(--cd-motion-ease-standard);
+    box-sizing: border-box;
   }
-  .cd-upload__dragger:hover,
-  .cd-upload__dragger:focus-visible {
-    border-color: var(--cd-upload-dragger-border-active);
-    background: var(--cd-upload-dragger-bg-active); /* 对齐 Semi 拖拽区 hover 背景 */
+  .cd-upload-drag-area:hover {
+    background-color: var(--cd-color-upload-drag-area-bg-hover);
+    border-color: var(--cd-color-upload-drag-area-border-hover);
   }
-  .cd-upload__dragger:focus-visible {
+  .cd-upload-drag-area:focus-visible {
     outline: none;
     box-shadow: var(--cd-focus-ring);
   }
-  .cd-upload--disabled .cd-upload__dragger {
-    cursor: not-allowed;
-    opacity: 0.5;
+  .cd-upload-drag-area-custom {
+    border: none;
+    padding: 0;
+    background-color: inherit;
   }
-  /* 组件级 size：拖拽区内边距/字号档。 */
-  .cd-upload--small .cd-upload__dragger {
-    padding-block: var(--cd-spacing-base);
-    font-size: var(--cd-font-size-small);
+  .cd-upload-drag-area-custom:hover {
+    background-color: inherit;
   }
-  .cd-upload--large .cd-upload__dragger {
-    padding-block: var(--cd-spacing-extra-loose, var(--cd-spacing-loose));
-    font-size: var(--cd-font-size-header-6);
+  .cd-upload-drag-area-legal {
+    background-color: var(--cd-color-upload-drag-area-bg-hover);
+    border-color: var(--cd-color-upload-drag-area-border-hover);
   }
-  /* 组件级 status：校验态影响上传区/卡片边框色（区别于 file.status 进度态）。 */
-  .cd-upload--warning .cd-upload__dragger {
-    border-color: var(--cd-upload-border-warning, var(--cd-color-warning));
+  .cd-upload-drag-area-legal .cd-upload-drag-area-sub-text {
+    display: none;
   }
-  .cd-upload--error .cd-upload__dragger {
-    border-color: var(--cd-upload-border-error, var(--cd-color-danger));
+  .cd-upload-drag-area-icon {
+    color: var(--cd-color-upload-drag-area-icon);
   }
-  .cd-upload--warning .cd-upload__trigger {
-    border-color: var(--cd-upload-border-warning, var(--cd-color-warning));
+  .cd-upload-drag-area-text {
+    text-align: center;
   }
-  .cd-upload--error .cd-upload__trigger {
-    border-color: var(--cd-upload-border-error, var(--cd-color-danger));
+  .cd-upload-drag-area-main-text {
+    cursor: pointer;
+    font-size: var(--cd-font-size-regular);
+    margin-block-end: var(--cd-spacing-upload-drag-area-main-text-marginbottom);
+    color: var(--cd-color-upload-drag-area-main-text-default);
   }
-  .cd-upload--warning .cd-upload__card,
-  .cd-upload--error .cd-upload__card {
-    border-color: var(--cd-upload-border-warning, var(--cd-color-warning));
+  .cd-upload-drag-area:hover .cd-upload-drag-area-main-text {
+    color: var(--cd-color-upload-drag-area-main-text-hover);
   }
-  .cd-upload--error .cd-upload__card {
-    border-color: var(--cd-upload-border-error, var(--cd-color-danger));
+  .cd-upload-drag-area:active .cd-upload-drag-area-main-text {
+    color: var(--cd-color-upload-drag-area-main-text-active);
   }
-  .cd-upload__list-title {
+  .cd-upload-drag-area-sub-text {
+    cursor: pointer;
     font-size: var(--cd-font-size-small);
-    color: var(--cd-color-text-1);
-    font-weight: 500;
-    margin-block-end: var(--cd-spacing-extra-tight);
+    color: var(--cd-color-upload-drag-area-sub-text-default);
   }
-  .cd-upload__list {
-    display: flex;
-    flex-direction: column;
-    gap: var(--cd-spacing-extra-tight);
-    margin: 0;
-    padding: 0;
-    list-style: none;
+  .cd-upload-drag-area:hover .cd-upload-drag-area-sub-text {
+    color: var(--cd-color-upload-drag-area-sub-text-hover);
   }
-  .cd-upload__item {
-    display: flex;
-    flex-direction: column;
-    gap: var(--cd-spacing-extra-tight);
-    padding-block: var(--cd-spacing-extra-tight);
-    padding-inline: var(--cd-spacing-tight);
-    border-radius: var(--cd-border-radius-small);
+  .cd-upload-drag-area:active .cd-upload-drag-area-sub-text {
+    color: var(--cd-color-upload-drag-area-sub-text-active);
   }
-  .cd-upload__item-main {
-    display: flex;
-    align-items: center;
-    gap: var(--cd-spacing-tight);
-  }
-  .cd-upload__item:hover {
-    background: var(--cd-upload-item-bg-hover);
+  .cd-upload-drag-area-tips {
+    font-size: var(--cd-font-size-small);
+    font-weight: var(--cd-font-upload-drag-area-tips-fontweight);
   }
-  .cd-upload__item--error {
-    color: var(--cd-upload-item-color-error);
+  .cd-upload-drag-area-tips-legal {
+    color: var(--cd-color-upload-drag-area-tips-text);
   }
-  .cd-upload__item-name {
-    flex: 1 1 auto;
-    min-inline-size: 0;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
+
+  /* ============ picture 添加瓦片（对齐 Semi picture-add 段） ============ */
+  .cd-upload-picture {
+    display: flex;
   }
-  .cd-upload__item-size,
-  .cd-upload__item-status {
-    flex: 0 0 auto;
-    color: var(--cd-color-text-2);
-    font-size: var(--cd-font-size-small);
+  .cd-upload-picture[x-prompt-pos='bottom'] {
+    flex-direction: column;
   }
-  .cd-upload__item--error .cd-upload__item-status {
-    color: var(--cd-upload-item-color-error);
+  .cd-upload-picture[x-prompt-pos='bottom'] .cd-upload-prompt,
+  .cd-upload-picture[x-prompt-pos='right'] .cd-upload-prompt {
+    order: 1;
   }
-  .cd-upload__item-remove {
-    flex: 0 0 auto;
+  .cd-upload-picture-add {
+    background-color: var(--cd-color-upload-pic-add-bg);
+    height: var(--cd-height-upload-file-pic-card);
+    width: var(--cd-width-upload-file-pic-card);
+    box-sizing: border-box;
     display: inline-flex;
-    align-items: center;
     justify-content: center;
-    padding: 0;
-    border: none;
-    background: transparent;
-    color: var(--cd-color-text-2);
+    align-items: center;
+    border: var(--cd-width-upload-picture-add-border) dashed var(--cd-color-upload-border);
+    color: var(--cd-color-upload-icon);
+    border-radius: var(--cd-radius-upload-picture-add);
     cursor: pointer;
-    border-radius: var(--cd-border-radius-small);
-    font-size: var(--cd-font-size-header-6);
-    line-height: 1;
   }
-  .cd-upload__item-remove:hover {
-    color: var(--cd-color-text-0);
+  .cd-upload-picture-add:hover {
+    background-color: var(--cd-color-upload-pic-add-bg-hover);
+  }
+  .cd-upload-picture-add:active {
+    background-color: var(--cd-color-upload-pic-add-bg-active);
   }
-  .cd-upload__item-remove:focus-visible {
+  .cd-upload-picture-add:focus-visible {
     outline: none;
     box-shadow: var(--cd-focus-ring);
   }
-  .cd-upload__item-remove:disabled {
+  .cd-upload-picture-add-disabled {
     cursor: not-allowed;
-    opacity: 0.5;
   }
-  .cd-upload__retry-btn {
-    flex: 0 0 auto;
-    display: inline-flex;
-    align-items: center;
-    padding: 0 var(--cd-spacing-extra-tight);
-    border: none;
-    background: transparent;
-    color: var(--cd-color-primary);
-    cursor: pointer;
-    font-size: var(--cd-font-size-small);
-    border-radius: var(--cd-border-radius-small);
+  .cd-upload-picture-add-disabled:hover,
+  .cd-upload-picture-add-disabled:active {
+    background-color: var(--cd-color-upload-pic-add-bg);
   }
-  .cd-upload__retry-btn:hover {
-    text-decoration: underline;
+  .cd-upload-picture-file-list {
+    flex-basis: inherit;
+    margin-block: 0;
   }
-  .cd-upload__retry-btn:disabled {
+
+  /* ============ 校验态 / disabled（对齐 Semi） ============ */
+  .cd-upload-warning .cd-upload-drag-area,
+  .cd-upload-warning .cd-upload-add,
+  .cd-upload-warning .cd-upload-picture-add {
+    border-color: var(--cd-color-warning);
+  }
+  .cd-upload-error .cd-upload-drag-area,
+  .cd-upload-error .cd-upload-add,
+  .cd-upload-error .cd-upload-picture-add {
+    border-color: var(--cd-color-danger);
+  }
+  .cd-upload-disabled {
     cursor: not-allowed;
-    opacity: 0.5;
   }
-  .cd-upload__clear-btn {
-    align-self: flex-end;
-    display: inline-flex;
-    align-items: center;
-    gap: var(--cd-spacing-extra-tight);
-    padding: var(--cd-spacing-extra-tight) var(--cd-spacing-tight);
+  .cd-upload-disabled .cd-upload-drag-area {
     border: none;
-    background: transparent;
-    color: var(--cd-color-text-2);
-    cursor: pointer;
-    font-size: var(--cd-font-size-small);
-    border-radius: var(--cd-border-radius-small);
-  }
-  .cd-upload__clear-btn:hover {
-    color: var(--cd-color-danger);
-    background: var(--cd-color-fill-1);
-  }
-  .cd-upload__clear-btn:disabled {
     cursor: not-allowed;
-    opacity: 0.5;
   }
-  .cd-upload__dragger-main {
-    display: block;
-    font-size: var(--cd-font-size-regular);
-    color: var(--cd-color-text-1);
+  .cd-upload-disabled .cd-upload-drag-area:hover {
+    background-color: var(--cd-color-upload-drag-area-bg);
   }
-  .cd-upload__dragger-sub {
-    display: block;
-    font-size: var(--cd-font-size-small);
-    color: var(--cd-color-text-2);
+  .cd-upload-disabled .cd-upload-drag-area-main-text,
+  .cd-upload-disabled .cd-upload-drag-area-sub-text,
+  .cd-upload-disabled .cd-upload-drag-area-icon {
+    cursor: not-allowed;
+    color: var(--cd-color-upload-drag-area-disabled-text);
   }
 
-  /* --- image / picture-card 缩略图网格 --- */
-  .cd-upload__grid {
-    display: flex;
-    flex-wrap: wrap;
-    gap: var(--cd-spacing-tight);
-    margin: 0;
-    padding: 0;
-    list-style: none;
-  }
-  .cd-upload__card {
-    position: relative;
-    inline-size: 96px;
-    block-size: 96px;
-    border: 1px solid var(--cd-color-border);
-    border-radius: var(--cd-border-radius-medium);
-    overflow: hidden;
-    background: var(--cd-color-fill-0);
-  }
-  .cd-upload__card--error {
-    border-color: var(--cd-upload-item-color-error, var(--cd-color-danger));
-  }
-  .cd-upload__thumb-btn {
+  .cd-upload-validate-message {
+    flex-basis: 100%;
+    flex-shrink: 0;
     display: block;
-    inline-size: 100%;
-    block-size: 100%;
-    padding: 0;
-    border: none;
-    background: transparent;
-    cursor: pointer;
-  }
-  .cd-upload__thumb-btn:focus-visible {
-    outline: none;
-    box-shadow: var(--cd-focus-ring);
+    color: var(--cd-color-upload-file-card-fail-info-text);
   }
-  .cd-upload__thumb {
+  .cd-upload-crop-body {
     inline-size: 100%;
-    block-size: 100%;
-    object-fit: cover;
-    display: block;
-  }
-  .cd-upload__thumb--placeholder {
-    background: var(--cd-color-fill-1);
-  }
-  .cd-upload__card-progress {
-    position: absolute;
-    inset-inline: var(--cd-spacing-extra-tight);
-    inset-block-end: var(--cd-spacing-extra-tight);
-  }
-  .cd-upload__card-overlay {
-    position: absolute;
-    inset-block-start: 0;
-    inset-inline: 0;
-    display: flex;
-    align-items: center;
-    gap: var(--cd-spacing-extra-tight);
-    padding: var(--cd-spacing-extra-tight);
-    background: linear-gradient(to bottom, rgba(0, 0, 0, 0.55), transparent);
-    opacity: 0;
-    transition: opacity var(--cd-motion-duration-fast) var(--cd-motion-ease-standard);
-  }
-  .cd-upload__card:hover .cd-upload__card-overlay,
-  .cd-upload__card:focus-within .cd-upload__card-overlay {
-    opacity: 1;
-  }
-  .cd-upload__card-name {
-    flex: 1 1 auto;
-    min-inline-size: 0;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-    color: #fff;
-    font-size: var(--cd-font-size-small);
-  }
-  .cd-upload__card-remove {
-    flex: 0 0 auto;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    padding: 0;
-    inline-size: 1.25rem;
-    block-size: 1.25rem;
-    border: none;
-    background: transparent;
-    color: #fff;
-    cursor: pointer;
-    font-size: var(--cd-font-size-header-6);
-    line-height: 1;
-  }
-  .cd-upload__card-remove:focus-visible {
-    outline: none;
-    box-shadow: var(--cd-focus-ring);
-  }
-  @media (prefers-reduced-motion: reduce) {
-    .cd-upload__card-overlay {
-      transition: none;
-    }
-    .cd-upload__dragger {
-      transition: none;
-    }
   }
 </style>