syncfusion-angular-uploader

Syncfusion Angular Uploader の実装

Syncfusion Angular Uploader（ejs-uploader）は、非同期アップロード、大容量ファイルのチャンクアップロード、ドラッグ＆ドロップ、クリップボードからの貼り付け、ディレクトリアップロード、ファイル検証、テンプレート、フォーム連携、JWT 認証、包括的なイベント処理に対応した、多機能なファイルアップロードコンポーネントです。

コンポーネントの概要

Syncfusion Angular Uploader では、次の機能を利用できます。

• 非同期アップロードモード： 自動アップロード（デフォルト）、またはアクションボタンを使った手動アップロード
• チャンクアップロード： 大容量ファイルを設定可能なバイトサイズのチャンクに分割し、再試行ロジックを適用
• 順次アップロード： ファイルを1つずつ処理してサーバーへのトラフィックを削減
• ファイルの取得元： ファイル選択ダイアログ、ドラッグ＆ドロップ、クリップボードからの貼り付け、ディレクトリの選択
• 検証： ファイル形式（拡張子）、最小／最大サイズ、カスタム件数上限、重複防止
• テンプレート： ファイルリスト項目の構造をカスタマイズし、完全にカスタムなアップロード UI を構築
• フォームサポート： HTML フォームの送信、テンプレート駆動フォーム（ngModel）、リアクティブフォーム（FormGroup）
• アクセシビリティ： WCAG 2.2、Section 508、キーボード操作、スクリーンリーダーのサポート
• ローカライズ： L10n を使ってすべての静的テキストをカスタマイズ

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

⚠️ エージェント利用時の注意： このガイドでは複数のリファレンスドキュメントにリンクしています。AI エージェントは、作業内容に関連するセクションのみを読み、すべてのリファレンスを自動的に次々と読み進めないでください。最小権限の原則に従い、必要なものだけを取得してください。

はじめに

📄 参照先： references/getting-started.md

• @syncfusion/ej2-angular-inputs のインストール ⚠️ 本番パイプラインで npm install を実行する前に、パッケージのバージョンと完全性を必ず確認してください（サプライチェーンの衛生管理）。
• パッケージのセットアップ、CSS のインポート、Angular のスタンドアロンコンポーネントの使用
• <ejs-uploader> コンポーネントの追加
• 非同期設定（saveUrl、removeUrl）の構成
• 成功イベントと失敗イベントの処理
• カスタムドロップエリアの追加

非同期アップロード

📄 参照先： references/async-upload.md

• 複数ファイルおよび単一ファイルのアップロードモード（multiple プロパティ）
• 保存アクションの構成とサーバー側での処理
• 削除アクションと postRawFile の使用
• 自動アップロードと手動アップロード（autoUpload プロパティ）
• 順次アップロード（sequentialUpload）
• 事前読み込みファイル（files プロパティ）
• アップロードリクエストへのカスタム HTTP ヘッダーの追加

チャンクアップロード

📄 参照先： references/chunk-upload.md

• asyncSettings.chunkSize によるチャンクアップロードの有効化
• チャンクアップロードの一時停止、再開、キャンセル
• 再試行の構成（retryCount、retryAfterDelay）
• chunkSuccess イベントと chunkFailure イベント
• サーバー側でのチャンク結合の実装

ファイル検証

📄 参照先： references/validation.md

