基于高德地图JS API的地块绘制与编辑实战指南

搞了差不多一个星期的地块管理功能终于能跑顺了，基于高德地图JS API做了一套支持多样式多图形的地块绘制、编辑、导入导出和删除完整流程。这篇博客不是官方文档的复读，而是把我实际开发中踩过的坑、核心代码逻辑和功能设计思路一起梳理出来。如果你正准备做类似的GIS可视化或者地图交互应用，尤其是地块审批、农业管理、地产规划这类场景，应该能从这篇文章里拿到一套可以直接落地的方案。

1. 项目整体设计与核心需求拆解

1.1 地块管理系统到底在解决什么问题

先说你拿到需求时最先要搞明白的一件事：地块管理系统不是单纯在地图上画几个多边形。它最基础但最关键的一步，是把现实中一宗地块（农田、建设用地、园区）转换成地图上一个有明确边界、有业务属性、能持久化存储的图形对象。

从我的角度来看，这个系统的核心需求有三块。第一个是交互绘制，用户得能用鼠标在地图上框出一个地块范围，并把地块保存下来。第二个是图形编辑，业务人员在外业调查或者审核中经常会发现边界需要微调，得能拖动顶点。第三个是数据流转，地块信息要能以标准格式导出、也能从标准格式导入，这样不同系统之间才能交换数据。至于删除，则要保证清理图形时干净利落，不留下内存或视觉残留。

三个业务模块分别对应“画、改、导”三个动作，听起来不算复杂，但真正动手后你会发现，高德地图JS API提供的基础能力只解决了20%的功能，剩下的80%需要自己做状态管理、图层管理、事件解耦和数据序列化。

1.2 为什么选高德地图JS API而不是Leaflet或百度地图

很多团队会在高德和Leaflet之间犹豫，我自己的选型结论是：如果项目只在国内使用、又有行政区域展示或业务场景依赖国内地理信息，直接选高德会省掉很多麻烦。

高德地图JS API相比Leaflet有几个实际优势。第一，它原生支持中国GCJ-02坐标系，不用自己处理坐标偏移。你用Leaflet加载国内底图，如果不做坐标纠偏，绘制出来的地块和底图是错位的，这个坑我早期就踩过。第二，高德的组件生态做得比较完整，MouseTool、PolygonEditor、DistrictSearch这些插件可以直接用，省去自己用开源库堆地物的开发量。第三，高德中文文档和示例相对丰富，团队内部的沟通成本也低。

当然，高德也有自己的限制，比如图层样式定制不如Leaflet自由、自定义渲染能力有所收敛，但针对地块绘制编辑这个场景，高德的基础能力刚好覆盖到，属于“用最少代码实现最多功能”的那种选择。

1.3 功能清单与业务流程设计

这套地块管理平台最终规划的功能清单是：

• 地块类型可配：耕地、建设用地、水域、林地，每种类型绑定不同的填充色和边框色。
• 多图形混绘：同一张地图上允许存在多个不同类型的地块，互不干扰。
• 交互式绘制：点击地图打点，双击完成绘制。
• 顶点级编辑：选中地块后，可拖动边界顶点进行形状调整。
• 支持导入：从本地GeoJSON文件恢复地块数据到地图。
• 支持导出：将地图全部地块导出为GeoJSON文本段。
• 单人删除：支持一次性删除单个地块，也支持清空地图。

从流程上看，用户需要先在地图上绘制地块，然后选择样式（实质上代表地块类型），接着保存到本页面的数据模型中，再通过导出功能落库到后台；等到下一次进入页面，用导入功能从后台拿到数据并重新渲染。整个流程环环相扣，每一个环节都需要有清晰的数据规范。

2. 地图初始化与地块数据模型设计

2.1 申请Key并引入高德地图JS API文件

