syncfusion-angular-file-manager

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing the Syncfusion Angular File Manager Component

实现Syncfusion Angular File Manager组件

The File Manager is a powerful graphical user interface component for managing file systems. It enables users to perform essential file operations—accessing, editing, sorting, uploading, downloading, and organizing files and folders—with an intuitive interface and comprehensive navigation functionality.
File Manager是一个功能强大的图形用户界面组件,用于管理文件系统。它允许用户通过直观的界面和全面的导航功能执行基本的文件操作——访问、编辑、排序、上传、下载以及组织文件和文件夹。

When to Use This Skill

何时使用此技能

Use the File Manager component when you need to:
  • Browse and navigate files and folders in a file system
  • Perform file operations (create, delete, rename, upload, download)
  • Display files in different view modes (details view, large icons view)
  • Implement drag-and-drop file management
  • Handle large file sets efficiently with virtualization
  • Customize toolbar, context menu, and file display
  • Support multi-selection, sorting, and localization
在以下场景中使用File Manager组件:
  • 浏览和导航文件系统中的文件和文件夹
  • 执行文件操作(创建、删除、重命名、上传、下载)
  • 以不同视图模式显示文件(详细信息视图、大图标视图)
  • 实现拖放式文件管理
  • 通过虚拟化高效处理大量文件集
  • 自定义工具栏、上下文菜单和文件显示
  • 支持多选、排序和本地化

Component Overview & Key Features

组件概述与核心特性

Core Capabilities

核心功能

  • File Operations: Read, create, delete, rename, upload, download files
  • Navigation: Breadcrumb navigation, navigation pane, folder hierarchy
  • View Options: Details view (sorted list) and Large Icons view (thumbnail display)
  • User Interaction: Multi-selection, drag-and-drop, right-click context menu
  • Performance: UI virtualization for large file sets, state persistence
  • Customization: Toolbar/context menu customization, CSS theming, custom icons
  • Accessibility: RTL support, localization, ARIA attributes
  • 文件操作:读取、创建、删除、重命名、上传、下载文件
  • 导航面包屑导航、导航窗格、文件夹层级
  • 视图选项:详细信息视图(排序列表)和大图标视图(缩略图显示)
  • 用户交互:多选、拖放、右键上下文菜单
  • 性能:针对大量文件集的UI虚拟化、状态持久化
  • 自定义:工具栏/上下文菜单自定义、CSS主题、自定义图标
  • 可访问性:RTL支持、本地化、ARIA属性

Architecture

架构

  • Server-based file operations via
    ajaxSettings
  • Or client-side data binding with
    fileSystemData
    (flat or nested JSON)
  • Feature modules: Navigation Pane, Toolbar, Details View, Virtualization
  • Event-driven architecture for custom workflows
  • 通过
    ajaxSettings
    实现基于服务器的文件操作
  • 或通过
    fileSystemData
    实现客户端数据绑定(扁平或嵌套JSON)
  • 功能模块:导航窗格、工具栏、详细信息视图、虚拟化
  • 用于自定义工作流的事件驱动架构

Documentation and Navigation Guide

文档与导航指南

API Reference (Start Here for API Details)

API参考(从这里开始了解API详情)

📄 Read: references/api-reference-complete.md
  • Complete component properties with descriptions
  • FileData interface for client-side binding
  • Configuration models and best practices
  • Service providers and utility functions
📄 阅读: references/api-reference-complete.md
  • 完整的组件属性及描述
  • 用于客户端绑定的FileData接口
  • 配置模型与最佳实践
  • 服务提供者与实用函数

Methods and Events Reference

方法与事件参考

📄 Read: references/methods-and-events.md
  • Complete list of all component methods with examples
  • All component events with event arguments
  • Event parameter interfaces and descriptions
  • Practical examples for each method and event
📄 阅读: references/methods-and-events.md
  • 所有组件方法的完整列表及示例
  • 所有组件事件及事件参数
  • 事件参数接口与描述
  • 每个方法和事件的实用示例

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Prerequisites (Angular 4+, TypeScript 2.6+)
  • Angular project setup and CLI commands
  • Package installation (Ivy vs ngcc compatibility)
  • CSS theme imports and styling
  • Basic component initialization
  • ajaxSettings configuration (file operations, download, upload, preview URLs)
  • Initial view and component rendering
