企业官网建设流程全解析

ECharts 5.x 实战：从china.js到官方GeoJSON的平滑迁移指南

如果你正在使用ECharts绘制中国地图，可能已经发现官方不再提供china.js文件下载。这背后是技术生态的一次重要升级——从静态地图文件转向动态GeoJSON数据源。本文将带你彻底告别china.js，掌握更现代、更灵活的官方推荐方案。

1. 为什么必须放弃china.js？

china.js曾是早期ECharts用户绘制中国地图的标配，但这个非官方维护的文件现在暴露出一系列问题：

• 维护停滞：最后一次更新停留在2018年，无法反映最新的行政区划变更
• 兼容性风险：与现代构建工具（如Webpack、Vite）配合时经常出现路径解析问题
• 功能局限：仅包含省级边界，缺乏市县级别精细数据
• 体积臃肿：未压缩版本超过1MB，而GeoJSON可通过按需加载优化

// 典型的china.js使用方式（已过时） import china from './lib/china.js' echarts.registerMap('china', china)

相比之下，官方GeoJSON方案具有显著优势：

提示：ECharts团队在5.0版本后明确推荐使用GeoJSON作为标准地理数据格式

2. 获取权威GeoJSON数据源

正确的地理数据是地图可视化的基础。以下是获取可靠中国地图GeoJSON的三种途径：

2.1 官方推荐渠道

1. 访问 阿里云DataV 地理小工具
2. 选择需要的行政区划级别（全国/省/市）
3. 点击"下载GeoJSON"按钮获取标准格式文件

2.2 通过npm安装

对于工程化项目，更推荐使用@geo-maps包：

npm install @geo-maps/countries-china-zh --save

安装后可通过模块化方式引入：

import chinaGeoJSON from '@geo-maps/countries-china-zh' echarts.registerMap('china', chinaGeoJSON)

2.3 自定义数据处理

当需要特殊区域组合时，可以使用mapshaper工具处理原始数据：

# 合并多个县级区域 mapshaper input.json -dissolve fields=region_id -o output.json

3. 完整配置迁移指南

从china.js切换到GeoJSON后，series配置需要相应调整。以下是关键变化点：

3.1 基础配置对比

旧版china.js配置：

series: [{ type: 'map', mapType: 'china', // 固定值 data: [...] }]

新版GeoJSON配置：

series: [{ type: 'map', map: 'china', // 与registerMap的名称对应 geoIndex: 0, // 当使用多个地理组件时指定索引 data: [...] }]

3.2 数据格式适配

GeoJSON方案要求更规范的数据结构：

// 推荐的数据格式 const data = [ { name: '广东', value: 12345 }, { name: '福建', value: 6789 }, // ... ] // 注册地图 echarts.registerMap('china', geoJSON) // 系列配置 series: [{ type: 'map', map: 'china', emphasis: { label: { show: true }, itemStyle: { areaColor: '#f4b927' } }, data: data }]

3.3 视觉映射优化

利用visualMap组件替代旧的dataRange：

visualMap: { type: 'continuous', min: 0, max: 10000, text: ['高', '低'], inRange: { color: ['#e0f3f8', '#abd9e9', '#74add1', '#4575b4', '#313695'] }, calculable: true }

4. 高级技巧与性能优化

4.1 按需加载策略

对于省级以下地图，可采用动态加载方案：

async function loadProvinceMap(provinceName) { const res = await import(`@geo-maps/provinces/${provinceName}.json`) echarts.registerMap(provinceName, res.default) return provinceName }

4.2 交互增强实现

结合GeoJSON的特性可以实现更丰富的交互：

// 双击下钻到省级 myChart.on('dblclick', params => { if (params.componentType === 'series' && params.seriesType === 'map') { loadProvinceMap(params.name).then(mapName => { myChart.setOption({ series: [{ map: mapName, data: getCityData(params.name) }] }) }) } })

4.3 性能优化方案

1. 简化几何数据：

   mapshaper input.json -simplify 10% -o output.json

2. WebWorker处理：

   // 在worker中处理大数据量 const worker = new Worker('./geoDataProcessor.js') worker.postMessage(geoJSON)

3. Canvas渲染优化：

   series: [{ progressive: 200, progressiveThreshold: 1000 }]

5. 常见问题解决方案

5.1 行政区划不匹配

当数据名称与GeoJSON不匹配时，可以使用nameMap转换：

series: [{ nameMap: { '北京市': '北京', '天津市': '天津', // ... } }]

5.2 特殊区域处理

对于南海诸岛等特殊区域，建议使用单独的配置：

geo: [{ map: 'china', left: '5%', right: '55%' }, { map: 'south-china-sea', left: '65%', top: '60%', width: '30%' }]

5.3 跨版本兼容

如果需要支持旧版ECharts，可以编写适配层：

function registerLegacyMap(echarts, name, geoJSON) { if (echarts.version[0] >= 5) { echarts.registerMap(name, geoJSON) } else { echarts.registerMap(name, convertToJS(geoJSON)) } }

在实际项目中迁移时，建议先在新分支上测试GeoJSON方案的兼容性。我曾在某大数据平台项目中，通过逐步替换策略，用三周时间完成了从china.js到GeoJSON的无缝迁移，最终使地图加载性能提升了40%。