地图 Map

地图 Map：空间数据可视化的基础

小象实战讲义 · ECharts 数据可视化

在数据分析中，我们常常会遇到与地理位置相关的数据，例如各省份的销售额、全球各国的用户分布等。将这些数据在地图上直观地呈现出来，能够极大地提升我们对空间分布模式的理解。本节我们将学习如何使用 pyecharts 中的 Map 图表，将你的地理数据转化为交互式的地图可视化。

💡 核心导读

• 地图资源准备：当前锁定的 pyecharts 2.1.0 环境默认从 assets.pyecharts.org/assets/v6/ 加载地图 JS；本课资源包提供 china / world / guangdong / zhejiang 等本地地图文件。
• 地图类型选择：通过 maptype 参数指定要绘制的地图范围，如 "china"（中国省级）、"world"（世界国家）、"广东"（广东省市级）。
• 数据格式要求：数据需为 [[地区名, 数值], …] 的列表形式，地区名必须与对应地图文件中的名称严格匹配；本课 china.js 使用“广东省 / 北京市”这类完整行政区名称。
• 基础配置与交互：使用 VisualMap（视觉映射）为数值映射颜色，图表天然支持缩放、拖拽和鼠标悬停查看详情等交互。

1. 地图数据：一切可视化的前提

在 pyecharts 中，地图的绘制依赖浏览器端加载底图 JS。当前锁定环境的 CurrentConfig.ONLINE_HOST 实测为 https://assets.pyecharts.org/assets/v6/；课程附件已经把常用地图文件放在本地 assets/maps/，避免依赖已经变化的在线证书与 CDN。

1.1 使用课程附带的本地地图资源

离线运行时，把 CurrentConfig.ONLINE_HOST 指向包含 echarts.min.js 和 maps/ 的本地 assets/ 目录：

from pyecharts.globals import CurrentConfig
CurrentConfig.ONLINE_HOST = "assets/"

课程资源至少包含：

assets/
├── echarts.min.js
├── echarts-gl.min.js
└── maps/
    ├── china.js
    ├── world.js
    ├── guangdong.js
    └── zhejiang.js

不要再安装旧的 echarts-*-pypkg 地图包：那套方式与当前 pyecharts 2.1.0 的资源加载路径不同，容易造成“代码能建图、HTML 却没有地图”。

1.2 理解 maptype 与数据匹配

maptype 参数决定了你绘制哪一幅地图。关键在于，你提供的数据中的“地区名称”必须与所选 maptype 对应的官方名称完全一致。

例如，绘制中国省级地图时，maptype="china"；本课 china.js 的区域名是“广东省”、“北京市”、“上海市”这类完整名称。其他地图文件可能使用不同命名，必须以实际 JS 中的区域名为准。

pyecharts/datasets/map_filename.json 只列出“地图名称 → JS 文件名”的映射，例如 "广东" → "guangdong"，不包含地图内部区域清单。具体区域名称需要查看对应地图 JS 的 name 字段。

2. 绘制你的第一张中国地图

让我们从最常用的中国省级地图开始。首先，我们需要准备符合格式要求的数据。

from pyecharts import options as opts
from pyecharts.charts import Map

# 这是完整的中国省级地图示例
map_data = [
    ["北京市", 120],
    ["上海市", 98],
    ["广东省", 156],
    ["浙江省", 77],
    ["四川省", 61],
]

china_map = (
    Map()
    .add(
        series_name="销量",
        data_pair=map_data,
        maptype="china",
        label_opts=opts.LabelOpts(is_show=False),
        is_map_symbol_show=False,
    )
    .set_global_opts(
        title_opts=opts.TitleOpts(title="中国区域销量分布（模拟数据）"),
        visualmap_opts=opts.VisualMapOpts(min_=50, max_=160, is_piecewise=True),
    )
)

print("图表类型:", type(china_map).__name__)
print("省级数据数量:", len(map_data))
print("地图类型:", "china")

图表类型: Map
省级数据数量: 5
地图类型: china

把 CurrentConfig.ONLINE_HOST 指向本地资源并调用 .render("china_map.html") 后，可在浏览器查看交互地图。鼠标悬停在省份上可查看数值，滚轮缩放、拖拽平移；VisualMap 会把数值映射为区域颜色。

3. 扩展：世界地图与省级地图

掌握了中国地图的绘制方法后，绘制世界地图或特定省份的地图就轻而易举了，核心在于更换 maptype 和匹配对应的地区数据。

3.1 世界地图

将 maptype 改为 “world”，并提供国家名称和对应数值。

from pyecharts import options as opts
from pyecharts.charts import Map

world_data = [
    ["China", 135],
    ["Canada", 68],
    ["Brazil", 107],
    ["Russia", 145],
    ["United States", 77],
]

world_map = (
    Map()
    .add(
        "人口（模拟）",
        world_data,
        "world",
        label_opts=opts.LabelOpts(is_show=False),  # 关闭国家名称标签，避免重叠
    )
    .set_global_opts(
        title_opts=opts.TitleOpts(title="世界人口分布模拟图"),
        visualmap_opts=opts.VisualMapOpts(max_=150)
    )
)

print("世界地图数据样例:")
for item in world_data[:5]:
    print(f"  {item}")
