1. 测距功能的核心设计思路

地图测距这个需求，乍一看很简单——不就是点两个点，算个距离嘛。但真正动手做过的人都知道，从“能用”到“好用”之间隔着大量细节。我前后在三个项目里实现过 Mapbox GL 的测距模块，每次都在上一版基础上推翻重来，原因就是交互体验始终差一口气。

1.1 为什么选择动态画线而不是静态绘制

最早一版我的做法是：用户点击地图，记录坐标，然后在地图上画一条完整的线。逻辑上没问题，但体验上有个致命伤——用户点完第一个点之后，完全不知道下一个点会连到哪里。鼠标移动的过程中没有任何反馈，必须点下去才看到线，点错了还得撤销重来。

动态画线的核心思路是：在用户移动鼠标的过程中，实时预览“如果在这里点击，线会画成什么样”。这需要维护两条线——一条是已经确认的“实线”，一条是跟随鼠标的“虚线预览线”。每次鼠标移动，更新虚线终点；每次点击，把虚线终点固化到实线里，同时虚线重新开始。

这个设计的好处是显而易见的。用户操作时有掌控感，知道自己在干什么，误操作率大幅下降。代价是每次mousemove都要更新 GeoJSON 数据源并触发重绘，对性能有一定要求。实测下来，只要控制好更新频率（后面会讲节流策略），在几千个点的场景下依然流畅。

1.2 Tooltip 的角色定位与信息层级

Tooltip 在这个功能里承担两个职责：一是显示当前鼠标位置到上一个确认点的距离（段距离），二是显示整条测距线的累计总距离。这两个信息不能混在一起展示，否则用户分不清哪个是哪个。

我的做法是：Tooltip 主体显示段距离，副标题显示总距离。段距离用大号字体，总距离用小号灰色字体。这样用户在移动鼠标时，视线焦点自然落在段距离上，需要看总距离时稍微下移即可。

还有一个细节：Tooltip 的位置不能直接贴着鼠标，否则会遮挡用户正在看的那个点。我一般设置一个 15px 左右的偏移量，让 Tooltip 出现在鼠标右下方。如果鼠标靠近屏幕右边缘，则自动翻转到左上方，避免 Tooltip 被裁切。

1.3 整体架构拆解

整个测距模块可以拆成四个独立的部分：

• 状态管理层：维护测距是否激活、已确认的点列表、当前鼠标位置、是否正在拖拽等状态。
• 渲染层：管理三个数据源——实线数据源、虚线预览数据源、节点标记数据源。
• 交互层：监听地图的 click、mousemove、dblclick、keydown 等事件，驱动状态变更。
• UI 层：Tooltip 的 DOM 元素创建、位置更新、内容更新、显示隐藏。

这四层之间通过一个简单的事件总线或回调函数通信，不要互相直接引用。我见过有人把所有逻辑塞在一个函数里，后期加个“撤销上一个点”的功能都改得痛不欲生。

提示：如果你的项目用的是 React/Vue 这类框架，建议把状态管理层放在框架的响应式系统里，渲染层和 UI 层通过 watch/effect 响应状态变化。但地图实例本身不要放进响应式系统，否则会有性能问题。

2. 核心细节解析与实操要点

2.1 数据源的设计与 GeoJSON 结构

Mapbox GL 的线绘制依赖 GeoJSON 数据源。我一般创建三个独立的 source：

// 实线数据源：已确认的测距路径 map.addSource('measure-line', { type: 'geojson', data: { type: 'Feature', geometry: { type: 'LineString', coordinates: [] } } }); // 虚线预览数据源：从最后一个确认点到鼠标当前位置 map.addSource('measure-preview', { type: 'geojson', data: { type: 'Feature', geometry: { type: 'LineString', coordinates: [] } } }); // 节点标记数据源：每个确认点的圆点 map.addSource('measure-points', { type: 'geojson', data: { type: 'FeatureCollection', features: [] } });

这里有个容易踩的坑：不要试图用一个 source 同时画实线和虚线。虽然理论上可以用line-dasharray属性配合 feature 的 properties 来区分，但每次更新都要重建整个 FeatureCollection，性能反而更差。分开管理，各司其职，更新时只动需要动的那一个。

