syncfusion-react-file-manager

Syncfusion React 文件管理器

一份全面的指南，介绍如何实现 Syncfusion React 文件管理器组件，以构建具备丰富功能的文件系统界面，例如拖放、多视图支持、自定义操作和完整的无障碍功能。

快速导航

🚀 刚开始使用？
→ 阅读入门，了解安装和基本设置

🛠️ 需要 Docker / 云后端？
→ 查看 Docker 部署，了解如何通过统一的提供程序镜像使用 Azure Blob Storage 和 Amazon S3

🛠️ 需要构建文件操作？
→ 查看文件操作（CRUD），了解创建、读取、更新和删除模式

📊 使用本地数据？
→ 查看扁平数据结构，了解内存中的文件和事件驱动操作

✅ 需要选择多个文件？
→ 阅读多选与范围选择，了解 Ctrl+单击、Shift+单击和拖动选择

⚡ 需要处理大型文件列表？
→ 使用虚拟化，实现 1000+ 个文件的流畅滚动

🎨 想要自定义 UI？
→ 查看自定义与样式，了解主题和布局选项

⚙️ 查找高级功能？
→ 探索高级功能，了解性能、自定义提供程序和 API 集成

♿ 需要无障碍功能或多语言支持？
→ 查看无障碍功能与本地化，了解 WCAG 和 i18n

🔐 需要用户访问控制？
→ 阅读访问控制，了解基于角色的权限和安全性

📤 需要向服务传递自定义请求头？
→ 查看向服务传递自定义值，了解 setRequestHeader 和身份验证

🎯 需要高级自定义？
→ 查看向上下文菜单添加自定义项和向工具栏添加自定义项

🔧 想要启用/禁用工具栏项？
→ 查看启用/禁用工具栏项，了解程序化控制

🖼️ 自定义缩略图和图标？
→ 阅读自定义缩略图，了解图标模板

📁 自定义导航窗格？
→ 查看自定义导航窗格，了解树视图自定义

✨ 预先选择项？
→ 阅读预选项，了解默认选择

📦 在对话框/标签页中使用文件管理器？
→ 查看嵌套项，了解如何嵌入其他组件

何时使用此技能

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

• 为应用创建文件浏览器界面
• 实现文件上传和下载功能
• 构建文件管理功能（创建、删除、重命名、刷新）
• 支持多种视图选项（详细信息和大图标）
• 为文件管理添加拖放功能
• 自定义上下文菜单、工具栏和样式
• 集成无障碍功能（键盘导航、ARIA）
• 支持国际化和 RTL 语言
• 连接到本地或远程文件系统
• 通过统一的 Syncfusion Docker 提供程序镜像部署托管文件服务
• 通过容器环境变量使用 Azure Blob Storage 或 Amazon S3 作为后端

组件概览

文件管理器 是用于管理文件系统的图形用户界面组件。它支持用户：

• 文件操作： 读取、创建、删除、重命名、上传、下载和刷新文件
• 多种视图： 在详细信息视图（排序列表）和大图标视图（缩略图）之间切换
• 导航： 使用面包屑导航路径和带树状视图的导航窗格浏览层级结构
• 上下文菜单： 提供可自定义选项的右键菜单
• 拖放： 使用可配置的放置区域在文件夹之间拖动文件
• 无障碍： 完全符合 WCAG 标准，支持键盘导航和屏幕阅读器
• 本地化： 支持多种语言，并为从右向左书写的语言提供 RTL 方向支持
• 自定义： 提供丰富的 API，用于自定义样式、主题和行为

文档与导航指南

核心功能

入门与安装

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 基本文件管理器实现
• CSS 导入和主题配置
• 初始配置和设置
• 连接到文件服务（AjaxSettings）

Docker 部署

📄 阅读： references/docker-deployment.md