print("世界地图配置完成。")
print("地图类型: world")
print("国家数量:", len(world_data))

世界地图数据样例:
  ['China', 135]
  ['Canada', 68]
  ['Brazil', 107]
  ['Russia', 145]
  ['United States', 77]
世界地图配置完成。
地图类型: world
国家数量: 5

3.2 省级（如广东）地图

要绘制某个省份的详细地图，maptype 直接设置为省份名称，如 "广东"。省级地图通常精确到地级市；若需显示区县，应改用对应城市名作为 maptype。

from pyecharts import options as opts
from pyecharts.charts import Map

guangdong_data = [
    ["广州市", 140],
    ["深圳市", 143],
    ["珠海市", 99],
    ["佛山市", 118],
    ["汕头市", 91],
]

gd_map = (
    Map()
    .add(
        "热度指数",
        guangdong_data,
        "广东",
        label_opts=opts.LabelOpts(is_show=False),
        is_map_symbol_show=False,
    )
    .set_global_opts(
        title_opts=opts.TitleOpts(title="广东省各城市热度指数模拟"),
        visualmap_opts=opts.VisualMapOpts(max_=150)
    )
)

print("广东省地图数据样例:")
for item in guangdong_data[:5]:
    print(f"  {item}")
print("广东省地图配置完成。")
print("地图类型: 广东")
print("城市数量:", len(guangdong_data))

广东省地图数据样例:
  ['广州市', 140]
  ['深圳市', 143]
  ['珠海市', 99]
  ['佛山市', 118]
  ['汕头市', 91]
广东省地图配置完成。
地图类型: 广东
城市数量: 5

4. 进阶配置：自定义视觉映射

VisualMap 是地图中非常强大的组件，除了简单的连续映射，还支持分段映射，可以将数值范围划分为几个区间，每个区间赋予不同的颜色和标签，使得数据层级更加清晰。

# 示例：使用分段型视觉映射 (VisualMap)
from pyecharts import options as opts

# 这是一个配置示例，展示了如何定义分段
visualmap_opts=opts.VisualMapOpts(
    is_piecewise=True,  # 开启分段模式
    pieces=[
        {"min": 0, "max": 50, "label": "0-50", "color": "#FFEFEF"},
        {"min": 51, "max": 100, "label": "51-100", "color": "#FFA39E"},
        {"min": 101, "max": 200, "label": "101-200", "color": "#FF4D4F"},
    ]
)

将此 visualmap_opts 配置替换到之前任意一个地图的 .set_global_opts() 中，地图就会根据你定义的区间和颜色进行渲染。

📝 动手练一练

1. 数据匹配练习：尝试绘制一张“浙江省”地图。请先思考 maptype 应该设置为什么，数据中的地区名应使用省级、市级还是县级名称。请使用资源包中的 zhejiang.js，并用下面这组市级数据：杭州 450、宁波 380、温州 290、嘉兴 220、湖州 180。

from pyecharts import options as opts
from pyecharts.charts import Map

zhejiang_data = [
    ["杭州市", 450],
    ["宁波市", 380],
    ["温州市", 290],
    ["嘉兴市", 220],
    ["湖州市", 180],
]

zhejiang_map = (
    Map()
    .add("指标", zhejiang_data, "浙江", label_opts=opts.LabelOpts(is_show=False))
    .set_global_opts(
        title_opts=opts.TitleOpts(title="浙江省城市数据展示"),
        visualmap_opts=opts.VisualMapOpts(max_=500),
    )
)

print("浙江省地图已创建，maptype=浙江，数据级别为市级。")

浙江省地图已创建，maptype=浙江，数据级别为市级。

2. 自定义分段地图：修改“中国地图”的示例，使用分段型视觉映射，将数值分为“低 (0-70)”、“中 (71-120)”、“高 (121-200)”三个区间，并分别指定浅绿、黄色、红色。

from pyecharts import options as opts
from pyecharts.charts import Map

map_data = [
    ["北京市", 60],
    ["广东省", 110],
    ["浙江省", 185],
]

china_map_piecewise = (
    Map()
    .add("销量", map_data, "china")
    .set_global_opts(
        title_opts=opts.TitleOpts(title="中国销量分布（分段显示）"),
        visualmap_opts=opts.VisualMapOpts(
            is_piecewise=True,
            pieces=[
                {"min": 0, "max": 70, "label": "低", "color": "#D9F7BE"},
                {"min": 71, "max": 120, "label": "中", "color": "#FFF1B8"},
                {"min": 121, "max": 200, "label": "高", "color": "#FFCCC7"},
            ]
        )
    )
)

本章小结

本节我们学习了使用 pyecharts Map 图表进行空间数据可视化的基础流程。关键在于准备好本地地图资源、选择正确的 maptype，以及确保数据区域名与地图 JS 中的名称精确匹配。Map 图表非常适合展示与地理区域相关的数值分布，形成“地理热力图”的效果。

📋 行动清单

• 确认本地 assets/maps/ 中已有目标地图 JS，并设置 CurrentConfig.ONLINE_HOST。
• 将地理数据整理成 [["地区名", 数值], ...] 的标准格式，并核对区域名称。
• 尝试绘制国家、省份等不同层级的地图，并添加 VisualMap 组件来增强数据的视觉表现力。

—— 小象教研组