syncfusion-aspnetcore-file-manager

实现 Syncfusion File Manager 组件

Syncfusion File Manager 是一款功能全面、可用于生产环境的组件，适用于 Web 应用中的文件浏览、管理和整理。它为用户提供类似资源管理器的界面，用于浏览文件系统、执行文件操作（创建、重命名、删除、复制、移动、上传、下载）、管理文件组织、搜索和筛选内容、控制访问权限，并通过虚拟化高效处理大型数据集。

何时使用此技能

文件浏览与导航

• 创建文件浏览器界面：通过大图标或详细列表视图显示文件夹层级结构
• 启用目录导航：支持面包屑导航、路径配置和后退导航
• 显示文件信息：显示文件名、大小、日期、类型和自定义属性
• 实现路径跟踪：维护并显示当前目录路径
• 支持文件预览：启用图像和文件预览功能

文件操作（CRUD）

• 创建文件夹：以编程方式创建新目录
• 读取和列出文件：显示目录内容，并支持筛选和排序
• 上传文件：支持单个、多个文件及目录上传，并跟踪进度
• 下载文件：支持下载单个和多个文件（支持 ZIP）
• 重命名文件/文件夹：更改名称，并进行验证和重复项处理
• 复制文件/文件夹：在不同位置之间复制文件
• 移动文件/文件夹：支持剪切和粘贴操作，并解决冲突
• 删除文件/文件夹：通过确认对话框移除项目
• 获取文件详情：检索详细的元数据和属性

文件整理与搜索

• 搜索文件：按名称查找项目，并可选择是否区分大小写
• 筛选内容：应用自定义筛选器，只显示匹配的项目
• 排序文件：按名称、大小、日期或自定义比较器排序
• 多选：使用 Ctrl+单击、Shift+单击和 Ctrl+A 选择多个项目
• 范围选择：拖动以选择多个连续项目
• 全选/清除选择：以编程方式控制选择

上传与拖放

• 文件上传：配置上传设置、允许的扩展名和文件大小限制
• 批量上传：按顺序或并行上传多个文件
• 分块上传：处理大文件，并支持暂停/恢复
• 目录上传：上传整个文件夹结构
• 拖放：接受来自外部来源的文件或文件管理器项目
• 上传进度：跟踪上传状态并向用户提供反馈

显示自定义

• 切换视图：在大图标视图和详细信息视图之间切换
• 自定义列：配置详细信息视图中的列（名称、大小、修改日期等）
• 自定义模板：为项目和导航窗格创建自定义渲染
• 显示缩略图：在大图标视图中显示图像预览
• 导航窗格：配置包含收藏夹文件夹和面包屑的侧边栏
• 自定义工具栏：添加、移除或自定义工具栏项目
• 上下文菜单：为文件、文件夹和布局配置上下文菜单

高级功能

• 虚拟化：通过虚拟滚动高效渲染大型文件列表
• 扁平数据结构：无需与服务端通信，即可从数组加载数据
• 状态持久化：跨会话记住用户偏好
• RTL 支持：为国际化应用支持从右向左的布局
• 本地化：支持多种语言和特定区域设置的格式
• 安全与权限：按角色或用户控制对文件夹和文件的访问
• 自定义身份验证：为请求添加标头、API 密钥或令牌

快速入门示例

控制器代码（FileManagerController.cs）

using Microsoft.AspNetCore.Mvc;
using Syncfusion.EJ2.FileManager;

public class FileManagerController : Controller
{
    public IActionResult Index()
    {
        return View();
    }
    
    [HttpPost]
    public IActionResult FileManager(string action, string path)
    {
        // Handle file operations based on action parameter
        if (action == "read")
        {
            // Return list of files and folders for the given path
            return Ok(new {
                cwd = new { name = "Root", hasChild = true, filterPath = "/" },
                files = new object[] { },
                error = (object)null,
                details = (object)null
            });
        }
        
        return Ok();
    }
}

