syncfusion-angular-file-manager

Syncfusion Angular File Manager コンポーネントの実装

File Manager は、ファイルシステムを管理するための強力なグラフィカルユーザーインターフェイスコンポーネントです。直感的なインターフェイスと包括的なナビゲーション機能により、ユーザーはファイルやフォルダーへのアクセス、編集、並べ替え、アップロード、ダウンロード、整理などの基本的なファイル操作を実行できます。

このスキルを使用する場面

次のような場合は、File Manager コンポーネントを使用してください。

• ファイルシステム内のファイルやフォルダーを参照および移動する
• ファイル操作（作成、削除、名前変更、アップロード、ダウンロード）を実行する
• ファイルを表示する（詳細表示、大きなアイコン表示）
• ドラッグ＆ドロップによるファイル管理を実装する
• 仮想化を使用して大規模なファイルセットを効率的に処理する
• ツールバー、コンテキストメニュー、ファイル表示をカスタマイズする
• 複数選択、並べ替え、ローカライズに対応する
• Azure Blob Storage または Amazon S3 用のバックエンドプロバイダーサービスを Docker 経由でデプロイする

コンポーネントの概要と主な機能

コア機能

• ファイル操作：ファイルの読み取り、作成、削除、名前変更、アップロード、ダウンロード
• ナビゲーション：パンくずリストによるナビゲーション、ナビゲーションペイン、フォルダー階層
• 表示オプション：詳細表示（並べ替えられたリスト）と大きなアイコン表示（サムネイル表示）
• ユーザー操作：複数選択、ドラッグ＆ドロップ、右クリックのコンテキストメニュー
• パフォーマンス：大規模なファイルセット向けの UI 仮想化、状態の永続化
• カスタマイズ：ツールバー／コンテキストメニューのカスタマイズ、CSS テーマ設定、カスタムアイコン
• アクセシビリティ：RTL 対応、ローカライズ、ARIA 属性

アーキテクチャ

• ajaxSettings を介したサーバーベースのファイル操作
• または fileSystemData（フラットまたはネストされた JSON）を使用したクライアントサイドのデータバインディング
• 機能モジュール：ナビゲーションペイン、ツールバー、詳細表示、仮想化
• カスタムワークフロー向けのイベント駆動型アーキテクチャ

ドキュメントとナビゲーションガイド

API リファレンス（API の詳細はこちらから）

📄 参照： references/api-reference-complete.md

• 説明付きのコンポーネントプロパティ全項目
• クライアントサイドバインディング用の FileData インターフェイス
• 設定モデルとベストプラクティス
• サービスプロバイダーとユーティリティ関数

メソッドとイベントのリファレンス

📄 参照： references/methods-and-events.md

• すべてのコンポーネントメソッドの一覧と例
• イベント引数を含むすべてのコンポーネントイベント
• イベントパラメーターのインターフェイスと説明
• 各メソッドとイベントの実用的な例

はじめに

📄 参照： references/getting-started.md

• 前提条件（Angular 4+、TypeScript 2.6+）
• Angular プロジェクトのセットアップと CLI コマンド
• パッケージのインストール（Ivy と ngcc の互換性）
• CSS テーマのインポートとスタイル設定
• 基本的なコンポーネントの初期化
• ajaxSettings の設定（ファイル操作、ダウンロード、アップロード、プレビュー URL）
• 初期表示とコンポーネントのレンダリング

ファイル操作

📄 参照： references/file-operations.md

• コア操作：読み取り、作成、削除、名前変更、アップロード、ダウンロード、コピー、移動
• ファイルシステムプロバイダーの設定
• サーバー統合のパターン
• カスタムファイルプロバイダー（Google Drive、Amazon S3、Azure）
• ディレクトリーのアップロード対応
• エラー処理と検証
• リクエスト／レスポンスのパターン

リクエストとレスポンスのパラメーター

📄 参照： references/request-response-parameters-reference.md

• 全 11 種類の操作に対応するレスポンスパラメーターの完全な一覧
• 各操作のリクエスト構造とパラメーター
• レスポンス形式と構造の仕様
• FileManagerDirectoryContent インターフェイスの定義
• DetailsObject とエラーレスポンスの形式
• すべての操作のリクエスト／レスポンス例
• エラーコードとエラー処理のパターン
• 共通データ構造とインターフェイス
• バックエンド実装のベストプラクティス

アップロードのカスタマイズ

📄 参照： references/upload-customizations.md

