企业官网建设流程全解析

高德地图 JS API v2 自定义路线实战：DragRoute 插件实现 16 途经点拖拽规划

在当今的 Web 开发中，地图功能已经成为许多应用的标配。无论是出行导航、物流配送还是旅游规划，交互式路线功能都能显著提升用户体验。高德地图 JS API v2 提供的AMap.DragRoute插件，为开发者提供了一种优雅的方式来实现可拖拽的自定义路线规划功能。

本文将深入探讨如何利用AMap.DragRoute插件构建一个完整的、可交互的路线规划模块，支持多达 16 个途经点的灵活配置。我们将从基础配置开始，逐步深入到高级功能实现，最终打造一个可直接集成到 Vue/React 项目中的可复用组件。

1. 环境准备与基础配置

在开始使用AMap.DragRoute插件前，我们需要完成一些基础准备工作。首先，确保你已经注册了高德开发者账号并获取了有效的 Key，这是使用所有高德地图 API 服务的前提。

1.1 引入高德地图 JS API

在 HTML 文件中引入高德地图 JS API v2：

<script src="https://webapi.amap.com/maps?v=2.0&key=你的高德Key"></script>

1.2 引入 DragRoute 插件

AMap.DragRoute是一个独立的插件，需要单独引入：

AMap.plugin('AMap.DragRoute', function() { // 插件加载完成后执行的回调 console.log('DragRoute 插件加载完成'); });

1.3 初始化地图实例

创建一个基础地图实例：

const map = new AMap.Map('map-container', { zoom: 12, // 初始缩放级别 center: [116.397428, 39.90923], // 初始中心点坐标（北京天安门） viewMode: '2D' // 使用2D视图 });

提示：在实际项目中，建议将地图初始化逻辑封装成一个独立的函数或类，便于复用和管理。

2. 创建可拖拽路线实例

AMap.DragRoute的核心功能是允许用户通过拖拽途经点来动态调整路线。下面我们来看如何创建一个完整的可拖拽路线实例。

2.1 基本参数配置

const path = [ [116.397428, 39.90923], // 起点（天安门） [116.407428, 39.90923], // 途经点1 [116.417428, 39.90923], // 途经点2 [116.427428, 39.90923] // 终点 ]; const dragRoute = new AMap.DragRoute(map, path, AMap.DrivingPolicy.LEAST_TIME, { // 路线样式配置 polyOptions: { strokeColor: '#3366FF', // 路线颜色 strokeWeight: 6, // 路线宽度 strokeOpacity: 0.8 // 路线透明度 } });

2.2 路线策略选择

高德地图提供了多种路线规划策略，可以根据不同需求选择：

2.3 自定义标记图标

我们可以为起点、终点和途经点设置不同的图标：

const dragRoute = new AMap.DragRoute(map, path, AMap.DrivingPolicy.LEAST_TIME, { startMarkerOptions: { offset: new AMap.Pixel(-13, -40), icon: new AMap.Icon({ size: new AMap.Size(26, 40), image: 'https://webapi.amap.com/theme/v1.3/markers/n/start.png' }) }, endMarkerOptions: { offset: new AMap.Pixel(-13, -40), icon: new AMap.Icon({ size: new AMap.Size(26, 40), image: 'https://webapi.amap.com/theme/v1.3/markers/n/end.png' }) }, midMarkerOptions: { offset: new AMap.Pixel(-5, -10), icon: new AMap.Icon({ size: new AMap.Size(15, 15), image: 'https://webapi.amap.com/theme/v1.3/markers/n/mid.png' }) } });

3. 事件处理与数据获取

AMap.DragRoute提供了丰富的事件，让我们可以实时获取路线信息并响应用户操作。

3.1 监听路线规划完成事件

dragRoute.on('complete', function(result) { const routeData = result.data.routes[0]; // 获取路线总距离（米转换为公里） const distance = (routeData.distance / 1000).toFixed(1); // 获取预计行驶时间（秒转换为分钟） const time = (routeData.time / 60).toFixed(0); console.log(`路线总距离: ${distance}公里`); console.log(`预计行驶时间: ${time}分钟`); // 获取详细的路径点 const path = routeData.path; console.log('详细路径点:', path); });

3.2 处理拖拽事件

当用户拖拽途经点时，会触发dragging和dragend事件：

dragRoute.on('dragging', function(event) { console.log('正在拖拽途经点:', event.target.getPosition()); }); dragRoute.on('dragend', function(event) { console.log('拖拽结束，新位置:', event.target.getPosition()); // 重新搜索路线 dragRoute.search(); });

3.3 错误处理

dragRoute.on('error', function(error) { console.error('路线规划错误:', error); // 可以根据不同的错误类型给出用户提示 if(error.info === 'INVALID_USER_KEY') { alert('无效的高德地图Key，请检查配置'); } else { alert('路线规划失败: ' + error.info); } });

4. 高级功能实现

掌握了基础功能后，我们可以进一步实现一些高级特性，提升用户体验。

4.1 动态添加/删除途经点

// 添加途经点 function addWaypoint(lnglat) { dragRoute.addWayPoint( new AMap.Marker({ position: lnglat, map: map, icon: new AMap.Icon({ size: new AMap.Size(15, 15), image: 'https://webapi.amap.com/theme/v1.3/markers/n/mid.png' }) }) ); dragRoute.search(); // 重新规划路线 } // 删除途经点 function removeWaypoint(index) { dragRoute.removeWayPoint(index); dragRoute.search(); // 重新规划路线 }

注意：高德地图 JS API v2 的AMap.DragRoute最多支持 16 个途经点（包括起点和终点），超出限制会导致规划失败。

4.2 路线信息展示面板

创建一个信息面板来展示路线详情：

<div id="route-info"> <h3>路线信息</h3> <p>起点: <span id="start-point"></span></p> <p>终点: <span id="end-point"></span></p> <p>途经点: <span id="waypoints-count">0</span>个</p> <p>总距离: <span id="total-distance">0</span>公里</p> <p>预计时间: <span id="estimated-time">0</span>分钟</p> </div>

然后在complete事件中更新这些信息：

dragRoute.on('complete', function(result) { const routeData = result.data.routes[0]; const distance = (routeData.distance / 1000).toFixed(1); const time = (routeData.time / 60).toFixed(0); document.getElementById('total-distance').textContent = distance; document.getElementById('estimated-time').textContent = time; // 获取途经点数量（总点数减去起点和终点） const waypointsCount = dragRoute.getWayPoints().length - 2; document.getElementById('waypoints-count').textContent = waypointsCount; });

4.3 路线分段信息展示

对于长距离路线，展示分段信息会更有帮助：

dragRoute.on('complete', function(result) { const routeData = result.data.routes[0]; const steps = routeData.steps; const stepsHtml = steps.map(step => ` <div class="route-step"> <h4>${step.instruction}</h4> <p>距离: ${(step.distance / 1000).toFixed(1)}公里</p> <p>预计时间: ${(step.time / 60).toFixed(0)}分钟</p> </div> `).join(''); document.getElementById('route-steps').innerHTML = stepsHtml; });

5. Vue/React 组件封装

为了在实际项目中复用，我们可以将上述功能封装成 Vue 或 React 组件。下面以 Vue 为例：

5.1 Vue 组件实现

<template> <div> <div ref="mapContainer" class="map-container"></div> <div class="route-info"> <h3>路线信息</h3> <p>总距离: {{ distance }}公里</p> <p>预计时间: {{ time }}分钟</p> <p>途经点: {{ waypointsCount }}个</p> </div> </div> </template> <script> export default { props: { startPoint: { type: Array, required: true }, endPoint: { type: Array, required: true }, waypoints: { type: Array, default: () => [] } }, data() { return { map: null, dragRoute: null, distance: 0, time: 0, waypointsCount: 0 }; }, mounted() { this.initMap(); }, methods: { initMap() { // 初始化地图 this.map = new AMap.Map(this.$refs.mapContainer, { zoom: 12, center: this.startPoint }); // 加载DragRoute插件 AMap.plugin('AMap.DragRoute', () => { this.initDragRoute(); }); }, initDragRoute() { // 合并所有路径点（起点+途经点+终点） const path = [this.startPoint, ...this.waypoints, this.endPoint]; this.dragRoute = new AMap.DragRoute(this.map, path, AMap.DrivingPolicy.LEAST_TIME, { startMarkerOptions: { offset: new AMap.Pixel(-13, -40), icon: new AMap.Icon({ size: new AMap.Size(26, 40), image: 'https://webapi.amap.com/theme/v1.3/markers/n/start.png' }) }, endMarkerOptions: { offset: new AMap.Pixel(-13, -40), icon: new AMap.Icon({ size: new AMap.Size(26, 40), image: 'https://webapi.amap.com/theme/v1.3/markers/n/end.png' }) }, midMarkerOptions: { offset: new AMap.Pixel(-5, -10), icon: new AMap.Icon({ size: new AMap.Size(15, 15), image: 'https://webapi.amap.com/theme/v1.3/markers/n/mid.png' }) } }); // 监听事件 this.dragRoute.on('complete', this.handleRouteComplete); this.dragRoute.on('error', this.handleRouteError); // 开始搜索路线 this.dragRoute.search(); }, handleRouteComplete(result) { const routeData = result.data.routes[0]; this.distance = (routeData.distance / 1000).toFixed(1); this.time = (routeData.time / 60).toFixed(0); this.waypointsCount = this.waypoints.length; // 触发事件通知父组件 this.$emit('route-update', { distance: this.distance, time: this.time, path: routeData.path }); }, handleRouteError(error) { console.error('路线规划错误:', error); this.$emit('route-error', error); }, // 添加途经点 addWaypoint(lnglat) { this.dragRoute.addWayPoint( new AMap.Marker({ position: lnglat, map: this.map, icon: new AMap.Icon({ size: new AMap.Size(15, 15), image: 'https://webapi.amap.com/theme/v1.3/markers/n/mid.png' }) }) ); this.dragRoute.search(); }, // 删除途经点 removeWaypoint(index) { this.dragRoute.removeWayPoint(index + 1); // +1 因为第一个点是起点 this.dragRoute.search(); } }, watch: { waypoints(newVal) { if (this.dragRoute) { // 移除所有途经点（保留起点和终点） const waypoints = this.dragRoute.getWayPoints(); for (let i = waypoints.length - 2; i > 0; i--) { this.dragRoute.removeWayPoint(i); } // 添加新的途经点 newVal.forEach(point => { this.addWaypoint(point); }); } } }, beforeDestroy() { if (this.map) { this.map.destroy(); } } }; </script> <style> .map-container { width: 100%; height: 500px; } .route-info { margin-top: 20px; padding: 15px; background: #f5f5f5; border-radius: 4px; } </style>

5.2 组件使用示例

<template> <div> <h1>自定义路线规划</h1> <drag-route :start-point="startPoint" :end-point="endPoint" :waypoints="waypoints" @route-update="handleRouteUpdate" /> <button @click="addWaypoint">添加途经点</button> </div> </template> <script> import DragRoute from './components/DragRoute.vue'; export default { components: { DragRoute }, data() { return { startPoint: [116.397428, 39.90923], // 天安门 endPoint: [116.404, 39.915], // 故宫 waypoints: [ [116.407428, 39.90923], [116.41, 39.91] ] }; }, methods: { handleRouteUpdate(data) { console.log('路线更新:', data); }, addWaypoint() { // 随机添加一个途经点 const lng = 116.39 + Math.random() * 0.03; const lat = 39.9 + Math.random() * 0.03; this.waypoints.push([lng, lat]); } } }; </script>

6. 性能优化与最佳实践

在实际项目中，我们需要考虑地图组件的性能和用户体验。以下是一些优化建议：

6.1 延迟加载地图资源

对于单页应用，可以考虑在用户需要时再加载地图资源：

// 动态加载高德地图JS function loadAMapScript() { return new Promise((resolve, reject) => { if (window.AMap) { return resolve(); } const script = document.createElement('script'); script.src = 'https://webapi.amap.com/maps?v=2.0&key=你的高德Key'; script.onload = resolve; script.onerror = reject; document.head.appendChild(script); }); } // 在组件中使用 async function initMap() { try { await loadAMapScript(); // 地图脚本加载完成后初始化地图 this.map = new AMap.Map(this.$refs.mapContainer, { zoom: 12, center: this.startPoint }); } catch (error) { console.error('加载高德地图失败:', error); } }

6.2 防抖处理频繁的路线搜索

当用户快速拖拽途经点时，可能会触发多次路线搜索请求，可以使用防抖技术优化：

import { debounce } from 'lodash'; // 在组件中 methods: { handleDragEnd: debounce(function(event) { this.dragRoute.search(); }, 500) }

6.3 合理设置地图视野

当路线较长时，自动调整地图视野以显示整个路线：

dragRoute.on('complete', function(result) { // 获取所有途经点的位置 const points = dragRoute.getWayPoints().map(marker => marker.getPosition()); // 设置地图视野包含所有点 map.setFitView(points, { padding: [50, 50, 50, 50], // 四周留白 animate: true // 使用动画效果 }); });

6.4 错误边界处理

为地图组件添加错误边界，避免整个应用崩溃：

// Vue错误边界组件 <template> <div v-if="hasError" class="error-fallback"> <h3>地图加载失败</h3> <button @click="retry">重试</button> </div> <slot v-else></slot> </template> <script> export default { data() { return { hasError: false }; }, errorCaptured(error, vm, info) { this.hasError = true; console.error('地图组件错误:', error); return false; // 阻止错误继续向上传播 }, methods: { retry() { this.hasError = false; this.$nextTick(() => { this.$emit('retry'); }); } } }; </script>

7. 实际应用场景扩展

AMap.DragRoute插件可以应用于多种场景，下面介绍几个典型的应用案例。

7.1 物流配送路线规划

物流系统需要规划包含多个配送点的最优路线：

// 模拟10个配送点 const deliveryPoints = [ [116.407428, 39.90923], [116.417428, 39.91923], [116.427428, 39.92923], // ...更多点 ]; // 创建配送路线 const deliveryRoute = new AMap.DragRoute(map, [ warehouseLocation, // 仓库位置 ...deliveryPoints // 配送点 ], AMap.DrivingPolicy.LEAST_DISTANCE); // 计算总距离和预计时间 deliveryRoute.on('complete', function(result) { const route = result.data.routes[0]; const totalDistance = (route.distance / 1000).toFixed(1); const totalTime = (route.time / 3600).toFixed(1); // 转换为小时 console.log(`本次配送总距离: ${totalDistance}公里`); console.log(`预计总耗时: ${totalTime}小时`); });

7.2 旅游行程规划

为游客规划包含多个景点的旅游路线：

// 景点坐标 const attractions = { '天安门': [116.397428, 39.90923], '故宫': [116.404, 39.915], '颐和园': [116.271, 39.999], '长城': [116.024, 40.362] }; // 创建旅游路线 const tourRoute = new AMap.DragRoute(map, [ attractions['天安门'], attractions['故宫'], attractions['颐和园'] ], AMap.DrivingPolicy.LEAST_TIME); // 添加景点描述 tourRoute.getWayPoints().forEach((marker, index) => { const name = Object.keys(attractions).find( key => attractions[key][0] === marker.getPosition().lng && attractions[key][1] === marker.getPosition().lat ); marker.setTitle(name || (index === 0 ? '起点' : index === tourRoute.getWayPoints().length - 1 ? '终点' : '途经点')); }); // 显示景点信息 map.on('click', function(e) { const marker = e.target; if (marker.getTitle) { alert(`您点击了: ${marker.getTitle()}`); } });

7.3 实时交通路况集成

结合高德的实时交通数据，显示路线上的交通状况：

// 加载交通态势图层 AMap.plugin('AMap.Traffic', function() { const traffic = new AMap.Traffic({ autoRefresh: true // 自动更新 }); map.add(traffic); }); // 创建考虑实时路况的路线 const realtimeRoute = new AMap.DragRoute(map, path, AMap.DrivingPolicy.REAL_TRAFFIC); // 定时刷新路线（每5分钟） setInterval(function() { realtimeRoute.search(); }, 5 * 60 * 1000);

8. 常见问题与解决方案

在实际开发中，你可能会遇到以下问题：

8.1 途经点数量限制

问题：AMap.DragRoute最多支持16个途经点（包括起点和终点），超出限制会报错。

解决方案：

• 对于多于16个点的情况，可以分段规划路线
• 或者使用高德地图的路径规划API自行实现类似功能

// 检查途经点数量 function checkWaypointsLimit(points) { if (points.length > 14) { // 起点+终点+14途经点=16 alert('最多支持14个途经点'); return false; } return true; }

8.2 跨城路线规划

问题：默认情况下，AMap.DragRoute适合市内路线规划，跨城路线可能需要特殊处理。

解决方案：

• 对于长距离路线，可以设置province和city参数
• 或者使用高德地图的AMap.Driving类进行更灵活的规划

const dragRoute = new AMap.DragRoute(map, path, AMap.DrivingPolicy.LEAST_TIME, { // 设置城市和省份 city: '北京', province: '北京' });

8.3 坐标转换问题

问题：有时需要将其他坐标系的坐标转换为高德坐标系。

解决方案：

• 使用高德提供的坐标转换API
• 或者在服务端进行坐标转换

// 将GPS坐标转换为高德坐标 AMap.convertFrom([116.40, 39.90], 'gps', function(status, result) { if (result.info === 'ok') { const lnglat = result.locations[0]; console.log('高德坐标:', lnglat); } });

8.4 移动端适配

问题：在移动设备上，拖拽操作可能需要特别优化。

解决方案：

• 增加触摸事件支持
• 调整标记图标大小以适应小屏幕

// 移动端特定配置 const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent); const dragRoute = new AMap.DragRoute(map, path, AMap.DrivingPolicy.LEAST_TIME, { midMarkerOptions: { offset: isMobile ? new AMap.Pixel(-10, -10) : new AMap.Pixel(-5, -5), icon: new AMap.Icon({ size: isMobile ? new AMap.Size(25, 25) : new AMap.Size(15, 15), image: 'https://webapi.amap.com/theme/v1.3/markers/n/mid.png' }) } });

9. 进阶技巧与扩展思路

掌握了基础功能后，我们可以探索一些更高级的应用技巧。

9.1 结合地点搜索API

实现搜索地点并添加到路线的功能：

// 搜索地点并添加到路线 function searchAndAddPlace(keyword, city) { AMap.plugin('AMap.PlaceSearch', function() { const placeSearch = new AMap.PlaceSearch({ city: city }); placeSearch.search(keyword, function(status, result) { if (status === 'complete' && result.poiList.pois.length) { const poi = result.poiList.pois[0]; addWaypoint([poi.location.lng, poi.location.lat]); } }); }); }

9.2 路线保存与分享

将规划好的路线保存到数据库或生成分享链接：

// 生成路线分享链接 function generateShareLink(route) { const points = route.getWayPoints().map(marker => { const pos = marker.getPosition(); return `${pos.lng},${pos.lat}`; }).join('|'); return `${window.location.origin}/share?route=${encodeURIComponent(points)}`; } // 解析分享的路线 function parseShareLink(link) { const params = new URLSearchParams(link.split('?')[1]); const pointsStr = params.get('route'); return pointsStr.split('|').map(point => { const [lng, lat] = point.split(','); return [parseFloat(lng), parseFloat(lat)]; }); }

9.3 3D路线展示

结合高德地图的3D功能，实现更炫酷的路线展示：

// 切换到3D视图 function enable3DView() { map.setViewMode('3D'); map.setPitch(60); // 设置俯仰角 // 为路线添加高度 const lineLayer = new Loca.LineLayer({ map: map, zIndex: 10 }); dragRoute.on('complete', function(result) { const path = result.data.routes[0].path.map(p => [p.lng, p.lat, 100]); // 添加高度 lineLayer.setData([{ path }], { lnglat: 'path' }); lineLayer.setOptions({ style: { height: 100, // 高度 color: '#3366FF', opacity: 0.8 } }); lineLayer.render(); }); }

9.4 路线优化算法

对于物流等专业场景，可以结合算法优化途经点顺序：

// 简单的最近邻算法优化途经点顺序 function optimizeRoute(points) { if (points.length <= 2) return points; const optimized = [points[0]]; // 起点 let remaining = points.slice(1); while (remaining.length) { const last = optimized[optimized.length - 1]; let nearestIdx = 0; let minDist = Infinity; // 找出距离上一个点最近的点 remaining.forEach((point, idx) => { const dist = Math.sqrt( Math.pow(point[0] - last[0], 2) + Math.pow(point[1] - last[1], 2) ); if (dist < minDist) { minDist = dist; nearestIdx = idx; } }); optimized.push(remaining[nearestIdx]); remaining.splice(nearestIdx, 1); } return optimized; }

10. 总结与资源推荐

通过本文的介绍，我们全面探讨了高德地图 JS API v2 中AMap.DragRoute插件的使用方法，从基础配置到高级功能实现，再到实际项目中的组件封装和优化技巧。

10.1 关键点回顾

• 基础配置：引入插件、初始化地图、创建可拖拽路线实例
• 事件处理：监听路线规划完成、拖拽事件和错误事件
• 自定义样式：设置起点、终点和途经点的图标样式
• 数据获取：获取路线距离、时间和详细路径点
• 组件封装：将功能封装为可复用的 Vue/React 组件
• 性能优化：延迟加载、防抖处理、合理设置视野
• 实际应用：物流配送、旅游规划等场景的实现
• 问题解决：途经点限制、跨城路线、坐标转换等常见问题

10.2 推荐资源

1. 高德地图 JS API 官方文档
2. DragRoute 插件详细说明
3. 高德地图示例中心
4. GitHub 上的开源地图项目

10.3 后续学习建议

• 探索高德地图的其他插件，如AMap.Driving、AMap.Transfer等
• 学习结合 WebGL 实现更复杂的地图可视化效果
• 了解服务端的地图数据处理和存储方案
• 关注高德地图 API 的更新日志，及时获取新特性

在实际项目中，根据具体需求选择合适的实现方案，平衡功能丰富性和性能表现。AMap.DragRoute插件虽然功能强大，但在某些特殊场景下，可能需要结合其他 API 或自定义实现来满足需求。