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

Vue3 + Baidu Map API 实战：手把手教你实现一个带搜索和自定义弹窗的店铺地图

news 2026/6/8 6:09:34

Vue3 + 百度地图深度实战：打造商业级店铺地图系统

在本地生活服务和电商平台蓬勃发展的今天，地图功能已成为连接线上线下的关键桥梁。想象一下这样的场景：用户打开你的应用，地图自动定位到附近区域，搜索框输入"咖啡厅"后，周边店铺立刻以醒目标记呈现，点击任意标记还能看到精美的店铺卡片——这正是我们要实现的商业级地图解决方案。

不同于基础的地图标记展示，我们将基于Vue3的组合式API和百度地图JavaScript API，构建一个包含智能搜索、自动定位和高定制化信息窗口的完整系统。这套方案特别适合需要展示实体门店的O2O平台、连锁企业管理系统或本地生活服务应用。

1. 环境准备与百度地图接入

1.1 申请百度地图开发者密钥

所有百度地图服务都需要合法的AK密钥。前往百度地图开放平台注册开发者账号，在控制台创建应用时需注意：

应用类型选择"浏览器端"
白名单建议设置为*用于开发测试，上线前需更改为生产域名
启用Place API和Geocoding API这两个必需服务

获取AK后，我们将其存储在环境变量中。创建.env.local文件：

VITE_BAIDU_MAP_AK=您的实际AK密钥

1.2 Vue3项目集成百度地图

推荐使用官方提供的vue-baidu-map-3x组件库，它针对Vue3进行了优化：

npm install vue-baidu-map-3x

在main.js中全局注册：

import { createApp } from 'vue' import BaiduMap from 'vue-baidu-map-3x' const app = createApp(App) app.use(BaiduMap, { ak: import.meta.env.VITE_BAIDU_MAP_AK })

2. 核心地图组件架构设计

2.1 基础地图容器组件

创建MapContainer.vue作为地图承载组件：