写代码前的第一步不是写地图，而是去高德开放平台申请一个Web端（JS API）的Key。申请过程就不赘述了，重点是在安全密钥设置里你要留意，开发阶段能不用代理、能直接用明文Key就先挺着，上线前再做域名白名单限制和代理转存，不然页面很容易因为Key安全策略导致地图加载失败。

然后通过script标签引入JS API文件，2.0版本是：

html复制<script type="text/javascript">
    window._AMapSecurityConfig = {
        securityJsCode: '你的安全密钥',
    }
</script>
<script src="https://webapi.amap.com/maps?v=2.0&key=你的Key&plugin=AMap.MouseTool,AMap.PolygonEditor"></script>

plugin参数这里特别重要。高德的插件不是随主文件一次性加载的，你要用MouseTool和PolygonEditor就必须在引入时显式声明，否则后续调用时会报“AMap.MouseTool is not a constructor”类似的错误。很多时候前端白屏不是Key的问题，而是插件没加载到位。

2.2 地图容器与初始视图的设置

HTML里需要有一个固定的地图容器，CSS给高度是必须的，比如：

html复制<div id="mapContainer" style="width:100%;height:100vh;"></div>

再初始化地图：

javascript复制const map = new AMap.Map('mapContainer', {
    zoom: 15,
    center: [116.397428, 39.90923],
    resizeEnable: true,
    viewMode: '2D',
});

这里有几个隐含的基础点。第一个是center坐标，建议写你项目实际的业务区域坐标，而不是让用户自己拖拽很久才找到地块位置。第二个是resizeEnable必须设为true，否则页面有容器尺寸变化时，地图不会自动重算尺寸，就会留白或者只画出半个地图。

地图初始化完成之后，就可以开始设计地块的对象模型。要注意的是，地图上的AMap.Polygon实例只是视图层对象，不能直接塞进数据库。

2.3 地块的数据模型设计

我使用的是GeoJSON格式作为统一交换标准。每个地块的Geometry本质是一个Polygon，包含外环坐标数组，在Web前端可以表示为一个Feature对象：

json复制{
    "type": "Feature",
    "properties": {
        "id": "uuid-1234",
        "name": "青年农场",
        "type": "耕地",
        "area": 21034.56,
        "createTime": "2025-06-12 10:30:00"
    },
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [116.397, 39.909],
                [116.398, 39.909],
                [116.398, 39.910],
                [116.397, 39.910]
            ]
        ]
    }
}

前后端的数据交换，核心就是这一串GeoJSON。前端接收到这个结构后，可以根据properties.type去查找该地块的样式配置，并用new AMap.Polygon来还原。导出的时候则反过来，遍历当前地图上所有地块对象，把getPath拿到的经纬度数组填充成GeoJSON。

一个容易忽略的点是坐标顺序。GeoJSON的标准顺序是经度在前、纬度在后，也就是[longitude, latitude]，高德地图的getPath返回的Point也是[lng, lat]的格式，这里没有歧义，但如果你对接了很多后台服务，一定要在接口层约定字段含义，避免和某些系统里的“x=纬，y=经”搞混。

3. 多样式多图形地块绘制功能实现

3.1 用MouseTool完成一次地块圈选

高德地图JS API里，画多边形最方便的方式是使用MouseTool插件。

javascript复制let mouseTool = null;
map.plugin(['AMap.MouseTool'], function () {
    mouseTool = new AMap.MouseTool(map);
});

调用绘制逻辑时，需要先选定地块类型，这会直接影响绘制样式的设置：

javascript复制function setDrawType(type) {
    currentDrawType = type;
    const style = typeStyleMap[type];
    mouseTool.polygon({
        strokeColor: style.strokeColor,
        strokeWeight: 2,
        strokeOpacity: 1,
        strokeStyle: 'dashed',
        fillColor: style.fillColor,
        fillOpacity: 0.4,
        cursor: 'crosshair',
    });
}

画完以后，会有事件回调，这时要把得到的polygon对象交给管理器统一维护：

