ant-design-blazor Upload 组件 defaultFileList 预置已上传文件列表实战指南

UI组件前端【免费下载链接】ant-design-blazorA rich set of enterprise-class UI components based on Ant Design and Blazor.项目地址https://gitcode.com/gh_mirrors/an/ant-design-blazor点击查看免费下载本篇指南聚焦 ant-design-blazor Upload 组件的DefaultFileList参数讲解如何在页面初始化时预置已上传文件列表含成功、失败两种状态并结合仓库源码剖析UploadFileItem数据模型、列表渲染机制与底层上传流程帮助开发者快速实现编辑页回显历史附件这类典型场景。一、defaultFileList 解决什么问题在真实业务中文件上传组件并非总是从空列表开始。最常见的场景是编辑/详情页面用户重新打开一条数据时表单里应直接展示该数据此前已上传的文件如历史图片、附件而不是让用户重新上传一遍。ant-design-blazor 的 Upload 组件为此提供了两个参数DefaultFileList非受控的预置文件列表只在组件初始化时生效一次用于页面初始化即展示已上传内容这正是本 Demo 的核心FileList受控的文件列表由开发者完全掌握列表的增删改适合需要动态限制数量、自定义排序等场景对应 fileList.md 演示。官方 Demo defaultFileList.md 的说明非常简洁使用defaultFileList设置已上传的内容。下面我们围绕这句话展开完整的实战讲解。二、完整可运行示例预置成功与失败的文件仓库中的示例实现位于 DefaultFileList.razor核心代码如下inject IMessageService _message Upload attributesattrs OnSingleCompletedOnSingleCompleted Button Iconupload spanUpload/span /Button /Upload code { Upload upload; Dictionarystring, object attrs new Dictionarystring, object { { Action, https://www.mocky.io/v2/5cc8019d300000980a055e76 }, { Name, files }, { DefaultFileList, new ListUploadFileItem { new UploadFileItem { Id 1, FileName 1.jpg, Url https://www.baidu.com/1.jpg, State UploadState.Success }, new UploadFileItem { Id 2, FileName 2.jpg, Response 网络错误, State UploadState.Fail } } } }; void OnSingleCompleted(UploadInfo fileinfo) { if (fileinfo.File.State UploadState.Success) { var result fileinfo.File.GetResponseResponseModel(); fileinfo.File.Url result.url; } } public class ResponseModel { public string name { get; set; } public string status { get; set; } public string url { get; set; } public string thumbUrl { get; set; } } }这段代码展示了两类最常见的预置文件形态文件项关键字段页面呈现效果1.jpgState UploadState.SuccessUrl指向远程地址展示为已成功上传的文件名称可点击跳转2.jpgState UploadState.FailResponse 网络错误展示为上传失败的文件鼠标悬停时通过 Tooltip 显示错误信息注意示例通过attributesattrs把参数以字典方式批量传入组件这是 Demo 的书写习惯在实际业务代码中完全可以直接使用强类型属性写法例如Upload Actionhttps://www.mocky.io/v2/5cc8019d300000980a055e76 Namefiles DefaultFileListdefaultFiles OnSingleCompletedOnSingleCompleted Button Iconupload spanUpload/span /Button /Upload三、UploadFileItem预置列表的数据模型DefaultFileList的类型是ListUploadFileItem每个文件项都通过 UploadFileItem 类描述。其完整字段如下属性类型说明预置列表中的典型用法Idstring文件唯一标识GUID手动指定任意字符串即可用于列表渲染时的key与回调定位FileNamestring文件名必填列表展示名称图片类文件还可用于推导扩展名Percentint已上传百分比预置项可留默认值 0渲染时仅在Uploading状态展示进度条ObjectURLstring文件对象 URL图片本地预览地址浏览器URL.createObjectURL生成预置远端文件时一般不需要Urlstring文件实际 URL成功文件的下载/预览跳转地址Responsestring服务端响应原文失败项可放入错误信息文本会被用作 Tooltip 内容StateUploadState上传状态预置时必须显式赋值见下文状态说明Sizelong文件大小字节可选Extstring文件扩展名可选不填时由IsPicture()从FileName自动推导Typestring文件 MIME 类型可选其中UploadState枚举定义在 UploadState.cs共有四种状态public enum UploadState { Success 0, // 上传成功 Fail, // 上传失败 Uploading, // 上传中 Waiting // 等待中Defer 手动上传模式下尚未开始 }在预置列表中开发者最常使用的是Success与Fail两种状态——它们分别对应历史已成功文件回显与历史失败记录保留提示。图片文件扩展名推导UploadFileItem内置了IsPicture()方法UploadFileItem.cs用于判断文件是否为图片若Ext为空会从FileName中截取最后一个.之后的子串并与静态集合ImageExtensions.jpg/.png/.gif/.ico/.jpeg/.bmp/.tga/.svg/.tif/.webp等比对。预置.jpg图片时无需手动设置Ext渲染层会自动识别并展示缩略图。四、状态如何驱动列表渲染源码级解析预置列表最终通过 Upload.razor 渲染。组件的渲染逻辑对每种状态做了差异化处理Success文件名以链接形式呈现href 取Url为空时回退到ObjectURL添加ant-upload-list-item-done样式类在PictureCard列表类型下会展示缩略图img src(file.ObjectURL ?? file.Url) /。Fail渲染ant-upload-list-item-error样式类并使用Tooltip展示提示文本——提示内容优先取Response属性为空时才使用本地化文案Locale.UploadError参见 Upload.razor。Uploading渲染 loading 图标与Progress进度条进度值来自file.Percent。Waiting仅在Defer手动上传模式下出现若ListType为图片类且设置了ObjectURL会先渲染本地预览缩略图。这就是为什么在示例中给失败项设置Response 网络错误后鼠标悬停即可看到错误提示——状态与文案完全由UploadFileItem的属性驱动无需额外模板代码。五、初始化时机DefaultFileList 如何并入列表从源码看DefaultFileList是一个独立参数Upload.razor.cs其初始化逻辑位于OnInitialized生命周期中protected override void OnInitialized() { base.OnInitialized(); // ...ClassMapper 初始化... FileList.InsertRange(0, DefaultFileList); }见 Upload.razor.cs这段代码揭示了两个关键点预置项会被整体插入FileList的头部索引 0 处随后列表渲染统一以FileList为准DefaultFileList只在OnInitialized执行一次属于非受控初始值。之后页面上的增删、上传进度更新都作用在FileList上不会再反向写入DefaultFileList。因此若业务需要在运行过程中动态控制列表如限制数量、根据响应改写 URL应当切换到受控参数FileListFileListChanged事件若只是想在页面打开时自带几个历史文件DefaultFileList是最简方案。六、与受控 FileList 的对比选型仓库中的 FileList.razor 演示了完全控制列表的场景对应说明文档 fileList.md两种模式的差异可总结为维度DefaultFileListFileList控制方式非受控仅初始化生效受控开发者全权管理典型场景页面回显历史附件限制上传数量、自定义列表逻辑变更通知无FileListChanged事件与渲染的关系初始化时被插入 FileList 头部直接决定渲染内容比如只保留最近 2 个文件的逻辑在受控模式下只需在OnChange回调中裁剪列表void HandleChange(UploadInfo fileinfo) { if (fileList.Count 2) { fileList.RemoveRange(0, fileList.Count - 2); } }七、进阶实战解析服务端响应并回填 Url示例中的OnSingleCompleted展示了一个高频需求——上传成功后用服务端返回的地址更新文件链接void OnSingleCompleted(UploadInfo fileinfo) { if (fileinfo.File.State UploadState.Success) { var result fileinfo.File.GetResponseResponseModel(); fileinfo.File.Url result.url; } }OnSingleCompleted回调参数类型为 UploadInfo包含当前操作的文件File与当前完整列表FileList。其中GetResponseTResponseModel()是UploadFileItem内置的反序列化方法UploadFileItem.cs内部使用System.Text.Json将Response字符串解析为强类型模型——这正是示例中定义ResponseModel含name、status、url、thumbUrl四个属性的原因。从调用链看服务端响应回填的完整流程是浏览器端 JS 通过XMLHttpRequest发起FormData上传并监听进度uploadHelper.ts请求完成后 JS 调用 .NET 侧[JSInvokable]方法UploadSuccess/UploadErrorUploadButton.razor.cs把Response写入文件项并触发回调OnSingleCompleted拿到UploadInfo后即可按需解析Response、改写Url等属性。值得注意的是服务端返回的 2xx 状态码均视为成功非 2xx 则进入失败分支并保留原始响应文本见 uploadHelper.ts。八、FAQ 要点下载链接与防伪令牌关于预置列表的展示组件官方 FAQfaq.zh-CN.md中有两点与本文主题直接相关1. 如何显示下载链接请设置fileList中每一项的属性url来控制链接的内容。这正是预置成功文件时设置Url的意义所在——列表中文件名的链接地址完全由Url决定。2. 服务端开启了 Antiforgery 验证怎么办Upload 组件在 JS 层会自动查找页面中的input typehidden name__RequestVerificationToken value...token... /并将其追加到上传的FormData中uploadHelper.ts。在 Blazor Server 中使用时需在静态App.razor中添加AntiforgeryToken /组件若通过 Ajax 方式获取令牌则通过Data或Headers参数手动携带。九、实践小结预置历史文件给Upload传DefaultFileListListUploadFileItem每项至少设置FileName与State成功项补充Url失败项可补充Response作为错误提示。状态驱动渲染Success展示可点击链接、Fail展示红色错误态与 Tooltip、Uploading展示进度条全部由 Upload.razor 自动完成。非受控特性DefaultFileList仅在初始化时合并进FileList头部运行期变更请改用受控的FileList。响应回填借助GetResponseT()可在OnSingleCompleted中解析服务端响应并动态设置Url实现上传即预览/可下载的闭环体验。赞分享UI组件前端【免费下载链接】ant-design-blazorA rich set of enterprise-class UI components based on Ant Design and Blazor.项目地址https://gitcode.com/gh_mirrors/an/ant-design-blazor点击查看免费下载相关推荐ant-design-blazor Upload 组件 defaultFileList 详解页面初始化时展示已上传文件列表ant design blazor Upload 组件 defaultFileList 详解页面初始化时展示已上传文件列表 导读 在 ant design b前端UI组件设计系统ant-design-blazor Upload 组件文件夹上传Upload directory实战指南ant design blazor Upload 组件文件夹上传Upload directory实战指南 导读 本文围绕 ant design blazor前端UI组件设计系统Pixelle-VideoAI 短视频自动生成如何 5 分钟出一条带解说的视频Pixelle VideoAI 短视频自动生成如何 5 分钟出一条带解说的视频 周五下午三点周一的评审会需要一段一分钟的产品介绍视频。按传统流程写文案、找人工智能AI 应用音视频媒体生成上一篇终极OSINT工具apk2url快速从APK中提取IP和URL端点的完整指南下一篇Tendis与Redis Cluster对比分析性能、成本与适用场景深度评测创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考