如何设置 pyecharts Map 数据格式以避免 ValueError: too many values to unpack 错误
在使用 pyecharts 绘制地图（Map）时，很多开发者会遇到 ValueError: too many values to unpack 的错误提示。这个错误通常不是 pyecharts 本身的 bug，而是传入地图组件的数据格式不符合要求导致的。本文将详细说明 Map 组件的数据格式要求，以及如何正确构造数据来避免这个错误。
错误原因分析
pyecharts 的 Map 组件在接收数据时，要求数据必须是可迭代的、每个元素包含两个值的结构，通常是一个列表，列表中的每个元素是长度为 2 的元组或列表，分别对应区域名称和对应数值。
当传入的数据结构不符合这个要求时，比如单个元素包含超过 2 个值，或者数据不是可迭代结构，Map 组件在解析数据时就会触发解包错误，也就是我们看到的 too many values to unpack。
正确数据格式要求
Map 的 add 方法中，data_pair 参数的正确格式需要满足以下条件：
- 整体是一个可迭代对象（通常是列表）
- 可迭代对象中的每个元素是一个长度为 2 的子序列（元组或列表均可）
- 子序列的第一个元素是字符串类型的区域名称（需要和地图底图的名称匹配，比如 "北京" 对应中国地图的北京市）
- 子序列的第二个元素是数值类型的对应数据（可以是整数、浮点数）
符合要求的示例格式如下：
# 正确数据格式示例
data_pair = [
("北京", 100),
("上海", 200),
("广东", 300),
("浙江", 150)
]常见错误写法与修正
错误1：单个元素包含超过2个值
有些开发者会把区域名称、数值、额外信息都放在一个元素里，比如三元组，这时候解包就会出错：
# 错误写法：每个元素是三元组，包含区域、数值、额外备注
wrong_data = [
("北京", 100, "一线城市"),
("上海", 200, "一线城市"),
("广东", 300, "沿海省份")
]
from pyecharts.charts import Map
from pyecharts.options import MapOpts
map_chart = Map()
# 传入错误数据会触发 ValueError: too many values to unpack
map_chart.add("销售额", wrong_data, "china")
map_chart.render()修正方法：只保留区域名称和数值两个字段，去掉多余的额外信息：
# 修正后的正确数据
correct_data = [
("北京", 100),
("上海", 200),
("广东", 300)
]
from pyecharts.charts import Map
map_chart = Map()
map_chart.add("销售额", correct_data, "china")
map_chart.render()错误2：数据不是可迭代结构
如果直接传入两个单独的列表，而不是组合成键值对结构，也会触发错误：
# 错误写法：分开传入区域列表和数值列表
regions = ["北京", "上海", "广东"]
values = [100, 200, 300]
from pyecharts.charts import Map
map_chart = Map()
# 直接传入两个列表不符合 data_pair 要求，会触发解包错误
map_chart.add("销售额", regions, "china")
map_chart.render()修正方法：将两个列表组合成要求的键值对结构，可以用 zip 函数快速处理：
# 修正后的正确数据：用 zip 组合两个列表
regions = ["北京", "上海", "广东"]
values = [100, 200, 300]
correct_data = list(zip(regions, values))
from pyecharts.charts import Map
map_chart = Map()
map_chart.add("销售额", correct_data, "china")
map_chart.render()错误3：区域名称和数据类型不匹配
除了元素数量的问题，区域名称不是字符串、数值不是数字类型也可能间接导致解包错误，比如区域名称用了数字，或者数值用了字符串：
# 错误写法：区域名称用数字，数值用字符串
wrong_data = [
(1, "100"), # 区域名称应该是字符串，数值应该是数字
(2, "200")
]
from pyecharts.charts import Map
map_chart = Map()
map_chart.add("销售额", wrong_data, "china")
map_chart.render()修正方法：统一区域名称为字符串，数值为数字类型：
# 修正后的正确数据
correct_data = [
("北京", 100),
("上海", 200)
]
from pyecharts.charts import Map
map_chart = Map()
map_chart.add("销售额", correct_data, "china")
map_chart.render()完整正确示例
下面是一个完整的、可运行的 Map 绘制示例，数据格式完全符合要求：
from pyecharts.charts import Map
from pyecharts.options import MapOpts, TitleOpts
# 构造符合要求的地图数据
data_pair = [
("北京", 1200),
("上海", 1150),
("广东", 980),
("浙江", 870),
("江苏", 920),
("山东", 760),
("河南", 690),
("四川", 650)
]
# 初始化地图对象
map_chart = Map()
# 添加数据，maptype 指定为中国地图
map_chart.add(
series_name="2023年各省份销售额",
data_pair=data_pair,
maptype="china"
)
# 设置标题
map_chart.set_global_opts(
title_opts=TitleOpts(title="全国各省份销售额分布", pos_left="center"),
visualmap_opts=MapOpts(visualmap_opts={"min_": 500, "max_": 1300}) # 设置视觉映射范围
)
# 渲染生成HTML文件
map_chart.render("map_sales.html")运行上述代码后，会生成 map_sales.html 文件，打开即可看到正确的中国各省份销售额分布地图，不会出现解包错误。
总结
避免 ValueError: too many values to unpack 错误的核心是严格遵循 Map 组件的数据格式要求：传入的 data_pair 必须是每个元素仅包含区域名称（字符串）和对应数值（数字）的可迭代结构。如果遇到错误，可以先打印传入的数据检查每个元素的长度和类型，快速定位问题所在。
pyechartsMap组件数据格式ValueError解包错误 本作品最后修改时间：2026-05-23 22:44:40