• 统一的 Syncfusion 文件管理器提供程序 Docker 镜像
• Azure Blob Storage 提供程序配置
• Amazon S3 提供程序配置
• docker-compose 设置和环境变量
• 为托管服务配置客户端 ajaxSettings
• 常见服务和 DNS 错误的故障排除

文件操作（CRUD）

📄 阅读： references/file-operations.md

• 创建文件夹和文件
• 读取和浏览文件系统
• 更新／重命名操作
• 删除文件和文件夹
• 上传和下载功能
• 多文件选择和批量操作
• 文件提供程序模式和自定义实现

视图与导航

📄 阅读： references/views-and-navigation.md

• 带列的详细信息视图
• 带缩略图的大图标视图
• 视图切换和配置
• 面包屑导航控件
• 导航窗格（树状视图侧边栏）
• 工具栏功能和布局

数据管理

扁平数据结构

📄 阅读： references/flat-data.md

• 使用本地 JSON 数据代替服务器调用
• FileData 接口及属性
• 按项目管理权限
• 由事件驱动的文件操作（创建、删除、重命名、搜索）
• 使用 React hooks 管理状态
• 后端同步模式
• 大型数据集的性能优化

多选与范围选择

📄 阅读： references/multiple-selection.md

• 启用／禁用多选功能
• 通过鼠标拖动进行范围选择
• 支持复选框选择
• 选择状态管理
• 所选项目 API 和事件
• 加载时预先选择项目
• 键盘快捷键（Ctrl+A、Shift+Click）

预先选择项目

📄 阅读： references/preselect-the-items.md

• 以编程方式在加载时选择项目
• 根据文件类型、大小或日期预先选择
• 上下文感知的预选
• 选择方法（selectAll、clearSelection）
• 以编程方式获取所选项目

性能与优化

虚拟化与性能

📄 阅读： references/virtualization.md

• 为大型数据集启用虚拟滚动
• 动态加载文件和文件夹
• 基于视口优化渲染
• 模块注入和设置
• 性能限制和解决方法
• 处理 1000+ 个项目的最佳实践

用户交互

拖放功能

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

• 启用／禁用拖放功能
• 放置区域配置
• 事件处理（fileDragStart、fileDragStop、fileDropped）
• 跨文件夹拖放
• 自定义拖放行为

自定义与样式

📄 阅读： references/customization.md

• 自定义上下文菜单
• 自定义工具栏
• 自定义详细信息视图列
• 自定义导航窗格
• 自定义工具提示
• 显示/隐藏文件扩展名和隐藏文件
• 配置大图标视图的缩略图
• 自定义 CSS 类和主题

高级自定义

向上下文菜单添加自定义项

📄 阅读： references/adding-custom-item-to-context-menu.md

• 向上下文菜单添加自定义菜单项
• 为菜单项添加图标
• 处理菜单点击事件
• 根据文件属性设置条件菜单项
• 动态自定义菜单

向工具栏添加自定义项

📄 阅读： references/adding-custom-item-to-toolbar.md

• 修改默认工具栏项
• 添加自定义工具栏项
• 为工具栏使用自定义模板
• 处理工具栏点击
• 自定义按钮、复选框和下拉菜单

启用/禁用工具栏项

📄 阅读： references/enable-disable-toolbar-item.md

• 以编程方式启用/禁用工具栏项
• 根据选择内容启用/禁用
• 基于角色控制工具栏
• 操作期间禁用
• 基于权限控制工具栏

自定义缩略图

📄 阅读： references/customize-custom-thumbnail.md

• 隐藏/显示缩略图
• 为大图标视图使用自定义模板
• 根据文件类型显示图标
• 根据大小进行颜色编码
• 根据日期显示图标指示器

自定义导航窗格

📄 阅读： references/customize-navigation-items.md

• 控制导航窗格的可见性和宽度
• 为导航节点使用自定义模板
• 添加文件数量和元数据
• 为文件夹设置颜色编码
• 自定义基于图标的导航样式
• 响应式导航窗格

嵌套项

📄 阅读： references/nested-items.md

