echarts 切换省

补充说明

以下是基于 ECharts 5.x（2026 更新） 整理的「省市区地图切换」完整教程，兼容旧代码的核心需求（点击省份选中、切换地图、更新内容区域），同时适配现代前端开发方式。

ECharts 5.x 省市区地图切换完整教程（2026最新）

大家好，这里是我的前端技术博客。
最近帮业务方做数据可视化大屏，需要实现「中国地图→省份地图→市区地图」的三级联动切换，翻到了 2016 年的旧代码，发现 ECharts 从 2.x 到 5.x 变化太大了——旧版用 RequireJS 引入，地图数据内置；新版需要单独引入 GeoJSON，API 也全面升级。
今天就把旧代码的核心需求（点击选中、地图切换、内容更新），用 ECharts 5.x 重新实现一遍，附完整可运行代码，跟着步骤走就能做出流畅的省市区三级联动地图。

一、先搞懂：ECharts 5.x 地图的核心变化

对比 2016 年的 ECharts 2.x 旧代码，5.x 有三个必须知道的核心变化：

引入方式变化：不再推荐 RequireJS，直接用 CDN 或 npm 引入；
地图数据变化：ECharts 5.x 不再内置地图数据，需要单独引入 GeoJSON 或 JSON 格式的地图数据；
API 变化：mapType、事件绑定、地图注册的 API 都有调整，旧代码无法直接运行。

二、前置准备：2步搞定环境与数据

1. 引入 ECharts 5.x

方式1：CDN 快速引入（适合快速测试/简单页面）

1 2	`<!-- 引入 ECharts 5.x 核心库 --> <script src="https://cdn.jsdelivr.net/npm/echarts@5.5.1/dist/echarts.min.js"></script>`

方式2：npm 安装（适合工程化项目/Vue/React）

1	`npm install echarts --save`

1 2	`// 工程化项目中引入 import * as echarts from 'echarts';`

2. 获取地图数据（关键，90%的问题来自这里）

ECharts 5.x 不再内置地图，需要自己准备 GeoJSON 数据，推荐两个可靠来源：

阿里云 DataV 地图选择器（推荐，免费下载省市区三级 GeoJSON）：https://datav.aliyun.com/portal/school/atlas/area_selector
ECharts 官方旧地图数据仓库（备用）：https://github.com/apache/echarts/tree/master/test/data

本文示例使用阿里云 DataV 的数据，下载后保存为 china.json（中国地图）、hubei.json（湖北省地图）、wuhan.json（武汉市地图），放到项目的 map-data 文件夹下。

三、完整实现：省市区三级联动切换