📄 阅读: references/getting-started.md
  • 前提条件(Angular 4+、TypeScript 2.6+)
  • Angular项目设置与CLI命令
  • 包安装(Ivy与ngcc兼容性)
  • CSS主题导入与样式设置
  • 基础组件初始化
  • ajaxSettings配置(文件操作、下载、上传、预览URL)
  • 初始视图与组件渲染

File Operations

文件操作

📄 Read: references/file-operations.md
  • Core operations: read, create, delete, rename, upload, download, copy, move
  • File system provider configuration
  • Server integration patterns
  • Custom file providers (Google Drive, Amazon S3, Azure)
  • Directory upload support
  • Error handling and validation
  • Request/response patterns
📄 阅读: references/file-operations.md
  • 核心操作:读取、创建、删除、重命名、上传、下载、复制、移动
  • 文件系统提供者配置
  • 服务器集成模式
  • 自定义文件提供者(Google Drive、Amazon S3、Azure)
  • 目录上传支持
  • 错误处理与验证
  • 请求/响应模式

Request and Response Parameters

请求与响应参数

📄 Read: references/request-response-parameters-reference.md
  • Complete response parameters for ALL 11 operations
  • Request structure and parameters for each operation
  • Response format and structure specifications
  • FileManagerDirectoryContent interface definition
  • DetailsObject and error response formats
  • Request/response examples for every operation
  • Error codes and error handling patterns
  • Common data structures and interfaces
  • Best practices for backend implementation
📄 阅读: references/request-response-parameters-reference.md
  • 全部11种操作的完整响应参数
  • 每种操作的请求结构与参数
  • 响应格式与结构规范
  • FileManagerDirectoryContent接口定义
  • DetailsObject与错误响应格式
  • 每种操作的请求/响应示例
  • 错误代码与错误处理模式
  • 通用数据结构与接口
  • 后端实现最佳实践

Upload Customizations

上传自定义

📄 Read: references/upload-customizations.md
  • Directory upload configuration (directoryUpload property)
  • Sequential upload setup (sequentialUpload property)
  • Chunk upload for large files (chunkSize configuration)
  • Auto-upload behavior control
  • File size validation (minFileSize, maxFileSize)
  • File type restrictions (allowedExtensions)
  • Upload events (beforeSend, onSuccess, onFailure)
  • Backend implementation examples (ASP.NET Core)
  • 3 practical examples covering image-only, document, and complete upload configs
📄 阅读: references/upload-customizations.md
  • 目录上传配置(directoryUpload属性)
  • 顺序上传设置(sequentialUpload属性)
  • 大文件分块上传(chunkSize配置)
  • 自动上传行为控制
  • 文件大小验证(minFileSize、maxFileSize)
  • 文件类型限制(allowedExtensions)
  • 上传事件(beforeSend、onSuccess、onFailure)
  • 后端实现示例(ASP.NET Core)
  • 3个实用示例,涵盖仅图片、文档和完整上传配置

File System Provider Reference

文件系统提供者参考

📄 Read: references/file-system-provider-reference.md
  • Overview of 9 different file system providers
  • Physical file system provider (on-premise local files)
  • Azure cloud file system provider (Azure Blob Storage)
  • Amazon S3 cloud file provider (AWS object storage)
  • SharePoint file provider (Microsoft SharePoint integration)
  • File Transfer Protocol provider (FTP server access)
  • SQL database file system provider (database-backed storage)
  • Node.js file system provider (lightweight Node.js runtime)
  • Google Drive file system provider (Google Drive integration)
  • Firebase Realtime Database provider (serverless cloud database)
  • Setup instructions for each provider
  • Configuration examples and best practices
  • Provider comparison table
  • Quick selection guide
📄 阅读: references/file-system-provider-reference.md
  • 9种不同文件系统提供者概述
  • 物理文件系统提供者(本地本地文件)
  • Azure云文件系统提供者(Azure Blob存储)
  • Amazon S3云文件提供者(AWS对象存储)
  • SharePoint文件提供者(Microsoft SharePoint集成)
  • 文件传输协议提供者(FTP服务器访问)
  • SQL数据库文件系统提供者(基于数据库的存储)
  • Node.js文件系统提供者(轻量级Node.js运行时)
  • Google Drive文件系统提供者(Google Drive集成)
  • Firebase实时数据库提供者(无服务器云数据库)
  • 每个提供者的设置说明
  • 配置示例与最佳实践
  • 提供者对比表
  • 快速选择指南

