做地图专题图的朋友，大概率都接过这样的需求：把某个省的所有地级市，用不同颜色块铺满，再把每个城市名字标上去，一眼就能看出全省的分布格局。用天地图API 4.0来实现，说简单也简单，说坑也是真的多。我第一次提交时，色块和底图整整偏了几公里，边界对不上、文字乱飞，排查了大半天才发现是坐标系在作祟。这篇文章就把“天地图API 4.0 + geojson + 全省市级色块 + 文字标记”这条链路完整拆开来讲，从数据准备、代码实现到性能优化和常见问题，一次性说透。
不管你是做政府项目、农业普查、人口统计，还是单纯的兴趣项目，只要想在天地图上做省市级的专题色块图，这篇文章都能直接当参考手册用。文中代码以四川省21个市州为例，但逻辑完全通用，换成任何一个省都只需要换数据和中心点坐标。
1. 内容整体设计与思路拆解
1.1 一句话说清这个需求要解决什么
需求拆开来看，其实是三件事：把天地图底图加载出来，把省市级行政区边界用geojson数据渲染成色块，再把城市名称标注在色块中心。单独任何一件都不难，难的是三件事拼在一起时，各种细节容易翻车。
先说说为什么需要geojson这个中间层。天地图API本身只是提供底图瓦片和基础覆盖物能力，它并不知道“四川省有21个市州”这件事。你必须自己准备一份描述边界的数据，告诉地图渲染引擎“这个多边形是成都，那个多边形是绵阳”。geojson就是这个通用交换格式，它用FeatureCollection来组织多个行政区，每个Feature的geometry字段存坐标环，properties字段里塞区域名称、编码、统计数据等属性。
我见过很多新手直接跳过数据检查，拿一份网上下载的geojson就往页面上怼，结果要么边界整体偏移、要么渲染出来一团乱麻。所以整个项目的第一设计决策，不是写代码，而是先保证数据靠谱。
1.2 方案选型：官方API原生实现还是叠加第三方库
天地图API 4.0提供了覆盖物体系，包括多边形和文字标注。用它来实现色块和文字，本质上是一个“数据格式转换”的过程，把geojson的Geometry结构转成TMap的MultiPolygon和MultiLabel能识别的结构。
但实际操作中，业内还有另一条路：把天地图瓦片当作底图，再用Leaflet或OpenLayers做数据图层叠加，很多教程也这么教。这个方案的优势是可视化生态丰富，样式定制灵活，适合复杂交互的项目。缺点是额外引一个框架，二开成本和对官方API的熟悉度要求都不一样。
我的建议是：如果需求就是“全省色块+城市名”，老老实实用天地图API 4.0的原生类就够了。MultiPolygon本身就是为批量化多边形渲染设计的，性能比逐个new Polygon再addTo好一个数量级；MultiLabel同理。直接用官方API，少引依赖、少踩框架版本冲突的坑，以后升级维护也方便。如果后期需求膨胀到需要复杂弹窗、数据联动、图表分析，再考虑引入其他库也不迟。
1.3 核心流程：底图 → 数据解析 → 色块 → 文字
整个实现的流程用文字描述是这样的：
- 在页面初始化天地图底图，设置中心点和缩放级别。
- 通过fetch或axios异步加载本地的geojson文件。
- 遍历FeatureCollection，把每个feature的geometry坐标提取出来，转换成TMap.MultiPolygon需要的paths数组格式。
- 为每个城市分配一个颜色样式，生成色块图层并add到地图上。
- 遍历所有城市，计算每个多边形的地理中心点坐标，生成TMap.MultiLabel文字标注。
- 配合地图事件或扩展需求，加上悬浮提示、点击高亮、分级配色等。
这个流程看起来直白，但每一步都有隐藏的雷区。比如geometry包含Polygon和MultiPolygon两种类型，转换时处理不好就会少画几个城市；再比如质心计算如果简单取坐标平均值，遇到凹多边形时文字会飘到区域外面去。这些细节会在后面逐一展开。
2. 核心细节解析与实操要点
2.1 geojson数据从哪来，拿到之后先做什么
市界数据来源很多。常见的是从阿里DataV的Atlas平台下载全国省市区划geojson，也有各种开源仓库整理了带统计字段的行政边界数据，还有人从项目里导出过离线数据。不管来源是什么，拿到数据后必须先做三件事：确认坐标系、检查属性字段、评估数据量。
坐标系是第一个大坑。天地图官方底图采用的是CGCS2000坐标系，国内各种数据来源却五花八门，有的是WGS84经纬度，有的是GCJ02火星坐标，甚至有把投影平面坐标直接存成经纬度的。GCJ02坐标如果直接渲染到天地图上，会出现肉眼可见的偏移，大概几百米到一公里，在市级边界上尤其明显。WGS84和CGCS2000在当前精度下差异很小，一般可以直接用。所以拿到数据后，先看属性字段里有没有coordinateSystem或epsg标记，没标记就手工抽一条边界坐标去百度地图或高德地图上比对一下，确认不偏再往下走。
属性字段的检查也很重要。geojson的properties里有没有name字段、adcode字段，决定了你后面怎么取城市名、怎么绑定统计数据。有些数据源字段名是中文，有些是英文缩写，在写代码前先console.log打印一条feature看清楚，能省很多调试时间。
数据量方面，一个省级的市级边界geojson，压缩后通常几十到几百KB，对前端来说压力不大。如果是全国县级边界，几千个多边形就要考虑性能优化了，后面专门讲。
2.2 TMap.MultiPolygon的坐标结构：从geojson到paths
天地图API 4.0的MultiPolygon，接收的geometries数组里每个元素包含paths字段。paths的结构是一个二维数组：最外层是多边形的多个环（外环和洞），每个环由经纬度点数组构成，每个点的格式是[lng, lat]。
geojson里Polygon类型的数据结构是：
{ "type": "Polygon", "coordinates": [ [[lng, lat], [lng, lat], ...], [[lng, lat], [lng, lat], ...] ] }第一个数组是外环，后面的数组是内环（如果有洞的话）。对照可以看出，从geojson到TMap的paths基本可以直接映射：Polygon的coordinates就是TMap需要的paths数组。而geojson的MultiPolygon类型，外层有一个polygon数组，每个polygon又包含多个ring，转换时要先展开。
我封装了一个转换函数，兼顾两种类型：
function geojsonToTmpaths(geometry) { if (!geometry) return []; if (geometry.type === 'Polygon') { return geometry.coordinates; } if (geometry.type === 'MultiPolygon') { let result = []; geometry.coordinates.forEach(polygon => { polygon.forEach(ring => { result.push(ring); }); }); return result; } return []; }注意一个容易忽略的细节：有些geojson数据的坐标环首尾没有闭合，也就是第一个点和最后一个点不同。TMap渲染时对闭合性要求没那么严格，但为了保险，在转换时最好做一次闭合检查。如果发现首尾不闭合，手动把第一个点push到底部，避免出现肉眼可见的缺口。
2.3 文字标注的核心：质心计算和Label样式
城市名要放在色块中间，就得先算出每个多边形的中心点。最简单粗暴的办法是坐标平均法，把边界所有点经纬度加起来求平均。这个方法对凸多边形效果好，但对凹多边形、L形或不规则形状，算出来的中心点很可能落在区域外面，文字就飘到旁边城市去了。
我做省级市界图时，发现部分城市边界包含较多岛屿或复杂弯曲，平均法容易出问题。更稳的是多边形面积加权质心算法，把多边形分解成多个三角形，按面积加权算重心。虽然计算量比平均法大，但对于前端一帧计算几十个多边形，完全没压力。
一个简化版实现：
function calcPolygonCenter(coords) { let area = 0; let cx = 0; let cy = 0; for (let i = 0; i < coords.length - 1; i++) { let xi = coords[i][0]; let yi = coords[i][1]; let xj = coords[i + 1][0]; let yj = coords[i + 1][1]; let temp = xi * yj - xj * yi; area += temp; cx += (xi + xj) * temp; cy += (yi + yj) * temp; } area = area / 2; cx = cx / (6 * area); cy = cy / (6 * area); return [cx, cy]; }如果geometry是MultiPolygon，就取面积最大的那个polygon计算质心，而不是简单取第一个polygon，因为有些城市的主城区之外还有离岛，取错子区域文字会标到海上去。
标签样式的设置同样有讲究。天地图的LabelStyle支持设置颜色、字号、对齐方式和背景色。我把城市名的样式统一设计为深色文字、半透明白底，这样无论底下色块是深是浅，文字都清晰可读。padding给到4到6像素，避免文字贴边。
3. 实操过程与核心环节实现
3.1 第一步：注册天地图应用并配置tk密钥
天地图API 4.0要求所有请求携带tk密钥。前往天地图官网注册账号，在控制台创建一个浏览器端应用，添加域名白名单。本地调试时白名单里要有http://localhost和http://127.0.0.1，上线后换成正式域名。
这一步最容易踩的坑是密钥类型选错。天地图有浏览器端和服务器端两类密钥，浏览器端tky是可以直接暴露在前端页面里的，服务器端sk不能出现在浏览器代码中。做前端色块渲染，请务必创建浏览器端应用并复制tk。
页面引入官方JS库：
<script src="https://api.tianditu.gov.cn/api?v=4.0&tk=YOUR_TIANDITU_KEY" type="text/javascript"></script>引入之后，全局会注册TMap命名空间，所有天地图4.0的类都从这里取。
3.2 第二步：初始化地图底图
初始化代码非常简单，但有几个参数要解释一下。center的取值是整个项目能否一上来就看到完整效果的关键。以四川省为例，省会成都在东经104.06度、北纬30.67度附近，全省范围东西跨度约1000公里，zoom设置为6，屏幕上就能显示出完整省界和主要城市的轮廓。
let map = new TMap.Map('map', { center: [104.06, 30.67], zoom: 6, viewMode: '2D', baseMap: { type: 'vec' } });baseMap.type支持vec（矢量）、img（影像）、ter（地形）等。做行政色块专题图，一般用vec矢量底图，色彩干净、边界清晰，和自定义色块叠加后不会被影像图上的纹理干扰。如果你要做的是遥感信息展示，也可以换成img影像模式。
3.3 第三步：加载并解析geojson数据
推荐把市界geojson文件放在与页面同级的data目录下，用fetch异步加载。为什么不建议直接写在JS文件里？因为一个省的数据至少包含几千个坐标点，直接写死在代码里既影响可读性，也不方便后续替换成全国数据。
fetch('./data/sichuan.json') .then(res => res.json()) .then(data => { renderProvince(data); }) .catch(err => { console.error('geojson加载失败', err); });这里必须提醒，用fetch加载本地json文件时，如果直接用file://协议打开页面，浏览器会拦截跨域请求导致数据加载失败。正确做法是在本地起一个静态服务器，用VS Code的Live Server插件，或者全局安装http-server，启动后在localhost端口访问页面。
拿到data之后，先打印一条feature看看属性字段：
console.log(data.features[0]);确认properties里有name字段再继续往下写。
3.4 第四步：生成色块图层
色块的核心是TMap.MultiPolygon。我先把每个城市对应的样式预定义好，再组装geometries数组，一次性批量渲染，性能碾压循环add Polygon的老写法。
配色方案上和专题图的业务含义强相关。如果是做分类统计，每个类别用同一色系深浅区分；如果只是纯粹让相邻城市颜色不同，就从色环中隔几个选一个基础色。我习惯用10到15种柔和色循环分配，避免相邻城市大面积撞色。
let styleColors = [ '#ffa07a', '#87ceeb', '#98fb98', '#ffd700', '#dda0dd', '#f08080', '#20b2aa', '#ffb6c1', '#b0e0e6', '#ffdab9' ]; let styles = {}; data.features.forEach((feature, index) => { let styleId = 'city_' + index; styles[styleId] = new TMap.PolygonStyle({ color: styleColors[index % styleColors.length], showBorder: true, borderColor: '#ffffff', borderWidth: 1 }); }); let geometries = []; data.features.forEach((feature, index) => { let paths = geojsonToTmpaths(feature.geometry); geometries.push({ paths: paths, styleId: 'city_' + index }); }); let multiPolygon = new TMap.MultiPolygon({ map: map, styles: styles, geometries: geometries });这里有个提升效果的小技巧：borderColor统一用白色，borderWidth给1到2像素，既能把相邻城市清晰区隔开，又不会在视觉上喧宾夺主。如果项目要求色块边缘更柔和，可以给color加透明度，比如rgba格式，或者用color的alpha参数。
3.5 第五步：生成城市文字标注
文字标注用TMap.MultiLabel。和MultiPolygon一样，MultiLabel也是批量类，接收一个geometries数组，每个元素包含坐标点、styleId和content文本信息。
let labelGeometries = data.features.map((feature, index) => { let center = calcLabelCenter(feature); return { lng: center[0], lat: center[1], styleId: 'cityLabel', content: feature.properties.name }; }); let multiLabel = new TMap.MultiLabel({ map: map, styles: { cityLabel: new TMap.LabelStyle({ color: '#333333', size: 14, align: 'center', verticalAlign: 'middle', backgroundColor: 'rgba(255, 255, 255, 0.75)', padding: new TMap.Point(4, 4) }) }, geometries: labelGeometries });calcLabelCenter函数里，我做了类型判断和质心算法选择。对Polygon直接取外环计算面积加权质心，对MultiPolygon先找出面积最大的子多边形，再计算质心。Word提醒一点，有些geojson的地级市面里包含了大量岛屿环，内环在质心计算时必须忽略，否则会把质心拉到奇怪的位置。
3.6 完整演示代码：四川省21市州色块标注
把上面各部分拼起来，一个可以直接运行的页面是这样的：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>天地图API 4.0 省市色块标注</title> <script src="https://api.tianditu.gov.cn/api?v=4.0&tk=YOUR_TIANDITU_KEY" type="text/javascript"></script> <style> html, body, #map { margin: 0; padding: 0; width: 100%; height: 100vh; } </style> </head> <body> <div id="map"></div> <script> let map = new TMap.Map('map', { center: [104.06, 30.67], zoom: 6, viewMode: '2D', baseMap: { type: 'vec' } }); function geojsonToTmpaths(geometry) { if (!geometry) return []; if (geometry.type === 'Polygon') { return geometry.coordinates; } if (geometry.type === 'MultiPolygon') { let result = []; geometry.coordinates.forEach(polygon => { polygon.forEach(ring => { result.push(ring); }); }); return result; } return []; } function calcPolygonAreaAndCenter(coords) { let area = 0; let cx = 0; let cy = 0; for (let i = 0; i < coords.length - 1; i++) { let xi = coords[i][0]; let yi = coords[i][1]; let xj = coords[i + 1][0]; let yj = coords[i + 1][1]; let temp = xi * yj - xj * yi; area += temp; cx += (xi + xj) * temp; cy += (yi + yj) * temp; } area = area / 2; if (Math.abs(area) < 0.000001) { return null; } cx = cx / (6 * area); cy = cy / (6 * area); return [cx, cy]; } function calcLabelCenter(feature) { let geometry = feature.geometry; if (geometry.type === 'Polygon') { let center = calcPolygonAreaAndCenter(geometry.coordinates[0]); if (center) return center; return geometry.coordinates[0][0]; } if (geometry.type === 'MultiPolygon') { let maxArea = -Infinity; let bestCenter = null; geometry.coordinates.forEach(polygon => { let center = calcPolygonAreaAndCenter(polygon[0]); if (!center) return; let area = Math.abs(polygon[0].reduce((sum, p, i, arr) => { let next = arr[(i + 1) % arr.length]; return sum + (p[0] * next[1] - next[0] * p[1]); }, 0) / 2); if (area > maxArea) { maxArea = area; bestCenter = center; } }); if (bestCenter) return bestCenter; return geometry.coordinates[0][0][0]; } return [0, 0]; } fetch('./data/sichuan.json') .then(res => res.json()) .then(data => { let styleColors = [ '#ffa07a', '#87ceeb', '#98fb98', '#ffd700', '#dda0dd', '#f08080', '#20b2aa', '#ffb6c1', '#b0e0e6', '#ffdab9' ]; let styles = {}; let geometries = []; data.features.forEach((feature, index) => { let styleId = 'city_' + index; styles[styleId] = new TMap.PolygonStyle({ color: styleColors[index % styleColors.length], showBorder: true, borderColor: '#ffffff', borderWidth: 1 }); geometries.push({ paths: geojsonToTmpaths(feature.geometry), styleId: styleId }); }); new TMap.MultiPolygon({ map: map, styles: styles, geometries: geometries }); let labelGeometries = data.features.map((feature, index) => { let center = calcLabelCenter(feature); return { lng: center[0], lat: center[1], styleId: 'cityLabel', content: feature.properties.name }; }); new TMap.MultiLabel({ map: map, styles: { cityLabel: new TMap.LabelStyle({ color: '#333333', size: 14, align: 'center', verticalAlign: 'middle', backgroundColor: 'rgba(255, 255, 255, 0.75)', padding: new TMap.Point(4, 4) }) }, geometries: labelGeometries }); map.setCenter([104.06, 30.67]); map.setZoom(6); }) .catch(err => { console.error('geojson加载失败', err); }); </script> </body> </html>提示：以上代码中的YOUR_TIANDITU_KEY需替换为你自己在天地图官网申请到的浏览器端tk密钥。
4. 常见问题与排查技巧实录
4.1 问题速查表
把我在实际开发和工区同事反馈中遇到的高频问题整理成了一张表，遇到问题可以直接对号入座：
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 页面空白，地图不显示 | tk密钥错误、域名白名单没配 | 检查tk是否正确，确认白名单包含当前域名和端口 |
| 色块整体偏移，边界对不上底图 | geojson坐标系与底图不一致 | 确认数据是CGCS2000/WGS84，若是GCJ02需先纠偏 |
| geojson加载失败报CORS错误 | file://直接打开或跨域未配置 | 本地起静态服务器，用localhost访问，或给服务设置CORS头 |
| 渲染后少了一些城市多边形 | geometry类型判断遗漏 | 确认转换函数同时处理Polygon和MultiPolygon |
| 所有色块一个颜色 | styleId没正确关联 | 检查geometries里每个元素是否都指定了存在的styleId |
| 城市名飘到区域外面 | 质心计算用了简单平均法 | 换成面积加权质心算法，或手工微调label位置 |
| 地图卡顿、拖动掉帧 | 多边形数量大或坐标点过多 | 简化边界数据，关闭多余交互，必要时实现分帧渲染 |
| 标签文字模糊 | 字号设置太小或缩放级别低 | 适当调大字号，或给label加背景色提高对比度 |
这张表每一行都是真实场景验证过的，尤其是坐标偏移和跨域问题，是新手翻车比例最高的两个点。
4.2 性能优化：从全省到全国数据量的应对策略
如果需求从省级扩展到全国，341个地级以上的多边形同时渲染，再加上县级数据，事情就变得复杂了。多边形数量上去了，除了MultiPolygon批量渲染之外，还需要考虑三个层面的优化。
第一是边界数据简化。geojson里每个边界点如果精度过高，坐标点数会非常多。可以使用地图简化算法，比如Douglas-Peucker算法，在保证轮廓基本不变的前提下，将坐标点数压缩到原来的1/3甚至更少。网上有简化库可以直接用，比如Simplify.js，压缩后对视觉影响很小。
第二是分帧渲染。如果数据量实在太大，一次性把几千个多边形全部交给MultiPolygon，地图初始化时会卡顿一两秒。可以把geometries数组切分成小组，每帧往MultiPolygon里追加一组（MultiPolygon有setGeometries方法），配合requestAnimationFrame控制节奏，让渲染过程平滑进行。
第三是视口裁剪和按需加载。对全国范围的数据，可以先根据比例尺判断需要展示的级别，低缩放级别时只渲染省级面，放大到市级级别再加载市级边界，再放大才加载县级边界。这样资源消耗大幅下降，交互顺畅度提升明显。
文字标注的优化同理。市名标注数量通常不大，但如果是县级标注，几百上千个label也会有性能压力。可以设置minZoom，在低缩放级别下隐藏一部分小城市名，放大后再显示，既保证可读性又保证性能。
4.3 交互增强：点击高亮和悬浮提示
基础色块图做完，很多业务场景还要加交互。我常用的增强功能有四个：点击城市高亮、悬浮显示统计信息、点击弹出详请面板、按指标分级配色。
点击高亮的实现思路是：在MultiPolygon上绑定点击事件，拿到当前feature后，把该feature的styleId临时换成高亮样式，同时把其他所有feature恢复默认样式。注意不要每次点击都重建MultiPolygon，直接调用setStyles或setGeometries局部更新即可。
分级配色是专题图的灵魂。核心逻辑是先从统计数据里算出最大值最小值，按区间把城市分成几级，每一级映射到同一个色系的深浅颜色。比如深色表示高值、浅色表示低值，图例再标注对应的数值区间。这个思路在人口密度、生产总值、资源分布等场景下非常实用。实现时只需要改styles映射的生成逻辑，几何结构完全不用动。
悬浮提示可以使用TMap的Popup或InfoWindow，在mouseover时显示城市名称和对应指标数据。但要注意频繁触发弹窗会遮挡地图拖拽操作，建议用延迟显示和延迟关闭来控制交互体验。
4.4 关于坐标转换的避坑补充
前面强调了坐标系风险，这里再说细致一些。如果你的geojson数据来自高德生态，大概率是GCJ02火星坐标，直接渲染到天地图上会有明显偏移。这时需要做一次坐标纠偏，通用的做法是引入coordtransform库，将每个坐标点从GCJ02转换到WGS84。虽然WGS84和CGCS2000仍有细微差异，但在这个场景下已经足够准确。
另一个容易忽视的问题是，有些数据源的经纬度顺序是反的，即lat在前、lng在后。如果渲染出来的地图点都跑到海里或者堆在一起，优先检查数据里第一个数字到底是经度还是纬度。天地图API的坐标点统一使用[lng, lat]顺序，和geojson规范一致，但很多人从Excel或CSV里手拼数据时容易搞反，这类问题给我发来的求助里占比不低。
5. 从专题图到数据可视化的几点延伸建议
色块加文字只是第一步，真正让地图产生价值的是数据表达。做完基础展示后，我一般会往下延伸两层。
第一层是让色块“带数据”。给每个城市的properties里塞入指标字段，比如人口、GDP、病例数、降水量，然后用分级配色方案渲染，让颜色深浅直接反映数值大小。这样地图就不再是单纯的行政区划图，而是一张可读性很强的统计专题图。
第二层是让地图“能联动”。点击某个城市，旁边图表联动展示时序趋势；或者反过来，点击统计图表中的城市名，地图自动飞到对应区域并高亮。这种联动效果在业务汇报里特别加分。开发时可以用乘法器的思路：地图事件抛出城市编码，图表组件监听并更新，状态管理统一维护选中城市。
再提一个易用性细节：加上图例和比例尺。天地图4.0提供了TMap.Control类，可以直接添加比例尺控件。图例则需要自己用HTML实现，放在地图的角落，色块颜色和数值区间对应清楚。别看图例是小部件，业务方看专题图时第一眼找的就是图例在哪里。
针对行政区边界数据更新的问题也想多说一句。行政区划会调整，比如县级市改区、撤地设市，如果项目长期运营，建议定时更新geojson数据源，并在代码里做好版本号或更新时间标记，避免你拿着旧边界图给业务方汇报时闹尴尬。
在实际项目里我还有一个习惯：geojson文件单独建一个data目录，文件名带上数据日期，比如sichuan_2025_v2.json。这样每次更新后，git历史里能清楚地看到底图数据的变化，排查问题也方便回滚。
这个技能熟练之后，往全国、往县级扩展都只是数据替换的问题。你把省级代码跑通一次，后面的路就顺畅多了。
