1
0
mirror of synced 2026-02-08 03:37:49 +08:00
Files
WxJava/docs/CommonUploadParam-FormFields-Usage.md
copilot-swe-agent[bot] 7e34702177 添加使用示例文档
Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>
2026-01-19 03:57:17 +00:00

5.5 KiB
Raw Blame History

CommonUploadParam 额外表单字段功能使用示例

背景

微信公众号在上传永久视频素材时需要在POST请求中同时提交文件和一个名为description的表单字段该字段包含视频的描述信息JSON格式

根据微信公众号文档:

在上传视频素材时需要POST另一个表单id为description包含素材的描述信息内容格式为JSON格式如下

{
    "title": "VIDEO_TITLE",
    "introduction": "INTRODUCTION"
}

解决方案

CommonUploadParam 类已经扩展支持额外的表单字段,可以在上传文件的同时提交其他表单数据。

使用示例

1. 基本用法 - 上传永久视频素材

import me.chanjar.weixin.common.bean.CommonUploadParam;
import me.chanjar.weixin.common.util.json.WxGsonBuilder;
import me.chanjar.weixin.mp.api.WxMpService;

import java.io.File;
import java.util.HashMap;
import java.util.Map;

public class VideoMaterialUploadExample {
  
  public void uploadVideoMaterial(WxMpService wxMpService) throws Exception {
    // 准备视频文件
    File videoFile = new File("/path/to/video.mp4");
    
    // 创建上传参数
    CommonUploadParam uploadParam = CommonUploadParam.fromFile("media", videoFile);
    
    // 准备视频描述信息JSON格式
    Map<String, String> description = new HashMap<>();
    description.put("title", "我的视频标题");
    description.put("introduction", "这是一个精彩的视频介绍");
    String descriptionJson = WxGsonBuilder.create().toJson(description);
    
    // 添加description表单字段
    uploadParam.addFormField("description", descriptionJson);
    
    // 调用微信API上传
    String url = "https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN&type=video";
    String response = wxMpService.upload(url, uploadParam);
    
    System.out.println("上传成功:" + response);
  }
}

2. 链式调用风格

import me.chanjar.weixin.common.bean.CommonUploadParam;
import com.google.gson.JsonObject;

public class ChainStyleExample {
  
  public void uploadWithChainStyle(WxMpService wxMpService) throws Exception {
    File videoFile = new File("/path/to/video.mp4");
    
    // 准备描述信息
    JsonObject description = new JsonObject();
    description.addProperty("title", "视频标题");
    description.addProperty("introduction", "视频介绍");
    
    // 使用链式调用
    String response = wxMpService.upload(
      "https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN&type=video",
      CommonUploadParam.fromFile("media", videoFile)
        .addFormField("description", description.toString())
    );
    
    System.out.println("上传成功:" + response);
  }
}

3. 多个额外表单字段

import me.chanjar.weixin.common.bean.CommonUploadParam;

public class MultipleFormFieldsExample {
  
  public void uploadWithMultipleFields(WxMpService wxMpService) throws Exception {
    File file = new File("/path/to/file.jpg");
    
    // 可以添加多个表单字段
    CommonUploadParam uploadParam = CommonUploadParam.fromFile("media", file)
      .addFormField("field1", "value1")
      .addFormField("field2", "value2")
      .addFormField("field3", "value3");
    
    String response = wxMpService.upload("https://api.weixin.qq.com/some/upload/url", uploadParam);
    
    System.out.println("上传成功:" + response);
  }
}

4. 从字节数组上传并添加表单字段

import me.chanjar.weixin.common.bean.CommonUploadParam;

public class ByteArrayUploadExample {
  
  public void uploadFromBytes(WxMpService wxMpService) throws Exception {
    // 从字节数组创建上传参数
    byte[] fileBytes = getFileBytes();
    
    CommonUploadParam uploadParam = CommonUploadParam
      .fromBytes("media", "video.mp4", fileBytes)
      .addFormField("description", "{\"title\":\"标题\",\"introduction\":\"介绍\"}");
    
    String response = wxMpService.upload(
      "https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN&type=video",
      uploadParam
    );
    
    System.out.println("上传成功:" + response);
  }
  
  private byte[] getFileBytes() {
    // 获取文件字节数组的逻辑
    return new byte[0];
  }
}

API 说明

CommonUploadParam 类

构造方法

  • fromFile(String name, File file) - 从文件创建上传参数
  • fromBytes(String name, String fileName, byte[] bytes) - 从字节数组创建上传参数

方法

  • addFormField(String fieldName, String fieldValue) - 添加额外的表单字段,返回当前对象支持链式调用
  • getFormFields() - 获取所有额外的表单字段Map类型
  • setFormFields(Map<String, String> formFields) - 设置额外的表单字段

属性

  • name - 文件对应的接口参数名称media
  • data - 上传数据CommonUploadData对象
  • formFields - 额外的表单字段可选Map<String, String>类型)

注意事项

  1. 表单字段是可选的:如果不需要额外的表单字段,可以不调用addFormField方法
  2. JSON格式对于需要JSON格式的表单字段如description需要先将对象转换为JSON字符串
  3. 编码表单字段值会使用UTF-8编码
  4. 所有HTTP客户端支持该功能在所有HTTP客户端实现中都得到支持OkHttp、Apache HttpClient、HttpComponents、JoddHttp

兼容性

该功能向后兼容,现有的不使用额外表单字段的代码无需修改即可继续工作。