Views and Layout

视图与布局

📄 Read: references/views-and-layout.md
  • Details view (sorted file list with columns)
  • Large Icons view (thumbnail display)
  • Switching views dynamically or at initialization
  • Initial view configuration
  • CSS class customization for styling
  • View-specific settings and configurations
📄 阅读: references/views-and-layout.md
  • 详细信息视图(带列的排序文件列表)
  • 大图标视图(缩略图显示)
  • 动态切换视图或初始化时设置视图
  • 初始视图配置
  • 用于样式设置的CSS类自定义
  • 特定视图的设置与配置

Navigation Features

导航特性

📄 Read: references/navigation-features.md
  • Breadcrumb navigation (folder hierarchy tracking)
  • Navigation pane configuration (left sidebar with folder tree)
  • Path specification and dynamic navigation
  • Folder hierarchy traversal
  • Showing/hiding navigation elements
📄 阅读: references/navigation-features.md
  • 面包屑导航(文件夹层级跟踪)
  • 导航窗格配置(带文件夹树的左侧边栏)
  • 路径指定与动态导航
  • 文件夹层级遍历
  • 显示/隐藏导航元素

Data Structures

数据结构

📄 Read: references/data-structures.md
  • Flat JSON data binding (no backend required)
  • Nested items (folder hierarchies in local data)
  • fileData interface and properties (name, size, date, isFile, hasChild, etc.)
  • Parent-child relationships via parentId
  • Flat vs nested approaches and trade-offs
  • Server-based vs client-side data
📄 阅读: references/data-structures.md
  • 扁平JSON数据绑定(无需后端)
  • 嵌套项(本地数据中的文件夹层级)
  • fileData接口与属性(name、size、date、isFile、hasChild等)
  • 通过parentId实现父子关系
  • 扁平与嵌套方式的权衡
  • 基于服务器与客户端数据

Nested Items Integration

嵌套项集成

📄 Read: references/nested-items-integration.md
  • Dialog nesting with file selection pattern
  • Tab nesting (multiple File Managers per tab)
  • Splitter nesting (side-by-side layout)
  • Accordion nesting (categorized file access)
  • Managing multiple nested File Manager state
  • Height calculation strategies
  • Dimension management best practices
  • 2 practical examples: file upload dialog, tabbed file management
📄 阅读: references/nested-items-integration.md
  • 带文件选择模式的对话框嵌套
  • 标签页嵌套(每个标签页一个File Manager)
  • 分割器嵌套(并排布局)
  • 手风琴嵌套(分类文件访问)
  • 管理多个嵌套File Manager的状态
  • 高度计算策略
  • 维度管理最佳实践
  • 2个实用示例:文件上传对话框、标签页式文件管理

Drag and Drop

拖放功能

📄 Read: references/drag-and-drop.md
  • Enabling drag-and-drop functionality
  • Drop target configuration
  • File move operations via dragging
  • Drag event handling (fileDragStart, fileDragging, fileDragStop, fileDropped)
  • Constraints and drop restrictions
  • Visual feedback during drag operations
📄 阅读: references/drag-and-drop.md
  • 启用拖放功能
  • 拖放目标配置
  • 通过拖拽实现文件移动操作
  • 拖拽事件处理(fileDragStart、fileDragging、fileDragStop、fileDropped)
  • 约束与拖放限制
  • 拖拽过程中的视觉反馈

Virtualization

虚拟化

📄 Read: references/virtualization.md
  • What is UI virtualization and performance benefits
  • Module injection (VirtualizationService)
  • Enabling virtualization (enableVirtualization property)
  • Handling large file sets (100s-1000s of files)
  • Memory optimization and scrolling performance
  • Virtual scrolling in details and large icons views
📄 阅读: references/virtualization.md
  • 什么是UI虚拟化及其性能优势
  • 模块注入(VirtualizationService)
  • 启用虚拟化(enableVirtualization属性)
  • 处理大量文件集(数百到数千个文件)
  • 内存优化与滚动性能
  • 详细信息视图和大图标视图中的虚拟滚动

Sorting and Filtering

排序与筛选