• ディレクトリのアップロード設定（directoryUpload プロパティ）
• 順次アップロードの設定（sequentialUpload プロパティ）
• 大容量ファイルのチャンクアップロード（chunkSize の設定）
• 自動アップロード動作の制御
• ファイルサイズの検証（minFileSize、maxFileSize）
• ファイル形式の制限（allowedExtensions）
• アップロードイベント（beforeSend、onSuccess、onFailure）
• バックエンドの実装例（ASP.NET Core）
• 画像のみ、ドキュメント、完全なアップロード設定を扱う実践的な例 3 件

ビューとレイアウト

📄 参照： references/views-and-layout.md

• 詳細ビュー（列付きの並べ替え可能なファイル一覧）
• 大きなアイコンビュー（サムネイル表示）
• ビューの動的な切り替え、または初期化時の設定
• 初期ビューの設定
• スタイル設定のための CSS クラスのカスタマイズ
• ビューごとの設定と構成

ナビゲーション機能

📄 参照： references/navigation-features.md

• パンくずナビゲーション（フォルダー階層の追跡）
• ナビゲーションペインの設定（フォルダーツリー付きの左サイドバー）
• パスの指定と動的なナビゲーション
• フォルダー階層の探索
• ナビゲーション要素の表示／非表示

データ構造

📄 参照： references/data-structures.md

• フラットな JSON データバインディング（バックエンド不要）
• ネストされた項目（ローカルデータ内のフォルダー階層）
• fileData インターフェースとプロパティ（name、size、date、isFile、hasChild など）
• parentId による親子関係
• フラット方式とネスト方式の比較およびトレードオフ
• サーバーベースのデータとクライアントサイドのデータ

ネストされた項目の統合

📄 参照： references/nested-items-integration.md

• ファイル選択パターンを使ったダイアログのネスト
• タブのネスト（各タブに複数の File Managers を配置）
• スプリッターのネスト（横並びのレイアウト）
• アコーディオンのネスト（カテゴリ別のファイルアクセス）
• 複数のネストされた File Manager の状態管理
• 高さの計算方法
• 寸法管理のベストプラクティス
• 実践的な例 2 件：ファイルアップロードダイアログ、タブ式のファイル管理

ドラッグ＆ドロップ

📄 参照： references/drag-and-drop.md

• ドラッグ＆ドロップ機能の有効化
• ドロップ先の設定
• ドラッグによるファイル移動操作
• ドラッグイベントの処理（fileDragStart、fileDragging、fileDragStop、fileDropped）
• 制約とドロップの制限
• ドラッグ操作中の視覚的なフィードバック

仮想化

📄 参照： references/virtualization.md

• UI 仮想化とは何か、およびパフォーマンス上の利点
• モジュールの注入（VirtualizationService）
• 仮想化の有効化（enableVirtualization プロパティ）
• 大量のファイル（数百〜数千件）の処理
• メモリの最適化とスクロールのパフォーマンス
• 詳細ビューおよび大きなアイコンビューでの仮想スクロール

並べ替えとフィルタリング

📄 参照： references/sorting-and-filtering.md

• sortComparer 関数によるカスタムの並べ替え
• 自然な並べ替え（Windows Explorer のような動作）
• 並べ替え順（昇順／降順）
• 詳細ビューでの複数列の並べ替え
• 列ごとの sortComparer 定義
• インポートした sortComparer ユーティリティ、またはカスタム実装

ツールバーのカスタマイズ

📄 参照： references/toolbar-customization.md

• ツールバーの設定と項目
• デフォルトのツールバー項目（NewFolder、Upload、View、Refresh、Cut、Copy、Paste、Delete、Download、Rename）
• テンプレートを使ったカスタムツールバー項目の追加
• ツールバー項目のプロパティの変更
• ツールバーアイコン（Syncfusion、Font Awesome、カスタム SVG）
• テンプレートベースのツールバー項目（チェックボックス、ドロップダウン）
• ツールバーのクリックイベントとイベント処理
• 選択内容に応じたツールバー項目の表示

コンテキストメニューのカスタマイズ

📄 参照： references/context-menu-customization.md

• デフォルトのコンテキストメニュー項目（開く、切り取り、コピー、貼り付け、削除、名前の変更、ダウンロード）
• カスタムコンテキストメニュー項目の追加
• ファイル、フォルダー、レイアウトのコンテキストメニュー設定
• メニューイベント（menuOpen、menuClose、menuClick）
• メニューの動的な変更と条件付き項目
• メニュー項目へのアイコンの追加
• カスタムメニューアクションと実装
• サブメニューのサポート

アクセス制御と権限

📄 参照： references/access-control-and-permissions.md