• 在对话框中嵌入文件管理器
• 在选项卡中嵌入文件管理器
• 在分隔器中嵌入文件管理器
• 使用文件管理器选择文件
• 使用文件管理器创建多面板布局

安全与集成

访问控制

📄 阅读： references/access-control.md

• 为文件夹/文件定义访问权限
• 权限类型（允许/拒绝）
• 基于角色的访问控制
• 为不同用户角色设置访问规则
• 后端权限验证

向服务端传递自定义值

📄 阅读： references/pass-custom-value-to-server.md

• 使用 setRequestHeader 设置自定义 HTTP 标头
• 用户身份验证标头
• 用户标识标头
• 跟踪文件操作
• 基于部门的访问控制
• 自定义下载操作
• 自定义图像加载
• 完整的服务端集成模式

无障碍访问与本地化

无障碍访问与本地化

📄 阅读： references/accessibility-localization.md

• 符合 WCAG 2.1 标准
• 键盘导航（方向键、回车键、删除键）
• ARIA 属性和角色
• 屏幕阅读器支持
• 国际化（i18n）
• 从右向左（RTL）支持
• 针对不同区域设置日期和数字格式

高级功能

高级功能

📄 阅读： references/advanced-features.md

• 自定义文件系统提供程序的实现
• API 集成模式
• 性能优化技巧
• 错误处理和边缘情况
• 事件系统和钩子
• 高级搜索和筛选
• 自定义排序和比较
• 嵌套组件（在对话框/选项卡中嵌入文件管理器）

快速入门示例

安装 Tailwind3 主题包和文件管理器：

npm install @syncfusion/ej2-react-filemanager
npm install @syncfusion/ej2-tailwind3-theme

在 src/App.css 中添加主题导入：

/* src/App.css */
@import "../node_modules/@syncfusion/ej2-tailwind3-theme/styles/file-manager/index.css";

在 src/App.tsx 中导入 App.css 和组件：

import React from 'react';
import { FileManagerComponent, Inject, DetailsView, NavigationPane, Toolbar } from '@syncfusion/ej2-react-filemanager';
import './App.css';

function App() {
  const hostUrl = "url";

  return (
    <div>
      <FileManagerComponent
        id="file"
        ajaxSettings={{
          url: hostUrl + "api/FileManager/FileOperations",
          getImageUrl: hostUrl + "api/FileManager/GetImage",
          uploadUrl: hostUrl + "api/FileManager/Upload",
          downloadUrl: hostUrl + "api/FileManager/Download"
        }}
        view="Details"
        height="375px"
      >
        <Inject services={[DetailsView, NavigationPane, Toolbar]} />
      </FileManagerComponent>
    </div>
  );
}

export default App;

方法参考

文件管理器提供用于控制操作的编程方法：

选择和视图控制

方法	参数	用途
selectAll()	-	选择当前路径中的所有文件和文件夹
clearSelection()	-	取消选择所有项目
getSelectedFiles()	-	获取所选文件对象的数组

文件操作

方法	参数	用途
createFolder(name?)	name: string（可选）	创建新文件夹；未提供名称时打开对话框
renameFile(id?, name?)	id: string, name: string	重命名文件或文件夹；未提供参数时打开对话框
deleteFiles(ids?)	ids: string[]	删除文件或文件夹；未提供参数时打开确认对话框
openFile(id)	id: string	打开文件或导航至文件夹
downloadFiles(ids?)	ids: string[]（可选）	下载所选文件；未提供参数时下载当前选择
uploadFiles()	-	打开文件上传对话框

导航和刷新

方法	参数	用途
refreshFiles()	-	刷新当前文件夹内容
refreshLayout()	-	刷新组件布局
traverseBackward()	-	导航至上级目录
filterFiles(filterData?)	filterData: Object	对显示的文件应用自定义筛选条件

工具栏和菜单控制