📄 Read: references/sorting-and-filtering.md
  • Custom sorting via sortComparer function
  • Natural sorting (like Windows Explorer)
  • Sort orders (ascending/descending)
  • Multi-column sorting in details view
  • Column-specific sortComparer definitions
  • Imported sortComparer utility or custom implementations
📄 阅读: references/sorting-and-filtering.md
  • 通过sortComparer函数实现自定义排序
  • 自然排序(类似Windows资源管理器)
  • 排序顺序(升序/降序)
  • 详细信息视图中的多列排序
  • 特定列的sortComparer定义
  • 导入sortComparer工具或自定义实现

Toolbar Customization

工具栏自定义

📄 Read: references/toolbar-customization.md
  • Toolbar configuration and items
  • Default toolbar items (NewFolder, Upload, View, Refresh, Cut, Copy, Paste, Delete, Download, Rename)
  • Adding custom toolbar items with templates
  • Modifying toolbar item properties
  • Toolbar icons (Syncfusion, Font Awesome, custom SVG)
  • Template-based toolbar items (checkboxes, dropdowns)
  • Toolbar click events and event handling
  • Conditional toolbar items based on selection
📄 阅读: references/toolbar-customization.md
  • 工具栏配置与项
  • 默认工具栏项(NewFolder、Upload、View、Refresh、Cut、Copy、Paste、Delete、Download、Rename)
  • 添加带模板的自定义工具栏项
  • 修改工具栏项属性
  • 工具栏图标(Syncfusion、Font Awesome、自定义SVG)
  • 基于模板的工具栏项(复选框、下拉菜单)
  • 工具栏点击事件与事件处理
  • 基于选择的条件工具栏项

Context Menu Customization

上下文菜单自定义

📄 Read: references/context-menu-customization.md
  • Default context menu items (Open, Cut, Copy, Paste, Delete, Rename, Download)
  • Adding custom context menu items
  • Context menu configuration for files, folders, and layout
  • Menu events (menuOpen, menuClose, menuClick)
  • Dynamic menu modification and conditional items
  • Adding icons to menu items
  • Custom menu actions and implementations
  • Submenu support
📄 阅读: references/context-menu-customization.md
  • 默认上下文菜单项(Open、Cut、Copy、Paste、Delete、Rename、Download)
  • 添加自定义上下文菜单项
  • 针对文件、文件夹和布局的上下文菜单配置
  • 菜单事件(menuOpen、menuClose、menuClick)
  • 动态菜单修改与条件项
  • 为菜单项添加图标
  • 自定义菜单操作与实现
  • 子菜单支持

Access Control and Permissions

访问控制与权限

📄 Read: references/access-control-and-permissions.md
  • Permission model and FileData permission structure
  • Implementing role-based access control (RBAC)
  • File-level and folder-level permissions
  • Backend permission rules configuration
  • Access rules with Permission enumeration (Allow/Deny)
  • Frontend permission handling and UI disabling
  • Administrator, Editor, and Viewer role examples
  • Audit logging and compliance
📄 阅读: references/access-control-and-permissions.md
  • 权限模型与FileData权限结构
  • 实现基于角色的访问控制(RBAC)
  • 文件级与文件夹级权限
  • 后端权限规则配置
  • 带Permission枚举的访问规则(Allow/Deny)
  • 前端权限处理与UI禁用
  • 管理员、编辑者和查看者角色示例
  • 审计日志与合规性

Authentication and Custom Values

认证与自定义值

📄 Read: references/authentication-and-custom-values.md
  • beforeSend event for adding authentication headers
  • JWT token authentication implementation
  • Bearer token patterns
  • Custom headers (API keys, request IDs, correlation IDs)
  • Custom data passing with requests
  • Query parameters and body data
  • CORS configuration and cross-origin requests
  • OAuth2 token refresh patterns
  • Multi-tenant file manager setup
  • Audit trail and request logging
📄 阅读: references/authentication-and-custom-values.md
  • 用于添加认证头的beforeSend事件
  • JWT令牌认证实现
  • Bearer令牌模式
  • 自定义头(API密钥、请求ID、关联ID)
  • 随请求传递自定义数据
  • 查询参数与请求体数据
  • CORS配置与跨域请求
  • OAuth2令牌刷新模式
  • 多租户文件管理器设置
  • 审计跟踪与请求日志

Custom File Providers

