syncfusion-aspnetcore-uploader

在 ASP.NET Core 中实现 Uploader

Uploader 是适用于 ASP.NET Core 的强大文件上传组件，可处理文件选择、验证、异步上传、拖放支持和进度跟踪。本技能将指导你使用 Syncfusion 的 TagHelper 语法，在 ASP.NET Core 应用程序中实现 Uploader。

何时使用此技能

在以下情况下使用此技能：

• 为图像、文档和媒体创建文件上传表单
• 实现带进度反馈的异步文件上传
• 在上传前验证文件类型和大小
• 支持拖放文件选择
• 同时处理多个文件上传
• 处理文件移除和清理
• 构建企业级文件管理界面
• 为大文件实现分块上传
• 将文件上传集成到 HTML 表单中
• 支持粘贴上传和目录上传
• 确保正确处理文件并保障安全

主要功能

功能	用例
异步上传	通过 SaveUrl/RemoveUrl 处理程序实现非阻塞上传
多文件上传	一次选择并上传多个文件
单文件上传	每次选择仅允许一个文件
文件验证	验证扩展名、大小、数量和重复文件
拖放	将文件直接拖放到上传区域
自定义拖放区域	将外部元素设为拖放区域
自动上传	自动或手动上传文件
进度跟踪	使用进度条显示上传进度
文件移除	通过 RemoveUrl 处理程序移除已上传的文件
分块上传	将大文件拆分为多个区块，以实现可靠上传
粘贴上传	从剪贴板上传图像
目录上传	上传整个文件夹及其目录结构
表单集成	将文件作为表单提交的一部分提交
模板	自定义文件列表和按钮的外观
本地化	支持多种语言和区域设置
错误处理	使用自定义消息显示上传失败

文档导航指南

入门

📄 阅读： references/getting-started.md

• 先决条件和系统要求
• 安装 Syncfusion.EJ2.AspNetCore NuGet 包
• 在 _ViewImports.cshtml 中配置 TagHelpers
• 通过 CDN 添加样式表和脚本资源
• 注册脚本管理器
• 创建首个 Uploader
• 基本配置和属性

异步上传

📄 阅读： references/async-upload.md

• 配置 SaveUrl 和 RemoveUrl 端点
• 单文件与多文件上传模式
• 自动上传设置和手动上传触发
• 成功和失败事件处理程序
• 进度跟踪和上传生命周期
• 处理上传取消

文件验证

📄 阅读： references/file-validation.md

• 使用 allowed-extensions 验证文件类型
• 文件大小限制（min-file-size、max-file-size）
• 最大文件数量限制
• 检测并阻止重复文件
• 自定义验证模式和错误消息
• 上传前和上传后的验证

拖放支持

📄 阅读： references/drag-drop-support.md

• 默认拖放行为
• 配置自定义拖放区域
• 在单个页面上设置多个拖放区域
• 拖放事件和事件处理
• 从剪贴板粘贴上传
• 支持拖放目录

模板和样式

📄 阅读： references/templates-and-styling.md

• 使用模板属性自定义 UI
• 自定义和排列按钮
• 渲染文件列表项
• 自定义 CSS 类
• 集成主题（Fluent、Material、Bootstrap）
• 响应式设计模式

高级模式

📄 阅读： references/advanced-patterns.md

• 大文件分块上传
• 带文件上传的表单提交
• 目录上传处理
• 文件移除和清理策略
• 高级错误处理
• 安全注意事项和 CORS

快速入门示例

使用异步上传的基本上传器（TagHelper）

<div class="form-group">
    <ejs-uploader id="uploader">
        <e-async-settings save-url="Home/Save" remove-url="Home/Remove"></e-async-settings>
        <e-upload-files></e-upload-files>
    </ejs-uploader>
</div>

<div id="uploadedFiles"></div>

在 HomeController.cs 中配置

using Microsoft.AspNetCore.Mvc;
using System.IO;

public class HomeController : Controller
{
    private readonly IWebHostEnvironment _webHostEnvironment;

    public HomeController(IWebHostEnvironment webHostEnvironment)
    {
        _webHostEnvironment = webHostEnvironment;
    }

    [HttpPost]
    public IActionResult Save(IFormFile[] uploader)
    {
        if (uploader != null && uploader.Length > 0)
        {
            string uploadPath = Path.Combine(_webHostEnvironment.WebRootPath, "Uploads");
            if (!Directory.Exists(uploadPath))
                Directory.CreateDirectory(uploadPath);

            foreach (IFormFile file in uploader)
            {
                string filePath = Path.Combine(uploadPath, file.FileName);
                using (FileStream fs = System.IO.File.Create(filePath))
                {
                    file.CopyTo(fs);
                    fs.Flush();
                }
            }
        }
        return Ok();
    }

    [HttpPost]
    public IActionResult Remove(string[] files)
    {
        string uploadPath = Path.Combine(_webHostEnvironment.WebRootPath, "Uploads");
        
        foreach (string file in files)
        {
            string filePath = Path.Combine(uploadPath, file);
            if (System.IO.File.Exists(filePath))
                System.IO.File.Delete(filePath);
        }
        return Ok();
    }
}