方法	参数	用途
disableToolbarItems(items)	items: string[]	禁用指定的工具栏按钮
enableToolbarItems(items)	items: string[]	启用指定的工具栏按钮
getToolbarItemIndex(item)	item: string	获取工具栏项目的位置
disableMenuItems(items)	items: string[]	禁用指定的上下文菜单项目
enableMenuItems(items)	items: string[]	启用指定的上下文菜单项目
getMenuItemIndex(item)	item: string	获取上下文菜单项目的位置

对话框控制

方法	参数	用途
closeDialog()	-	关闭所有已打开的对话框

组件生命周期

方法	参数	用途
destroy()	-	清理组件资源

事件参考

文件管理器提供全面的事件钩子，便于自定义：

文件选择事件

事件	参数	触发时机
fileSelection	FileSelectionEventArgs	即将选择文件或文件夹时（可取消）
fileSelect	FileSelectEventArgs	选择或取消选择文件或文件夹时

文件导航事件

事件	参数	触发时机
fileOpen	FileOpenEventArgs	即将打开文件或文件夹时
fileLoad	FileLoadEventArgs	渲染文件或文件夹项目时

文件操作事件

事件	参数	触发时机
beforeFolderCreate	FolderCreateEventArgs	请求创建文件夹时（可取消）
folderCreate	FolderCreateEventArgs	成功创建文件夹时
beforeRename	RenameEventArgs	请求执行重命名操作时（可取消）
rename	RenameEventArgs	成功重命名文件或文件夹时
beforeDelete	DeleteEventArgs	请求删除时（可取消）
delete	DeleteEventArgs	成功删除文件或文件夹时
beforeMove	MoveEventArgs	开始移动或复制操作时
move	MoveEventArgs	成功移动或复制文件或文件夹时

拖放事件

事件	参数	触发时机
fileDragStart	FileDragEventArgs	开始拖动操作时
fileDragging	FileDragEventArgs	正在拖动时
fileDragStop	FileDragEventArgs	即将放下时（可取消）
fileDropped	FileDragEventArgs	成功放下文件或文件夹时

上传事件

事件	参数	触发时机
uploadListCreate	UploadListCreateArgs	上传界面创建时（上传前验证）
beforeDownload	BeforeDownloadEventArgs	请求下载时

菜单和上下文事件

事件	参数	触发时机
menuOpen	MenuOpenEventArgs	上下文菜单即将打开时
menuClose	MenuCloseEventArgs	上下文菜单关闭时
menuClick	MenuClickEventArgs	点击上下文菜单项时

搜索和对话框事件

事件	参数	触发时机
search	SearchEventArgs	用户在搜索框中输入时
beforePopupOpen	BeforePopupOpenCloseEventArgs	对话框即将打开时
popupOpen	PopupOpenCloseEventArgs	对话框打开时
beforePopupClose	BeforePopupOpenCloseEventArgs	对话框即将关闭时
popupClose	PopupOpenCloseEventArgs	对话框关闭时

AJAX 和服务端事件

事件	参数	触发时机
beforeSend	BeforeSendEventArgs	发送 AJAX 请求时（添加自定义标头）
success	SuccessEventArgs	AJAX 请求成功时
failure	FailureEventArgs	AJAX 请求失败时
beforeImageLoad	BeforeImageLoadEventArgs	发送图像/缩略图请求时

生命周期事件

事件	参数	触发时机
created	Object	组件初始化完成时
destroyed	Object	组件销毁时

工具栏事件

事件	参数	触发时机
toolbarCreate	ToolbarCreateEventArgs	创建工具栏时
toolbarClick	ToolbarClickEventArgs	点击工具栏按钮时

常见模式

1. 基本设置模式

首先，安装 Tailwind3 主题包：

npm install @syncfusion/ej2-tailwind3-theme

将主题导入语句添加到 src/App.css：

/* src/App.css */
@import "../node_modules/@syncfusion/ej2-tailwind3-theme/styles/file-manager/index.css";

然后使用组件：

