Vditor 自定义文件上传处理实践指南

Vditor 作为一款优秀的 Markdown 编辑器，提供了灵活的文件上传机制。本文将详细介绍如何通过自定义上传处理器实现文件上传功能，特别是针对阿里云 OSS 存储服务的集成方案。

核心概念：upload.handler

Vditor 的 upload.handler 是一个强大的回调函数，允许开发者完全接管文件上传流程。当配置了这个处理器后，Vditor 会将文件对象直接传递给开发者，而不是使用内置的上传机制。

实现方案

基础实现结构

自定义上传处理器的基本结构如下：

upload: {
  handler: async (files) => {
    try {
      // 上传逻辑
      const file = files[0];
      // 执行上传操作...
      
      // 返回标准格式的响应
      return {
        msg: '',
        code: 0,
        data: {
          errFiles: [],
          succMap: {
            [file.name]: '上传后的URL'
          }
        }
      };
    } catch (error) {
      return {
        msg: error.message,
        code: 1,
        data: {}
      };
    }
  }
}

阿里云 OSS 集成示例

对于需要与阿里云 OSS 集成的场景，可以这样实现：

upload: {
  handler: async (files) => {
    const file = files[0];
    
    // 1. 获取OSS临时凭证
    const stsData = await getOssSTS();
    
    // 2. 初始化OSS客户端
    const client = new OSS({
      region: 'your-region',
      credentialId: stsData.CredentialId,
      credentialSecret: stsData.CredentialSecret,
      stsToken: stsData.SecurityToken,
      bucket: 'your-bucket'
    });
    
    // 3. 执行上传
    const result = await client.put(file.name, file);
    
    // 4. 返回结果
    return {
      msg: '',
      code: 0,
      data: {
        errFiles: [],
        succMap: {
          [file.name]: result.url
        }
      }
    };
  }
}

关键注意事项

1. 文件插入处理：自定义上传后需要手动处理文件在编辑器中的插入操作，可以通过 vditor.insertValue() 方法实现。

2. 错误处理：务必完善错误处理逻辑，包括凭证获取失败、上传失败等场景。

3. 响应格式：必须按照 Vditor 要求的格式返回响应数据，否则可能导致上传状态显示异常。

4. 性能优化：对于大文件，建议实现分片上传和进度显示功能。

高级技巧

• 文件类型识别：可以根据文件 MIME 类型自动识别是图片还是普通文件，决定是否添加 Markdown 图片标记(!)

• 多文件上传：虽然示例中处理了单个文件，但 handler 接收的是文件数组，可以扩展为支持批量上传

• 本地预览：在上传完成前，可以使用 URL.createObjectURL 生成本地预览

通过合理利用 upload.handler，开发者可以轻松实现各种复杂的文件上传场景，满足企业级应用的需求。