Razor 视图（Index.cshtml）

<ejs-filemanager id="filemanager"
    path="/"
    width="100%"
    height="400px"
    allowDragAndDrop="true"
    allowMultiSelection="true"
    showThumbnail="true"
    enablePersistence="true">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager"
        downloadUrl="/FileManager/Download"
        uploadUrl="/FileManager/Upload"
        getImageUrl="/FileManager/GetImage">
    </e-filemanager-ajaxsettings>
</ejs-filemanager>

导航指南

根据实现需求，导航到相应的参考文件：

入门与设置

📄 阅读： references/getting-started.md

• 组件安装和包设置
• 基本初始化和渲染
• AJAX 端点配置
• 宽度和高度配置
• 视图选择（LargeIcons 与 Details）
• 初始路径配置
• 区域设置和 RTL 配置
• 状态持久化配置

文件操作（CRUD）

📄 阅读： references/file-operations.md

• 以编程方式创建新文件夹
• 重命名文件和文件夹
• 复制和粘贴操作
• 剪切和移动操作
• 删除文件和文件夹
• 获取文件/文件夹详情
• 请求和响应格式
• 错误处理和错误代码
• 最佳实践和模式

文件上传与拖放

📄 阅读： references/file-upload.md

• 上传设置配置
• 文件类型筛选（allowedExtensions）
• 文件大小限制（minFileSize、maxFileSize）
• 自动上传行为和手动上传
• 顺序上传与并行上传
• 大文件分块上传，支持暂停/恢复
• 目录（文件夹）上传支持
• 上传事件和处理程序
• 上传进度跟踪

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

• 启用拖放功能
• 放置区域配置
• 内部拖放（在文件管理器项目之间）
• 外部拖放（从桌面或外部来源）
• 拖动事件处理程序（fileDragStart、fileDragging、fileDragStop、fileDropped）
• 阻止浏览器默认行为
• 支持拖放多个文件
• 自定义拖放样式

显示视图与自定义

📄 阅读： references/views-overview.md

• 大图标视图（默认）
• 带可配置列的详细信息视图
• 动态切换视图
• 自定义大图标模板
• 配置详细信息视图中的列
• 缩略图显示设置
• 文件扩展名显示控制

📄 阅读： references/layouts-customization.md

• 导航窗格设置和可见性
• 面包屑导航和自定义
• 工具栏配置和可见性
• 布局响应式设置
• 基于模板的自定义（导航窗格、大图标）
• 移动视图优化
• 自定义导航项
• 显示/隐藏隐藏项
• 显示/隐藏文件扩展名

选择、搜索、排序与筛选

📄 阅读： references/selection-modes.md

• 多选（默认启用）
• 单选模式
• 使用鼠标拖动进行范围选择
• 基于复选框的选择
• 键盘快捷键（Ctrl+A、Ctrl+Click、Shift+Click）
• 选择事件（fileSelect、fileSelection）
• 程序化选择方法
• 清除选择功能

📄 阅读： references/search-sort-filter.md

• 搜索功能和设置
• 区分大小写的搜索选项
• 用户输入时实时搜索
• 按名称、修改日期、大小排序
• 自定义排序比较器
• 筛选类型（contains、startswith、endswith）
• 隐藏项可见性
• 文件扩展名显示

工具栏与上下文菜单自定义

📄 阅读： references/toolbar-customization.md

• 工具栏项配置
• 默认工具栏项列表
• 自定义工具栏项和操作
• 动态启用/禁用工具栏项
• 工具栏可见性设置
• 工具栏布局和样式
• 工具栏点击事件处理

📄 阅读： references/context-menu.md

• 文件、文件夹和布局的上下文菜单设置
• 默认上下文菜单项
• 动态启用/禁用菜单项
• 菜单项事件处理
• 自定义菜单项和操作
• 菜单可见性配置
• 菜单事件（menuOpen、menuClick、menuClose）

