syncfusion-angular-uploader

实现 Syncfusion Angular Uploader

Syncfusion Angular Uploader（ejs-uploader）是一款功能全面的文件上传组件，支持异步上传、大文件分块上传、拖放、剪贴板粘贴、目录上传、文件验证、模板、表单集成、JWT 身份验证和全面的事件处理。

组件概览

Syncfusion Angular Uploader 提供：

• 异步上传模式： 自动上传（默认）或通过操作按钮手动上传
• 分块上传： 将大文件拆分为可配置字节大小的分块，并支持重试逻辑
• 顺序上传： 每次处理一个文件，以减少服务器流量
• 文件来源： 浏览对话框、拖放、剪贴板粘贴、目录选择
• 验证： 文件类型（扩展名）、最小/最大大小、自定义数量限制、防止重复
• 模板： 自定义文件列表项结构；构建完全自定义的上传 UI
• 表单支持： HTML 表单提交、模板驱动表单（ngModel）、响应式表单（FormGroup）
• 无障碍功能： WCAG 2.2、Section 508、键盘导航、屏幕阅读器支持
• 本地化： 通过 L10n 自定义所有静态文本

文档与导航指南

⚠️ Agent 使用须知： 本指南链接到多个参考文档。AI Agent 应仅阅读与当前任务相关的部分，不要自动遍历所有参考文档。遵循最小权限原则：只获取所需内容。

快速入门

📄 阅读： 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	一次上传一个文件
[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（loaded、total）
(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 开始