<template> <div class="map-wrapper"> <baidu-map class="bm-view" :center="mapCenter" :zoom="zoomLevel" :scroll-wheel-zoom="true" @ready="handleMapReady" > <slot></slot> </baidu-map> </div> </template> <script setup> import { ref } from 'vue' const mapCenter = ref({ lng: 116.404, lat: 39.915 }) const zoomLevel = ref(15) const mapInstance = ref(null) const handleMapReady = ({ BMap, map }) => { mapInstance.value = map // 自动定位到用户当前位置 if (navigator.geolocation) { navigator.geolocation.getCurrentPosition(pos => { const point = new BMap.Point( pos.coords.longitude, pos.coords.latitude ) mapCenter.value = point }) } } defineExpose({ mapInstance }) </script> <style scoped> .map-wrapper { position: relative; height: 100vh; width: 100%; } .bm-view { width: 100%; height: 100%; } </style>

2.2 店铺标记点组件

创建ShopMarker.vue实现可复用的标记点：

<template> <bm-marker :position="position" :icon="customIcon" @click="handleMarkerClick" > <bm-info-window :show="showInfoWindow" @close="showInfoWindow = false" > <ShopInfoCard :shop="shopData" /> </bm-info-window> </bm-marker> </template> <script setup> import { ref } from 'vue' const props = defineProps({ position: { type: Object, required: true }, shopData: { type: Object, required: true } }) const showInfoWindow = ref(false) const customIcon = { url: 'https://api.iconify.design/mdi/store.svg', size: { width: 32, height: 32 } } const handleMarkerClick = () => { showInfoWindow.value = true } </script>

3. 实现店铺搜索与地理编码

3.1 智能搜索组件

创建MapSearch.vue组件：

<template> <div class="search-box"> <input v-model="searchQuery" @keyup.enter="handleSearch" placeholder="搜索店铺或地址..." /> <button @click="handleSearch">搜索</button> </div> </template> <script setup> import { ref } from 'vue' import { useMapStore } from '@/stores/map' const searchQuery = ref('') const mapStore = useMapStore() const handleSearch = () => { if (!searchQuery.value.trim()) return const localSearch = new BMap.LocalSearch(mapStore.mapInstance, { onSearchComplete: results => { if (localSearch.getStatus() === BMAP_STATUS_SUCCESS) { const pois = results.getPoi() mapStore.updateShops(pois.map(poi => ({ id: poi.uid, name: poi.title, address: poi.address, position: poi.point, phone: poi.phone || '暂无', businessHours: '09:00-21:00' }))) } } }) localSearch.search(searchQuery.value) } </script> <style scoped> .search-box { position: absolute; top: 20px; left: 20px; z-index: 1000; display: flex; background: white; padding: 8px; border-radius: 4px; box-shadow: 0 2px 6px rgba(0,0,0,0.1); } input { padding: 8px; border: 1px solid #ddd; border-radius: 4px; min-width: 300px; } button { margin-left: 8px; padding: 0 16px; background: #3385ff; color: white; border: none; border-radius: 4px; cursor: pointer; } </style>

3.2 地址解析服务

实现地址与坐标的相互转换：

// utils/geocoder.js export const addressToPoint = async (address) => { return new Promise((resolve) => { const geocoder = new BMap.Geocoder() geocoder.getPoint(address, point => { resolve(point || null) }) }) } export const pointToAddress = async (point) => { return new Promise((resolve) => { const geocoder = new BMap.Geocoder() geocoder.getLocation(point, result => { resolve(result?.address || '未知地址') }) }) }

4. 高级功能：自定义信息窗口

4.1 店铺信息卡片组件

创建ShopInfoCard.vue：

<template> <div class="shop-card"> <div class="shop-header"> <img :src="shop.logo || defaultLogo" class="shop-logo" /> <div> <h3>{{ shop.name }}</h3> <div class="rating"> <span v-for="i in 5" :key="i" :class="['star', i <= shop.rating ? 'filled' : '']"> ★ </span> </div> </div> </div> <div class="shop-details"> <p><strong>营业时间：</strong>{{ shop.businessHours }}</p> <p><strong>联系电话：</strong>{{ shop.phone }}</p> <p><strong>地址：</strong>{{ shop.address }}</p> </div> <div class="action-buttons"> <button @click="handleNavigation">导航</button> <button @click="handleCall">拨打电话</button> </div> </div> </template> <script setup> import { computed } from 'vue' import defaultLogo from '@/assets/shop-default.png' const props = defineProps({ shop: { type: Object, required: true } }) const handleNavigation = () => { // 调用百度地图导航接口 const { lng, lat } = props.shop.position window.open(`https://api.map.baidu.com/direction?origin=我的位置&destination=${lat},${lng}&mode=driving`) } const handleCall = () => { if (props.shop.phone) { window.location.href = `tel:${props.shop.phone}` } } </script> <style scoped> .shop-card { width: 280px; padding: 16px; font-family: 'PingFang SC', sans-serif; } .shop-header { display: flex; align-items: center; margin-bottom: 12px; } .shop-logo { width: 50px; height: 50px; border-radius: 4px; margin-right: 12px; object-fit: cover; } .rating { color: #ffb800; font-size: 14px; } .star { opacity: 0.3; } .star.filled { opacity: 1; } .shop-details { margin: 12px 0; font-size: 14px; line-height: 1.6; } .action-buttons { display: flex; gap: 8px; } button { flex: 1; padding: 6px 0; background: #3385ff; color: white; border: none; border-radius: 4px; cursor: pointer; } </style>

4.2 信息窗口动画优化

为提升用户体验，我们可以为信息窗口添加动画效果。修改ShopMarker.vue：

<template> <bm-marker :position="position" @click="handleMarkerClick"> <bm-info-window :show="showInfoWindow" @close="showInfoWindow = false" :offset="{ width: 0, height: -30 }" class="animated-window" > <ShopInfoCard :shop="shopData" /> </bm-info-window> </bm-marker> </template> <style scoped> .animated-window { animation: fadeIn 0.3s ease-out; } @keyframes fadeIn { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } } </style>

5. 性能优化与最佳实践

5.1 标记点聚类优化

当展示大量店铺时，使用标记点聚类提升性能：

import BMapLib from 'vue-baidu-map-3x/lib/extra/MarkerClusterer' const setupMarkerClusterer = (map, markers) => { const markerClusterer = new BMapLib.MarkerClusterer(map, { markers: markers.map(createMarker), styles: [{ url: 'https://api.iconify.design/mdi/circle-multiple.svg', size: new BMap.Size(40, 40), textColor: '#fff', textSize: 12 }] }) return markerClusterer }

5.2 地图事件节流处理

对地图移动事件进行节流，避免频繁触发搜索：

import { throttle } from 'lodash-es' const throttledSearch = throttle(searchNearbyShops, 1000) const handleMapMoveEnd = () => { const center = mapInstance.value.getCenter() throttledSearch(center) }

5.3 离线缓存策略

使用localStorage缓存店铺数据：

const CACHE_KEY = 'shop_map_data' const saveToCache = (data) => { localStorage.setItem(CACHE_KEY, JSON.stringify({ data, timestamp: Date.now() })) } const loadFromCache = () => { const cached = localStorage.getItem(CACHE_KEY) if (!cached) return null const { data, timestamp } = JSON.parse(cached) // 缓存有效期1小时 if (Date.now() - timestamp < 3600 * 1000) { return data } return null }

6. 完整示例与业务集成

6.1 主页面集成

ShopMapPage.vue的完整实现：

<template> <div class="shop-map-page"> <MapContainer ref="mapRef"> <template #default> <ShopMarker v-for="shop in shops" :key="shop.id" :position="shop.position" :shop-data="shop" /> </template> </MapContainer> <MapSearch /> <div class="shop-list-toggle" @click="showList = !showList"> {{ showList ? '隐藏列表' : '显示列表' }} </div> <transition name="slide-up"> <ShopList v-if="showList" :shops="shops" /> </transition> </div> </template> <script setup> import { ref, onMounted } from 'vue' import { useMapStore } from '@/stores/map' import MapContainer from '@/components/MapContainer.vue' import MapSearch from '@/components/MapSearch.vue' import ShopMarker from '@/components/ShopMarker.vue' import ShopList from '@/components/ShopList.vue' const mapRef = ref(null) const shops = ref([]) const showList = ref(false) const mapStore = useMapStore() onMounted(async () => { await mapRef.value?.mapInstance // 初始加载附近店铺 const center = mapStore.mapInstance.getCenter() searchNearbyShops(center) }) const searchNearbyShops = (center) => { // 实际项目中这里调用API获取数据 const demoShops = generateDemoShops(center) shops.value = demoShops } </script> <style scoped> .shop-map-page { position: relative; height: 100vh; width: 100%; } .shop-list-toggle { position: absolute; bottom: 20px; left: 50%; transform: translateX(-50%); background: white; padding: 8px 16px; border-radius: 20px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); cursor: pointer; z-index: 1000; } .slide-up-enter-active, .slide-up-leave-active { transition: all 0.3s ease; } .slide-up-enter-from, .slide-up-leave-to { transform: translateY(100%); } </style>

6.2 与后端API集成

实际项目中，店铺数据通常来自后端API。这里提供一个模拟的API调用示例：

// api/shop.js import { mockShops } from '@/mocks/shops' export const fetchNearbyShops = async (center, radius = 2000) => { // 实际项目中替换为真实的API调用 return new Promise(resolve => { setTimeout(() => { resolve(mockShops.filter(shop => { const distance = calculateDistance( center.lat, center.lng, shop.position.lat, shop.position.lng ) return distance <= radius })) }, 500) }) } function calculateDistance(lat1, lng1, lat2, lng2) { // 简化的距离计算，实际项目应使用更精确的算法 return Math.sqrt(Math.pow(lat1 - lat2, 2) + Math.pow(lng1 - lng2, 2)) * 111000 }

7. 错误处理与边界情况

7.1 地图加载失败处理

增强MapContainer.vue的健壮性：

<template> <div class="map-wrapper"> <div v-if="loadError" class="map-error"> <p>地图加载失败，请刷新重试</p> <button @click="reloadPage">刷新页面</button> </div> <baidu-map v-else ...></baidu-map> </div> </template> <script setup> const loadError = ref(false) const handleMapReady = ({ BMap, map }) => { try { // ...原有逻辑 } catch (error) { console.error('地图初始化失败:', error) loadError.value = true } } const reloadPage = () => location.reload() </script>

7.2 定位失败降级方案

当用户拒绝定位或定位失败时，提供默认城市选择：

const handleMapReady = ({ BMap, map }) => { if (navigator.geolocation) { navigator.geolocation.getCurrentPosition( pos => { // 定位成功处理 }, error => { console.warn('定位失败:', error) // 使用IP定位作为降级方案 const myCity = new BMap.LocalCity() myCity.get(result => { mapCenter.value = result.center }) }, { timeout: 5000 } ) } }

8. 移动端适配与增强体验

8.1 触摸事件优化

针对移动设备优化标记点点击体验：

<template> <bm-marker @touchstart="handleTouchStart" @touchend="handleTouchEnd" > <!-- ... --> </bm-marker> </template> <script setup> const touchTimer = ref(null) const handleTouchStart = () => { touchTimer.value = setTimeout(() => { showInfoWindow.value = true }, 300) } const handleTouchEnd = () => { clearTimeout(touchTimer.value) } </script>

8.2 手势缩放控制

禁用双指缩放页面干扰地图操作：

.map-wrapper { touch-action: none; }

9. 测试与调试技巧

9.1 开发环境模拟定位

Chrome开发者工具中模拟不同位置：

打开DevTools (F12)
进入"传感器"面板
覆盖地理位置坐标
设置合适的模拟精度

9.2 性能监测

使用百度地图自带的性能统计工具：

const map = new BMap.Map("container") map.enablePerformanceMonitor = true

10. 部署注意事项

10.1 AK密钥安全

生产环境务必：

限制AK的HTTP Referer
设置IP白名单
定期轮换密钥
不要将AK直接暴露在前端代码中

10.2 CDN加速

考虑使用百度地图的CDN加速：

<script type="text/javascript" src="https://api.map.baidu.com/api?v=3.0&ak=您的AK&s=1"> </script>

11. 扩展功能思路

11.1 热力图展示

const heatmapOverlay = new BMapLib.HeatmapOverlay({ radius: 20, visible: true }) map.addOverlay(heatmapOverlay) // 设置热力图数据 heatmapOverlay.setDataSet({ data: shops.value.map(shop => ({ lng: shop.position.lng, lat: shop.position.lat, count: shop.visits || 10 })), max: 100 })

11.2 路线规划集成

const driving = new BMap.DrivingRoute(map, { renderOptions: { map: map, autoViewport: true }, onSearchComplete: results => { if (driving.getStatus() === BMAP_STATUS_SUCCESS) { const plan = results.getPlan(0) console.log('路线距离:', plan.getDistance()) } } }) // 计算从当前位置到目标店铺的路线 driving.search(currentPosition, shopPosition)

12. 样式深度定制

12.1 自定义地图样式

通过Map.setMapStyle方法应用个性化样式：

const mapStyle = { features: ["road", "building"], style: "dark" // 支持light/dark/normal等预设或自定义 } map.setMapStyle(mapStyle)

12.2 主题色系统

使用CSS变量实现动态主题：

:root { --primary-color: #3385ff; --info-window-bg: #ffffff; } .shop-card { border-top: 3px solid var(--primary-color); } .action-buttons button { background: var(--primary-color); }

13. 状态管理与数据流

13.1 Pinia存储设计

创建mapStore.js集中管理地图状态：

import { defineStore } from 'pinia' export const useMapStore = defineStore('map', { state: () => ({ mapInstance: null, currentPosition: null, shops: [], searchHistory: [] }), actions: { setMapInstance(map) { this.mapInstance = map }, addSearchHistory(query) { this.searchHistory.unshift(query) if (this.searchHistory.length > 5) { this.searchHistory.pop() } } } })

13.2 组件间通信模式

通信场景	推荐方式	示例
父→子	Props	`<ShopMarker :shop="data" />`
子→父	Emits	`@marker-click="handler"`
兄弟组件	Store	通过Pinia共享状态
深层组件	Provide/Inject	`provide('mapInstance', map)`

14. 无障碍访问优化

14.1 ARIA属性添加

<bm-marker :aria-label="`${shop.name}，评分${shop.rating}星`" :aria-describedby="`desc-${shop.id}`" > <div :id="`desc-${shop.id}`" class="sr-only"> 位于{{ shop.address }}，营业时间{{ shop.businessHours }} </div> </bm-marker>

14.2 键盘导航支持

document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && showInfoWindow.value) { showInfoWindow.value = false } })

15. 国际化与多语言

15.1 多语言配置

使用Vue I18n实现：

const messages = { en: { shop: { openHours: 'Business Hours', phone: 'Phone', address: 'Address' } }, zh: { shop: { openHours: '营业时间', phone: '联系电话', address: '地址' } } }

15.2 地图控件语言切换

const changeMapLanguage = (lang) => { if (window.BMap) { BMap.setCurrentCity(lang === 'en' ? 'Beijing' : '北京市') } }

16. 实际项目经验分享

在最近一个连锁药店管理系统的开发中，我们遇到了店铺密集区域标记点重叠的问题。最终解决方案是：

实现基于四叉树的空间索引算法
动态调整标记点显示优先级
添加"查看周边"聚合功能
引入淡入淡出动画减少视觉跳跃感

另一个性能优化技巧是：对于超过500个标记点的场景，建议：

使用Canvas渲染替代DOM标记
实现视口裁剪，只渲染可见区域标记
采用Web Worker处理地理计算
分级加载，先显示主要区域再加载周边

17. 常见问题解决方案

17.1 地图空白问题排查流程

检查AK是否有效且未过期
验证域名是否在AK白名单中
查看网络请求是否被浏览器插件拦截
确认百度地图JS文件加载成功
检查容器元素尺寸是否不为零

17.2 标记点闪烁问题

通常是由于重复创建导致，解决方案：

// 错误做法 - 每次渲染都创建新标记 markers.value = newShops.map(shop => new BMap.Marker(shop.position)) // 正确做法 - 复用已有标记 const existingMarkers = markers.value markers.value = newShops.map((shop, index) => { return existingMarkers[index] ? existingMarkers[index].setPosition(shop.position) : new BMap.Marker(shop.position) })

18. 监控与统计分析

18.1 用户行为埋点

const trackMapEvent = (eventName, payload) => { if (window.analytics) { analytics.track(`map_${eventName}`, { ...payload, zoomLevel: map.getZoom(), center: map.getCenter() }) } } // 示例：追踪标记点点击 const handleMarkerClick = (shop) => { trackMapEvent('marker_click', { shop_id: shop.id, category: shop.category }) // ...其他逻辑 }

18.2 性能指标收集

使用Performance API监测关键操作耗时：

const measureSearchPerformance = async () => { const start = performance.now() await searchNearbyShops() const duration = performance.now() - start if (duration > 1000) { reportSlowSearch(duration) } }

19. 安全防护措施

19.1 输入过滤

对所有搜索输入进行消毒处理：

const sanitizeInput = (input) => { return input.replace(/[<>"'&]/g, '') } const handleSearch = () => { const safeQuery = sanitizeInput(searchQuery.value) // ...执行搜索 }

19.2 防滥用策略

let lastSearchTime = 0 const SEARCH_COOLDOWN = 1000 // 1秒冷却 const handleSearch = () => { const now = Date.now() if (now - lastSearchTime < SEARCH_COOLDOWN) { showToast('操作过于频繁，请稍后再试') return } lastSearchTime = now // ...正常搜索逻辑 }