• 権限モデルと FileData の権限構造
• ロールベースのアクセス制御（RBAC）の実装
• ファイルレベルおよびフォルダーレベルの権限
• バックエンドの権限ルール設定
• Permission 列挙型（Allow/Deny）を使用したアクセスルール
• フロントエンドでの権限処理と UI の無効化
• 管理者、編集者、閲覧者のロール例
• 監査ログとコンプライアンス

認証とカスタム値

📄 参照： references/authentication-and-custom-values.md

• 認証ヘッダーを追加する beforeSend イベント
• JWT トークン認証の実装
• ベアラートークンのパターン
• カスタムヘッダー（API キー、リクエスト ID、相関 ID）
• リクエストを使用したカスタムデータの受け渡し
• クエリパラメーターと本文データ
• CORS の設定とクロスオリジンリクエスト
• OAuth2 トークンの更新パターン
• マルチテナントのファイルマネージャーのセットアップ
• 監査証跡とリクエストのログ記録

カスタムファイルプロバイダー

📄 参照： references/custom-file-provider.md

• カスタムファイルプロバイダーのアーキテクチャ
• 必須の API エンドポイント（FileOperations、Upload、Download、GetImage）
• リクエスト／レスポンス形式の仕様
• ASP.NET Core によるカスタムバックエンドの実装
• Azure Blob Storage との統合
• AWS S3 との統合
• データベースを利用したファイルシステム（SQL）
• Google Drive およびクラウドストレージのパターン
• ICustomFileService インターフェイスの実装

Docker のデプロイ

📄 参照： references/docker-deployment.md

• Azure Blob Storage と Amazon S3 に対応した統合ファイルマネージャープロバイダーの Docker イメージ
• FILEMANAGER_PROVIDER 環境変数によるストレージプロバイダーの選択
• Docker、Azure Storage、Amazon S3 の前提条件
• AZURE_* および AWS_* 設定用の環境変数リファレンス
• docker-compose.yml を使用した Docker デプロイの手順
• 公開済みの syncfusion/filemanager-provider イメージのプル
• http://localhost:5000/api/Test によるサービスの確認
• コンテナー化されたサービスを参照するよう Angular クライアントの ajaxSettings を設定
• 一般的なデプロイ、ポートマッピング、DNS の問題のトラブルシューティング

高度な機能

📄 参照： references/advanced-features.md

• ファイルとフォルダーの複数選択
• 状態の永続化（enablePersistence プロパティ）
• ページの再読み込み後もビュー、パス、選択項目を維持
• Ajax イベント（success、failure）
• コンポーネントのライフサイクル（created イベント）
• ファイル操作のプログラムによる更新
• 一括操作での複数ファイル選択

UI のカスタマイズ

📄 参照： references/ui-customizations.md

• 大きなアイコンのカスタマイズ（サイズ、レイアウト、スタイル）
• ファイルの種類に応じたカスタムアイコンのマッピング
• showFileExtension プロパティと動的な制御
• showHiddenItems の設定とサーバー側のフィルタリング
• ファイル情報を含むツールチップのカスタマイズ
• allowMultiSelection による選択の制御と単一選択／複数選択の切り替え
• 複数選択の制限パターン
• showThumbnail：サムネイル表示の制御（大規模なコレクション向けのパフォーマンス調整）
• showItemCheckBoxes：選択チェックボックスの有効化（モバイルでの使いやすさとアクセシビリティ）
• enableHtmlSanitizer：XSS 攻撃を防ぐセキュリティプロパティ（重要：有効なままにしてください）
• popupTarget：ポップアップ／ダイアログのコンテナーを指定（ネストされたファイルマネージャーで必須）
• CSS パターンと高度な設定を含む、15 件以上の動作するコード例
• UI カスタマイズの完全な例

ナビゲーション項目のカスタマイズ

📄 参照： references/navigation-items-customization.md

• navigationPaneTemplate の基本的な使い方と高度な使い方
• 階層スタイルを使ったカスタム項目のレンダリング
• アイコンとバッジの統合パターン
• ナビゲーション項目の CSS スタイル設定方法
• 動的なテーマの適用（ライト／ダークの切り替え）
• パスに応じたアイコンのカスタマイズ
• プロフェッショナルなナビゲーションデザインのパターン
• 包括的なプロフェッショナルナビゲーションの例 1 件

カスタマイズとスタイル設定

📄 参照： references/customization-styling.md

• CSS クラスのカスタマイズ（cssClass プロパティ）
• テーマのカスタマイズと Theme Studio の統合
• カスタムサムネイル（showThumbnail プロパティ）
• ファイルとフォルダーのカスタムアイコン表示
• レスポンシブデザインとコンテナーのサイズ設定
• 高度なスタイル設定の例
• CSS 変数のオーバーライド