javascript复制mouseTool.on('draw', function (e) {
    const polygon = e.obj;
    savePolygonToManager(polygon);
});

这里有一个我自己反复测试得出的结论：MouseTool的polygon模式在鼠标双击后就自动结束绘制，生成的geometry对象已经是一个AMap.Polygon实例。如果用MouseTool又自己去监听click事件闭路生成多边形，反而会造成一次绘制生成多个图形的问题。

至于多样式，提前维护一个"类型->颜色"映射对象会省很多心：

javascript复制const typeStyleMap = {
    'a1': { name: '耕地', strokeColor: '#2c7c31', fillColor: '#5eb564' },
    'a2': { name: '建设用地', strokeColor: '#3d6db5', fillColor: '#7fa8de' },
    'a3': { name: '水域', strokeColor: '#18a0a0', fillColor: '#73d5d5' },
};

3.2 多图形共存的地图状态管理

当页面里不止有一个地块时，需要一套简单的地图状态管理机制。我这里没有引入Vuex或者Redux之类复杂的状态库，直接用了一个全局数组polygonList来维护所有AMap.Polygon实例，并为每一个实例额外挂一个业务属性config。

AMap.Polygon本身并不支持直接挂自定义属性，但JavaScript对象是可以动态添加属性的：

javascript复制function savePolygonToManager(polygon) {
    const feature = {
        id: generateUUID(),
        type: currentDrawType,
        bounds: [],
        rawPolygon: polygon,
        name: currentDrawType === 'a1' ? '农田地块' : '建设用地'
    };
    polygon.setExtData(feature);
    polygonList.push(polygon);
}

setExtData是高德提供的方法，专门用来给覆盖物挂业务数据，非常合适。遍历时先拿polygonList的索引，再根据setExtData存的内容去取业务ID，这就为后续的删除、编辑、导出做好了数据基础。

还有一个要注意的地方：地图上的事件监听一旦绑定了多个draw事件回调，要记得在绘制开始时提前清理上一次绘制残留。否则连续划两个地块，第一次创建的地块可能被MouseTool内部的事件状态再次触发。

3.3 多样式绘制的本质是样式数据化

多样式的关键不只是能画不同颜色的圈，而是要让颜色和业务类型强绑定。比如当你从后端拿到一个地块，属性type=“水域”，那么它在地图上渲染时就必须自动变成蓝色多边形，而不是让用户手动选颜色。

所以我在实际代码中让样式配置与GeoJSON的属性字段映射起来。绘制前指定类型，绘制后把类型写入properties.type，渲染读取properties.type，再反查typeStyleMap设置样式。这样就可以保证任何时候重新加载或导入导出，地块的多样性都不会丢失。

我自己额外做了一步：把样式的strokeWidth、fillOpacity也做成可配置项，通过界面上的下拉框让用户修改。这样等于把整个地块图层的视觉也动态化了。

4. 地块编辑、删除与样式动态切换

4.1 PolygonEditor实现顶点级编辑

当鼠标点击某个已经画好的地块时，需要进入编辑状态。编辑状态下用户可以拖拽图形边界的每个顶点，来调整地块形状。

在进入编辑状态前，要确保当前只有一个激活的editor，否则你可能同时打开多个编辑器，导致拖拽时图形互相串。使用变量currentEditor来维护：

javascript复制function startEditPolygon(polygon) {
    if (currentEditor) {
        currentEditor.close();
        currentEditor = null;
    }
    if (!editorPlugin) {
        map.plugin(['AMap.PolygonEditor'], function () {
            editorPlugin = true;
            initEditorAndOpen(polygon);
        });
    } else {
        initEditorAndOpen(polygon);
    }
}

function initEditorAndOpen(polygon) {
    currentEditor = new AMap.PolygonEditor(map, polygon);
    currentEditor.open();
}

PolygonEditor.open()调用后，地块的边界顶点会出现可拖拽的小圆圈，拖动一个顶点时，多边形会实时重绘，整个交互非常流畅。

