AtomUI/docs/Desktop.Controls/Upload/UploadAPI.md

Upload API 参考

命名空间

namespace AtomUI.Desktop.Controls;

AXAML 命名空间前缀：atom（xmlns:atom="https://atomui.net"）

---

枚举类型

UploadListType

上传列表展示类型枚举，控制文件列表的外观和布局。

值	说明
Text	文本列表，仅显示文件名、进度条和操作按钮
Picture	图片列表，在文本列表基础上增加缩略图预览
PictureCard	图片卡片墙，以卡片网格形式展示，触发按钮嵌入网格中
PictureCircle	圆形图片墙，与 PictureCard 类似但使用圆形展示

UploadPredicateResult

上传拦截结果枚举，用于 UploadTaskAboutToScheduling 事件中控制上传行为。

值	说明
Schedule	正常调度上传（默认值）
Cancel	取消上传，文件不显示在列表中（对标 Ant Design LIST_IGNORE）
CancelWithInTaskList	取消上传，但文件显示在列表中并标记为失败

FileUploadStatus（来自 AtomUI.Controls）

文件上传状态枚举，定义于设备无关层 AtomUI.Controls.Shared。

值	说明
Pending	等待调度
Uploading	上传中
Success	上传成功
Failed	上传失败
Cancelled	已取消

FileUploadErrorCode（来自 AtomUI.Controls）

文件上传错误码枚举，定义于设备无关层 AtomUI.Controls.Shared。

值	说明
None	无错误
NetworkError	网络连接/超时问题
ServerError	服务器 5xx 错误
ClientError	服务器 4xx 错误（如认证失败、参数错误）
FileError	本地文件错误（找不到、无权限）
ValidationFailed	验证失败（如文件类型、大小不符）
Cancelled	操作被取消
Unknown	未知错误

---

Upload 公共属性

StyledProperty

属性名	类型	默认值	说明
Accepts	IReadOnlyList<string>?	null	文件类型过滤列表，支持模式匹配（如 *.png、*.jpg），应用于文件选择对话框
ExtraContext	object?	null	附加上下文对象，随上传任务传递到 IFileUploadTransport.UploadAsync 的 context 参数
MaxCount	int	int.MaxValue	最大文件数量限制。1 时新文件替换旧文件，>1 时达上限后忽略新文件
IsUploadDirectoryEnabled	bool	false	是否启用目录上传模式（弹出文件夹选择对话框）
ListType	UploadListType	UploadListType.Text	文件列表展示类型
IsMultipleEnabled	bool	false	是否允许多选文件
IsOpenFileDialogOnClick	bool	true	点击触发区时是否打开文件选择对话框
IsShowUploadList	bool	true	是否显示文件列表
IsShowUploadTrigger	bool	true	是否显示上传触发区
DefaultTaskList	IList<UploadTaskInfo>?	null	默认文件列表，页面初始化时展示已有文件
MaxConcurrentTasks	int	3	最大并发上传任务数
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画（共享属性，通过 AddOwner 注册）

DirectProperty

属性名	类型	默认值	说明
UploadTransport	IFileUploadTransport?	null	上传传输实现，未设置时文件选择后不会启动上传
IsTaskRunning	bool	false	只读，是否有上传任务正在运行

公共集合属性

属性名	类型	说明
TaskInfoList	AvaloniaList<UploadTaskInfo>	当前文件列表（可观察集合），包含所有上传任务的信息

公共回调

属性名	类型	说明
IsImageFilePredicate	Func<UploadFileInfo, bool>?	自定义图片文件判断回调。未设置时使用内置的扩展名匹配（支持 .webp、.svg、.png、.gif、.jpg 等 12 种格式）

继承自 ContentControl 的常用属性

属性名	类型	默认值	说明
Content	object?	null	上传触发区内容（如 Button、UploadDefaultDropArea）
ContentTemplate	IDataTemplate?	null	内容模板
HorizontalContentAlignment	HorizontalAlignment	Left	触发区内容水平对齐
VerticalContentAlignment	VerticalAlignment	Center	触发区内容垂直对齐
IsEnabled	bool	true	是否启用

---

Upload 公共方法

方法名	返回类型	说明
ResetAsync()	Task	异步重置控件：取消所有正在进行的上传任务并清空文件列表
Reset()	void	同步版重置，内部调度到 UI 线程异步执行取消操作

---

Upload 事件

事件名	事件参数类型	说明
UploadTaskCreated	UploadTaskCreatedEventArgs	文件选择后、上传任务创建时触发
UploadTaskAboutToScheduling	UploadTaskAboutToSchedulingEventArgs	任务即将调度上传前触发，可通过设置 Result 属性拦截上传
UploadTaskProgress	UploadTaskProgressEventArgs	上传进度更新时触发
UploadTaskCompleted	UploadTaskCompletedEventArgs	上传成功完成时触发
UploadTaskFailed	UploadTaskFailedEventArgs	上传失败时触发
UploadTaskCancelled	UploadTaskCancelledEventArgs	上传被取消时触发
UploadTaskRemoved	UploadTaskRemovedEventArgs	文件从列表中移除时触发

事件参数详情

UploadTaskCreatedEventArgs