import React from 'react';
import { FileManagerComponent, Inject, DetailsView, NavigationPane, Toolbar } from '@syncfusion/ej2-react-filemanager';
import './App.css';

export default function BasicFileManager() {
  return (
    <FileManagerComponent
      id="file"
      ajaxSettings={{
        url: "url",
        getImageUrl: "url",
        uploadUrl: "url",
        downloadUrl: "url"
      }}
      view="Details"
      height="500px"
    >
      <Inject services={[DetailsView, NavigationPane, Toolbar]} />
    </FileManagerComponent>
  );
}

设置步骤：

1. 安装 @syncfusion/ej2-react-filemanager 及其所有对等依赖项
2. 安装主题包：npm install @syncfusion/ej2-tailwind3-theme
3. 在 App.css 中添加主题导入语句：@import "../node_modules/@syncfusion/ej2-tailwind3-theme/styles/file-manager/index.css";
4. 配置 ajaxSettings 端点
5. 选择视图（Details 或 LargeIcons）
6. 注入所需服务（要启用的功能）

2. 文件服务后端模式

预期的端点结构：

ajaxSettings={{
  url: "url",
  getImageUrl: "url",
  uploadUrl: "url",
  downloadUrl: "url"
}}

后端实现（ASP.NET Core 示例）：

[ApiController]
[Route("api/[controller]")]
public class FileManagerController : ControllerBase
{
    [HttpPost("FileOperations")]
    public IActionResult FileOperations(
        [FromForm] string action,
        [FromForm] string path,
        [FromForm] string name = null,
        [FromForm] IFormFile uploadFiles = null)
    {
        switch (action)
        {
            case "read":
                // Return files and folders at given path
                return Ok(new { files = GetDirectoryContents(path) });
            case "create":
                // Create new folder
                Directory.CreateDirectory(Path.Combine(path, name));
                return Ok();
            case "delete":
                // Delete files/folders
                return Ok();
            case "rename":
                // Rename file/folder
                return Ok();
            case "move":
                // Move or copy files
                return Ok();
            default:
                return BadRequest("Invalid action");
        }
    }

    [HttpGet("GetImage")]
    public IActionResult GetImage([FromQuery] string path)
    {
        // Return thumbnail or image file
        var filePath = ResolvePath(path);
        return PhysicalFile(filePath, "image/jpeg");
    }

    [HttpPost("Upload")]
    public IActionResult Upload([FromForm] IFormFile uploadFiles, [FromForm] string path)
    {
        // Handle file upload
        var filePath = Path.Combine(path, uploadFiles.FileName);
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            uploadFiles.CopyTo(stream);
        }
        return Ok();
    }

    [HttpGet("Download")]
    public IActionResult Download([FromQuery] string path)
    {
        // Return file for download
        var file = System.IO.File.ReadAllBytes(path);
        var fileName = Path.GetFileName(path);
        return File(file, "application/octet-stream", fileName);
    }
}

3. 状态管理模式

import React, { useRef, useState } from 'react';

export default function FileManagerWithState() {
  const fileManagerRef = useRef(null);
  const [selectedFiles, setSelectedFiles] = useState([]);
  const [currentPath, setCurrentPath] = useState('/');

  const handleFileSelect = (args) => {
    setSelectedFiles(args.fileDetails);
  };

  const handleCreateFolder = () => {
    fileManagerRef.current?.createFolder('NewFolder');
  };

  const handleDeleteSelected = () => {
    const ids = selectedFiles.map(f => f.name);
    fileManagerRef.current?.deleteFiles(ids);
  };

  return (
    <div>
      <div className="toolbar">
        <button onClick={handleCreateFolder}>Create Folder</button>
        <button onClick={handleDeleteSelected} disabled={!selectedFiles.length}>
          Delete ({selectedFiles.length})
        </button>
        <span>Path: {currentPath}</span>
      </div>
      <FileManagerComponent
        ref={fileManagerRef}
        fileSelect={handleFileSelect}
        ajaxSettings={{...}}
        height="400px"
      >
        <Inject services={[DetailsView, NavigationPane, Toolbar]} />
      </FileManagerComponent>
    </div>
  );
}

