Flutter Dio包中如何为MapEntry传入Map类型表单字段值

开发者阿泽

2026-8-27

问题原因

Dio内置的FormData类中，fields属性的类型为List<MapEntry<String, String>>，强制要求所有存入的字段值必须是String类型，直接传入Map类型值会触发类型不匹配的编译错误。这也符合multipart/form-data表单的标准规范：普通表单字段仅支持字符串类型的值，不存在原生的复杂结构传值能力。

解决方案

根据后端接口的解析规则，二选一即可：

方案1：将Map序列化为JSON字符串（通用首选）

绝大多数后端接口接收表单中的复杂结构字段时，都要求字段值为JSON格式的字符串，你只需要用Dart内置的JSON转换方法把Map转成字符串传入即可。

首先在文件头部引入dart:convert依赖：
```
import 'dart:convert';
```

替换原来报错的代码段，对Map做JSON序列化：

formData.fields.add(MapEntry('category', _category));
formData.fields.add(MapEntry('license_number', _licenseNumber.text));
formData.fields.add(MapEntry('license_issued_on', _licenseIssueDateString));
// 将Map序列化为JSON字符串传入
formData.fields.add(MapEntry(
  'address',
  jsonEncode({
    'address': _address.text,
    'lattitude': _addressLat,
    'longitude': _addressLng
  })
));

方案2：拆分为带层级标识的平级字段

如果后端要求按照传统表单的嵌套字段规则（通过父键[子键]的命名格式标识层级）接收数据，就把Map里的每一个属性拆成独立的表单字段，注意所有非字符串类型的值都要手动转成String：

formData.fields.add(MapEntry('category', _category));
formData.fields.add(MapEntry('license_number', _licenseNumber.text));
formData.fields.add(MapEntry('license_issued_on', _licenseIssueDateString));
// 拆分嵌套Map为平级字段
formData.fields.add(MapEntry('address[address]', _address.text));
formData.fields.add(MapEntry('address[lattitude]', _addressLat.toString()));
formData.fields.add(MapEntry('address[longitude]', _addressLng.toString()));