属性	类型	说明
TaskId	Guid	上传任务唯一标识
UploadFileInfo	UploadFileInfo	上传文件信息

UploadTaskAboutToSchedulingEventArgs

属性	类型	说明
TaskId	Guid	上传任务唯一标识
UploadFileInfo	UploadFileInfo	上传文件信息
Result	UploadPredicateResult	可设置的拦截结果（默认 Schedule）
CancelReason	string?	取消原因说明（设置 Result 为取消时使用）

UploadTaskProgressEventArgs

属性	类型	说明
TaskId	Guid	上传任务唯一标识
UploadFileInfo	UploadFileInfo	上传文件信息
Progress	double	上传进度百分比（0~100）

UploadTaskCompletedEventArgs

属性	类型	说明
TaskId	Guid	上传任务唯一标识
UploadFileInfo	UploadFileInfo	上传文件信息
Result	FileUploadResult	上传结果（包含远端 URL、文件 ID 等信息）

UploadTaskFailedEventArgs

属性	类型	说明
TaskId	Guid	上传任务唯一标识
UploadFileInfo	UploadFileInfo	上传文件信息
Result	FileUploadResult	失败结果（包含错误码和错误消息）

UploadTaskCancelledEventArgs

属性	类型	说明
TaskId	Guid	上传任务唯一标识
UploadFileInfo	UploadFileInfo	上传文件信息
Result	FileUploadResult	取消结果

UploadTaskRemovedEventArgs

属性	类型	说明
TaskId	Guid	上传任务唯一标识
UploadFileInfo	UploadFileInfo	上传文件信息

---

UploadTaskInfo 属性

UploadTaskInfo 继承自 AvaloniaObject，表示文件列表中每个上传任务的信息。

属性名	类型	说明
TaskId	Guid	上传任务唯一标识
FileName	string?	文件名
Progress	double	上传进度（0~100）
IsImageFile	bool	是否为图片文件
Status	FileUploadStatus	上传状态
ErrorMessage	string?	错误消息（失败时使用）
FilePath	Uri?	文件路径（本地路径或 avares:// 资源路径）

---

UploadDefaultDropArea 公共属性

UploadDefaultDropArea 是公共拖拽上传区域控件，可作为 Upload.Content 使用。

属性名	类型	默认值	说明
DropIcon	PathIcon?	InboxOutlined	拖拽区域图标
Header	object?	本地化字符串 DragUploadHead	拖拽区域主标题
HeaderTemplate	IDataTemplate?	null	主标题模板
SubHeader	object?	null	拖拽区域副标题
SubHeaderTemplate	IDataTemplate?	null	副标题模板
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画

UploadDefaultDropArea 事件

事件名	事件参数类型	说明
FilesDropped	UploadFilesDroppedEventArgs	文件拖放到区域时触发（冒泡路由事件）

UploadFilesDroppedEventArgs

属性	类型	说明
Files	IReadOnlyList<IStorageFile>	被拖放的文件列表

---

设备无关层类型（AtomUI.Controls.Shared）

IFileUploadTransport 接口

namespace AtomUI.Controls;

public interface IFileUploadTransport
{
    Task<FileUploadResult> UploadAsync(
        UploadFileInfo fileInfo,
        object? context = null,
        IProgress<FileUploadProgress>? progress = null,
        CancellationToken cancellationToken = default);
}

UploadFileInfo record

属性	类型	说明
Name	string	文件名
FilePath	Uri	文件路径
Size	long	文件大小（字节）
DateCreated	DateTimeOffset?	文件创建时间
DateModified	DateTimeOffset?	文件修改时间

FileUploadProgress record

属性	类型	说明
BytesSent	long	已发送字节数
TotalBytes	long	总字节数
Percentage	double	进度百分比（只读，自动计算）

FileUploadResult record

属性	类型	说明
Status	FileUploadStatus	上传最终状态
IsSuccess	bool	是否成功（只读便捷属性）
ErrorCode	FileUploadErrorCode	分类错误码
UserFriendlyMessage	string?	用户友好的错误消息
InternalErrorMessage	string?	内部错误信息（用于调试）
Exception	Exception?	关联的异常
RemoteUrl	Uri?	文件在服务器上的访问地址
FileId	string?	服务器返回的文件标识
FileHash	string?	ETag 或文件哈希
FileSize	long	文件大小（字节）
ElapsedTime	TimeSpan	上传耗时
AverageSpeed	double	平均上传速度（字节/秒，只读）
Metadata	Dictionary<string, object>?	服务器返回的自定义元数据

静态工厂方法：

方法	说明
SuccessResult(remoteUrl, fileSize, elapsedTime, ...)	创建成功结果
FailureResult(errorCode, userFriendlyMessage, ...)	创建失败结果
CancelledResult(userFriendlyMessage)	创建取消结果

---

实现的接口

IMotionAwareControl

public bool IsMotionEnabled { get; set; }

控制 Upload 及其子组件的过渡动画开关。

IFormItemAware

可作为 FormItem 的子控件参与表单验证流程。提供 ValueChanged 事件、SetFormValue / GetFormValue / ClearFormValue 方法。

注意：Upload 的表单值定义目前尚在开发中（源码中标注 TODO）。