syncfusion-angular-uploader

用途

Syncfusion Angular Uploader（组件标签为 ejs-uploader）是用于在 Angular 应用中实现文件上传的组件，覆盖单文件与多文件上传、异步上传、大文件分块上传、拖拽与剪贴板粘贴、目录上传、文件校验、模板自定义、表单集成、JWT 认证以及事件处理等需求。

主要能力

上传模式：异步上传支持自动上传（默认）或通过操作按钮手动上传；支持顺序上传（一次处理一个文件）以降低服务器压力；支持 preloaded files（files 属性）展示服务器已有文件。
分块上传：通过 asyncSettings.chunkSize 将大文件拆分为可配置字节大小的分块，支持暂停、恢复、取消以及重试配置（retryCount、retryAfterDelay），并提供 chunkSuccess 与 chunkFailure 事件；文档说明涉及服务端分块组装实现。
文件来源：浏览对话框、拖拽放置（内置或自定义放置区）、剪贴板粘贴图片、目录（文件夹）上传（directoryUpload）。
校验：通过 allowedExtensions 限制扩展名，minFileSize/maxFileSize 限制体积，可在 selected 事件中限制上传数量、防止重复文件，支持上传前 MIME 类型校验以及拖拽时的 image/* 校验。
模板与自定义 UI：用 template 属性自定义文件列表项；通过 showFileList 隐藏默认列表以构建完全自定义上传界面；通过 buttons 属性自定义操作按钮；可自定义进度条外观、上传前预览图片、上传前压缩图片尺寸。
表单集成：可在 HTML 表单内使用（同步提交），支持 ngModel 模板驱动表单、FormGroup 响应式表单、required 必填校验以及表单 reset 行为。
可访问性与本地化：符合 WCAG 2.2、Section 508，支持键盘导航、屏幕阅读器与 RTL，可通过 L10n 本地化全部静态文案。
外观定制：可定制上传组件容器尺寸、浏览按钮样式、放置区文案、文件列表容器，并可隐藏默认放置区，文档提供关键元素的 CSS 类参考。

使用方式

安装包为 @syncfusion/ej2-angular-inputs，需引入组件与样式。文档中的最小示例使用 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);
  }
}

样式在 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';

文档给出的常见模式包括：自动上传配合拖拽（设置 dropArea、multiple）、大文件分块上传（asyncSettings.chunkSize，例如 500000 字节）、类型与体积校验上传（allowedExtensions、minFileSize、maxFileSize）、预加载文件（files）、JWT 认证上传（在 uploading/removing 事件中通过 args.currentRequest.setRequestHeader 添加 Authorization 头）。文档提示：不要硬编码令牌，应从安全认证服务获取，并始终通过 HTTPS 传输、不要将令牌作为 URL 查询参数。

关键属性与事件

关键属性包括 asyncSettings（AsyncSettingsModel，默认 saveUrl/removeUrl 为空）、autoUpload（默认 true）、multiple（默认 true）、allowedExtensions（默认空）、minFileSize（默认 0）、maxFileSize（默认 30000000，约 28.6 MB）、files、dropArea、directoryUpload（默认 false）、sequentialUpload（默认 false）、showFileList（默认 true）、template、buttons、enabled、cssClass、enableRtl、enableHtmlSanitizer（默认 true，防止文件名 XSS）、dropEffect。

关键事件覆盖 selected、uploading、success、failure、progress、removing、beforeRemove、beforeUpload、change、clearing、chunkSuccess、chunkFailure、chunkUploading、pausing、resuming、canceling、fileListRendering、actionComplete、created。

关键方法包括 upload、remove、cancel、pause、resume、retry、clearAll、getFilesData、createFileList、sortFileList、bytesToSize、destroy。

适用场景

文档列出的典型用例包括：头像上传（单文件、限制图片扩展名与体积、selected 事件预览、自动上传配合进度提示）；文档上传门户（多文件、限制办公文档扩展名、分块上传配合暂停恢复、顺序上传控制服务器负载）；图库批量上传（多文件、目录上传、selected + FileReader 预览缩略图、上传前按文件名排序）；安全文件上传（通过 uploading 事件注入 JWT、用 customFormData 传递元数据、服务端校验令牌）；带必填文件的表单（autoUpload=false、同步表单提交、required 校验、模板驱动或响应式表单绑定）。

限制与注意事项

服务端保存与移除接口（saveUrl、removeUrl）以及分块上传的服务端组装逻辑需要自行实现，文档未提供具体服务端代码。分块上传的默认上限、错误恢复细节未在资料中给出。npm 安装在生产流水线中应先验证包版本与完整性。组件为 Syncfusion 商业组件，但资料未提供收费、价格或授权信息。文档同时提示 AI 代理应遵循最小必要阅读原则，只读取与任务相关的章节，不要自动串联全部引用文档。