• allowedExtensions によるファイル形式の制限
• ファイルの最小／最大サイズ制限（minFileSize、maxFileSize）
• selected イベントによるアップロード件数の制限
• ファイルの重複アップロードの防止
• アップロード前の MIME タイプ検証
• ドラッグ＆ドロップ時の Image/* 検証

ファイルの取得元

📄 参照先： references/file-sources.md

• クリップボードからの画像の貼り付け
• directoryUpload によるディレクトリ（フォルダー）のアップロード
• 組み込みおよびカスタムドロップエリアを使ったドラッグ＆ドロップ
• カスタムドロップエリアのスタイル設定（.e-upload-drag-hover）
• 外部ボタンからのファイル選択の起動

テンプレートとカスタム UI

📄 参照先： references/templates-and-custom-ui.md

• template プロパティによるファイルリストテンプレート
• 完全にカスタムなアップロード UI の構築（showFileList によるデフォルトリストの非表示）
• HTML 要素によるアクションボタンのカスタマイズ（buttons プロパティ）
• プログレスバーの表示のカスタマイズ
• アップロード前の画像プレビュー
• サーバーへのアップロード前の画像のリサイズ

フォーム連携

📄 参照： references/form-integration.md

• HTML フォーム内での Uploader の使用（同期送信）
• ngModel を使用したテンプレート駆動フォーム
• FormGroup を使用したリアクティブフォーム
• 必須フィールドの検証（required 属性）
• フォームのリセット時の動作

スタイルと外観

📄 参照： references/styling-and-appearance.md

• アップローダーのラッパーのサイズのカスタマイズ
• 参照ボタンのスタイル設定
• ドロップエリアのテキストのカスタマイズ
• ファイルリストのコンテナーのカスタマイズ
• デフォルトのドロップエリアを非表示にする
• Uploader の主要な要素の CSS クラスリファレンス

アクセシビリティとローカライズ

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

• WCAG 2.2、Section 508、キーボードショートカット
• スクリーンリーダーと RTL のサポート
• L10n ですべての静的ラベルとメッセージをローカライズ

高度な使い方のパターン

📄 参照： references/advanced-patterns.md

• upload() メソッドでプログラムからファイルをアップロードする
• 非表示（バックグラウンド）アップロード
• customFormData で追加のフォームデータを追加する
• アップロード／削除リクエストでの JWT 認証
• ファイルを削除する前に確認ダイアログを表示する
• 選択したファイルの合計サイズを取得する
• ファイルリスト内の選択したファイルを並べ替える
• サーバー上のアップロード済みファイルを開いて編集する
• アップロードした画像をバイナリ形式に変換する

API リファレンス

📄 参照： references/api.md

• プロパティ、メソッド、イベントの完全なリファレンス
• AsyncSettingsModel、ButtonsPropsModel、FilesPropModel
• すべてのイベント引数の型とそのフィールド

クイックスタートの例

非同期アップロードを使用する最小構成のファイルアップローダー（Angular 21 以降のスタンドアロン）：

import { Component } from '@angular/core';
import { UploaderModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  imports: [UploaderModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-uploader
      [asyncSettings]="asyncSettings"
      [autoUpload]="false"
      (success)="onSuccess($event)"
      (failure)="onFailure($event)">
    </ejs-uploader>
  `
})
export class AppComponent {
  public asyncSettings = {
    saveUrl: 'https://your-api/upload/save',
    removeUrl: 'https://your-api/upload/remove'
  };

  onSuccess(args: any): void {
    console.log('Upload operation:', args.operation, 'File:', args.file.name);
  }

  onFailure(args: any): void {
    console.error('Upload failed:', args.file.name);
  }
}

CSS テーマの設定（styles.css）：

@import 'node_modules/@syncfusion/ej2-base/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import 'node_modules/@syncfusion/ej2-angular-inputs/styles/material3.css';

よくあるパターン

パターン 1：ドラッグ＆ドロップで自動アップロード

// Automatically uploads dropped or browsed files
<ejs-uploader
  [asyncSettings]="asyncSettings"
  [dropArea]="dropElement"
  [multiple]="true"
  (success)="onSuccess($event)">
</ejs-uploader>

パターン 2：大容量ファイルのチャンクアップロード

<ejs-uploader
  [asyncSettings]="chunkSettings"
  (chunkSuccess)="onChunkSuccess($event)"
  (chunkFailure)="onChunkFailure($event)">
</ejs-uploader>

// In component:
chunkSettings = {
  saveUrl: 'https://your-api/upload/save',
  removeUrl: 'https://your-api/upload/remove',
  chunkSize: 500000  // 500 KB chunks
};

パターン 3：検証付きアップロード（種類＋サイズ）

<ejs-uploader
  [asyncSettings]="asyncSettings"
  allowedExtensions=".jpg,.png,.pdf"
  [minFileSize]="1024"
  [maxFileSize]="5000000">
</ejs-uploader>

パターン 4：事前読み込み済みファイル

<ejs-uploader
  [asyncSettings]="asyncSettings"
  [files]="preloadedFiles">
</ejs-uploader>

// In component:
preloadedFiles = [
  { name: 'report', size: 200000, type: '.pdf' },
  { name: 'photo', size: 500000, type: '.jpg' }
];

パターン 5：JWT 認証によるアップロード

<ejs-uploader
  [asyncSettings]="asyncSettings"
  (uploading)="addAuthHeader($event)"
  (removing)="addAuthHeader($event)">
</ejs-uploader>

// ⚠️ Never hardcode tokens — always retrieve from a secure auth service (e.g., Angular AuthService or OAuth library).
// ⚠️ Always transmit tokens over HTTPS only. Never pass tokens as URL query parameters.
addAuthHeader(args: any): void {
  args.currentRequest.setRequestHeader('Authorization', `Bearer ${this.token}`);
}

主なプロパティ

プロパティ	型	デフォルト	用途
[asyncSettings]	AsyncSettingsModel	{saveUrl:'',removeUrl:''}	サーバーの保存／削除 URL とチャンク設定
[autoUpload]	boolean	true	ファイル選択時にすぐアップロードする
[multiple]	boolean	true	複数ファイルの選択を許可する
[allowedExtensions]	string	''	許可する拡張子（カンマ区切り、例：.jpg,.png）
[minFileSize]	number	0	最小ファイルサイズ（バイト）
[maxFileSize]	number	30000000	最大ファイルサイズ（バイト、約 28.6 MB）
[files]	FilesPropModel[]	[]	サーバーから事前読み込みするファイル
[dropArea]	string | HTMLElement	null	カスタムのドロップ対象要素またはセレクター
[directoryUpload]	boolean	false	フォルダー／ディレクトリーのアップロードを有効にする
[sequentialUpload]	boolean	false	ファイルを 1 つずつアップロードする
[showFileList]	boolean	true	デフォルトのファイルリストを表示／非表示にする
[template]	any	null	ファイルリスト項目のカスタムテンプレート
[buttons]	ButtonsPropsModel	{browse,clear,upload}	ボタンのテキスト／HTML をカスタマイズする
[enabled]	boolean	true	コンポーネントを有効または無効にする
[cssClass]	string	''	ルート要素に追加する CSS クラス
[enableRtl]	boolean	false	右から左への表示
[enableHtmlSanitizer]	boolean	true	ファイル名による XSS を防止する
[dropEffect]	DropEffect	'Default'	ドラッグ効果：Copy、Move、Link、None

主要イベント

イベント	発生するタイミング	主な引数
(selected)	ファイルが選択またはドロップされたとき	filesData, cancel, modifiedFilesData
(uploading)	各ファイルのアップロード開始前	fileData, currentRequest, customFormData, cancel
(success)	アップロードまたは削除が成功したとき	file, operation (upload|remove), event
(failure)	アップロードまたは削除が失敗したとき	file, operation, event
(progress)	アップロードの進行中	file, event (読み込み済み、合計)
(removing)	ファイル削除リクエストの前	filesData, postRawFile, currentRequest
(beforeRemove)	削除確認の前	filesData, cancel
(beforeUpload)	アップロード処理の前	fileData, customFormData
(change)	ファイルリストが変更されたとき	file
(clearing)	すべてクリアする操作の前	cancel
(chunkSuccess)	各チャンクのアップロード成功時	chunkIndex, totalChunk, chunkSize, file
(chunkFailure)	各チャンクのアップロード失敗時	chunkIndex, totalChunk, chunkSize, file, cancel
(chunkUploading)	各チャンクのアップロード前	fileData, currentRequest, customFormData
(pausing)	チャンクのアップロードが一時停止されたとき	file, chunkIndex
(resuming)	チャンクのアップロードが再開されたとき	file, chunkIndex
(canceling)	アップロードがキャンセルされたとき	file
(fileListRendering)	各ファイル項目のレンダリング前	element, fileInfo
(actionComplete)	すべてのファイルの処理完了時	fileData
(created)	コンポーネントの初期化時	—

主なメソッド

メソッド	目的
upload(files?, custom?)	選択したファイルまたは指定したファイルのアップロードをプログラムから開始します
remove(fileData?, custom?, postRawFile?)	リストまたはサーバーからファイルを削除します
cancel(fileData?)	進行中のチャンクアップロードをキャンセルします
pause(fileData?, custom?)	チャンクアップロードを一時停止します
resume(fileData?, custom?)	一時停止中のチャンクアップロードを再開します
retry(fileData?, fromCanceledStage?, custom?)	失敗またはキャンセルされたアップロードを再試行します
clearAll()	リストからすべてのファイルをクリアします
getFilesData(index?)	リストに表示されているファイルデータ配列を取得します
createFileList(fileData)	プログラムからファイルリスト項目を作成します
sortFileList(filesData?)	ファイルリストをアルファベット順に並べ替えます
bytesToSize(bytes)	バイト数を人が読みやすい KB／MB 形式の文字列に変換します
destroy()	コンポーネントを破棄してイベントを切り離します

よくあるユースケース

ユースケース 1：プロフィール写真のアップロード

• multiple="false"、allowedExtensions=".jpg,.png,.gif,.webp"、maxFileSize=5000000
• selected イベントを使用して、アップロード前にプレビューします
• 進行状況インジケーター付きの自動アップロード

ユースケース 2：ドキュメントアップロードポータル

• 複数ファイル、allowedExtensions=".pdf,.doc,.docx,.xlsx"
• 大きなファイルには一時停止／再開機能付きのチャンクアップロードを使用します
• サーバー負荷を管理するために順次アップロードします

ユースケース 3：画像ギャラリーの一括アップロード

• 複数ファイル、ディレクトリアップロードを有効化
• selected イベントと FileReader を使用してサムネイルをプレビューします
• アップロード前にファイル名で並べ替えます

ユースケース 4：セキュアなファイルアップロード（API 認証）

• uploading イベントのヘッダーを介して JWT トークンを挿入します
• カスタムの customFormData でメタデータを渡します
• 保存前にサーバーでトークンを検証します

ユースケース 5：必須ファイル付きフォーム

• autoUpload=false、同期フォーム送信
• data-required-message を使用した必須属性の検証
• テンプレート駆動またはリアクティブフォームのバインディング

次のステップ

1. はじめに → パッケージをインストールし、基本的なアップローダーをレンダリングします
2. 非同期アップロード → 保存／削除 URL とアップロードモードを設定します
3. 検証 → 拡張子とサイズの制約を追加します
4. チャンクアップロード → 一時停止／再開機能で大きなファイルを処理します
5. テンプレート → ファイルリストの外観をカスタマイズします
6. フォーム連携 → Angular フォームにバインドします
7. 高度なパターン → JWT 認証、プログラムからのアップロード、カスタム UI
8. API リファレンス → プロパティ、メソッド、イベントの全一覧

---

実装の詳細については、references/getting-started.md から始めてください