syncfusion-blazor-file-manager

实现 Syncfusion Blazor FileManager

何时使用此技能

在需要以下功能时使用此技能：

• 创建文件管理界面 - 构建用于浏览、上传、下载和管理文件的 Web 应用
• 设置云存储集成 - 连接到 Azure Blob Storage、Amazon S3、Google Drive、SharePoint 或 Firebase
• 通过 Docker 部署统一的提供程序服务 - 运行整合 Azure Blob / Amazon S3 提供程序的镜像，并将 Blazor File Manager 指向该服务
• 实现文件操作 - 允许用户创建、删除、重命名、复制、移动和搜索文件及文件夹
• 处理大量文件 - 通过虚拟化和分页显示数千个文件
• 自定义 UI - 根据需求调整工具栏、上下文菜单、视图和导航
• 添加拖放功能 - 允许用户通过拖放上传或整理文件
• 构建无障碍文件系统 - 提供符合 WCAG 标准且支持键盘导航的文件管理
• 处理复杂工作流 - 实现自定义排序、筛选、预览和多提供程序场景

组件概述

Syncfusion Blazor FileManager 是一个全面的文件和文件夹管理组件，提供：

• 多种文件操作：读取、创建、删除、重命名、搜索、复制、移动、上传、下载、获取详细信息、GetSelectedFiles
• 灵活的数据绑定：AJAX 设置、列表对象或注入式服务
• 丰富的事件系统：20 多个事件，包括用于分页的 PageChanging/PageChanged
• 多种 UI 自定义选项：工具栏、上下文菜单、视图模式（Details、LargeIcons）、NavigationPaneTemplate
• 文件预览功能：通过 ShowThumbnail 属性显示图像和文件预览
• 云提供程序支持：物理文件、Azure、AWS S3、Google Drive、SharePoint、Firebase、SQL、FTP
• 高级功能：虚拟化、支持事件的分页、拖放、自定义筛选、排序、无障碍功能
• 布局管理：使用 RefreshLayoutAsync 动态调整大小并支持嵌套组件场景
• 高性能：通过虚拟化和延迟加载处理大量文件

文档和导航指南

入门

📄 阅读： references/getting-started.md

• Web App、Server App、WASM App 和 MAUI App 的安装
• NuGet 包设置和服务注册
• 基本组件初始化和 AJAX 配置
• 文件提供程序设置和 wwwroot 配置
• 5 分钟内创建第一个文件管理器实例

文件操作

📄 阅读： references/file-operations.md

• 11 项核心操作：读取、创建、删除、重命名、搜索、详细信息、复制、移动、上传、下载、GetImage
• 请求/响应数据结构和参数
• 文档中的操作代码示例
• 公共方法：DownloadFilesAsync(selectedItems)、GetSelectedFiles()
• 使用 ShowThumbnail 属性实现文件预览
• 使用 SortBy 和 SortOrder 属性进行排序

数据绑定模式

📄 阅读： references/data-binding.md

• 用于远程数据绑定的 AjaxSettings
• 使用本地数据和 OnRead 事件的列表对象
• 适用于复杂场景的注入式服务模式
• FileManagerDirectoryContent 结构
• 各种绑定方法的适用场景

事件和回调

📄 阅读： references/events-and-callbacks.md

• 20 多个文件管理器事件及其完整签名
• 事件生命周期和时序
• 常见事件处理程序模式
• BeforeDownload、BeforeImageLoad、OnFileOpen 事件
• ItemsDeleting、ItemsDeleted、FolderCreating、FolderCreated 事件
• Searching、Searched、ItemRenaming、ItemRenamed 事件

自定义和 UI

📄 阅读： references/customization.md

• 工具栏自定义和项目配置
• 上下文菜单自定义
• 视图模式：详细信息视图、大图标视图
• 使用 NavigationPaneTemplate 自定义导航项目
• 使用图标和元数据自定义导航窗格模板
• 样式和 CSS 自定义
• 外观和主题配置

文件提供程序和存储

📄 阅读： references/file-providers.md

• 物理文件提供程序（本地文件系统）
• Azure Blob Storage 配置
• Amazon S3 云提供程序
• Google Drive 集成
• SharePoint Online 提供程序
• Firebase 实时数据库
• SQL 数据库提供程序
• FTP（文件传输协议）提供程序

Docker 部署

📄 阅读： references/docker-deployment.md

• 适用于 Azure Blob Storage 和 Amazon S3 提供程序的统一 Docker 镜像
• 使用 FILEMANAGER_PROVIDER 环境变量切换后端
• 两种提供程序的 docker-compose.yml 配置
• 客户端 FileManagerAjaxSettings 与运行中的容器连接
• 存储、端口和 DNS 问题排查

上传和下载

📄 阅读： references/upload-download.md

• 文件上传配置和事件
• 目录上传（文件夹上传）
• 支持单个文件和 ZIP 的文件下载
• 大文件处理
• 上传进度跟踪
• 下载阻止和验证
• 用于自定义逻辑的 BeforeDownload 事件

高级功能

📄 阅读： references/advanced-features.md

• 大量文件集的虚拟化
• 使用 PageChanging 和 PageChanged 事件配置分页
• 拖放功能
• 限制拖放上传
• 自定义筛选和搜索
• 使用 RefreshLayoutAsync 方法处理嵌套项目
• 在对话框和容器中集成组件
• 无障碍功能（符合 WCAG 标准）
• 支持键盘导航
• 多文件选择