编辑完成时，要监听相应事件来更新业务字段：

javascript复制currentEditor.on('end', function (e) {
    const shape = e.target;
    const extData = shape.getExtData();
    extData.bounds = shape.getPath();
    console.log('编辑结束，需要重新计算面积或上报变化');
});

在业务层，地块编辑结束后一般要通知后端保存新的边界。比较好的设计是点击保存按钮时统一把多边形List导出并调后台接口，而不是每次拖拽完了就立即调接口，否则后台会被频繁请求打爆。

4.2 样式动态切换与高亮反馈

地图上地块众多时，用户很难从视觉上区分哪个地块处于选中状态。所以在实现单击选中时，我额外做了高亮处理：对选中的地块，把strokeWeight从2增加到4，并且fillOpacity调高。

具体代码如下：

javascript复制polygon.on('click', function (e) {
    const target = e.target;
    resetAllPolygonStyle();
    target.setOptions({
        strokeWeight: 4,
        fillOpacity: 0.6,
        strokeOpacity: 1,
        strokeColor: '#e84040'
    });
    selectedPolygon = target;
    startEditPolygon(target);
});

resetAllPolygonStyle则是一个遍历所有地块并按原定类型恢复样式的函数。这个过程看似简单，但如果你不写这个恢复函数，很容易出现高亮一次后颜色再也回不去的bug。

这里的核心经验是：编辑和高亮是两个互相影响的动作，编辑态下的拖拽可能会临时改变样式，不要直接拿着style配置去setOptions，而是用一块独立的、可回滚的状态区来保存地块的默认样式。

4.3 删除单个地块和清空地图

删除动作比想象中容易出问题。不能用鼠标画完再按“删除键”，就真的以为移除了。你需要判断用户到底是想删除当前正在编辑的地块，还是清空所有地块。

我的实现逻辑并不复杂，一个删除按钮是删选中地块，另一个清空按钮是遍历移除所有地块：

javascript复制function deleteSelectedPolygon() {
    if (!selectedPolygon) return;
    map.remove(selectedPolygon);
    polygonList = polygonList.filter(p => p !== selectedPolygon);
    if (currentEditor) {
        currentEditor.close();
        currentEditor = null;
    }
    selectedPolygon = null;
}

function clearAllPolygons() {
    if (!polygonList.length) return;
    map.remove(polygonList);
    polygonList = [];
    if (currentEditor) {
        currentEditor.close();
        currentEditor = null;
    }
    selectedPolygon = null;
}

删除之后一定要同步调整polygonList数组。如果忘记过滤数组里的对象，就会造成明明地图上已经看不到图形了，但导出的数据里仍然带着那条记录的现象，用户会觉得系统bug很严重。

5. 导出GeoJSON与导入渲染的完整链路

5.1 从地图上的地块生成GeoJSON字符串

导出是整个系统非常关键的一环，因为它是和后台真正协作的输入。实现上，遍历polygonList中的每一个覆盖物，然后取它的path坐标和extData业务信息。

javascript复制function exportToGeoJSON() {
    const features = polygonList.map(p => {
        const path = p.getPath();
        const coords = [path.map(point => [point.lng, point.lat])];
        const data = p.getExtData() || {};
        return {
            type: 'Feature',
            properties: {
                id: data.id || generateUUID(),
                name: data.name || '',
                type: data.type || '',
                area: AMap.GeometryUtil.ringArea(path),
                createTime: data.createTime || new Date().toISOString()
            },
            geometry: {
                type: 'Polygon',
                coordinates: coords
            }
        };
    });

    const geoJson = {
        type: 'FeatureCollection',
        features: features
    };

    return JSON.stringify(geoJson);
}

AMap.GeometryUtil.ringArea可以直接计算多边形面积，单位似乎是平方米。这个方法非常省事，不用自己用球面三角公式去计算。在实际项目里，你可以利用这个面积来计算农作物的施肥用量，或者做土地租金结算。