在 _ViewImports.cshtml 中配置（一次性设置）

@addTagHelper *, Syncfusion.EJ2

在 _Layout.cshtml 中配置（一次性设置）

W012 – 运行时远程代码依赖风险： 从外部 CDN 加载脚本和样式，意味着如果 CDN 文件遭到入侵或篡改，就会在用户的浏览器中执行。请采用以下两种方法之一来降低风险。

首选 – 自托管资源（完全消除运行时远程依赖）：

1. 将 ej2.min.js 和主题 CSS 从 NuGet 包或一次性 CDN 下载复制到 wwwroot/lib/syncfusion/。
2. 使用相对路径引用它们——由于文件由你自己的源站提供，因此不需要 integrity 属性。

替代方案 – 使用子资源完整性（SRI）的 CDN： 如果必须使用 CDN，请使用 integrity 哈希固定文件，以便浏览器拒绝任何被篡改的版本。使用 openssl dgst -sha384 -binary <file> | openssl base64 -A 计算哈希，并在每次升级版本时更新它。

选项 A — 自托管（推荐）

<head>
    
    <link rel="stylesheet" href="~/lib/syncfusion/fluent.css" />
</head>
<body>
    @RenderBody()

    <script src="~/lib/syncfusion/ej2.min.js"></script>
    <ejs-scripts></ejs-scripts>
</body>

选项 B — 使用 SRI 固定版本的 CDN

<head>
    
    <link rel="stylesheet"
          href="https://cdn.syncfusion.com/ej2/24.1.48/fluent.css"
          integrity="sha384-REPLACE_WITH_ACTUAL_HASH_FOR_fluent.css"
          crossorigin="anonymous" />
</head>
<body>
    @RenderBody()

    <script src="https://cdn.syncfusion.com/ej2/24.1.48/dist/ej2.min.js"
            integrity="sha384-REPLACE_WITH_ACTUAL_HASH_FOR_ej2.min.js"
            crossorigin="anonymous"></script>
    <ejs-scripts></ejs-scripts>
</body>

常见模式

模式 1：带进度显示的多文件上传

<ejs-uploader id="multiUploader"
    allowed-extensions=".jpg,.png,.pdf,.doc,.docx"
    max-file-size="5242880"
    auto-upload="false"
    multiple="true"
    uploading="onUploading"
    success="onSuccess"
    failure="onFailure">
    <e-async-settings save-url="Home/Save" remove-url="Home/Remove"></e-async-settings>
</ejs-uploader>

<script>
function onUploading(args) {
    console.log('Uploading: ' + args.file.name);
    console.log('Progress: ' + (args.percentComplete * 100) + '%');
}

function onSuccess(args) {
    if (args.operation === 'upload') {
        console.log(args.file.name + ' uploaded successfully');
    }
}

function onFailure(args) {
    console.log('Upload failed: ' + args.response);
}
</script>

模式 2：带验证的单文件上传

<ejs-uploader id="singleUploader"
    allowed-extensions=".jpg,.png,.jpeg"
    max-file-size="2097152"
    multiple="false"
    selected="onFileSelected"
    auto-upload="true">
    <e-async-settings save-url="Home/Save" remove-url="Home/Remove"></e-async-settings>
</ejs-uploader>

<script>
function onFileSelected(args) {
    if (args.filesData.length > 1) {
        args.filesData.splice(1);
        alert('Only one file can be selected');
    }
}
</script>

模式 3：带自定义区域的拖放

<div id="dropArea" style="border: 2px dashed #ccc; padding: 20px; min-height: 200px;">
    Drop files here
</div>

<ejs-uploader id="uploader"
    drop-area="#dropArea"
    auto-upload="true">
    <e-async-settings save-url="Home/Save" remove-url="Home/Remove"></e-async-settings>
</ejs-uploader>

关键属性

属性	类型	默认值	用途
allowed-extensions	string	""	允许的文件类型（例如，“.jpg,.png”）
max-file-size	long	28.4MB	文件大小上限，单位为字节
min-file-size	long	0	文件大小下限，单位为字节
multiple	bool	true	允许选择多个文件
auto-upload	bool	true	选择文件后自动上传
save-url	string	""	用于保存文件的 URL 处理程序
remove-url	string	""	用于移除文件的 URL 处理程序
drop-area	string	""	自定义拖放区域的 CSS 选择器

常见用例

用例 1：上传个人资料图片

• 单个文件，仅限图片，自动上传
• 参考：references/advanced-patterns.md

用例 2：文档管理

• 多个文件、验证，以及大文件分块上传
• 参考：references/async-upload.md

用例 3：批量导入

• 目录上传、表单提交、错误处理
• 参考：references/advanced-patterns.md

用例 4：媒体图库

• 多文件上传、自定义模板、拖放
• 参考：references/templates-and-styling.md

---

下一步： 阅读 references/getting-started.md，开始在 ASP.NET Core 应用程序中实现 Uploader。