4. 事件驱动的自定义逻辑模式

<FileManagerComponent
  // Prevent deletion of certain files
  beforeDelete={(args) => {
    if (args.fileDetails[0].name.startsWith('.')) {
      args.cancel = true;
      alert('Cannot delete system files');
    }
  }}
  
  // Add headers to AJAX requests
  beforeSend={(args) => {
    args.headers = { ...args.headers, 'Authorization': `Bearer ${token}` };
  }}
  
  // Validate before upload
  uploadListCreate={(args) => {
    args.fileDetails.forEach(file => {
      if (file.size > 5000000) { // 5MB limit
        args.cancel = true;
      }
    });
  }}
  
  // Track successful operations
  success={(args) => {
    console.log('Operation successful:', args.action, args.result);
  }}
  
  // Handle errors
  failure={(args) => {
    console.error('Operation failed:', args.error);
  }}
/>

5. 自定义模式

<FileManagerComponent
  // Customize toolbar
  toolbarSettings={{
    items: ['NewFolder', 'Upload', '|', 'Cut', 'Copy', 'Paste', '|', 'Delete', 'Download'],
    visible: true
  }}
  
  // Customize context menu
  contextMenuSettings={{
    file: ['Open', '|', 'Cut', 'Copy', '|', 'Delete', 'Rename', '|', 'Details'],
    folder: ['Open', '|', 'Cut', 'Copy', 'Paste', '|', 'Delete', 'Rename'],
    layout: ['SortBy', 'View', 'Refresh', '|', 'NewFolder', 'Upload'],
    visible: true
  }}
  
  // Customize columns in details view
  detailsViewSettings={{
    columns: [
      {
        field: 'name',
        headerText: 'Name',
        minWidth: 120,
        template: '<span class="custom-name">${name}</span>'
      },
      {
        field: '_fm_modified',
        headerText: 'Modified',
        type: 'dateTime',
        format: 'MMMM dd, yyyy HH:mm',
        minWidth: 120
      },
      {
        field: 'size',
        headerText: 'Size',
        minWidth: 90,
        template: '<span>${size}</span>'
      }
    ]
  }}
  
  // Customize navigation pane
  navigationPaneSettings={{
    maxWidth: '650px',
    minWidth: '240px',
    visible: true,
    sortOrder: 'None'
  }}
/>

6. 性能优化模式

<FileManagerComponent
  // Enable virtualization for large datasets
  enableVirtualization={true}
  
  // Enable persistence to maintain state
  enablePersistence={true}
  
  // Configure search settings
  searchSettings={{
    allowSearchOnTyping: true,
    filterType: 'contains',
    ignoreCase: true
  }}
  
  // Configure upload settings
  uploadSettings={{
    autoUpload: true,
    minFileSize: 0,
    maxFileSize: 30000000, // 30MB
    allowedExtensions: '.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx',
    autoClose: false,
    directoryUpload: false,
    sequentialUpload: false
  }}
  
  // Sort optimization
  sortBy="name"
  sortOrder="Ascending"
/>

关键属性

核心配置

属性	类型	默认值	用途
ajaxSettings	Object	见下文	配置文件操作的后端端点
path	string	"/"	当前文件夹路径
view	string	"LargeIcons"	视图类型："Details" 或 "LargeIcons"
width	string	"100%"	组件宽度
height	string	"400px"	组件高度

显示和行为

属性	类型	默认值	用途
showFileExtension	boolean	true	显示文件扩展名
showHiddenItems	boolean	false	显示隐藏文件/文件夹
showThumbnail	boolean	true	在大图标视图中显示缩略图
showItemCheckBoxes	boolean	true	悬停时显示复选框
sortBy	string	"name"	排序字段："name"、"dateModified"、"size"
sortOrder	string	"Ascending"	排序方向："Ascending"、"Descending" 或 "None"
enableRtl	boolean	false	支持从右向左布局
locale	string	"en-US"	本地化语言代码