导出数据的文件下载实现也很简单，把生成的字符串转成Blob，再触发一个a标签的下载即可。

5.2 从GeoJSON导入并渲染地块

导入模块的本质是接收外部数据，把它转成AMap.Polygon对象添加到地图，同时推入polygonList。

由于GeoJSON里geometry.coordinates可能是个三维数组，第一个维度是Polygon的外环，所以读取的时候要保持谨慎：

javascript复制function importFromGeoJSON(geoJsonStr) {
    const geoJson = JSON.parse(geoJsonStr);
    if (geoJson.type !== 'FeatureCollection') return;
    geoJson.features.forEach(feature => {
        const coordinates = feature.geometry.coordinates[0];
        const path = coordinates.map(coord => new AMap.LngLat(coord[0], coord[1]));
        const type = feature.properties.type;
        const style = typeStyleMap[type] || typeStyleMap.default;

        const polygon = new AMap.Polygon({
            path: path,
            strokeColor: style.strokeColor,
            strokeWeight: 2,
            strokeOpacity: 1,
            fillColor: style.fillColor,
            fillOpacity: 0.4,
        });

        polygon.setExtData({
            id: feature.properties.id || generateUUID(),
            name: feature.properties.name || '',
            type: type,
            createTime: feature.properties.createTime || ''
        });

        polygon.on('click', function () {
            /** 进入选中与编辑逻辑 */
        });

        polygonList.push(polygon);
        polygon.setMap(map);
    });
}

导入时建议做一次地图视野自适应，让刚导入的所有地块都落在可视区域内：

javascript复制map.setFitView(polygonList);

如果不做这一步，可能用户导入了一份位于另一个城市的数据，地图却还停留在初始化时的中心，页面上看不到任何导入结果，用户就会以为导入失败了。这个细节务必加上。

5.3 与后台数据库协作的约定

前端导出GeoJSON后，一般是通过HTTP接口发送到后端存储。根据我在项目里的做法，可以设计一个简单接口：

bash复制POST /api/land-parcels/import
Body: { "geoJson": "...", "projectId": "xxx" }

后端保存时可以直接存字符串，也可以解析GeoJSON后把features写入关系型表。前端导入的时候，由项目接口动态返回GeoJSON字符串，然后前端直接调用上面写的importFromGeoJSON。

在整个数据链路里，一个重要约定是：用feature.properties.id作为业务主键，而不是直接用多边形坐标。因为坐标在编辑时是高频变化的，用坐标当主键一旦图形发生微调，前后端对应关系就完全乱掉了。

6. 常见问题与踩坑排查实录

6.1 绘制完成后多边形没有出现在地图上

这类问题八九不离十是MouseTool初始化时机不对。在异步加载高德JS API时，偶尔会出现在地图实例还没有完全ready之前就去实例化工具，导致new MouseTool(map)的行为异常。

稳妥的画法是在地图的complete事件后再去创建MouseTool：

javascript复制map.on('complete', function () {
    // 初始化MouseTool
});

另一种情况是没有把mouseTool.draw后的polygon对象setMap到地图。MouseTool画完以后默认会把图形加在地图上，但如果你是在回调里新建了一个Polygon，就很容易漏掉新的polygon.setMap(map)。

6.2 编辑状态下保存的数据不是最新的

这个问题非常有代表性。当用户拖拽了顶点，然后立刻点保存按钮，导出的GeoJSON里坐标有时却是旧值。原因在于PolygonEditor拖动过程中，地图的path可能还没有把最后的拖拽结果提交到多边形对象里。

我的解决方法是延迟一下再导出，或者监听PolygonEditor的end事件，等end触发后再更新polygonList里的数据缓存。最简单但有效的办法是每次保存前强制执行一次：

javascript复制if (currentEditor) {
    currentEditor.close();
}

editor.close()会强制将当前正在编辑的多边形的path刷新到最新状态，再把currentEditor置空，这样导出结果就不会有旧数据了。