快速入门示例

@using Syncfusion.Blazor.FileManager

<SfFileManager TValue="FileManagerDirectoryContent">
    <FileManagerAjaxSettings Url="/api/FileManager/FileOperations"
                             UploadUrl="/api/FileManager/Upload"
                             DownloadUrl="/api/FileManager/Download"
                             GetImageUrl="/api/FileManager/GetImage">
    </FileManagerAjaxSettings>
</SfFileManager>

服务端设置（Program.cs）：

using Syncfusion.Blazor;

builder.Services.AddSyncfusionBlazor();
builder.Services.AddControllers();

app.UseRouting();
app.MapControllers();

HTML 设置（App.razor）：

<head>
    <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
</head>
<body>
    <script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>
</body>

常见模式

模式 1：使用 OnRead 事件的本地数据

<SfFileManager TValue="FileManagerDirectoryContent">
    <FileManagerEvents TValue="FileManagerDirectoryContent" OnRead="OnReadAsync"></FileManagerEvents>
</SfFileManager>

@code {
    private async Task OnReadAsync(ReadEventArgs<FileManagerDirectoryContent> args)
    {
        // Load data from your service
        var response = await YourService.GetFilesAsync(args.Path);
        args.Response = response;
    }
}

模式 2：使用 Azure 提供程序的云存储

<SfFileManager TValue="FileManagerDirectoryContent">
    <FileManagerAjaxSettings Url="/api/AzureProvider/FileOperations"
                             UploadUrl="/api/AzureProvider/Upload"
                             DownloadUrl="/api/AzureProvider/Download"
                             GetImageUrl="/api/AzureProvider/GetImage">
    </FileManagerAjaxSettings>
</SfFileManager>

模式 3：以编程方式下载

@ref="FileManager"

<SfButton OnClick="DownloadFiles">Download Selected</SfButton>
<SfFileManager @ref="FileManager" TValue="FileManagerDirectoryContent">
    
</SfFileManager>

@code {
    SfFileManager<FileManagerDirectoryContent> FileManager;
    
    public async Task DownloadFiles()
    {
        await FileManager.DownloadFilesAsync(FileManager.SelectedItems);
    }
}

模式 4：自定义事件处理

<SfFileManager TValue="FileManagerDirectoryContent">
    <FileManagerEvents TValue="FileManagerDirectoryContent" 
                       ItemsDeleting="OnItemsDeleting"
                       BeforeDownload="OnBeforeDownload">
    </FileManagerEvents>
</SfFileManager>

@code {
    public async Task OnItemsDeleting(ItemsDeleteEventArgs<FileManagerDirectoryContent> args)
    {
        // Validate before delete
        if (args.Files.Count > 10)
        {
            args.Cancel = true;
        }
    }

    public void OnBeforeDownload(BeforeDownloadEventArgs<FileManagerDirectoryContent> args)
    {
        // Custom download logic
    }
}

关键属性

属性	类型	默认值	用途
TValue	Generic	FileManagerDirectoryContent	数据模型类型
Url	string	-	文件操作的 AJAX 端点
UploadUrl	string	-	上传端点
DownloadUrl	string	-	下载端点
GetImageUrl	string	-	图片预览端点
SortBy	string	Name	排序字段（Name、Size、DateModified、DateCreated）
SortOrder	SortOrder	Ascending	排序方向（None、Ascending、Descending）
View	ViewType	LargeIcons	显示模式（Details、LargeIcons）
EnableVirtualization	bool	false	为大型数据集启用虚拟滚动
RootPath	string	-	根目录路径
ShowHiddenItems	bool	false	显示隐藏文件和文件夹
EnablePagination	bool	false	启用分页支持
PageSize	int	100	每页项目数
DirectoryUpload	bool	false	允许目录上传

常见用例

1. 内部文档管理

• 使用物理文件提供程序进行设置
• 使用工具栏执行 CRUD 操作
• 启用搜索和筛选
• 添加事件处理程序以记录审计日志

2. 基于云的团队协作

• 连接到 Azure 或 AWS S3
• 启用拖放上传
• 添加用于共享的自定义工具栏
• 通过事件实现访问控制

3. 媒体库

• 使用 GetImageUrl 启用图像预览
• 使用 LargeIcons 视图显示缩略图
• 实现分页以提升性能
• 按文件类型添加自定义筛选

4. 备份和归档系统

• 连接多个存储提供程序
• 启用压缩下载
• 对大型数据集使用虚拟化
• 添加自定义排序和筛选

5. 公共文件共享门户

• 通过事件处理程序限制操作
• 禁用删除和重命名
• 仅启用下载和预览
• 自定义导航和 UI

6. 容器化云存储后端

• 运行统一的 syncfusion/filemanager-provider Docker 镜像
• 使用 FILEMANAGER_PROVIDER 环境变量在 Azure Blob Storage 和 Amazon S3 之间切换
• 将 Blazor 客户端的 FileManagerAjaxSettings 指向容器的 API 端点

后续步骤

1. 选择设置方式：从适用于你平台的入门指南开始
2. 选择数据源：阅读数据绑定模式，选择 AJAX、本地数据或服务
3. 配置文件操作：查看文件操作，了解可用操作
4. 处理事件：查看事件和回调，了解所需的处理程序
5. 自定义 UI：参阅自定义，了解工具栏和主题
6. 选择存储方式：在文件提供程序中选择提供程序
7. 容器化后端：使用 Docker 部署部署统一的 Azure / S3 提供程序