事件与方法

📄 阅读： references/file-events.md

• 文件操作事件：beforeDelete、delete、rename、folderCreate、beforeMove、move
• 选择事件：fileSelect、fileSelection
• 导航事件：fileOpen、fileLoad
• 上传事件：uploadListCreate、success、failure
• AJAX 事件：beforeSend、beforeDownload、beforeImageLoad
• 弹出窗口事件：popupOpen、beforePopupOpen、popupClose、beforePopupClose
• 工具栏/菜单事件：toolbarClick、toolbarCreate、menuClick、menuOpen、menuClose
• 搜索事件：search
• 组件生命周期：created、destroyed
• 事件处理程序模式与最佳实践

📄 阅读： references/programmatic-methods.md

• 选择方法：selectAll()、clearSelection()、getSelectedFiles()
• 文件操作方法：createFolder()、deleteFiles()、renameFile()、downloadFiles()
• 导航方法：openFile()、traverseBackward()、refreshFiles()、refreshLayout()
• 上传方法：uploadFiles()
• 对话框方法：closeDialog()
• 工具栏/菜单方法：disableToolbarItems()、enableToolbarItems()、disableMenuItems()、enableMenuItems()
• 筛选方法：filterFiles()
• 高级方法：getMenuItemIndex()、getToolbarItemIndex()
• 异步操作处理

性能与高级功能

📄 阅读： references/virtualization.md

• 大型文件列表的虚拟滚动
• 虚拟化配置
• 虚拟化限制与解决方法
• 大型数据集的性能优化
• 内存管理最佳实践
• 使用虚拟化时选择文件

📄 阅读： references/flat-data-customization.md

• 扁平数据结构与配置
• 无需与服务端通信即可加载数据
• 本地文件数组与 JSON 数据
• 扁平数据事件处理（创建、删除、重命名、移动）
• UI 自定义（扩展名、隐藏项、缩略图）
• 自定义文件提供程序实现
• 懒加载模式

安全与访问控制

📄 阅读： references/security-basics.md

• HTML 清理，防止 XSS 攻击
• 输入验证与错误处理
• 防止 SQL 注入
• 文件类型验证
• 常见安全漏洞
• 安全文件处理实践
• 基于权限的访问控制

📄 阅读： references/authentication-headers.md

• 为 AJAX 请求添加标头
• 使用 Before Send 事件设置自定义标头
• Bearer 令牌身份验证
• API 密钥身份验证
• 基本身份验证
• Before Download 事件处理
• Before Image Load 事件处理
• OAuth 令牌刷新模式
• 请求标头模式与示例

服务端集成

📄 阅读： references/server-integration.md

• ASP.NET Core 后端实现
• Node.js 后端实现
• 请求/响应模式与格式
• 分块上传请求
• 错误处理策略
• 可恢复上传模式
• 文件操作请求/响应结构

完整 API 参考

📄 阅读： references/api-complete-reference.md

• 所有属性：ajaxSettings、path、view、width、height 等 40 多项
• 所有方法：selectAll()、clearSelection()、createFolder()、deleteFiles()、renameFile()、downloadFiles() 等 15 多项
• 所有事件：beforeDelete、delete、fileSelect、beforeSend、beforeDownload、beforeImageLoad 等 20 多项
• 类型定义：FileData、AjaxSettingsModel、UploadSettingsModel 等
• 完整可运行示例：包含所有功能的完整实现

常见模式

模式 1：使用工具栏和上下文菜单的基本设置

视图代码（Index.cshtml）：

