当前位置：首页 > news >正文

Vue 3 + 高德地图实战：打造全能定位与搜索组件

news 2026/5/23 3:15:12

在前端开发中，地图功能往往是复杂业务场景的核心需求。无论是外卖配送、打卡签到还是物流追踪，都需要精准的定位和便捷的地点搜索能力。
本文将基于Vue 3和高德地图 JS API 2.0，详细解析如何实现一个集点击地图定位、关键词搜索联想、经纬度精确定位于一体的地图组件。

1. 项目准备与环境配置

1.1 安装依赖

我们需要使用官方推荐的加载器@amap/amap-jsapi-loader来异步加载高德地图 SDK，避免全局污染并更好地管理生命周期。

npm install @amap/amap-jsapi-loader

1.2 获取 Key 与安全密钥

在高德开放平台创建应用，获取Key和安全密钥 (Security Code)。注意：自高德地图 JS API 2.0 起，必须配合安全密钥使用，否则无法加载地图。

2. 核心架构设计

我们的组件主要包含以下模块：

地图容器：用于渲染地图实例。
工具栏：输入经纬度、设置半径、清除标记。
搜索栏：支持关键词输入，下拉展示搜索建议（POI）。
信息展示区：显示当前选中位置的详细地址。

3. 关键功能实现详解

3.1 初始化地图与安全配置

在onMounted中，我们首先处理 Mock 数据对地图请求的影响（开发环境中常见坑点），然后配置安全密钥并加载地图。

// 解决 Mock.js拦截高德地图请求导致白屏的问题 window.XMLHttpRequest = window._XMLHttpRequest || window.XMLHttpRequest; window.fetch = window._fetch || window.fetch; // 配置安全密钥 window._AMapSecurityConfig = { securityJsCode: AMAP_SECURITY_CODE, }; // 加载地图 AMapLoader.load({ key: AMAP_KEY, version: "2.0", plugins: [ "AMap.Scale", // 比例尺 "AMap.ToolBar", // 工具条 "AMap.Geocoder", // 地理编码/逆地理编码 a "AMap.PlaceSearch", // 地点搜索服务 ], }) .then((AMap) => { // 初始化地图实例 const map = new AMap.Map("container", { viewMode: "3D", zoom: 11, center: [116.397428, 39.90923], // 默认北京 resizeEnable: true, }); // 添加控件 map.addControl(new AMap.Scale()); map.addControl(new AMap.ToolBar()); mapInstance.value = map; });

3.2 点击地图与逆地理编码

用户点击地图任意位置时，我们需要做三件事：

获取经纬度。
添加标记点（Marker）和范围圈（Circle）。
通过逆地理编码将坐标转换为人类可读的地址字符串。

// 地图点击事件 map.on("click", (e) => { const point = e.lnglat; const lng = point.lng; const lat = point.lat; // 更新双向绑定的数据 longitude.value = lng; latitude.value = lat; // 添加标记和圆圈 addMarker([lng, lat]); // 逆地理编码获取地址详情 reverseGeocode({ lng, lat }); }); // 逆地理编码函数 const reverseGeocode = (point) => { const geocoder = new AMap.Geocoder(); geocoder.getAddress([point.lng, point.lat], (status, result) => { if (status === "complete" && result.info === "OK") { // 获取格式化地址 currentLocation.value = result.geocodes[0].formattedAddress; } else { currentLocation.value = `坐标: ${point.lng}, ${point.lat}`; } }); };

3.3 智能搜索与联想（PlaceSearch）

这是提升用户体验的关键。我们使用AMap.PlaceSearch插件来实现“边输边搜”的效果。

实现逻辑：

监听输入框的 input 事件。
当输入字符大于 2 时，调用placeSearch.search()。
将返回的 POI（兴趣点）数据格式化，渲染到下拉列表中。
用户点击某一项时，地图自动定位到该点。

const handleSearchInput = (value) => { if (!mapInstance.value || !value || value.length < 2) { searchTips.value = []; return; } const placeSearch = new AMap.PlaceSearch({ city: "全球", citylimit: false, // 允许全国搜索 pageSize: 10, extensions: "all", // 返回详细信息 }); placeSearch.search(value, (status: string, result: any) => { if (status === "complete" && result.poiList) { searchTips.value = result.poiList.pois.map((poi) => ({ name: poi.name, district: `${poi.pname}${poi.cityname}${poi.adname}`, address: poi.address, location: poi.location, // AMap.LngLat 对象 })); } else { searchTips.value = []; } }); }; // 选择搜索结果 const selectSearchResult = (item) => { searchAddress.value = item.name; searchTips.value = []; // 隐藏列表 const lng = item.location.lng; const lat = item.location.lat; // 地图视角切换 mapInstance.value.setCenter([lng, lat]); mapInstance.value.setZoom(15); // 更新状态 longitude.value = lng; latitude.value = lat; addMarker([lng, lat]); currentLocation.value = item.district + item.address; };

3.4 经纬度手动定位与范围绘制

除了鼠标操作，业务场景中常需要直接输入坐标进行定位。同时，为了模拟“电子围栏”或“打卡范围”，我们需要绘制一个圆形覆盖物。

const locateByCoordinate = () => { const lng = parseFloat(longitude.value); const lat = parseFloat(latitude.value); if (isNaN(lng) || isNaN(lat)) { ElMessage.error("请输入有效的经纬度"); return; } const center = [lng, lat]; mapInstance.value.setCenter(center); mapInstance.value.setZoom(15); addMarker(center); // 绘制圆形范围 createCircle(center, radius.value); reverseGeocode({ lng, lat }); }; // 创建圆形覆盖物 const createCircle = (center, radiusVal) => { clearCircleOnly(); // 先清除旧圆圈 const circle = new AMap.Circle({ center: center, radius: parseFloat(radiusVal), // 单位：米 strokeColor: "#0091ff", strokeWeight: 2, fillColor: "rgba(0, 145, 255, 0.1)", fillOpacity: 0.5, }); mapInstance.value.add(circle); };

4. UI 交互细节优化

4.1 下拉列表样式

为了让搜索体验更像原生 App，我们使用绝对定位将下拉列表悬浮在输入框下方，并添加了阴影和滚动条限制。

.search-tips-list { position: absolute; top: 100%; left: 0; width: 100%; max-height: 300px; overflow-y: auto; background: #fff; border: 1px solid #dcdfe6; z-index: 1000; li { padding: 10px 15px; cursor: pointer; &:hover { background-color: #f5f7fa; color: #409eff; } } }

4.2 清理机制

在添加新标记或圆圈前，务必清除旧的覆盖物，防止地图元素堆积导致性能下降或视觉混乱。

const clearAll = () => { clearCircleOnly(); if (currentMarker.value) { mapInstance.value.remove(currentMarker.value); currentMarker.value = null; } // 重置其他状态... };

5. 常见问题与避坑指南

Mock.js 冲突：
- 现象：引入 Mock.js 后，地图瓦片加载失败，页面白屏。
- 解决：如代码所示，在加载地图前备份并恢复原生的XMLHttpRequest和fetch。
地图容器尺寸问题：
- 现象：地图只显示左上角一小块。
- 解决：确保父容器有明确的高度。如果在 Tab 切换或动态显示中初始化地图，需在 DOM 更新后调用map.resize()。
安全密钥配置：
- 现象：控制台报错INVALID_USER_SCODE。
- 解决：确保window._AMapSecurityConfig在AMapLoader.load之前执行，且密钥正确。