syncfusion-angular-uploader（syncfusion Angular uploader 命令行）

Implementing Syncfusion Angular Uploader

The Syncfusion Angular Uploader (ejs-uploader) is a full-featured file upload component that supports asynchronous uploads, chunk uploading of large files, drag-and-drop, clipboard paste, directory upload, file validation, templates, form integration, JWT authentication, and comprehensive event handling.

Component Overview

The Syncfusion Angular Uploader provides:

• Async upload modes: Auto upload (default) or manual upload with action buttons
• Chunk upload: Split large files into configurable byte-size chunks with retry logic
• Sequential upload: Process files one at a time to reduce server traffic
• File sources: Browse dialog, drag-and-drop, clipboard paste, directory selection
• Validation: File type (extensions), min/max size, custom count limits, duplicate prevention
• Templates: Customize the file list item structure; build fully custom upload UIs
• Form support: HTML form submission, template-driven forms (ngModel), reactive forms (FormGroup)
• Accessibility: WCAG 2.2, Section 508, keyboard navigation, screen reader support
• Localization: Customize all static text via L10n

Documentation & Navigation Guide

⚠️ Agentic use note: This guide links to multiple reference documents. AI agents should read only the sections relevant to the task at hand — do not chain through all references automatically. Follow least-privilege reading: fetch only what is needed.

Getting Started

📄 Read: references/getting-started.md

• Installation of @syncfusion/ej2-angular-inputs ⚠️ Always verify the package version and integrity before running npm install in production pipelines (supply-chain hygiene).
• Package setup, CSS imports, and Angular standalone component usage
• Adding the <ejs-uploader> component
• Configuring async settings (saveUrl, removeUrl)
• Handling success and failure events
• Adding a custom drop area

Asynchronous Upload

📄 Read: references/async-upload.md

• Multiple and single file upload modes (multiple property)
• Save action configuration and server-side handling
• Remove action and postRawFile usage
• Auto upload vs manual upload (autoUpload property)
• Sequential upload (sequentialUpload)
• Preloaded files (files property)
• Adding custom HTTP headers to upload requests

Chunk Upload

📄 Read: references/chunk-upload.md

• Enabling chunk upload via asyncSettings.chunkSize
• Pause, resume, and cancel chunk uploads
• Retry configuration (retryCount, retryAfterDelay)
• chunkSuccess and chunkFailure events
• Server-side chunk assembly implementation

File Validation

📄 Read: references/validation.md

• Restricting file types with allowedExtensions
• Min/max file size constraints (minFileSize, maxFileSize)
• Limiting upload count via the selected event
• Preventing duplicate file uploads
• MIME type validation before upload
• Image/* validation on drag-and-drop

File Sources

📄 Read: references/file-sources.md

• Paste images from clipboard
• Directory (folder) upload with directoryUpload
• Drag-and-drop with built-in and custom drop areas
• Custom drop area styling (.e-upload-drag-hover)
• Triggering file browse from an external button

Templates & Custom UI

📄 Read: references/templates-and-custom-ui.md

• File list template with the template property
• Building a completely custom upload UI (hiding default list with showFileList)
• Customizing action buttons with HTML elements (buttons property)
• Customizing the progress bar appearance
• Preview images before uploading
• Resize images before uploading to server

Form Integration

📄 Read: references/form-integration.md

• Using Uploader inside HTML forms (synchronous submission)
• Template-driven forms with ngModel
• Reactive forms with FormGroup
• Required field validation (required attribute)
• Reset behavior with form reset

Styling & Appearance

📄 Read: references/styling-and-appearance.md

• Customizing the uploader wrapper dimensions
• Styling the browse button
• Customizing the drop area text
• Customizing the file list container
• Hiding the default drop area
• CSS class reference for key Uploader elements

Accessibility & Localization

📄 Read: references/accessibility-and-localization.md

• WCAG 2.2, Section 508, keyboard shortcuts
• Screen reader and RTL support
• Localizing all static labels and messages with L10n

Advanced How-To Patterns

📄 Read: references/advanced-patterns.md

• Upload files programmatically with the upload() method
• Invisible (background) upload
• Adding additional form data with customFormData
• JWT authentication for upload/remove requests
• Show confirmation dialog before removing files
• Get total size of selected files
• Sort selected files in the file list
• Open and edit uploaded files from the server
• Convert uploaded images to binary format

API Reference

📄 Read: references/api.md

• Complete properties, methods, and events reference
• AsyncSettingsModel, ButtonsPropsModel, FilesPropModel
• All event argument types and their fields

Quick Start Example

Minimal file uploader with async upload (Angular 21+ standalone):

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 Theme Setup (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';

Common Patterns

Pattern 1: Auto Upload with Drag-and-Drop

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

Pattern 2: Chunk Upload for Large Files

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

Pattern 3: Validated Upload (Type + Size)

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

Pattern 4: Preloaded Files

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

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

Pattern 5: JWT-Authenticated Upload

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

Key Properties

Key Events

Key Methods

Common Use Cases

Use Case 1: Profile Photo Upload

• multiple="false", allowedExtensions=".jpg,.png,.gif,.webp", maxFileSize=5000000
• Use selected event to preview before upload
• Auto upload with progress indicator

Use Case 2: Document Upload Portal

• Multiple files, allowedExtensions=".pdf,.doc,.docx,.xlsx"
• Chunk upload for large files with pause/resume
• Sequential upload to manage server load

Use Case 3: Image Gallery Batch Upload

• Multiple files, directory upload enabled
• Preview thumbnails using selected event + FileReader
• Sort by file name before upload

Use Case 4: Secure File Upload (API-Authenticated)

• JWT token injected via uploading event header
• Custom customFormData to pass metadata
• Server validates token before saving

Use Case 5: Form with Required File

• autoUpload=false, synchronous form submission
• Required attribute validation with data-required-message
• Template-driven or reactive form binding

Next Steps

1. Getting Started → Install package and render basic uploader
2. Async Upload → Configure save/remove URLs and upload modes
3. Validation → Add extension and size constraints
4. Chunk Upload → Handle large files with pause/resume
5. Templates → Customize file list appearance
6. Form Integration → Bind to Angular forms
7. Advanced Patterns → JWT auth, programmatic upload, custom UI
8. API Reference → Full properties, methods, events list

For detailed implementation, start with references/getting-started.md