workspace/code/file-preview/.trae/documents/add-features-plan.md

功能添加计划

需求分析

用户要求添加两个功能：

功能一：双击事件扩展

• 添加 onDblClick 回调选项，供外部使用
• 如果外部注册了 onDblClick，则优先执行外部回调
• 如果外部未注册 onDblClick，则双击文件时跳转到文件预览页面（fullPreviewUrl）

功能二：onUploadBefore 回调

• 添加 onUploadBefore 回调选项，参考 onBeforeDelete 的实现方式
• 支持返回值类型：
  • false: 阻止上传
  • Promise: 异步确认后再上传
  • Function: 回调确认后再上传
  • 其他/undefined: 继续执行上传
• 同时将 onBeforeDelete 名称修改为 onDeleteBefore

修改文件

1. index.js：
   • 在 defaults 配置中添加 onDblClick 和 onUploadBefore
   • 在 bindEvents 中添加文件项双击事件处理
   • 在 handleUpload 方法中添加 onUploadBefore 逻辑

实现步骤

步骤一：添加配置项

在 defaults 对象中添加：

onDblClick: null,
onUploadBefore: null,

步骤二：添加双击事件处理

在文件列表事件委托中添加双击事件：

// 文件项双击
.on("dblclick", ".g3-file-item", function (e) {
  // 阻止冒泡到子元素
  if ($(e.target).closest(".g3-file-action, .g3-file-checkbox, .g3-file-delete-btn").length) {
    return;
  }
  var id = $(this).data("id");
  var file = self.getFileById(id);
  if (!file) return;
  if (!self.hasPermission(file, "view")) return;
  
  // 如果外部注册了 onDblClick，优先执行外部回调
  if (typeof self.options.onDblClick === "function") {
    self.options.onDblClick(file);
    return;
  }
  
  // 否则跳转到预览页面
  var isUploaded = file.status === "uploaded";
  var isPreviewable = self.isPreviewableFile(file.name);
  var fileUrl = file.url && file.url !== "" ? file.url : null;
  
  if (isUploaded && fileUrl && isPreviewable) {
    var previewUrl = self.options.previewUrl || "";
    var fullPreviewUrl = previewUrl
      ? previewUrl + G3FileUtils.base64Encode(fileUrl)
      : fileUrl;
    window.open(fullPreviewUrl, "_blank");
  }
})

步骤三：添加 onUploadBefore 逻辑

在 handleUpload 方法开头添加：

// onUploadBefore 处理
if (typeof self.options.onUploadBefore === "function") {
  var result = self.options.onUploadBefore(pendingFiles);
  if (result === false) return;
  if (typeof result.then === "function") {
    result.then(function (confirmed) {
      if (confirmed) self.internalHandleUpload(pendingFiles, taskId);
    });
    return;
  }
  if (typeof result === "function") {
    result(function (confirmed) {
      if (confirmed) self.internalHandleUpload(pendingFiles, taskId);
    });
    return;
  }
}

需要将原有的上传逻辑提取为 internalHandleUpload 方法。

风险处理

1. 兼容性风险：确保修改不会影响现有功能
2. 异步处理风险：正确处理 Promise 和回调函数的情况
3. 权限检查：双击事件需要检查 view 权限

测试要点

1. 测试双击文件时：
   • 注册 onDblClick 时是否优先执行外部回调
   • 未注册 onDblClick 时是否正确跳转到预览页面
   • 未上传的文件双击时不跳转
   • 无权限文件双击时不响应
2. 测试上传时：
   • onUploadBefore 返回 false 时是否阻止上传
   • onUploadBefore 返回 Promise 时是否等待异步结果
   • onUploadBefore 返回回调函数时是否正确处理

依赖分析

• 依赖 isPreviewableFile 方法判断文件是否可预览
• 依赖 G3FileUtils.base64Encode 方法编码 URL
• 依赖 getFileById 方法获取文件信息