6.3 多个地块互相粘连导致无法选中目标地块

高德地图的Polygon默认开启touch事件后，点击重叠区域时会选中顶层的图形。如果你的业务中允许地块重叠，这就会变成麻烦。比如我要先选择被遮挡的下层地块，就必须操作起来非常难受。

一个折中方案是使用overlayMap事件，通过地图的click事件，然后遍历所有polygon，利用geometry.contains(point)判断哪个图形包含你鼠标点击的点。这个方案在地块不多的时候完全够用，比维护复杂的图层层级简单。

javascript复制map.on('click', function (e) {
    const point = e.lnglat;
    const hitPolygon = polygonList.filter(p => p.getBounds().contains(point) || containsPoint(p, point));
    if (hitPolygon.length) {
        // 激活命中第一个
    }
});

严格的多边形包含可以使用AMap.GeometryUtil.isPointInRing(point, polygon.getPath())。

6.4 getPath()不返回高德坐标对象

有时你导出数据时会发现path里每个point是普通Object，并不带lng和lat方法，那是因为从其它方式创建的polygon path里保存的是数组点位。为了保证数据一致，我统一在导出时使用point.lng和point.lat取值，而不是point.getLng()。

但如果某个polygon是自己解析GeoJSON时手动创建的，你让path存的是AMap.LngLat构造出来的对象，那就能直接用getLng()方法。为了兼容，写一个辅助函数：

javascript复制function toLngLat(point) {
    if (point instanceof AMap.LngLat) {
        return { lng: point.getLng(), lat: point.getLat() };
    }
    return { lng: point.lng || point[0], lat: point.lat || point[1] };
}

这样处理不管内部什么格式，导出都不会出错。

6.5 样式丢失问题

有一个情况是：用户画了一个水域类型的水塘，颜色是蓝色，但当他从导入功能重新加载这个数据时，水塘变成了默认红色。原因多半是properties.type没有写入，导入时找不到对应的样式名称，最后落入default分支。

我的建议是绘制完多边形，立刻把type字段存入extData，并通过geojson导出时带上properties.type。绝对不要让数据模型和视觉模型脱节。

7. 实操体验与进一步扩展建议

这套基于高德地图JS API的地块绘制编辑导入导出删除模块，目前已经在一个农业项目里跑了一段时间。从实际使用感受来说，稳定性完全没有问题，但高德的交互细节还需要开发者自己补全一点“手感”。

比如绘制时，如果用户中途误双击导致提前结束，需要用取消按钮恢复状态；编辑时如果图形非常复杂，顶点数上千，地图拖拽可能会存在卡顿。我一般建议对地块顶点做抽稀处理，或者限制单个地块顶点数量不超过800个。这套方案对大多数人来说够用，可要是地块精细到河道或山体这种自然边界，顶点抽稀算法就变成必须具备的东西。

另一个具体的升级方向是给地块添加编号标注。我试过直接用AMap.Text标记地块名称，不过当地块随地图缩放或旋转时，坐标位置需要实时同步，否则标注会脱离地块。这时候可以用AMap.Marker和polygon的path联动实时更新位置，效果还不错。

如果打算做分层绘制，比如一个底图显示所有农田，一个图层显示所有建设用地，可以继续用高德自定义图层的方式把不同地块放到不同的CustomLayer去渲染，或者在业务层用多个polygonList分别维护，再通过setMap(null)或setMap(map)来切换显隐。

完整示例代码我已经放到了自己的服务端上，结构基本就是上面文章里写的那些核心函数组装起来，再包了一层Vue的页面控制逻辑。从开发周期上讲，只要把绘制和编辑两个基础插件打通，后面导出导入和删除都是水磨工夫。建议你从最小原型开始跑，先画一个地块，再编辑它，再导出，再去走导入流程，整个链路能闭上，再考虑多地块和样式管理问题，开发难度会降低不少。