自定义文件提供者

📄 Read: references/custom-file-provider.md
  • Custom file provider architecture
  • Required API endpoints (FileOperations, Upload, Download, GetImage)
  • Request/response format specifications
  • ASP.NET Core custom backend implementation
  • Azure Blob Storage integration
  • AWS S3 integration
  • Database-backed file system (SQL)
  • Google Drive and cloud storage patterns
  • Implementing ICustomFileService interface
📄 阅读: references/custom-file-provider.md
  • 自定义文件提供者架构
  • 所需API端点(FileOperations、Upload、Download、GetImage)
  • 请求/响应格式规范
  • ASP.NET Core自定义后端实现
  • Azure Blob存储集成
  • AWS S3集成
  • 基于数据库的文件系统(SQL)
  • Google Drive与云存储模式
  • 实现ICustomFileService接口

Advanced Features

高级特性

📄 Read: references/advanced-features.md
  • Multi-selection of files and folders
  • State persistence (enablePersistence property)
  • Maintaining view, path, and selected items across page reload
  • Ajax events (success, failure)
  • Component lifecycle (created event)
  • Refresh file operations programmatically
  • Multiple file selection with bulk operations
📄 阅读: references/advanced-features.md
  • 文件与文件夹的多选
  • 状态持久化(enablePersistence属性)
  • 在页面刷新后保持视图、路径和选中项
  • Ajax事件(success、failure)
  • 组件生命周期(created事件)
  • 以编程方式刷新文件操作
  • 多选文件与批量操作

UI Customizations

UI自定义

📄 Read: references/ui-customizations.md
  • Large icon customization (size, layout, styling)
  • Custom file type icons mapping
  • showFileExtension property and dynamic control
  • showHiddenItems configuration with server-side filtering
  • Tooltip customization with file information
  • allowMultiSelection control with single/multi toggle
  • Multi-selection limitation patterns
  • showThumbnail: Control thumbnail display (performance tuning for large collections)
  • showItemCheckBoxes: Enable selection checkboxes (mobile-friendly & accessibility)
  • enableHtmlSanitizer: Security property to prevent XSS attacks (CRITICAL: keep enabled)
  • popupTarget: Specify popup/dialog container (required for nested File Managers)
  • 15+ working code examples with CSS patterns and advanced configurations
  • Complete UI customization examples
📄 阅读: references/ui-customizations.md
  • 大图标自定义(大小、布局、样式)
  • 自定义文件类型图标映射
  • showFileExtension属性与动态控制
  • 带服务器端筛选的showHiddenItems配置
  • 带文件信息的工具提示自定义
  • 带单/多切换的allowMultiSelection控制
  • 多选限制模式
  • showThumbnail:控制缩略图显示(针对大型集合的性能调优)
  • showItemCheckBoxes:启用选择复选框(移动友好与可访问性)
  • enableHtmlSanitizer:防止XSS攻击的安全属性(重要:保持启用状态)
  • popupTarget:指定弹出窗口/对话框容器(嵌套File Manager必需)
  • 15+个带CSS模式和高级配置的可运行代码示例
  • 完整的UI自定义示例

Navigation Items Customization

导航项自定义

📄 Read: references/navigation-items-customization.md
  • navigationPaneTemplate basic and advanced usage
  • Custom item rendering with hierarchical styling
  • Icon and badge integration patterns
  • CSS styling approaches for navigation items
  • Dynamic theme application (light/dark toggle)
  • Path-based icon customization
  • Professional navigation design patterns
  • 1 comprehensive professional navigation example
📄 阅读: references/navigation-items-customization.md
  • navigationPaneTemplate的基础与高级用法
  • 带层级样式的自定义项渲染
  • 图标与徽章集成模式
  • 导航项的CSS样式方法
  • 动态主题应用(亮/暗模式切换)
  • 基于路径的图标自定义
  • 专业导航设计模式
  • 1个综合的专业导航示例

Customization and Styling

自定义与样式设置

📄 Read: references/customization-styling.md
  • CSS class customization (cssClass property)
  • Theme customization and Theme Studio integration
  • Custom thumbnails (showThumbnail property)
  • Custom icon display for files and folders
  • Responsive design and container sizing
  • Advanced styling examples
  • CSS variable overrides