<ejs-filemanager id="filemanager"
    path="/"
    width="100%"
    height="400px">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager"
        uploadUrl="/FileManager/Upload"
        downloadUrl="/FileManager/Download"
        getImageUrl="/FileManager/GetImage">
    </e-filemanager-ajaxsettings>
    <e-filemanager-toolbarsettings items="@new string[] {'NewFolder', 'Upload', 'Cut', 'Copy', 'Paste', 'Delete', 'Download', 'Rename', 'Refresh'}">
    </e-filemanager-toolbarsettings>
    <e-filemanager-contextmenusettings file="@new string[] {'Open', 'Delete', 'Rename', 'Download', 'Details'}"
        folder="@new string[] {'Open', 'Delete', 'Rename', 'Download', 'Details'}"
        layout="@new string[] {'SortBy', 'View', 'Refresh', 'NewFolder', 'Upload'}">
    </e-filemanager-contextmenusettings>
</ejs-filemanager>

模式 2：带验证和限制的上传

视图代码（Index.cshtml）：

<ejs-filemanager id="filemanager" path="/">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager"
        uploadUrl="/FileManager/Upload">
    </e-filemanager-ajaxsettings>
    <e-filemanager-uploadsettings autoUpload="true"
        allowedExtensions=".jpg,.png,.pdf,.doc,.docx"
        minFileSize="1024"
        maxFileSize="5242880">
    </e-filemanager-uploadsettings>
</ejs-filemanager>

模式 3：使用自定义列的详细信息视图

视图代码（Index.cshtml）：

<ejs-filemanager id="filemanager" view="Details">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager">
    </e-filemanager-ajaxsettings>
    <e-filemanager-detailsviewsettings>
        <e-detailsviewsettings-columns>
            <e-detailsviewsettings-column field="name" headerText="Name" minWidth="150" width="200"></e-detailsviewsettings-column>
            <e-detailsviewsettings-column field="_fm_modified" headerText="Date Modified" type="dateTime" minWidth="120" width="150"></e-detailsviewsettings-column>
            <e-detailsviewsettings-column field="size" headerText="Size" minWidth="90" width="120"></e-detailsviewsettings-column>
        </e-detailsviewsettings-columns>
    </e-filemanager-detailsviewsettings>
</ejs-filemanager>

模式 4：以编程方式执行文件操作

视图代码（Index.cshtml）：

<button onclick="selectAllAndDelete()">Select All & Delete</button>

<ejs-filemanager id="filemanager">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager">
    </e-filemanager-ajaxsettings>
</ejs-filemanager>

<script>
    function selectAllAndDelete() {
        var filemanager = document.getElementById('filemanager').ej2_instances[0];
        filemanager.selectAll();
        var selected = filemanager.getSelectedFiles();
        var names = selected.map(function(f) { return f.name; });
        filemanager.deleteFiles(names);
    }
</script>

模式 5：实时筛选搜索

视图代码（Index.cshtml）：

<ejs-filemanager id="filemanager" search="onSearch">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager">
    </e-filemanager-ajaxsettings>
    <e-filemanager-searchsettings allowSearchOnTyping="true"
        filterType="Contains"
        ignoreCase="true">
    </e-filemanager-searchsettings>
</ejs-filemanager>

<script>
    function onSearch(args) {
        console.log('Search query:', args.searchString);
    }
</script>

模式 6：拖放上传

视图代码（Index.cshtml）：

<ejs-filemanager id="filemanager"
    allowDragAndDrop="true"
    fileDragStart="onFileDragStart"
    fileDragStop="onFileDragStop"
    fileDropped="onFileDropped">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager"
        uploadUrl="/FileManager/Upload">
    </e-filemanager-ajaxsettings>
    <e-filemanager-uploadsettings autoUpload="true"
        allowedExtensions=".jpg,.png,.pdf">
    </e-filemanager-uploadsettings>
</ejs-filemanager>

<script>
    function onFileDragStart(args) {
        console.log('Drag started:', args.fileDetails);
    }
    
    function onFileDragStop(args) {
        console.log('Drag stopped');
    }
    
    function onFileDropped(args) {
        console.log('File dropped:', args.fileDetails);
    }
</script>