ローカライズと RTL

📄 参照： references/localization-and-rtl.md

• 右から左へ記述する言語（RTL）のサポート（enableRtl プロパティ）
• ローカライズライブラリ（l10）の統合
• 言語の設定と切り替え
• カスタムテキストとメッセージのローカライズ
• 地域に応じた日付／時刻の書式設定

クイックスタートの例

基本的なファイルマネージャーのセットアップ

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: 'url',
    getImageUrl: 'url',
    uploadUrl: 'url',
    downloadUrl: 'url'
  };
}

ローカル JSON データを使用する場合（バックエンドなし）

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: { [key: string]: Object }[] = [
    {
      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')
    }
  ];
}

よくあるパターン

パターン 1：完全な設定によるサーバー統合

使用する場面： バックエンドサービスを備えた本番環境向けのファイルマネージャーを構築する場合

// 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']
};

パターン 2：カスタム書式を使用したローカルデータ

使用する場面： データは API から取得するものの、バックエンドのファイル操作が不要な場合

API のレスポンスを fileData 形式に変換します：

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)
}));

パターン 3：大規模データセット向けの仮想化

使用する場面： 1,000 件以上のファイルを扱う場合

// Inject VirtualizationService, enable enableVirtualization
providers: [VirtualizationService]

// In template
<ejs-filemanager 
  [enableVirtualization]="true"
  [view]="'Details'"
  ...>
</ejs-filemanager>

パターン 4：アクションを伴う複数選択

使用する場面： ファイルの一括操作が必要な場合

onDownloadSelected() {
  const selected = this.fileManager.selectedItems;
  // Download multiple files (server returns ZIP)
}

主なプロパティと設定

コア設定

プロパティ	型	用途
ajaxSettings	AjaxSettingsModel	ファイル操作用のサーバーエンドポイント（url、uploadUrl、downloadUrl、getImageUrl）
fileSystemData	FileData[]	ローカル JSON データ（ajaxSettings の代替）
path	string	最初に表示するディレクトリのパス
view	ViewType	初期表示モード：'Details' または 'LargeIcons'
height	string | number	コンポーネントの高さ
width	string | number	コンポーネントの幅

選択と複数選択

プロパティ	型	用途
allowMultiSelection	boolean	Ctrl+クリックおよび Shift+クリックによる選択を有効化
enableRangeSelection	boolean	ドラッグによる選択を有効化（Windows エクスプローラー形式）

ファイル操作

プロパティ	型	用途
allowDragAndDrop	boolean	ドラッグ＆ドロップによるファイル移動を有効化
uploadSettings	UploadSettingsModel	アップロード設定（maxFileSize、minFileSize、autoUpload、allowedExtensions、directoryUpload）
searchSettings	SearchSettingsModel	検索設定（filterType、allowSearchOnTyping、caseSensitive）

表示とパフォーマンス

プロパティ	型	用途
showThumbnail	boolean	画像のサムネイルを表示します
showHiddenItems	boolean	隠しファイルとフォルダーを表示／非表示にします（デフォルト：false）
showFileExtension	boolean	ファイル拡張子を表示します（デフォルト：true）
enableVirtualization	boolean	大量のファイル（1000 件以上）を仮想化します
enablePersistence	boolean	表示、パス、選択した項目を永続化します
enableRtl	boolean	右から左へのレイアウトをサポートします
enableHtmlSanitizer	boolean	セキュリティのために HTML をサニタイズします

UI のカスタマイズ

プロパティ	型	用途
toolbarSettings	ToolbarSettingsModel	ツールバーの項目と表示設定
navigationPaneSettings	NavigationPaneSettingsModel	左側のサイドバーの設定
contextMenuSettings	ContextMenuSettingsModel	右クリックメニューのカスタマイズ
detailsViewSettings	DetailsViewSettingsModel	詳細ビューの列と並べ替え
navigationPaneTemplate	string | object	ナビゲーションノードのカスタムテンプレート
largeIconsTemplate	string | object	大きなアイコン表示用のカスタムテンプレート
cssClass	string	テーマ設定用の CSS クラス
locale	string	ローカライズのカルチャ（例：'de-DE'、'ja-JP'）

並べ替えと比較

プロパティ	型	用途
sortComparer	Function	カスタムの並べ替え関数（Windows エクスプローラーのような並べ替えが可能）

アプローチを選ぶための判断ツリー

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

---

次のステップ： 現在のタスクに合ったリファレンスを選び、コード例とベストプラクティスを参考に実装の詳細を確認してください。