选择与导航

属性	类型	默认值	用途
allowMultiSelection	boolean	true	允许选择多个文件
enableRangeSelection	boolean	false	通过拖动鼠标选择多个项目
selectedItems	string[]	[]	初始选中的文件名
allowDragAndDrop	boolean	false	启用拖放操作

性能与功能

属性	类型	默认值	用途
enableVirtualization	boolean	false	对大型数据集启用虚拟滚动
enablePersistence	boolean	false	持久化视图、路径和选择状态
enableHtmlSanitizer	boolean	true	清理 HTML 以防止 XSS 攻击
cssClass	string	""	用于设置样式的自定义 CSS 类
rootAliasName	string	null	根文件夹的显示名称
popupTarget	HTMLElement	null	对话框弹出窗口的目标元素

数据与设置对象

属性	类型	用途
fileSystemData	Object[]	用于本地文件的扁平数据结构
contextMenuSettings	Object	自定义上下文菜单项
toolbarSettings	Object	配置工具栏项和布局
detailsViewSettings	Object	自定义列和列宽
navigationPaneSettings	Object	配置侧边栏的行为和外观
searchSettings	Object	配置搜索筛选选项
uploadSettings	Object	配置上传行为
sortComparer	Function	自定义排序函数
largeIconsTemplate	string | Function	大图标视图的自定义模板
navigationPaneTemplate	string | Function	导航窗格的自定义模板

AJAX 设置配置

ajaxSettings={{
  url: "url",     // Main CRUD endpoint (required)
  getImageUrl: "url",   // Thumbnail retrieval
  uploadUrl: "url",       // File upload endpoint
  downloadUrl: "url",   // File download endpoint
  // Optional: Add custom headers
  // headers: { 'Authorization': 'Bearer token' }
}}

后端端点要求：

• url - 接收带有 action 参数的 POST 请求：

  • read：列出路径中的文件
  • create：创建新文件夹
  • delete：删除文件／文件夹
  • rename：重命名文件／文件夹
  • move：移动／复制文件（复制或剪切）
  • search：搜索文件
  • upload：处理文件上传
  • download：准备下载

• getImageUrl - 使用 path 参数获取缩略图图片 URL 的 GET 请求

• uploadUrl - 使用 multipart 表单数据和文件上传的 POST 请求

• downloadUrl - 启动文件下载流

常见用例

用例 1：文档管理系统

实现支持上传、下载和文件夹整理的文档浏览器：

• 使用详细信息视图显示元数据
• 配置用于文档操作的上下文菜单
• 添加搜索功能
• 在后端实现访问控制

用例 2：媒体文件浏览器

构建带有图片／视频缩略图的图库：

• 使用大图标视图显示缩略图
• 配置 getImageUrl 以生成预览
• 实现延迟加载以提升性能
• 添加拖放功能以便整理

用例 3：管理员文件管理器

创建内部文件管理工具：

• 自定义工具栏，添加管理员专用操作
• 实现高级上下文菜单选项
• 添加日志记录和审计跟踪
• 在后端配置权限

用例 4：本地化文件管理器

支持多种语言和 RTL：

• 将 locale 设置为用户使用的语言
• 为 RTL 语言启用 enableRtl
• 按语言自定义上下文菜单标签
• 根据区域设置格式化日期和大小

---

后续步骤

1. 开始使用： 阅读 references/getting-started.md，了解安装和基本设置
2. 后端： 如需使用 Azure Blob Storage / Amazon S3，请参阅 references/docker-deployment.md
3. 实现： 选择符合需求的功能参考文档
4. 自定义： 查看 references/customization.md，了解样式和配置
5. 优化： 查阅 references/advanced-features.md，了解性能和边缘情况
6. 无障碍： 确保符合 references/accessibility-localization.md 中的要求

---