@sia.soul/sia-react-ui 0.1.28 → 0.1.30

package/dist/{core-CTe-Sfl1.d.cts → core-B687rqFa.d.cts}

@@ -377,12 +377,14 @@ declare const Icon: react.ForwardRefExoticComponent<IconProps & react.RefAttribu
 
 /** 标签的状态类型。 */
 type TagStatus = "default" | "success" | "processing" | "warning" | "error";
-/** 标签的视觉样式。 */
+/** 标签的视觉样式：soft 为柔和浅底，outlined 为透明底描边，filled 为实色背景。 */
 type TagVariant = "soft" | "outlined" | "filled";
 /** 标签的属性配置。 */
 interface TagProps extends HTMLAttributes<HTMLSpanElement> {
+    /** 自定义 CSS 颜色，支持十六进制、rgb、颜色名称及 CSS 变量；覆盖 status 的颜色，由 variant 决定浅底、描边或实色效果。未提供非空颜色时沿用状态配色，style 中对应属性优先级最高。 */
+    color?: string;
     /**
-     * 语义状态
+     * 语义状态配色；提供 color 时由自定义颜色覆盖。
      * @defaultValue "default"
      */
     status?: TagStatus;
@@ -392,7 +394,7 @@ interface TagProps extends HTMLAttributes<HTMLSpanElement> {
      */
     compact?: boolean;
     /**
-     组件的视觉样式。
+     * 视觉样式：soft 使用浅色背景和彩色文字；outlined 使用透明背景、彩色边框和文字；filled 使用实色背景、白字和透明边框。同样适用于自定义 color；实色浅底可通过 style.color 调整文字。
      * @defaultValue "soft"
      */
     variant?: TagVariant;
@@ -403,7 +405,10 @@ interface TagProps extends HTMLAttributes<HTMLSpanElement> {
      * @defaultValue false
      */
     closable?: boolean;
-    /** 悬停或键盘聚焦时展开关闭按钮。 */
+    /**
+     * 配合 closable 使用：默认隐藏关闭按钮且不占宽度，鼠标悬停或内部获得键盘焦点时，标签向右扩展并显示按钮；离开后收回，过渡为 180 毫秒。禁用时不展开，无悬停能力的触屏设备直接显示以便操作，减少动态效果偏好下取消动画。
+     * @defaultValue false
+     */
     closeOnHover?: boolean;
     /**
      * 禁用关闭操作
@@ -413,8 +418,8 @@ interface TagProps extends HTMLAttributes<HTMLSpanElement> {
     /** 请求关闭时触发的回调。 */
     onClose?: (event: MouseEvent<HTMLButtonElement>) => void;
 }
-/** 标签组件。 */
-declare function Tag({ status, compact, variant, icon, closable, closeOnHover, disabled, onClose, className, children, ...props }: TagProps): react.JSX.Element;
+/** 标记状态或筛选条件的标签，支持语义配色、自定义边框色或背景色及关闭操作。 */
+declare function Tag({ color, status, compact, variant, icon, closable, closeOnHover, disabled, onClose, className, children, style, ...props }: TagProps): react.JSX.Element;
 
 /** 菜单的模式类型。 */
 type MenuMode = "vertical" | "horizontal" | "inline";
@@ -1804,119 +1809,174 @@ interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "prefix
 /** 输入框组件。 */
 declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
 
-declare const LIST_IGNORE: unique symbol;
-/** UploadFile的状态类型。 */
+/** ready 为待上传，uploading 为进行中，done 为成功，error 为校验或网络失败。 */
 type UploadFileStatus = "ready" | "uploading" | "done" | "error";
-/** 上传文件的状态记录，包含唯一标识、文件名、原始文件和服务端响应。 */
+/** 文件记录；受控更新时应保持 uid 不变。 */
 interface UploadFile {
-    /** 文件的唯一标识。 */
+    /** 列表中唯一的文件标识。 */
     uid: string;
-    /** 名称或字段标识。 */
+    /** 显示文件名，不含目录。 */
     name: string;
-    /** 组件尺寸；用于调整控件高度、字号和间距。 */
+    /** 文件大小，单位字节。 */
     size?: number;
-    /** 类型标识，用于选择对应的表现形式。 */
+    /** MIME 类型，例如 image/png。 */
     type?: string;
-    /** 当前状态，用于选择对应的状态样式。 */
+    /** 当前状态，缺省按 ready 展示。 */
     status?: UploadFileStatus;
-    /** 进度百分比。 */
+    /** 上传百分比，范围 0–100。 */
     percent?: number;
-    /** 文件或资源的访问地址。 */
+    /** 远程访问地址，用于预览和文件链接。 */
     url?: string;
-    /** 上传服务返回的响应数据。 */
+    /** 缩略图地址，优先于本地缩略图；预览优先使用 url。 */
+    thumbUrl?: string;
+    /** 包含所选根目录的相对路径，例如 photos/trip/a.png；普通文件为文件名。 */
+    relativePath?: string;
+    /** 服务端成功响应；内置请求优先解析 JSON，否则保留文本。 */
     response?: unknown;
-    /** 错误信息或错误对象。 */
+    /** 最近一次校验或上传错误。 */
     error?: unknown;
-    /** 上传前的原始 File 对象。 */
+    /** 原始 File，用于本地预览与重试；beforeUpload 转换只影响当次请求。 */
     originFileObj?: File;
 }
-/** UploadRequest的配置选项。 */
+/** 自定义上传参数，可用于 SDK、分片、断点续传或业务请求。 */
 interface UploadRequestOptions {
-    /** 当前操作涉及的文件。 */
+    /** 已经 beforeUpload 转换的实际上传文件。 */
     file: File;
-    /** 文件名。 */
+    /** 文件名，不是 multipart 字段名。 */
     filename: string;
-    /** 上传进度更新时调用。 */
+    /** 本次上传的列表记录快照，uid 可关联业务任务。 */
+    uploadFile: UploadFile;
+    /** 相对路径；普通文件为文件名。 */
+    relativePath: string;
+    /** 取消、移除或卸载时中止；获取签名及分片请求也应监听此信号。 */
+    signal: AbortSignal;
+    /** 更新百分比 0–100；任务结束或取消后的回调会被忽略。 */
     onProgress: (percent: number) => void;
-    /** 上传成功时调用，接收响应数据。 */
-    onSuccess: (response?: unknown) => void;
-    /** 操作发生错误时调用，可用于显示业务错误提示。 */
+    /** 上传完成时调用一次，保存 response；url 可指定访问地址。 */
+    onSuccess: (response?: unknown, url?: string) => void;
+    /** 失败时调用一次，保存错误并通知 onChange。 */
     onError: (error: unknown) => void;
 }
-/** 文件上传的变更事件上下文。 */
+/** 上传取消句柄，与 signal 一起用于中止底层任务。 */
+interface UploadRequestHandle {
+    /** 取消、移除或卸载时调用；应终止 SDK 或分片上传。 */
+    abort?: () => void;
+}
+/** 通用 HTTP 上传配置，支持业务接口、OSS 签名表单和预签名 PUT。 */
+interface UploadHttpRequest {
+    /** 上传地址；签名应由业务服务端生成。 */
+    action: string;
+    /** 请求方法，预签名二进制直传通常使用 PUT。 @defaultValue "POST" */
+    method?: "POST" | "PUT" | "PATCH";
+    /** form-data 为 multipart 表单，file 为 File 二进制。 @defaultValue "form-data" */
+    body?: "form-data" | "file";
+    /** multipart 文件字段名。 @defaultValue "file" */
+    name?: string;
+    /** multipart 额外字段，在文件之前添加，例如 key、policy、签名和令牌。 */
+    data?: Readonly<Record<string, string | Blob>>;
+    /** 自定义请求头，需与签名一致；multipart 不要手动设置 Content-Type。 */
+    headers?: Readonly<Record<string, string>>;
+    /** 是否携带跨域 Cookie。 @defaultValue false */
+    withCredentials?: boolean;
+    /** 超时毫秒数，0 为不设超时。 @defaultValue 0 */
+    timeout?: number;
+    /** 成功后写入文件记录的访问地址。 */
+    url?: string;
+}
+/** 文件列表变化的上下文。 */
 interface UploadChangeInfo {
-    /** 当前操作涉及的文件。 */
+    /** 本次变化的文件；移除时仍提供被移除的记录。 */
     file: UploadFile;
-    /** 受控的文件列表。 */
+    /** 最新完整列表，受控模式需回填给 fileList。 */
     fileList: readonly UploadFile[];
+    /** 触发原因：添加、开始、进度、成功、失败、移除或取消。 */
+    event: "add" | "start" | "progress" | "success" | "error" | "remove" | "cancel";
+}
+/** 类型或数量限制拒绝的文件。 */
+interface UploadRejectInfo {
+    /** 未加入列表的原始文件。 */
+    file: File;
+    /** accept 为类型不匹配，max-count 为达到数量上限。 */
+    reason: "accept" | "max-count";
+}
+/** 自定义列表项可调用的操作，仍遵循禁用、取消和 onRemove 规则。 */
+interface UploadItemActions {
+    /** 开始或重试当前文件；已上传成功或正在上传时不重复启动。 */
+    upload: () => Promise<void>;
+    /** 取消当前任务并回到 ready，保留文件。 */
+    abort: () => void;
+    /** 请求移除，等待 onRemove 允许后取消并删除。 */
+    remove: () => Promise<void>;
+    /** 触发自定义 onPreview，未提供时打开框架图片预览。 */
+    preview: () => void;
+}
+/** Upload 的命令式句柄，适用于手动上传及业务工具栏。 */
+interface UploadRef {
+    /** 开始 ready/error 文件；省略 uid 开始所有待上传项。Promise 在这些任务成功、失败或取消后完成，结果通过 onChange 通知。 */
+    upload: (uid?: string) => Promise<void>;
+    /** 取消指定文件，省略 uid 取消全部；保留记录为 ready，可再次 upload。 */
+    abort: (uid?: string) => void;
+    /** 请求移除指定文件；onRemove 拒绝时保留记录。 */
+    remove: (uid: string) => Promise<void>;
 }
-/** 文件上传的属性配置。 */
+/** 文件上传属性；未配置 request/customRequest 时仅选择文件，不模拟上传成功。 */
 interface UploadProps extends Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange"> {
-    /** 允许的文件类型，格式同原生 input 的 accept。 */
+    /** 扩展名或 MIME 类型，逗号分隔；点击、拖拽和粘贴均校验。 */
     accept?: string;
-    /**
-     是否允许同时选择多个项目。
-     * @defaultValue false
-     */
+    /** 每批是否允许多个文件；false 仅取首个，directory 模式不受此限制。 @defaultValue false */
     multiple?: boolean;
-    /**
-     * 是否允许选择文件夹。
-     * @defaultValue false
-     */
+    /** 选择或拖入文件夹，文件路径保存在 relativePath；不会上传空目录。 @defaultValue false */
     directory?: boolean;
-    /**
-     * 是否禁用交互。
-     * @defaultValue false
-     */
+    /** 是否包括子文件夹中的文件；false 仅处理根目录直接包含的文件。 @defaultValue true */
+    recursive?: boolean;
+    /** 聚焦本区域后允许粘贴文件或截图，不监听整个页面也不处理普通文本。 @defaultValue false */
+    pastable?: boolean;
+    /** 禁止添加、移除和启动上传；已在进行的请求不会自动取消。 @defaultValue false */
     disabled?: boolean;
-    /** 允许的最大文件数量。 */
+    /** 添加后自动上传；false 为手动模式，调用 ref.upload 或自定义列表操作启动。 @defaultValue true */
+    autoUpload?: boolean;
+    /** 最大文件数量，包含等待及失败项；超出部分拒绝，不替换已有文件。默认不限。 */
     maxCount?: number;
-    /** 受控的文件列表。 */
+    /** 受控列表，onChange 中回填；外部移除记录会取消关联请求。 */
     fileList?: readonly UploadFile[];
-    /**
-     * 非受控模式下的初始文件列表。
-     * @defaultValue []
-     */
+    /** 非受控初始列表，后续修改不重置列表。 @defaultValue [] */
     defaultFileList?: readonly UploadFile[];
-    /**
-     * 上传文件列表的展示形式。
-     * @defaultValue "text"
-     */
+    /** text 为文件列表，picture 为图片行，picture-card 为照片墙；照片墙满额隐藏添加入口。 @defaultValue "text" */
     listType?: "text" | "picture" | "picture-card";
-    /**
-     * 是否显示上传文件列表。
-     * @defaultValue true
-     */
+    /** 是否显示列表；隐藏时仍执行数量限制和变更通知。 @defaultValue true */
     showUploadList?: boolean;
-    /** 上传前校验或转换文件 */
-    beforeUpload?: (file: File, fileList: readonly File[]) => boolean | File | typeof LIST_IGNORE | Promise<boolean | File | typeof LIST_IGNORE>;
-    /** 自定义上传实现 */
-    customRequest?: (options: UploadRequestOptions) => void | {
-        /** 取消当前上传请求。 */
-        abort?: () => void;
-    };
-    /** 值发生变化时调用；参数为新值及类型声明中列出的关联信息。 */
+    /** 启动前校验，可异步；false 保留 ready，Upload.LIST_IGNORE 移除，File 转换本次上传内容；拒绝或抛错进入 error。手动上传时在调用 upload 后执行。 */
+    beforeUpload?: (file: File, fileList: readonly File[]) => boolean | File | symbol | Promise<boolean | File | symbol>;
+    /** HTTP 配置或逐文件异步签名函数，拒绝时进入 error；接收记录和取消信号。customRequest 优先。 */
+    request?: UploadHttpRequest | ((file: UploadFile, signal: AbortSignal) => UploadHttpRequest | Promise<UploadHttpRequest>);
+    /** 自定义上传，负责调用状态回调，可异步返回取消句柄；函数异常或 Promise 拒绝按失败处理。优先于 request。 */
+    customRequest?: (options: UploadRequestOptions) => void | UploadRequestHandle | Promise<void | UploadRequestHandle>;
+    /** 添加、开始、进度、完成、失败、取消和移除时调用；取消任务的迟到回调被忽略。 */
     onChange?: (info: UploadChangeInfo) => void;
-    /** 请求移除文件时调用；返回值控制是否允许移除。 */
-    onRemove?: (file: UploadFile) => boolean | Promise<boolean>;
-    /** 子内容；组件嵌套内容或当前节点的子项。 */
+    /** 移除前调用；false 或 Promise 拒绝阻止移除，否则取消任务并删除。 */
+    onRemove?: (file: UploadFile) => boolean | void | Promise<boolean | void>;
+    /** 文件类型不匹配或数量超限时调用，该文件不进入列表。 */
+    onReject?: (info: UploadRejectInfo) => void;
+    /** 拖拽目录读取失败时调用，本次批次不上传。 */
+    onReadError?: (error: unknown) => void;
+    /** 点击预览时调用，提供后完全接管预览，可实现 PDF、视频或业务弹窗。 */
+    onPreview?: (file: UploadFile) => void;
+    /** 完全自定义列表项；接收默认节点、记录、最新列表及操作句柄，应自行提供可访问的按钮。 */
+    itemRender?: (node: ReactNode, file: UploadFile, fileList: readonly UploadFile[], actions: UploadItemActions) => ReactNode;
+    /** 上传按钮内容，不应嵌套其他交互控件；外层负责点击和键盘操作。 */
     children?: ReactNode;
 }
-/** UploadDragger的属性配置。 */
+/** 拖拽区域继承全部 Upload 能力，ref 同样支持手动控制。 */
 interface UploadDraggerProps extends UploadProps {
-    /**
-     * 帮助或校验信息
-     * @defaultValue "支持单个或批量上传"
-     */
+    /** 辅助说明文字。 @defaultValue "支持单个或批量上传" */
     hint?: ReactNode;
 }
-declare function UploadRoot({ accept, multiple, directory, disabled, maxCount, fileList, defaultFileList, listType, showUploadList, beforeUpload, customRequest, onChange, onRemove, children, className, onDragOver, onDrop, ...props }: UploadProps): react.JSX.Element;
-declare function UploadDragger({ hint, children, className, ...props }: UploadDraggerProps): react.JSX.Element;
-/** 文件上传组件。 */
-declare const Upload: typeof UploadRoot & {
-    /** 支持拖入文件上传的区域组件。 */
-    Dragger: typeof UploadDragger;
-    /** beforeUpload 返回此标记时忽略该文件，不加入上传列表。 */
+
+/** 上传组件，支持图片列表、照片墙、目录、粘贴与完全受控请求；未配置请求时仅选择文件。 */
+declare const Upload: react.ForwardRefExoticComponent<UploadProps & react.RefAttributes<UploadRef>> & {
+    /** 可点击、键盘操作和拖拽的上传区域，ref 支持手动上传、取消及移除。 */
+    Dragger: react.ForwardRefExoticComponent<UploadDraggerProps & react.RefAttributes<UploadRef>>;
+    /** beforeUpload 返回时移除该文件，不进行上传。 */
     LIST_IGNORE: symbol;
 };
 
@@ -2169,4 +2229,4 @@ declare const FloatButton: react.ForwardRefExoticComponent<FloatButtonProps & re
     BackTop: typeof FloatButtonBackTop;
 };
 
-export { type MenuTheme as $, type FloatButtonGroupProps as A, type BadgeProps as B, Calendar as C, Dropdown as D, type FloatButtonProps as E, FILLED_ICON_NAMES as F, type FloatButtonShape as G, type FloatingPlacement as H, type FloatingTrigger as I, ICON_NAMES as J, Icon as K, type IconName as L, type IconProps as M, type IconVariant as N, Image as O, ImagePreview as P, type ImagePreviewConfig as Q, type ImagePreviewProps as R, type ImageProps as S, type TagStatus as T, Input as U, type InputProps as V, Menu as W, type MenuClickInfo as X, type MenuItem as Y, type MenuMode as Z, type MenuProps as _, Badge as a, type UploadRequestOptions as a$, type MessageConfig as a0, type MessageHandle as a1, type MessageKey as a2, type MessageType as a3, type NotificationConfig as a4, type NotificationPlacement as a5, type NotificationType as a6, Popconfirm as a7, type PopconfirmProps as a8, Popover as a9, Timeline as aA, type TimelineItem as aB, type TimelineProps as aC, Toolbar as aD, type ToolbarItem as aE, type ToolbarProps as aF, Tooltip as aG, type TooltipProps as aH, Tour as aI, type TourProps as aJ, type TourStep as aK, Tree as aL, type TreeDropPosition as aM, type TreeKey as aN, type TreeNode as aO, type TreeProps as aP, Typography as aQ, type TypographyLinkProps as aR, type TypographyProps as aS, type TypographyTitleProps as aT, type TypographyType as aU, Upload as aV, type UploadChangeInfo as aW, type UploadDraggerProps as aX, type UploadFile as aY, type UploadFileStatus as aZ, type UploadProps as a_, type PopoverProps as aa, Progress as ab, type ProgressProps as ac, type ProgressStatus as ad, Rate as ae, type RateProps as af, Segmented as ag, type SegmentedOption as ah, type SegmentedProps as ai, type SegmentedValue as aj, Spin as ak, type SpinProps as al, type StepItem as am, type StepStatus as an, Steps as ao, type StepsProps as ap, type TabItem as aq, Tabs as ar, type TabsContextMenuClickInfo as as, type TabsOrientation as at, type TabsPosition as au, type TabsProps as av, type TabsType as aw, Tag as ax, type TagProps as ay, type TagVariant as az, type BadgeRibbonProps as b, Watermark as b0, type WatermarkFont as b1, type WatermarkProps as b2, message as b3, notification as b4, type BadgeStatus as c, Breadcrumb as d, type BreadcrumbItem as e, type BreadcrumbProps as f, type CalendarProps as g, Card as h, type CardAccent as i, type CardProps as j, Carousel as k, type CarouselProps as l, type CarouselRef as m, Collapse as n, type CollapseItem as o, type CollapseKey as p, type CollapseProps as q, type DropdownButtonProps as r, type DropdownMenuProps as s, type DropdownOpenSource as t, type DropdownPlacement as u, type DropdownProps as v, type DropdownTrigger as w, type FilledIconName as x, FloatButton as y, type FloatButtonBackTopProps as z };
+export { type MenuTheme as $, type FloatButtonGroupProps as A, type BadgeProps as B, Calendar as C, Dropdown as D, type FloatButtonProps as E, FILLED_ICON_NAMES as F, type FloatButtonShape as G, type FloatingPlacement as H, type FloatingTrigger as I, ICON_NAMES as J, Icon as K, type IconName as L, type IconProps as M, type IconVariant as N, Image as O, ImagePreview as P, type ImagePreviewConfig as Q, type ImagePreviewProps as R, type ImageProps as S, type TagStatus as T, Input as U, type InputProps as V, Menu as W, type MenuClickInfo as X, type MenuItem as Y, type MenuMode as Z, type MenuProps as _, Badge as a, type UploadItemActions as a$, type MessageConfig as a0, type MessageHandle as a1, type MessageKey as a2, type MessageType as a3, type NotificationConfig as a4, type NotificationPlacement as a5, type NotificationType as a6, Popconfirm as a7, type PopconfirmProps as a8, Popover as a9, Timeline as aA, type TimelineItem as aB, type TimelineProps as aC, Toolbar as aD, type ToolbarItem as aE, type ToolbarProps as aF, Tooltip as aG, type TooltipProps as aH, Tour as aI, type TourProps as aJ, type TourStep as aK, Tree as aL, type TreeDropPosition as aM, type TreeKey as aN, type TreeNode as aO, type TreeProps as aP, Typography as aQ, type TypographyLinkProps as aR, type TypographyProps as aS, type TypographyTitleProps as aT, type TypographyType as aU, Upload as aV, type UploadChangeInfo as aW, type UploadDraggerProps as aX, type UploadFile as aY, type UploadFileStatus as aZ, type UploadHttpRequest as a_, type PopoverProps as aa, Progress as ab, type ProgressProps as ac, type ProgressStatus as ad, Rate as ae, type RateProps as af, Segmented as ag, type SegmentedOption as ah, type SegmentedProps as ai, type SegmentedValue as aj, Spin as ak, type SpinProps as al, type StepItem as am, type StepStatus as an, Steps as ao, type StepsProps as ap, type TabItem as aq, Tabs as ar, type TabsContextMenuClickInfo as as, type TabsOrientation as at, type TabsPosition as au, type TabsProps as av, type TabsType as aw, Tag as ax, type TagProps as ay, type TagVariant as az, type BadgeRibbonProps as b, type UploadProps as b0, type UploadRef as b1, type UploadRejectInfo as b2, type UploadRequestHandle as b3, type UploadRequestOptions as b4, Watermark as b5, type WatermarkFont as b6, type WatermarkProps as b7, message as b8, notification as b9, type BadgeStatus as c, Breadcrumb as d, type BreadcrumbItem as e, type BreadcrumbProps as f, type CalendarProps as g, Card as h, type CardAccent as i, type CardProps as j, Carousel as k, type CarouselProps as l, type CarouselRef as m, Collapse as n, type CollapseItem as o, type CollapseKey as p, type CollapseProps as q, type DropdownButtonProps as r, type DropdownMenuProps as s, type DropdownOpenSource as t, type DropdownPlacement as u, type DropdownProps as v, type DropdownTrigger as w, type FilledIconName as x, FloatButton as y, type FloatButtonBackTopProps as z };

package/dist/{core-DlvCqFU7.d.ts → core-BwuvPHYM.d.ts}

@@ -377,12 +377,14 @@ declare const Icon: react.ForwardRefExoticComponent<IconProps & react.RefAttribu
 
 /** 标签的状态类型。 */
 type TagStatus = "default" | "success" | "processing" | "warning" | "error";
-/** 标签的视觉样式。 */
+/** 标签的视觉样式：soft 为柔和浅底，outlined 为透明底描边，filled 为实色背景。 */
 type TagVariant = "soft" | "outlined" | "filled";
 /** 标签的属性配置。 */
 interface TagProps extends HTMLAttributes<HTMLSpanElement> {
+    /** 自定义 CSS 颜色，支持十六进制、rgb、颜色名称及 CSS 变量；覆盖 status 的颜色，由 variant 决定浅底、描边或实色效果。未提供非空颜色时沿用状态配色，style 中对应属性优先级最高。 */
+    color?: string;
     /**
-     * 语义状态
+     * 语义状态配色；提供 color 时由自定义颜色覆盖。
      * @defaultValue "default"
      */
     status?: TagStatus;
@@ -392,7 +394,7 @@ interface TagProps extends HTMLAttributes<HTMLSpanElement> {
      */
     compact?: boolean;
     /**
-     组件的视觉样式。
+     * 视觉样式：soft 使用浅色背景和彩色文字；outlined 使用透明背景、彩色边框和文字；filled 使用实色背景、白字和透明边框。同样适用于自定义 color；实色浅底可通过 style.color 调整文字。
      * @defaultValue "soft"
      */
     variant?: TagVariant;
@@ -403,7 +405,10 @@ interface TagProps extends HTMLAttributes<HTMLSpanElement> {
      * @defaultValue false
      */
     closable?: boolean;
-    /** 悬停或键盘聚焦时展开关闭按钮。 */
+    /**
+     * 配合 closable 使用：默认隐藏关闭按钮且不占宽度，鼠标悬停或内部获得键盘焦点时，标签向右扩展并显示按钮；离开后收回，过渡为 180 毫秒。禁用时不展开，无悬停能力的触屏设备直接显示以便操作，减少动态效果偏好下取消动画。
+     * @defaultValue false
+     */
     closeOnHover?: boolean;
     /**
      * 禁用关闭操作
@@ -413,8 +418,8 @@ interface TagProps extends HTMLAttributes<HTMLSpanElement> {
     /** 请求关闭时触发的回调。 */
     onClose?: (event: MouseEvent<HTMLButtonElement>) => void;
 }
-/** 标签组件。 */
-declare function Tag({ status, compact, variant, icon, closable, closeOnHover, disabled, onClose, className, children, ...props }: TagProps): react.JSX.Element;
+/** 标记状态或筛选条件的标签，支持语义配色、自定义边框色或背景色及关闭操作。 */
+declare function Tag({ color, status, compact, variant, icon, closable, closeOnHover, disabled, onClose, className, children, style, ...props }: TagProps): react.JSX.Element;
 
 /** 菜单的模式类型。 */
 type MenuMode = "vertical" | "horizontal" | "inline";
@@ -1804,119 +1809,174 @@ interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "prefix
 /** 输入框组件。 */
 declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
 
-declare const LIST_IGNORE: unique symbol;
-/** UploadFile的状态类型。 */
+/** ready 为待上传，uploading 为进行中，done 为成功，error 为校验或网络失败。 */
 type UploadFileStatus = "ready" | "uploading" | "done" | "error";
-/** 上传文件的状态记录，包含唯一标识、文件名、原始文件和服务端响应。 */
+/** 文件记录；受控更新时应保持 uid 不变。 */
 interface UploadFile {
-    /** 文件的唯一标识。 */
+    /** 列表中唯一的文件标识。 */
     uid: string;
-    /** 名称或字段标识。 */
+    /** 显示文件名，不含目录。 */
     name: string;
-    /** 组件尺寸；用于调整控件高度、字号和间距。 */
+    /** 文件大小，单位字节。 */
     size?: number;
-    /** 类型标识，用于选择对应的表现形式。 */
+    /** MIME 类型，例如 image/png。 */
     type?: string;
-    /** 当前状态，用于选择对应的状态样式。 */
+    /** 当前状态，缺省按 ready 展示。 */
     status?: UploadFileStatus;
-    /** 进度百分比。 */
+    /** 上传百分比，范围 0–100。 */
     percent?: number;
-    /** 文件或资源的访问地址。 */
+    /** 远程访问地址，用于预览和文件链接。 */
     url?: string;
-    /** 上传服务返回的响应数据。 */
+    /** 缩略图地址，优先于本地缩略图；预览优先使用 url。 */
+    thumbUrl?: string;
+    /** 包含所选根目录的相对路径，例如 photos/trip/a.png；普通文件为文件名。 */
+    relativePath?: string;
+    /** 服务端成功响应；内置请求优先解析 JSON，否则保留文本。 */
     response?: unknown;
-    /** 错误信息或错误对象。 */
+    /** 最近一次校验或上传错误。 */
     error?: unknown;
-    /** 上传前的原始 File 对象。 */
+    /** 原始 File，用于本地预览与重试；beforeUpload 转换只影响当次请求。 */
     originFileObj?: File;
 }
-/** UploadRequest的配置选项。 */
+/** 自定义上传参数，可用于 SDK、分片、断点续传或业务请求。 */
 interface UploadRequestOptions {
-    /** 当前操作涉及的文件。 */
+    /** 已经 beforeUpload 转换的实际上传文件。 */
     file: File;
-    /** 文件名。 */
+    /** 文件名，不是 multipart 字段名。 */
     filename: string;
-    /** 上传进度更新时调用。 */
+    /** 本次上传的列表记录快照，uid 可关联业务任务。 */
+    uploadFile: UploadFile;
+    /** 相对路径；普通文件为文件名。 */
+    relativePath: string;
+    /** 取消、移除或卸载时中止；获取签名及分片请求也应监听此信号。 */
+    signal: AbortSignal;
+    /** 更新百分比 0–100；任务结束或取消后的回调会被忽略。 */
     onProgress: (percent: number) => void;
-    /** 上传成功时调用，接收响应数据。 */
-    onSuccess: (response?: unknown) => void;
-    /** 操作发生错误时调用，可用于显示业务错误提示。 */
+    /** 上传完成时调用一次，保存 response；url 可指定访问地址。 */
+    onSuccess: (response?: unknown, url?: string) => void;
+    /** 失败时调用一次，保存错误并通知 onChange。 */
     onError: (error: unknown) => void;
 }
-/** 文件上传的变更事件上下文。 */
+/** 上传取消句柄，与 signal 一起用于中止底层任务。 */
+interface UploadRequestHandle {
+    /** 取消、移除或卸载时调用；应终止 SDK 或分片上传。 */
+    abort?: () => void;
+}
+/** 通用 HTTP 上传配置，支持业务接口、OSS 签名表单和预签名 PUT。 */
+interface UploadHttpRequest {
+    /** 上传地址；签名应由业务服务端生成。 */
+    action: string;
+    /** 请求方法，预签名二进制直传通常使用 PUT。 @defaultValue "POST" */
+    method?: "POST" | "PUT" | "PATCH";
+    /** form-data 为 multipart 表单，file 为 File 二进制。 @defaultValue "form-data" */
+    body?: "form-data" | "file";
+    /** multipart 文件字段名。 @defaultValue "file" */
+    name?: string;
+    /** multipart 额外字段，在文件之前添加，例如 key、policy、签名和令牌。 */
+    data?: Readonly<Record<string, string | Blob>>;
+    /** 自定义请求头，需与签名一致；multipart 不要手动设置 Content-Type。 */
+    headers?: Readonly<Record<string, string>>;
+    /** 是否携带跨域 Cookie。 @defaultValue false */
+    withCredentials?: boolean;
+    /** 超时毫秒数，0 为不设超时。 @defaultValue 0 */
+    timeout?: number;
+    /** 成功后写入文件记录的访问地址。 */
+    url?: string;
+}
+/** 文件列表变化的上下文。 */
 interface UploadChangeInfo {
-    /** 当前操作涉及的文件。 */
+    /** 本次变化的文件；移除时仍提供被移除的记录。 */
     file: UploadFile;
-    /** 受控的文件列表。 */
+    /** 最新完整列表，受控模式需回填给 fileList。 */
     fileList: readonly UploadFile[];
+    /** 触发原因：添加、开始、进度、成功、失败、移除或取消。 */
+    event: "add" | "start" | "progress" | "success" | "error" | "remove" | "cancel";
+}
+/** 类型或数量限制拒绝的文件。 */
+interface UploadRejectInfo {
+    /** 未加入列表的原始文件。 */
+    file: File;
+    /** accept 为类型不匹配，max-count 为达到数量上限。 */
+    reason: "accept" | "max-count";
+}
+/** 自定义列表项可调用的操作，仍遵循禁用、取消和 onRemove 规则。 */
+interface UploadItemActions {
+    /** 开始或重试当前文件；已上传成功或正在上传时不重复启动。 */
+    upload: () => Promise<void>;
+    /** 取消当前任务并回到 ready，保留文件。 */
+    abort: () => void;
+    /** 请求移除，等待 onRemove 允许后取消并删除。 */
+    remove: () => Promise<void>;
+    /** 触发自定义 onPreview，未提供时打开框架图片预览。 */
+    preview: () => void;
+}
+/** Upload 的命令式句柄，适用于手动上传及业务工具栏。 */
+interface UploadRef {
+    /** 开始 ready/error 文件；省略 uid 开始所有待上传项。Promise 在这些任务成功、失败或取消后完成，结果通过 onChange 通知。 */
+    upload: (uid?: string) => Promise<void>;
+    /** 取消指定文件，省略 uid 取消全部；保留记录为 ready，可再次 upload。 */
+    abort: (uid?: string) => void;
+    /** 请求移除指定文件；onRemove 拒绝时保留记录。 */
+    remove: (uid: string) => Promise<void>;
 }
-/** 文件上传的属性配置。 */
+/** 文件上传属性；未配置 request/customRequest 时仅选择文件，不模拟上传成功。 */
 interface UploadProps extends Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange"> {
-    /** 允许的文件类型，格式同原生 input 的 accept。 */
+    /** 扩展名或 MIME 类型，逗号分隔；点击、拖拽和粘贴均校验。 */
     accept?: string;
-    /**
-     是否允许同时选择多个项目。
-     * @defaultValue false
-     */
+    /** 每批是否允许多个文件；false 仅取首个，directory 模式不受此限制。 @defaultValue false */
     multiple?: boolean;
-    /**
-     * 是否允许选择文件夹。
-     * @defaultValue false
-     */
+    /** 选择或拖入文件夹，文件路径保存在 relativePath；不会上传空目录。 @defaultValue false */
     directory?: boolean;
-    /**
-     * 是否禁用交互。
-     * @defaultValue false
-     */
+    /** 是否包括子文件夹中的文件；false 仅处理根目录直接包含的文件。 @defaultValue true */
+    recursive?: boolean;
+    /** 聚焦本区域后允许粘贴文件或截图，不监听整个页面也不处理普通文本。 @defaultValue false */
+    pastable?: boolean;
+    /** 禁止添加、移除和启动上传；已在进行的请求不会自动取消。 @defaultValue false */
     disabled?: boolean;
-    /** 允许的最大文件数量。 */
+    /** 添加后自动上传；false 为手动模式，调用 ref.upload 或自定义列表操作启动。 @defaultValue true */
+    autoUpload?: boolean;
+    /** 最大文件数量，包含等待及失败项；超出部分拒绝，不替换已有文件。默认不限。 */
     maxCount?: number;
-    /** 受控的文件列表。 */
+    /** 受控列表，onChange 中回填；外部移除记录会取消关联请求。 */
     fileList?: readonly UploadFile[];
-    /**
-     * 非受控模式下的初始文件列表。
-     * @defaultValue []
-     */
+    /** 非受控初始列表，后续修改不重置列表。 @defaultValue [] */
     defaultFileList?: readonly UploadFile[];
-    /**
-     * 上传文件列表的展示形式。
-     * @defaultValue "text"
-     */
+    /** text 为文件列表，picture 为图片行，picture-card 为照片墙；照片墙满额隐藏添加入口。 @defaultValue "text" */
     listType?: "text" | "picture" | "picture-card";
-    /**
-     * 是否显示上传文件列表。
-     * @defaultValue true
-     */
+    /** 是否显示列表；隐藏时仍执行数量限制和变更通知。 @defaultValue true */
     showUploadList?: boolean;
-    /** 上传前校验或转换文件 */
-    beforeUpload?: (file: File, fileList: readonly File[]) => boolean | File | typeof LIST_IGNORE | Promise<boolean | File | typeof LIST_IGNORE>;
-    /** 自定义上传实现 */
-    customRequest?: (options: UploadRequestOptions) => void | {
-        /** 取消当前上传请求。 */
-        abort?: () => void;
-    };
-    /** 值发生变化时调用；参数为新值及类型声明中列出的关联信息。 */
+    /** 启动前校验，可异步；false 保留 ready，Upload.LIST_IGNORE 移除，File 转换本次上传内容；拒绝或抛错进入 error。手动上传时在调用 upload 后执行。 */
+    beforeUpload?: (file: File, fileList: readonly File[]) => boolean | File | symbol | Promise<boolean | File | symbol>;
+    /** HTTP 配置或逐文件异步签名函数，拒绝时进入 error；接收记录和取消信号。customRequest 优先。 */
+    request?: UploadHttpRequest | ((file: UploadFile, signal: AbortSignal) => UploadHttpRequest | Promise<UploadHttpRequest>);
+    /** 自定义上传，负责调用状态回调，可异步返回取消句柄；函数异常或 Promise 拒绝按失败处理。优先于 request。 */
+    customRequest?: (options: UploadRequestOptions) => void | UploadRequestHandle | Promise<void | UploadRequestHandle>;
+    /** 添加、开始、进度、完成、失败、取消和移除时调用；取消任务的迟到回调被忽略。 */
     onChange?: (info: UploadChangeInfo) => void;
-    /** 请求移除文件时调用；返回值控制是否允许移除。 */
-    onRemove?: (file: UploadFile) => boolean | Promise<boolean>;
-    /** 子内容；组件嵌套内容或当前节点的子项。 */
+    /** 移除前调用；false 或 Promise 拒绝阻止移除，否则取消任务并删除。 */
+    onRemove?: (file: UploadFile) => boolean | void | Promise<boolean | void>;
+    /** 文件类型不匹配或数量超限时调用，该文件不进入列表。 */
+    onReject?: (info: UploadRejectInfo) => void;
+    /** 拖拽目录读取失败时调用，本次批次不上传。 */
+    onReadError?: (error: unknown) => void;
+    /** 点击预览时调用，提供后完全接管预览，可实现 PDF、视频或业务弹窗。 */
+    onPreview?: (file: UploadFile) => void;
+    /** 完全自定义列表项；接收默认节点、记录、最新列表及操作句柄，应自行提供可访问的按钮。 */
+    itemRender?: (node: ReactNode, file: UploadFile, fileList: readonly UploadFile[], actions: UploadItemActions) => ReactNode;
+    /** 上传按钮内容，不应嵌套其他交互控件；外层负责点击和键盘操作。 */
     children?: ReactNode;
 }
-/** UploadDragger的属性配置。 */
+/** 拖拽区域继承全部 Upload 能力，ref 同样支持手动控制。 */
 interface UploadDraggerProps extends UploadProps {
-    /**
-     * 帮助或校验信息
-     * @defaultValue "支持单个或批量上传"
-     */
+    /** 辅助说明文字。 @defaultValue "支持单个或批量上传" */
     hint?: ReactNode;
 }
-declare function UploadRoot({ accept, multiple, directory, disabled, maxCount, fileList, defaultFileList, listType, showUploadList, beforeUpload, customRequest, onChange, onRemove, children, className, onDragOver, onDrop, ...props }: UploadProps): react.JSX.Element;
-declare function UploadDragger({ hint, children, className, ...props }: UploadDraggerProps): react.JSX.Element;
-/** 文件上传组件。 */
-declare const Upload: typeof UploadRoot & {
-    /** 支持拖入文件上传的区域组件。 */
-    Dragger: typeof UploadDragger;
-    /** beforeUpload 返回此标记时忽略该文件，不加入上传列表。 */
+
+/** 上传组件，支持图片列表、照片墙、目录、粘贴与完全受控请求；未配置请求时仅选择文件。 */
+declare const Upload: react.ForwardRefExoticComponent<UploadProps & react.RefAttributes<UploadRef>> & {
+    /** 可点击、键盘操作和拖拽的上传区域，ref 支持手动上传、取消及移除。 */
+    Dragger: react.ForwardRefExoticComponent<UploadDraggerProps & react.RefAttributes<UploadRef>>;
+    /** beforeUpload 返回时移除该文件，不进行上传。 */
     LIST_IGNORE: symbol;
 };
 
@@ -2169,4 +2229,4 @@ declare const FloatButton: react.ForwardRefExoticComponent<FloatButtonProps & re
     BackTop: typeof FloatButtonBackTop;
 };
 
-export { type MenuTheme as $, type FloatButtonGroupProps as A, type BadgeProps as B, Calendar as C, Dropdown as D, type FloatButtonProps as E, FILLED_ICON_NAMES as F, type FloatButtonShape as G, type FloatingPlacement as H, type FloatingTrigger as I, ICON_NAMES as J, Icon as K, type IconName as L, type IconProps as M, type IconVariant as N, Image as O, ImagePreview as P, type ImagePreviewConfig as Q, type ImagePreviewProps as R, type ImageProps as S, type TagStatus as T, Input as U, type InputProps as V, Menu as W, type MenuClickInfo as X, type MenuItem as Y, type MenuMode as Z, type MenuProps as _, Badge as a, type UploadRequestOptions as a$, type MessageConfig as a0, type MessageHandle as a1, type MessageKey as a2, type MessageType as a3, type NotificationConfig as a4, type NotificationPlacement as a5, type NotificationType as a6, Popconfirm as a7, type PopconfirmProps as a8, Popover as a9, Timeline as aA, type TimelineItem as aB, type TimelineProps as aC, Toolbar as aD, type ToolbarItem as aE, type ToolbarProps as aF, Tooltip as aG, type TooltipProps as aH, Tour as aI, type TourProps as aJ, type TourStep as aK, Tree as aL, type TreeDropPosition as aM, type TreeKey as aN, type TreeNode as aO, type TreeProps as aP, Typography as aQ, type TypographyLinkProps as aR, type TypographyProps as aS, type TypographyTitleProps as aT, type TypographyType as aU, Upload as aV, type UploadChangeInfo as aW, type UploadDraggerProps as aX, type UploadFile as aY, type UploadFileStatus as aZ, type UploadProps as a_, type PopoverProps as aa, Progress as ab, type ProgressProps as ac, type ProgressStatus as ad, Rate as ae, type RateProps as af, Segmented as ag, type SegmentedOption as ah, type SegmentedProps as ai, type SegmentedValue as aj, Spin as ak, type SpinProps as al, type StepItem as am, type StepStatus as an, Steps as ao, type StepsProps as ap, type TabItem as aq, Tabs as ar, type TabsContextMenuClickInfo as as, type TabsOrientation as at, type TabsPosition as au, type TabsProps as av, type TabsType as aw, Tag as ax, type TagProps as ay, type TagVariant as az, type BadgeRibbonProps as b, Watermark as b0, type WatermarkFont as b1, type WatermarkProps as b2, message as b3, notification as b4, type BadgeStatus as c, Breadcrumb as d, type BreadcrumbItem as e, type BreadcrumbProps as f, type CalendarProps as g, Card as h, type CardAccent as i, type CardProps as j, Carousel as k, type CarouselProps as l, type CarouselRef as m, Collapse as n, type CollapseItem as o, type CollapseKey as p, type CollapseProps as q, type DropdownButtonProps as r, type DropdownMenuProps as s, type DropdownOpenSource as t, type DropdownPlacement as u, type DropdownProps as v, type DropdownTrigger as w, type FilledIconName as x, FloatButton as y, type FloatButtonBackTopProps as z };
+export { type MenuTheme as $, type FloatButtonGroupProps as A, type BadgeProps as B, Calendar as C, Dropdown as D, type FloatButtonProps as E, FILLED_ICON_NAMES as F, type FloatButtonShape as G, type FloatingPlacement as H, type FloatingTrigger as I, ICON_NAMES as J, Icon as K, type IconName as L, type IconProps as M, type IconVariant as N, Image as O, ImagePreview as P, type ImagePreviewConfig as Q, type ImagePreviewProps as R, type ImageProps as S, type TagStatus as T, Input as U, type InputProps as V, Menu as W, type MenuClickInfo as X, type MenuItem as Y, type MenuMode as Z, type MenuProps as _, Badge as a, type UploadItemActions as a$, type MessageConfig as a0, type MessageHandle as a1, type MessageKey as a2, type MessageType as a3, type NotificationConfig as a4, type NotificationPlacement as a5, type NotificationType as a6, Popconfirm as a7, type PopconfirmProps as a8, Popover as a9, Timeline as aA, type TimelineItem as aB, type TimelineProps as aC, Toolbar as aD, type ToolbarItem as aE, type ToolbarProps as aF, Tooltip as aG, type TooltipProps as aH, Tour as aI, type TourProps as aJ, type TourStep as aK, Tree as aL, type TreeDropPosition as aM, type TreeKey as aN, type TreeNode as aO, type TreeProps as aP, Typography as aQ, type TypographyLinkProps as aR, type TypographyProps as aS, type TypographyTitleProps as aT, type TypographyType as aU, Upload as aV, type UploadChangeInfo as aW, type UploadDraggerProps as aX, type UploadFile as aY, type UploadFileStatus as aZ, type UploadHttpRequest as a_, type PopoverProps as aa, Progress as ab, type ProgressProps as ac, type ProgressStatus as ad, Rate as ae, type RateProps as af, Segmented as ag, type SegmentedOption as ah, type SegmentedProps as ai, type SegmentedValue as aj, Spin as ak, type SpinProps as al, type StepItem as am, type StepStatus as an, Steps as ao, type StepsProps as ap, type TabItem as aq, Tabs as ar, type TabsContextMenuClickInfo as as, type TabsOrientation as at, type TabsPosition as au, type TabsProps as av, type TabsType as aw, Tag as ax, type TagProps as ay, type TagVariant as az, type BadgeRibbonProps as b, type UploadProps as b0, type UploadRef as b1, type UploadRejectInfo as b2, type UploadRequestHandle as b3, type UploadRequestOptions as b4, Watermark as b5, type WatermarkFont as b6, type WatermarkProps as b7, message as b8, notification as b9, type BadgeStatus as c, Breadcrumb as d, type BreadcrumbItem as e, type BreadcrumbProps as f, type CalendarProps as g, Card as h, type CardAccent as i, type CardProps as j, Carousel as k, type CarouselProps as l, type CarouselRef as m, Collapse as n, type CollapseItem as o, type CollapseKey as p, type CollapseProps as q, type DropdownButtonProps as r, type DropdownMenuProps as s, type DropdownOpenSource as t, type DropdownPlacement as u, type DropdownProps as v, type DropdownTrigger as w, type FilledIconName as x, FloatButton as y, type FloatButtonBackTopProps as z };