话不多说，直接上完整可运行的代码，复制到 HTML 文件中打开就能看到效果：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>ECharts 5.x 省市区地图切换</title>
    <!-- 引入 ECharts 5.x -->
    <script src="https://cdn.jsdelivr.net/npm/echarts@5.5.1/dist/echarts.min.js"></script>
    <style>
        /* 地图容器：必须有明确的宽高 */
        #map-container {
            width: 100%;
            height: 600px;
            margin: 20px 0;
        }
        /* 内容展示区域 */
        #info-panel {
            text-align: center;
            padding: 20px;
            background: #f5f5f5;
            border-radius: 8px;
            margin: 0 20px;
        }
        /* 返回按钮 */
        #back-btn {
            display: none; /* 默认隐藏，进入省份/市区后显示 */
            padding: 10px 20px;
            background: #1890ff;
            color: white;
            border: none;
            border-radius: 4px;
            cursor: pointer;
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
    <div style="max-width: 1200px; margin: 0 auto; padding: 20px;">
        <!-- 返回按钮 -->
        <button id="back-btn">返回上一级</button>
        <!-- 地图容器 -->
        <div id="map-container"></div>
        <!-- 内容展示区域 -->
        <div id="info-panel">
            <h2 id="area-name">中国</h2>
            <p id="area-content">点击地图上的省份，进入该省份地图查看详情</p>
        </div>
    </div>

    <script>
        // 1. 初始化 ECharts 实例
        const chartDom = document.getElementById('map-container');
        const myChart = echarts.init(chartDom);

        // 2. 全局状态管理：当前地图级别、当前选中区域
        let currentLevel = 'country'; // country（国家）→ province（省份）→ city（市区）
        let currentArea = 'china';
        let mapDataCache = {}; // 地图数据缓存，避免重复请求

        // 3. 地图数据映射表：根据区域名匹配对应的 GeoJSON 文件路径
        // 实际项目中可以用接口动态获取，这里用本地路径示例
        const mapPathMap = {
            'china': './map-data/china.json',
            '湖北省': './map-data/hubei.json',
            '武汉市': './map-data/wuhan.json'
            // 可以继续添加其他省份/市区的映射
        };

        // 4. 核心函数：加载并注册地图数据
        async function loadAndRegisterMap(areaName) {
            // 如果缓存中有，直接返回
            if (mapDataCache[areaName]) {
                return mapDataCache[areaName];
            }
            // 从映射表中获取路径
            const mapPath = mapPathMap[areaName];
            if (!mapPath) {
                alert(`暂无 ${areaName} 的地图数据`);
                return null;
            }
            // 异步加载 GeoJSON 数据
            try {
                const response = await fetch(mapPath);
                const geoJSON = await response.json();
                // 注册地图：ECharts 5.x 用 registerMap 注册
                echarts.registerMap(areaName, geoJSON);
                // 存入缓存
                mapDataCache[areaName] = geoJSON;
                return geoJSON;
            } catch (error) {
                console.error('地图数据加载失败：', error);
                alert('地图数据加载失败，请检查路径');
                return null;
            }
        }

        // 5. 核心函数：生成地图配置
        function getMapOption(areaName, mapType) {
            return {
                title: {
                    text: areaName,
                    left: 'center',
                    top: 10
                },
                tooltip: {
                    trigger: 'item',
                    formatter: '{b}' // 鼠标悬停显示区域名
                },
                visualMap: {
                    min: 0,
                    max: 100,
                    left: 'left',
                    top: 'bottom',
                    text: ['高', '低'],
                    calculable: true,
                    inRange: {
                        color: ['#e0f3f8', '#abd9e9', '#74add1', '#4575b4', '#313695'] // 颜色渐变
                    }
                },
                series: [
                    {
                        name: areaName,
                        type: 'map',
                        map: mapType, // ECharts 5.x 用 map 替代旧版的 mapType
                        roam: true, // 开启缩放和平移
                        selectedMode: 'single', // 单选模式（点击选中）
                        label: {
                            show: true, // 显示区域名称
                            fontSize: 12
                        },
                        emphasis: {
                            label: {
                                show: true,
                                fontSize: 14
                            },
                            itemStyle: {
                                areaColor: '#ffd700' // 鼠标悬停颜色
                            }
                        },
                        // 模拟数据：实际项目中替换为你的业务数据
                        data: [
                            { name: '湖北省', value: 80 },
                            { name: '武汉市', value: 90 }
                        ]
                    }
                ]
            };
        }

        // 6. 核心函数：更新内容展示区域
        function updateInfoPanel(areaName) {
            document.getElementById('area-name').innerText = areaName;
            document.getElementById('area-content').innerText = `${areaName} 的详细内容区域，可在这里展示业务数据、图表等`;
        }

        // 7. 核心函数：切换地图
        async function switchMap(areaName) {
            // 加载并注册地图
            const geoJSON = await loadAndRegisterMap(areaName);
            if (!geoJSON) return;

            // 生成配置并渲染
            const option = getMapOption(areaName, areaName);
            myChart.setOption(option, true); // true 表示不合并配置，完全替换

            // 更新内容区域
            updateInfoPanel(areaName);

            // 控制返回按钮显示
            const backBtn = document.getElementById('back-btn');
            backBtn.style.display = currentLevel === 'country' ? 'none' : 'block';
        }

        // 8. 绑定地图点击事件：实现三级联动
        myChart.on('click', async function (params) {
            const clickedArea = params.name;
            if (!clickedArea) return;

            // 根据当前级别判断下一级
            if (currentLevel === 'country') {
                // 从中国地图点击进入省份地图
                currentLevel = 'province';
                currentArea = clickedArea;
                await switchMap(clickedArea);
            } else if (currentLevel === 'province') {
                // 从省份地图点击进入市区地图
                currentLevel = 'city';
                currentArea = clickedArea;
                await switchMap(clickedArea);
            }
            // 市区地图点击后可以继续下钻，或者展示详情
        });

        // 9. 绑定返回按钮事件
        document.getElementById('back-btn').addEventListener('click', async function () {
            if (currentLevel === 'city') {
                // 从市区返回省份
                currentLevel = 'province';
                // 这里需要根据当前省份重新设置 currentArea，实际项目中可以用栈记录历史
                // 简化示例：直接返回中国地图
                currentLevel = 'country';
                currentArea = 'china';
                await switchMap('china');
            } else if (currentLevel === 'province') {
                // 从省份返回中国
                currentLevel = 'country';
                currentArea = 'china';
                await switchMap('china');
            }
        });

        // 10. 初始化：加载中国地图
        switchMap('china');

        // 11. 响应窗口大小变化
        window.addEventListener('resize', function () {
            myChart.resize();
        });
    </script>
</body>
</html>

四、核心 API 详解：对比旧代码的变化

为了方便大家从旧代码迁移，我把核心变化整理成了表格：

功能	ECharts 2.x 旧代码	ECharts 5.x 新代码
地图类型配置	`mapType: 'china'`	`map: 'china'`
地图注册	无需注册（内置）	`echarts.registerMap(areaName, geoJSON)`
事件绑定	`myChart.on(ecConfig.EVENT.MAP_SELECTED, ...)`	`myChart.on('click', ...)`（直接用事件名）
引入方式	RequireJS + `paths` 配置	CDN 或 npm 直接引入
地图数据	内置	需单独引入 GeoJSON

五、常见问题排查

1. 地图不显示

检查地图容器是否有明确的宽高（必须是块级元素，宽高不能为 0）；
检查地图数据路径是否正确，打开浏览器控制台看是否有 404 错误；
检查是否调用了 echarts.registerMap() 注册地图数据（这是 5.x 最容易忘的一步）。

2. 点击事件不触发

检查 selectedMode 是否设置为 'single' 或 'multiple'；
检查是否在 setOption() 之后绑定的事件（建议先绑定事件，再 setOption()）。

3. 地图缩放/平移不流畅

确保 roam 设置为 true；
如果地图数据太大，建议简化 GeoJSON（可以用 mapshaper 工具：https://mapshaper.org/）。

六、写在最后

虽然 ECharts 从 2.x 到 5.x 变化很大，但核心思想是一致的——数据驱动视图。旧代码里的「点击选中、内容更新、地图切换」需求，在新版里用更简洁的 API 就能实现，而且性能更好、功能更强大。

学无止境

echarts 切换省

https://cszy.top/2016-05-10 echarts省市区图/

作者

csorz

发布于

2016年5月10日

许可协议

echarts迁徙图上一篇

javascript编码规范下一篇