2.2 距离计算的精度问题

Mapbox GL 本身不提供测距 API，距离计算得自己来。最常用的公式是Haversine 公式，它把地球近似为球体，计算两点间的大圆距离。在大多数场景下，Haversine 的精度已经足够（误差在 0.5% 以内）。

但如果你做的是高精度测绘类应用，比如电力巡线、管道测量，那就得用Vincenty 公式，它把地球视为椭球体，精度更高，但计算量也更大。我的建议是：普通场景用 Haversine，专业场景用 Vincenty，不要为了“可能用不到”的精度牺牲性能。

Haversine 公式的实现：

function haversineDistance(coord1, coord2) { const R = 6371008.8; // 地球平均半径，单位米 const toRad = Math.PI / 180; const lat1 = coord1[1] * toRad; const lat2 = coord2[1] * toRad; const dLat = (coord2[1] - coord1[1]) * toRad; const dLon = (coord2[0] - coord1[0]) * toRad; const a = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2; const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a)); return R * c; }

注意坐标顺序：GeoJSON 是[经度, 纬度]，而很多距离计算库习惯[纬度, 经度]。我在这上面栽过跟头，算出来的距离差了十万八千里，排查了半天才发现是坐标顺序反了。

2.3 动态画线的节流策略

mousemove事件的触发频率极高，一秒钟可能几十上百次。如果每次触发都更新数据源并重绘，地图会卡成幻灯片。必须做节流。

我的做法是：用requestAnimationFrame做节流，而不是setTimeout。因为requestAnimationFrame的回调执行时机与浏览器渲染帧对齐，不会出现“更新了但没渲染”的浪费。

let rafId = null; let pendingCoord = null; function onMouseMove(e) { pendingCoord = [e.lngLat.lng, e.lngLat.lat]; if (rafId === null) { rafId = requestAnimationFrame(() => { updatePreviewLine(pendingCoord); updateTooltip(pendingCoord); rafId = null; }); } }

这样即使mousemove触发了一百次，实际更新最多也就每秒 60 次（取决于显示器刷新率），而且每次更新都恰好赶在渲染之前，效率最高。

2.4 Tooltip 的 DOM 管理与定位

Tooltip 不要用 Mapbox 的 Popup 类，那个太重了，而且定位逻辑不够灵活。我直接用原生 DOM 元素，绝对定位在地图容器里。

const tooltip = document.createElement('div'); tooltip.className = 'measure-tooltip'; tooltip.style.cssText = ` position: absolute; pointer-events: none; background: rgba(0, 0, 0, 0.75); color: #fff; padding: 6px 10px; border-radius: 4px; font-size: 13px; line-height: 1.4; white-space: nowrap; z-index: 1000; display: none; `; map.getContainer().appendChild(tooltip);

定位时，用map.project(lngLat)把地理坐标转成屏幕像素坐标，然后加上偏移量：

function updateTooltipPosition(lngLat) { const point = map.project(lngLat); const container = map.getContainer(); const tooltipWidth = tooltip.offsetWidth; const tooltipHeight = tooltip.offsetHeight; let left = point.x + 15; let top = point.y + 15; // 右边缘翻转 if (left + tooltipWidth > container.clientWidth) { left = point.x - tooltipWidth - 15; } // 下边缘翻转 if (top + tooltipHeight > container.clientHeight) { top = point.y - tooltipHeight - 15; } tooltip.style.left = left + 'px'; tooltip.style.top = top + 'px'; }

注意：map.project()返回的是相对于地图容器的像素坐标，不是相对于页面的。所以 Tooltip 必须挂在地图容器内部，且地图容器要有position: relative。

3. 完整实操流程与核心环节实现

3.1 初始化与图层配置

先创建地图实例，然后依次添加三个数据源和对应的图层。图层的顺序很重要：实线在最底层，虚线在中间，节点在最上层。这样节点不会被线遮挡。

// 实线图层 map.addLayer({ id: 'measure-line-layer', type: 'line', source: 'measure-line', layout: { 'line-cap': 'round', 'line-join': 'round' }, paint: { 'line-color': '#ff6b35', 'line-width': 3, 'line-opacity': 0.9 } }); // 虚线预览图层 map.addLayer({ id: 'measure-preview-layer', type: 'line', source: 'measure-preview', layout: { 'line-cap': 'round', 'line-join': 'round' }, paint: { 'line-color': '#ff6b35', 'line-width': 2, 'line-opacity': 0.6, 'line-dasharray': [2, 2] } }); // 节点图层 map.addLayer({ id: 'measure-points-layer', type: 'circle', source: 'measure-points', paint: { 'circle-radius': 5, 'circle-color': '#fff', 'circle-stroke-color': '#ff6b35', 'circle-stroke-width': 2 } });

line-dasharray的值是[实线长度, 空白长度]，单位是像素。我一般用[2, 2]，虚线感明显但不至于太碎。如果你想要更长的虚线，可以改成[4, 3]之类的。

3.2 点击添加测距点

每次点击地图，把当前坐标追加到已确认点列表，然后更新实线数据源和节点数据源。

let confirmedPoints = []; function onMapClick(e) { if (!measureActive) return; const coord = [e.lngLat.lng, e.lngLat.lat]; confirmedPoints.push(coord); // 更新实线 map.getSource('measure-line').setData({ type: 'Feature', geometry: { type: 'LineString', coordinates: confirmedPoints } }); // 更新节点 const features = confirmedPoints.map((c, i) => ({ type: 'Feature', geometry: { type: 'Point', coordinates: c }, properties: { index: i } })); map.getSource('measure-points').setData({ type: 'FeatureCollection', features }); // 清空预览线 map.getSource('measure-preview').setData({ type: 'Feature', geometry: { type: 'LineString', coordinates: [] } }); }

这里有个细节：点击时如果已经有预览线，要先清空预览线。否则用户点击后，预览线还停留在上一个位置，视觉上会有一条“幽灵线”残留，直到鼠标再次移动才消失。

3.3 鼠标移动更新预览线与 Tooltip

这是整个模块最核心的部分。每次鼠标移动，要做三件事：更新预览线终点、更新 Tooltip 内容、更新 Tooltip 位置。

function updatePreviewLine(currentCoord) { if (confirmedPoints.length === 0) return; const lastPoint = confirmedPoints[confirmedPoints.length - 1]; map.getSource('measure-preview').setData({ type: 'Feature', geometry: { type: 'LineString', coordinates: [lastPoint, currentCoord] } }); } function updateTooltipContent(currentCoord) { if (confirmedPoints.length === 0) { tooltip.style.display = 'none'; return; } const lastPoint = confirmedPoints[confirmedPoints.length - 1]; const segmentDist = haversineDistance(lastPoint, currentCoord); const totalDist = calculateTotalDistance(confirmedPoints) + segmentDist; tooltip.innerHTML = ` <div style="font-size:15px;font-weight:600;">${formatDistance(segmentDist)}</div> <div style="font-size:11px;color:#ccc;margin-top:2px;">总计 ${formatDistance(totalDist)}</div> `; tooltip.style.display = 'block'; }

formatDistance函数负责把米数转成人类可读的格式：小于 1000 米显示“XX 米”，大于等于 1000 米显示“X.XX 公里”。

function formatDistance(meters) { if (meters < 1000) { return meters.toFixed(1) + ' 米'; } return (meters / 1000).toFixed(2) + ' 公里'; }

3.4 双击结束测距与右键撤销

双击结束测距是地图交互的通用约定。但 Mapbox GL 的dblclick事件有个坑：它会在click之后触发，导致双击时先添加了一个点，然后才结束测距。解决方案是用一个定时器区分单击和双击：

let clickTimer = null; map.on('click', (e) => { if (clickTimer) { clearTimeout(clickTimer); clickTimer = null; return; // 双击的第二下，忽略 } clickTimer = setTimeout(() => { clickTimer = null; handleSingleClick(e); }, 250); }); map.on('dblclick', (e) => { if (clickTimer) { clearTimeout(clickTimer); clickTimer = null; } finishMeasure(); });

250ms 是经验值，太短了用户双击会被识别成两次单击，太长了单击响应会感觉迟钝。你可以根据实际用户群体调整，年轻用户居多的产品可以调到 200ms，中老年用户居多的调到 300ms。

右键撤销上一个点：

map.on('contextmenu', (e) => { e.preventDefault(); if (confirmedPoints.length === 0) return; confirmedPoints.pop(); // 更新实线 map.getSource('measure-line').setData({ type: 'Feature', geometry: { type: 'LineString', coordinates: confirmedPoints } }); // 更新节点 const features = confirmedPoints.map((c, i) => ({ type: 'Feature', geometry: { type: 'Point', coordinates: c }, properties: { index: i } })); map.getSource('measure-points').setData({ type: 'FeatureCollection', features }); // 如果还有剩余点，更新预览线到鼠标位置 if (confirmedPoints.length > 0) { const lastPoint = confirmedPoints[confirmedPoints.length - 1]; // 预览线会在下次 mousemove 时自动更新 } else { map.getSource('measure-preview').setData({ type: 'Feature', geometry: { type: 'LineString', coordinates: [] } }); tooltip.style.display = 'none'; } });

3.5 测距结果的展示与复制

测距结束后，我一般会在 Tooltip 里显示总距离，并提供一个“复制”按钮。但 Tooltip 是pointer-events: none的，没法点击。所以结束时的结果展示要换一个元素，或者临时把 Tooltip 的pointer-events改成auto。

我的做法是：测距结束后，在屏幕中央或底部弹出一个结果面板，显示总距离和“复制结果”按钮。复制的内容格式为“总距离：X.XX 公里，共 N 个测距点”。

function finishMeasure() { if (confirmedPoints.length < 2) { resetMeasure(); return; } const totalDist = calculateTotalDistance(confirmedPoints); const resultText = `总距离：${formatDistance(totalDist)}，共 ${confirmedPoints.length} 个测距点`; // 显示结果面板 showResultPanel(resultText); // 清空预览线和 Tooltip map.getSource('measure-preview').setData({ type: 'Feature', geometry: { type: 'LineString', coordinates: [] } }); tooltip.style.display = 'none'; measureActive = false; }

4. 常见问题与排查技巧实录

4.1 测距线不显示或显示异常

这是最常见的问题，通常有以下几个原因：

我遇到过一次线不显示的问题，排查了半天发现是map.addSource时数据源的data字段写成了{ type: 'Feature', geometry: { type: 'LineString', coordinates: [] } }，但coordinates是空数组，Mapbox 直接忽略了。后来改成先给一个占位坐标，或者等有数据时再addSource，问题解决。

4.2 Tooltip 闪烁或位置跳动

Tooltip 闪烁通常是因为mousemove触发太频繁，Tooltip 的display属性在block和none之间反复切换。解决方案是：不要频繁切换 display，而是用visibility或opacity。或者干脆一直显示，只是内容为空时透明。

位置跳动则可能是因为map.project()的结果在每一帧之间有细微差异。用requestAnimationFrame节流后，这个问题基本消失。

还有一个坑：如果 Tooltip 的宽度是动态的（内容长度变化），offsetWidth在内容更新后才会变化。如果你先读offsetWidth再更新内容，拿到的就是旧宽度。正确顺序是：先更新内容，再读 offsetWidth，最后定位。

4.3 性能问题与优化策略

测距点超过 100 个之后，每次mousemove都要重新计算总距离，如果每次都从头遍历所有点，计算量是 O(n)。优化方法是维护一个totalDistance变量，每次添加点时累加，撤销点时减去，这样总距离计算就是 O(1)。

let totalDistance = 0; function addPoint(coord) { if (confirmedPoints.length > 0) { const lastPoint = confirmedPoints[confirmedPoints.length - 1]; totalDistance += haversineDistance(lastPoint, coord); } confirmedPoints.push(coord); } function removeLastPoint() { if (confirmedPoints.length < 2) { confirmedPoints.pop(); totalDistance = 0; return; } const lastPoint = confirmedPoints.pop(); const newLastPoint = confirmedPoints[confirmedPoints.length - 1]; totalDistance -= haversineDistance(newLastPoint, lastPoint); }

另外，如果测距点非常多（比如 500 个以上），可以考虑用line-gradient或者简化显示，但大多数业务场景不会用到这么多点。

4.4 移动端适配的坑

移动端没有mousemove事件，只有touchmove。Mapbox GL 在移动端会把触摸事件转换成mousemove和click，但行为有差异。比如，手指按下时就会触发click，而不是抬起时。这导致移动端测距时，用户想拖动地图却意外添加了测距点。

解决方案是：在移动端用长按来添加测距点，而不是单击。或者提供一个“添加点”按钮，用户点击按钮才添加当前地图中心的点。

let isTouchDevice = 'ontouchstart' in window; if (isTouchDevice) { // 移动端：长按添加点 let longPressTimer = null; map.on('touchstart', (e) => { longPressTimer = setTimeout(() => { handleSingleClick(e); }, 500); }); map.on('touchend', () => { clearTimeout(longPressTimer); }); map.on('touchmove', () => { clearTimeout(longPressTimer); }); }

4.5 测距单位切换与精度控制

不同场景对距离单位的需求不同。国内用户习惯“米/公里”，但有些国际项目需要“英尺/英里”。我一般提供一个单位切换开关，默认公制。

let unitSystem = 'metric'; // 'metric' 或 'imperial' function formatDistance(meters) { if (unitSystem === 'metric') { if (meters < 1000) return meters.toFixed(1) + ' 米'; return (meters / 1000).toFixed(2) + ' 公里'; } else { const feet = meters * 3.28084; if (feet < 5280) return feet.toFixed(1) + ' 英尺'; return (feet / 5280).toFixed(2) + ' 英里'; } }

精度方面，我一般保留两位小数。但要注意，toFixed返回的是字符串，如果后续还要参与计算，记得用parseFloat转回来。

提示：如果测距结果要用于正式报告或存档，建议在 Tooltip 和结果面板里都显示完整精度（比如 6 位小数），同时提供一个“复制高精度结果”的选项。用户日常看两位小数就够了，但存档时需要原始精度。

5. 一些实战中攒下来的经验

测距功能上线后，我收到过一条用户反馈：“为什么我点了一个点，移动鼠标时线在动，但距离显示的是 0？”排查后发现，用户只点了一个点，还没有点第二个点，此时段距离是“上一个确认点到鼠标”的距离，但上一个确认点就是第一个点，所以段距离是有的。问题出在calculateTotalDistance上——它计算的是已确认点之间的总距离，只有一个点时总距离是 0。用户看到“总计 0 米”，以为功能坏了。

后来我改成：只有一个确认点时，Tooltip 只显示段距离，不显示总距离。两个点以上才显示总距离。这个小改动让用户困惑率大幅下降。

还有一个经验：测距过程中要禁用地图的默认双击缩放。Mapbox GL 默认双击是放大，和测距的双击结束冲突。需要在测距激活时调用map.doubleClickZoom.disable()，测距结束后再enable()。

function activateMeasure() { measureActive = true; map.doubleClickZoom.disable(); map.getCanvas().style.cursor = 'crosshair'; } function deactivateMeasure() { measureActive = false; map.doubleClickZoom.enable(); map.getCanvas().style.cursor = ''; }

光标样式改成crosshair（十字准星）也是个细节，用户看到十字准星就知道现在处于“绘制模式”，心理模型更清晰。

最后分享一个我最近才加上的功能：测距线的“吸附”效果。当鼠标靠近某个已确认点时，预览线的终点自动吸附到那个点上。这在绘制闭合区域时特别有用，用户不需要精确点击起点，靠近就行。实现方式是每次mousemove时，计算鼠标位置到所有已确认点的屏幕像素距离，如果小于 10px，就把预览线终点设为那个点的坐标。

function snapToNearestPoint(currentCoord) { const currentPixel = map.project(currentCoord); let nearest = null; let minDist = 10; // 10px 吸附阈值 confirmedPoints.forEach((point, index) => { const pixel = map.project(point); const dist = Math.sqrt( (pixel.x - currentPixel.x) ** 2 + (pixel.y - currentPixel.y) ** 2 ); if (dist < minDist) { minDist = dist; nearest = { coord: point, index }; } }); return nearest ? nearest.coord : currentCoord; }

这个功能加上之后，用户绘制多边形区域的效率明显提升，尤其是需要闭合的时候，不用再小心翼翼地瞄准起点了。