📄 阅读: references/customization-styling.md
  • CSS类自定义(cssClass属性)
  • 主题自定义与Theme Studio集成
  • 自定义缩略图(showThumbnail属性)
  • 文件与文件夹的自定义图标显示
  • 响应式设计与容器大小调整
  • 高级样式示例
  • CSS变量覆盖

Localization and RTL

本地化与RTL

📄 Read: references/localization-and-rtl.md
  • Right-to-left (RTL) language support (enableRtl property)
  • Localization library (l10) integration
  • Language configuration and switching
  • Custom text and message localization
  • Regional date/time formatting
📄 阅读: references/localization-and-rtl.md
  • 从右到左(RTL)语言支持(enableRtl属性)
  • 本地化库(l10)集成
  • 语言配置与切换
  • 自定义文本与消息本地化
  • 区域日期/时间格式化

Quick Start Example

快速入门示例

Basic File Manager Setup

基础文件管理器设置

typescript
import { Component } from '@angular/core';
import { FileManagerModule, NavigationPaneService, ToolbarService, DetailsViewService } from '@syncfusion/ej2-angular-filemanager';

@Component({
  imports: [FileManagerModule],
  providers: [NavigationPaneService, ToolbarService, DetailsViewService],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-filemanager 
    id='file-manager' 
    [ajaxSettings]='ajaxSettings' 
    height="500px">
  </ejs-filemanager>`
})
export class AppComponent {
  public ajaxSettings = {
    url: 'https://ej2-aspcore-service.azurewebsites.net/api/FileManager/FileOperations',
    getImageUrl: 'https://ej2-aspcore-service.azurewebsites.net/api/FileManager/GetImage',
    uploadUrl: 'https://ej2-aspcore-service.azurewebsites.net/api/FileManager/Upload',
    downloadUrl: 'https://ej2-aspcore-service.azurewebsites.net/api/FileManager/Download'
  };
}
typescript
import { Component } from '@angular/core';
import { FileManagerModule, NavigationPaneService, ToolbarService, DetailsViewService } from '@syncfusion/ej2-angular-filemanager';

@Component({
  imports: [FileManagerModule],
  providers: [NavigationPaneService, ToolbarService, DetailsViewService],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-filemanager 
    id='file-manager' 
    [ajaxSettings]='ajaxSettings' 
    height="500px">
  </ejs-filemanager>`
})
export class AppComponent {
  public ajaxSettings = {
    url: 'https://ej2-aspcore-service.azurewebsites.net/api/FileManager/FileOperations',
    getImageUrl: 'https://ej2-aspcore-service.azurewebsites.net/api/FileManager/GetImage',
    uploadUrl: 'https://ej2-aspcore-service.azurewebsites.net/api/FileManager/Upload',
    downloadUrl: 'https://ej2-aspcore-service.azurewebsites.net/api/FileManager/Download'
  };
}

With Local JSON Data (No Backend)

基于本地JSON数据(无需后端)

typescript
import { Component } from '@angular/core';
import { FileManagerModule } from '@syncfusion/ej2-angular-filemanager';
import { FileData } from '@syncfusion/ej2-filemanager';

@Component({
  imports: [FileManagerModule],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-filemanager 
    id='file-manager' 
    [fileSystemData]='fileData' 
    height="500px">
  </ejs-filemanager>`
})
export class AppComponent {
  public fileData: FileData[] = [
    {
      id: '1',
      name: 'Documents',
      isFile: false,
      hasChild: true,
      parentId: null,
      dateModified: new Date('2024-01-15')
    },
    {
      id: '2',
      name: 'Resume.pdf',
      isFile: true,
      hasChild: false,
      parentId: '1',
      size: 204800,
      dateModified: new Date('2024-01-10')
    }
  ];
}
typescript
import { Component } from '@angular/core';
import { FileManagerModule } from '@syncfusion/ej2-angular-filemanager';
import { FileData } from '@syncfusion/ej2-filemanager';

@Component({
  imports: [FileManagerModule],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-filemanager 
    id='file-manager' 
    [fileSystemData]='fileData' 
    height="500px">
  </ejs-filemanager>`
})
export class AppComponent {
  public fileData: FileData[] = [
    {
      id: '1',
      name: 'Documents',
      isFile: false,
      hasChild: true,
      parentId: null,
      dateModified: new Date('2024-01-15')
    },
    {
      id: '2',
      name: 'Resume.pdf',
      isFile: true,
      hasChild: false,
      parentId: '1',
      size: 204800,
      dateModified: new Date('2024-01-10')
    }
  ];
}

