Ember File Upload 升级指南：从 v4 到 v8 的全面解析

前言

Ember File Upload 是一个强大的文件上传解决方案，随着版本的迭代，项目在架构和 API 设计上有了显著改进。本文将详细解析从 v4 到 v8 的主要变更点，帮助开发者顺利完成升级。

v8 版本升级要点

新增 peerDependencies 依赖

v8 版本将以下包调整为 peerDependencies：

• @ember/test-helpers
• @glimmer/component
• @glimmer/tracking
• ember-modifier
• tracked-built-ins

这意味着你的应用需要自行安装这些依赖。对于新创建的 Ember 应用，这些包通常已经默认包含。

安装命令示例：

# 使用 pnpm
pnpm add --save-dev @ember/test-helpers @glimmer/component @glimmer/tracking ember-modifier tracked-built-ins

# 使用 npm
npm install --save-dev @ember/test-helpers @glimmer/component @glimmer/tracking ember-modifier tracked-built-ins

# 使用 Yarn
yarn add --dev @ember/test-helpers @glimmer/component @glimmer/tracking ember-modifier tracked-built-ins

v7 版本升级要点

模块导入方式变更

v7 版本重构了模块导出方式，所有公共模块现在都从包顶层导出。

变更示例：

// v6 及之前版本
import UploadFile from 'ember-file-upload/upload-file';
import Queue from 'ember-file-upload/queue';

// v7 及之后版本
import { UploadFile, Queue } from 'ember-file-upload';

Mirage 处理器重命名

为了提升代码清晰度，Mirage 处理器被重命名：

// v6 及之前版本
import { upload } from 'ember-file-upload/mirage';

// v7 及之后版本
import { uploadHandler } from 'ember-file-upload';

v6 版本升级要点

v6 版本移除了 v5 中的所有废弃 API。如果你已经按照 v5 的升级指南进行了调整，升级到 v6 将无需额外修改。

v5 版本升级要点

文件验证机制变更

移除了通过 @accept 参数验证文件的方式，推荐使用自定义验证方案。

FileUpload 组件重构

出于可访问性和 DOM 灵活性的考虑，v5 废弃了 <FileUpload> 组件，改用 queue.selectFile 修饰器。

新旧对比示例：

{{! v4 语法 }}
<FileUpload
  @name="photos"
  @onFileAdd={{this.uploadPhoto}}
  @for="upload-photo"
  @accept="image/*"
  @multiple={{true}}
>
  <a tabindex="0">选择照片</a>
</FileUpload>

{{! v5 语法 }}
{{#let (file-queue name="photos" onFileAdded=this.uploadPhoto) as |queue|}}
  <label for="upload-photo">
    <span role="button" tabindex="0" aria-controls="upload-photo">
      选择照片
    </span>
  </label>
  <input
    type="file"
    id="upload-photo"
    accept="image/*"
    multiple
    hidden
    {{queue.selectFile}}
  >
{{/let}}

最佳实践建议：考虑使用可见的文件输入控件以简化模板并提升可访问性。

FileDropzone 组件变更

• 移除了 @accept 参数，推荐使用自定义验证
• 移除了 @disabled 参数，应在应用代码中控制上传状态
• 移除了 @allowUploadsFromWebsites 参数
• 推荐使用 @queue 参数直接传递队列
• HTML 属性现在直接应用于 Dropzone 元素

新旧对比示例：

{{! v4 语法 }}
<FileDropzone
  @name="photos"
  @onFileAdd={{this.uploadPhoto}}
  @accept="image/*"
  @class="photo-dropzone"
  as |dropzone|
>
</FileDropzone>

{{! v5 语法 }}
{{#let (file-queue name="photos" onFileAdded=this.uploadPhoto) as |queue|}}
  <FileDropzone
    @queue={{queue}}
    @filter={{this.validatePhoto}}
    class="photo-dropzone"
    as |dropzone|
  >
  </FileDropzone>
{{/let}}

File 类重命名

为避免与原生 File 类冲突，File 类被重命名为 UploadFile。

// v4
import File from 'ember-file-upload/file';

// v5+
import UploadFile from 'ember-file-upload/upload-file';

升级策略建议

1. 逐步升级：建议按照版本顺序逐步升级，先升级到 v5，解决所有废弃 API 问题，再升级到 v6，最后升级到 v7 和 v8。

2. 测试覆盖：升级过程中应确保有充分的测试覆盖，特别是文件上传和验证相关功能。

3. 代码审查：重点关注以下变更点：

   • 文件验证逻辑
   • 文件上传组件的使用方式
   • 模块导入路径
   • 依赖管理

4. 性能考量：新版本在性能上有所优化，升级后可进行适当的性能测试。

常见问题解答

Q：为什么 v5 要移除 FileUpload 组件？ A：主要是出于可访问性考虑，同时提供更灵活的 DOM 结构控制能力。新的修饰器方案让开发者可以完全控制文件输入元素的呈现方式。

Q：自定义文件验证应该如何实现？ A：可以通过 filter 回调函数实现，该函数接收文件对象并返回布尔值表示是否接受该文件。

Q：升级到 v8 后出现依赖错误怎么办？ A：确保已安装所有 peerDependencies，并检查版本兼容性。如有疑问，可参考 Ember 官方文档中的依赖管理指南。

结语

Ember File Upload 的版本演进反映了 Ember 生态系统的最佳实践发展方向。通过本文的升级指南，开发者可以系统性地了解各版本变更，制定合理的升级计划。最新版本提供了更灵活的 API 设计、更好的可访问性支持以及更清晰的模块结构，值得投入时间进行升级。