模式 7：事件驱动的文件操作

视图代码（Index.cshtml）：

<ejs-filemanager id="filemanager"
    beforeDelete="beforeDelete"
    delete="onDelete"
    beforeSend="beforeSend">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager">
    </e-filemanager-ajaxsettings>
</ejs-filemanager>

<script>
    function beforeDelete(args) {
        console.log('Before delete:', args.fileDetails);
        // Validate or prevent deletion
        var isReadOnly = args.fileDetails.some(function(f) { return f.isReadOnly; });
        if (isReadOnly) {
            args.cancel = true;
        }
    }
    
    function onDelete(args) {
        console.log('File deleted:', args.fileDetails);
        // Update UI or log action
    }
    
    function beforeSend(args) {
        // Add custom headers
        args.ajaxSettings.headers = args.ajaxSettings.headers || {};
        args.ajaxSettings.headers['Authorization'] = 'Bearer ' + getToken();
    }
</script>

模式 8：针对大型数据集的虚拟滚动

视图代码（Index.cshtml）：

<ejs-filemanager id="filemanager"
    enableVirtualization="true"
    height="600px"
    width="100%">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager">
    </e-filemanager-ajaxsettings>
</ejs-filemanager>

模式 9：状态持久化

视图代码（Index.cshtml）：

<ejs-filemanager id="filemanager"
    enablePersistence="true">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager">
    </e-filemanager-ajaxsettings>
</ejs-filemanager>

模式 10：本地化与 RTL

视图代码（Index.cshtml）：

<ejs-filemanager id="filemanager"
    locale="ar-AE"
    enableRtl="true">
    <e-filemanager-ajaxsettings url="/FileManager/FileManager">
    </e-filemanager-ajaxsettings>
</ejs-filemanager>

关键属性摘要

基本配置：

• ajaxSettings - 服务器通信端点（url、uploadUrl、downloadUrl、getImageUrl）
• path - 当前目录路径
• width / height - 组件尺寸
• view - 显示模式（LargeIcons 或 Details）
• allowDragAndDrop - 启用拖放功能
• allowMultiSelection - 启用多选
• showThumbnail - 显示图像缩略图

上传设置：

• uploadSettings.autoUpload - 自动上传文件
• uploadSettings.allowedExtensions - 限制文件类型
• uploadSettings.maxFileSize - 最大文件大小限制
• uploadSettings.directoryUpload - 启用文件夹上传
• uploadSettings.sequentialUpload - 逐个上传文件

自定义：

• toolbarSettings - 配置工具栏项目及其可见性
• contextMenuSettings - 配置不同上下文的上下文菜单
• navigationPaneSettings - 配置左侧边栏
• detailsViewSettings - 配置详细信息视图中的列
• searchSettings - 配置搜索行为

高级设置：

• enableVirtualization - 优化大型列表的渲染
• enablePersistence - 记住用户偏好设置
• enableRtl - 支持从右向左的布局
• cssClass - 应用自定义 CSS 样式
• showFileExtension - 显示文件扩展名
• showHiddenItems - 显示/隐藏隐藏文件
• showItemCheckBoxes - 显示用于选择的复选框

常见使用场景

使用场景 1：文档管理系统

• 用户按文件夹浏览上传的文档
• 按元数据搜索和筛选文档
• 下载或预览文档
• 上传带有访问控制的新文档

使用场景 2：图像图库管理器

• 浏览带有缩略图预览的图像文件夹
• 通过拖放整理图像
• 重命名并整理图像集
• 将选中的图像下载为 ZIP 文件

使用场景 3：内容管理

• 管理网站内容文件夹
• 创建并整理文件夹层级
• 重命名和删除内容项目
• 控制用户对特定文件夹的访问权限

使用场景 4：云存储客户端

• 完整的文件管理操作
• 多文件上传并跟踪进度
• 跨会话保留用户偏好设置
• 同步状态

---