Common Patterns

常见模式

Pattern 1: Server Integration with Full Configuration

模式1:带完整配置的服务器集成

Use when: Building a production file manager with backend services
typescript
// app.component.ts
ajaxSettings = {
  url: '/api/FileManager/FileOperations',
  getImageUrl: '/api/FileManager/GetImage',
  uploadUrl: '/api/FileManager/Upload',
  downloadUrl: '/api/FileManager/Download'
};

toolbarSettings = {
  items: ['NewFolder', 'Upload', 'Download', 'Delete', 'Refresh', 'View', 'Details']
};
适用场景: 构建带后端服务的生产级文件管理器
typescript
// app.component.ts
ajaxSettings = {
  url: '/api/FileManager/FileOperations',
  getImageUrl: '/api/FileManager/GetImage',
  uploadUrl: '/api/FileManager/Upload',
  downloadUrl: '/api/FileManager/Download'
};

toolbarSettings = {
  items: ['NewFolder', 'Upload', 'Download', 'Delete', 'Refresh', 'View', 'Details']
};

Pattern 2: Local Data with Custom Formatting

模式2:带自定义格式化的本地数据

Use when: Data comes from API but doesn't need backend file operations
Transform API response into fileData format:
typescript
fileData = this.apiService.getFiles().map(file => ({
  id: file.id,
  name: file.fileName,
  isFile: file.type === 'file',
  parentId: file.parentId || null,
  size: file.fileSize,
  dateModified: new Date(file.modified)
}));
适用场景: 数据来自API但无需后端文件操作
将API响应转换为fileData格式:
typescript
fileData = this.apiService.getFiles().map(file => ({
  id: file.id,
  name: file.fileName,
  isFile: file.type === 'file',
  parentId: file.parentId || null,
  size: file.fileSize,
  dateModified: new Date(file.modified)
}));

Pattern 3: Virtualization for Large Datasets

模式3:针对大型数据集的虚拟化

Use when: Handling 1000+ files
typescript
// Inject VirtualizationService, enable enableVirtualization
providers: [VirtualizationService]

// In template
<ejs-filemanager 
  [enableVirtualization]="true"
  [view]="'Details'"
  ...>
</ejs-filemanager>
适用场景: 处理1000+个文件
typescript
// 注入VirtualizationService,启用enableVirtualization
providers: [VirtualizationService]

// 在模板中
<ejs-filemanager 
  [enableVirtualization]="true"
  [view]="'Details'"
  ...>
</ejs-filemanager>

Pattern 4: Multi-Selection with Actions

模式4:带操作的多选

Use when: Bulk file operations needed
typescript
onDownloadSelected() {
  const selected = this.fileManager.selectedItems;
  // Download multiple files (server returns ZIP)
}
适用场景: 需要批量文件操作
typescript
onDownloadSelected() {
  const selected = this.fileManager.selectedItems;
  // 下载多个文件(服务器返回ZIP)
}

Key Props and Settings

核心属性与设置

Core Configuration

核心配置

PropertyTypePurpose
ajaxSettings
AjaxSettingsModelServer endpoints for file operations (url, uploadUrl, downloadUrl, getImageUrl)
fileSystemData
FileData[]Local JSON data (alternative to ajaxSettings)
path
stringInitial directory path to display
view
ViewTypeInitial view mode: 'Details' or 'LargeIcons'
height
string | numberComponent height
width
string | numberComponent width
属性类型用途
ajaxSettings
AjaxSettingsModel文件操作的服务器端点(url、uploadUrl、downloadUrl、getImageUrl)
fileSystemData
FileData[]本地JSON数据(ajaxSettings的替代方案)
path
string初始显示的目录路径
view
ViewType初始视图模式:'Details'或'LargeIcons'
height
string | number组件高度
width
string | number组件宽度

Selection & Multi-Selection

选择与多选

PropertyTypePurpose
allowMultiSelection
booleanEnable Ctrl+Click and Shift+Click selection
enableRangeSelection
booleanEnable drag-based selection (Windows Explorer style)
属性类型用途
allowMultiSelection
boolean启用Ctrl+点击和Shift+点击选择
enableRangeSelection
boolean启用基于拖拽的选择(类似Windows资源管理器)

File Operations

文件操作

PropertyTypePurpose
allowDragAndDrop
booleanEnable drag-and-drop file movement
uploadSettings
UploadSettingsModelUpload config (maxFileSize, minFileSize, autoUpload, allowedExtensions, directoryUpload)
searchSettings
SearchSettingsModelSearch config (filterType, allowSearchOnTyping, caseSensitive)
属性类型用途
allowDragAndDrop
boolean启用拖放式文件移动
uploadSettings
UploadSettingsModel上传配置(maxFileSize、minFileSize、autoUpload、allowedExtensions、directoryUpload)
searchSettings
SearchSettingsModel搜索配置(filterType、allowSearchOnTyping、caseSensitive)

Display & Performance

显示与性能

PropertyTypePurpose
showThumbnail
booleanDisplay image thumbnails
showHiddenItems
booleanShow/hide hidden files and folders (default: false)
showFileExtension
booleanDisplay file extensions (default: true)
enableVirtualization
booleanVirtualize large file sets (1000+ items)
enablePersistence
booleanPersist view, path, and selected items
enableRtl
booleanRight-to-left layout support
enableHtmlSanitizer
booleanSanitize HTML for security
属性类型用途
showThumbnail
boolean显示图片缩略图
showHiddenItems
boolean显示/隐藏隐藏文件和文件夹(默认:false)
showFileExtension
boolean显示文件扩展名(默认:true)
enableVirtualization
boolean虚拟化大型文件集(1000+项)
enablePersistence
boolean持久化视图、路径和选中项
enableRtl
boolean从右到左布局支持
enableHtmlSanitizer
boolean对HTML进行 sanitize 处理以保障安全

UI Customization

UI自定义

PropertyTypePurpose
toolbarSettings
ToolbarSettingsModelToolbar items and visibility
navigationPaneSettings
NavigationPaneSettingsModelLeft sidebar configuration
contextMenuSettings
ContextMenuSettingsModelRight-click menu customization
detailsViewSettings
DetailsViewSettingsModelDetails view columns and sorting
navigationPaneTemplate
string | objectCustom template for navigation nodes
largeIconsTemplate
string | objectCustom template for large icons view
cssClass
stringCSS class for theming
locale
stringLocalization culture (e.g., 'de-DE', 'ja-JP')
属性类型用途
toolbarSettings
ToolbarSettingsModel工具栏项与可见性
navigationPaneSettings
NavigationPaneSettingsModel左侧边栏配置
contextMenuSettings
ContextMenuSettingsModel右键菜单自定义
detailsViewSettings
DetailsViewSettingsModel详细信息视图列与排序
navigationPaneTemplate
string | object导航节点的自定义模板
largeIconsTemplate
string | object大图标视图的自定义模板
cssClass
string用于主题设置的CSS类
locale
string本地化文化(例如:'de-DE'、'ja-JP')

Sorting & Comparison

排序与比较

PropertyTypePurpose
sortComparer
FunctionCustom sort function (Windows Explorer-like sorting available)
属性类型用途
sortComparer
Function自定义排序函数(提供类似Windows资源管理器的排序)

Decision Tree: Choose Your Approach

决策树:选择合适的实现方式

Do you have a backend file service? 
  ├─ YES → Use ajaxSettings (see Getting Started)
  │        └─ Need to handle 1000+ files?
  │            ├─ YES → Enable enableVirtualization
  │            └─ NO → Standard setup
  └─ NO → Use fileSystemData with local JSON
           └─ Need to organize hierarchically?
               ├─ YES → Use nested items with parentId
               └─ NO → Use flat data structure

Next Steps: Select the reference that matches your current task and dive into implementation details with code examples and best practices.
你是否有后端文件服务? 
  ├─ 是 → 使用ajaxSettings(参见快速入门)
  │        └─ 需要处理1000+个文件?
  │            ├─ 是 → 启用enableVirtualization
  │            └─ 否 → 标准设置
  └─ 否 → 使用fileSystemData与本地JSON
           └─ 需要层级组织?
               ├─ 是 → 使用带parentId的嵌套项
               └─ 否 → 使用扁平数据结构

下一步: 选择与当前任务匹配的参考文档,结合代码示例和最佳实践深入实现细节。