🌐【开源解析】基于PyQt5+Folium的谷歌地图应用开发：从入门到实战
🌈 个人主页：创客白泽 - CSDN博客
🔥 系列专栏：🐍《Python开源项目实战》
💡 热爱不止于代码，热情源自每一个灵感闪现的夜晚。愿以开源之火，点亮前行之路。
👍 如果觉得这篇文章有帮助，欢迎您一键三连，分享给更多人哦
📌 概述
在当今数据可视化与地理信息系统的交叉领域，交互式地图应用已成为不可或缺的工具。本文将深入剖析一个基于Python技术栈（PyQt5+Folium+Geopy）开发的**"谷歌地图"桌面应用**，它集成了地址解析、地图标注、距离测量等实用功能，并提供了三种不同的地图样式选择。
相较于传统Web地图应用，本项目的创新点在于：
- 桌面端集成：通过PyQt5实现原生应用体验
- 混合渲染技术：结合Folium的HTML生成与QWebEngineView的嵌入式渲染
- 跨框架通信：实现Python与JavaScript的双向交互
- 轻量级架构：无需复杂GIS系统即可实现核心功能
🛠️ 功能特性
核心功能矩阵
| 功能模块 | 实现技术 | 特色说明 |
|---|---|---|
| 地理编码 | Geopy/Nominatim | 支持全球地址解析 |
| 地图渲染 | Folium+Leaflet | 三种专业地图样式 |
| 距离测量 | Geodesic算法 | 高精度大圆距离计算 |
| 交互界面 | PyQt5 | 响应式桌面UI |
| 地图导出 | HTML5 | 可独立运行的网页地图 |
特色功能详解
- 智能地址解析：基于OpenStreetMap的Nominatim服务，支持模糊地址匹配
- 实时距离测量：选择两个标记点即可显示精确的球面距离
- 动态标记高亮：可视化连线辅助空间关系分析
- 多地图样式：街道图、卫星图、地形图一键切换
- 跨平台运行：生成的HTML地图可在任何浏览器查看
🎨 效果展示
街道地图
卫星地图
地形图
距离测量演示
🧩 实现步骤详解
1. 环境搭建
pip install PyQt5 folium geopy PyQtWebEngine
2. 核心架构设计
3. 关键技术实现
3.1 混合地图渲染
def initialize_map(self):
# 加载Leaflet库
html = """
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"/>
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
</head>
<body>
<div id="map"></div>
<script>
// JavaScript地图控制逻辑
var map = L.map('map').setView([39.9042, 116.4074], 4);
</script>
</body>
</html>
"""
self.map_view.setHtml(html)
3.2 跨语言通信
# Python调用JavaScript
self.map_view.page().runJavaScript("addMarker(39.9, 116.4, '北京', '中国首都');")
# JavaScript回调Python
self.map_view.page().runJavaScript("""
map.on('click', function(e) {
console.log(e.latlng);
});
""")
3.3 距离测量算法
from geopy.distance import geodesic
def calculate_distance(loc1, loc2):
"""使用Vincenty公式计算球面距离"""
return geodesic(
(loc1['latitude'], loc1['longitude']),
(loc2['latitude'], loc2['longitude'])
).kilometers
🔍 代码深度解析
1. 地理编码服务封装
def geocode_location(self, address):
try:
location = self.geolocator.geocode(address)
if location:
return (location.latitude, location.longitude)
return None
except (GeocoderTimedOut, GeocoderServiceError) as e:
# 实现自动重试机制
time.sleep(0.5)
return self.geocode_location(address)
优化点：增加了异常处理和自动重试机制，提高服务稳定性
2. 动态标记管理
def update_embedded_map(self):
# 使用JS批量操作DOM元素
js_clear = "clearMarkers();"
js_add_markers = []
for loc in self.locations:
js_add_markers.append(
f"addMarker({loc['latitude']}, {loc['longitude']}, "
f"'{loc['name']}', '{loc['address']}');"
)
self.map_view.page().runJavaScript(js_clear + "".join(js_add_markers))
性能优化：减少Python-JS通信次数，使用批量操作提升渲染效率
3. 地图样式热切换
self.map_styles = {
"🌍 街道地图": {
"url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
"attr": "OpenStreetMap"
},
"🛰️ 卫星地图": {
"url": "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}",
"attr": "Google"
}
}
def update_map_style(self):
style = next(s for s in self.map_styles
if self.style_buttons[s].isChecked())
js = f"""
map.eachLayer(layer => {{
if (layer instanceof L.TileLayer) {{
map.removeLayer(layer);
}}
}});
L.tileLayer('{self.map_styles[style]["url"]}', {{
attribution: '{self.map_styles[style]["attr"]}'
}}).addTo(map);
"""
self.map_view.page().runJavaScript(js)
📥 源码下载
import folium
from geopy.geocoders import Nominatim
from geopy.distance import geodesic # 添加距离计算功能
from geopy.exc import GeocoderTimedOut, GeocoderServiceError
from PyQt5.QtWidgets import (QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout,
QLabel, QLineEdit, QPushButton, QTreeWidget, QTreeWidgetItem,
QRadioButton, QGroupBox, QFileDialog, QMessageBox, QScrollArea)
from PyQt5.QtCore import Qt, QUrl, QTimer
from PyQt5.QtWebEngineWidgets import QWebEngineView
from PyQt5.QtGui import QIcon
import sys
import webbrowser
import os
import time
class SimpleMapViewerApp(QMainWindow):
def __init__(self):
super().__init__()
self.setWindowTitle("谷歌桌面地图")
self.setGeometry(100, 100, 1200, 800)
self.geolocator = Nominatim(user_agent="simple_map_viewer")
self.locations = []
self.current_map_file = os.path.join(os.path.expanduser("~"), "map.html")
self.map_view = None
self.map_initialized = False
self.selected_markers = [] # 存储选中的标记用于距离计算
# 地图样式选项
self.map_styles = {
"🌍 街道地图": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
"🛰️ 卫星地图": "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}",
"⛰️ 地形图": "https://mt1.google.com/vt/lyrs=p&x={x}&y={y}&z={z}"
}
# 创建UI
self.create_widgets()
# 延迟初始化地图，确保WebEngineView完全加载
QTimer.singleShot(500, self.initialize_map)
def create_widgets(self):
# 主窗口布局
main_widget = QWidget()
self.setCentralWidget(main_widget)
main_layout = QHBoxLayout(main_widget)
# 左侧控制面板
control_panel = QWidget()
control_panel.setMinimumWidth(350)
control_panel.setMaximumWidth(400)
control_layout = QVBoxLayout(control_panel)
# 地图样式选择
style_group = QGroupBox("🗂️ 地图样式")
style_layout = QVBoxLayout()
self.style_buttons = []
for style_name in self.map_styles:
btn = QRadioButton(style_name)
btn.toggled.connect(lambda checked, name=style_name: self.update_map_style() if checked else None)
style_layout.addWidget(btn)
self.style_buttons.append(btn)
self.style_buttons[0].setChecked(True)
style_group.setLayout(style_layout)
control_layout.addWidget(style_group)
# 搜索框
search_group = QGroupBox("🔍 位置搜索")
search_layout = QVBoxLayout()
self.search_entry = QLineEdit()
self.search_entry.setPlaceholderText("输入地址或地名...")
search_layout.addWidget(self.search_entry)
search_btn = QPushButton("搜索")
search_btn.setIcon(QIcon.fromTheme("edit-find"))
search_btn.clicked.connect(self.search_location)
search_layout.addWidget(search_btn)
search_group.setLayout(search_layout)
control_layout.addWidget(search_group)
# 位置列表
list_group = QGroupBox("📍 位置列表")
list_layout = QVBoxLayout()
self.location_list = QTreeWidget()
self.location_list.setHeaderLabels(["名称", "地址"])
self.location_list.setColumnWidth(0, 150)
self.location_list.setSelectionMode(QTreeWidget.ExtendedSelection)
self.location_list.itemSelectionChanged.connect(self.on_location_selection_changed) # 添加选择变化事件
list_layout.addWidget(self.location_list)
# 距离显示标签
self.distance_label = QLabel("两地距离: 未选择")
self.distance_label.setAlignment(Qt.AlignCenter)
self.distance_label.setStyleSheet("font-weight: bold; color: #2c3e50;")
list_layout.addWidget(self.distance_label)
# 列表操作按钮
list_btn_layout = QHBoxLayout()
remove_btn = QPushButton("🗑️ 删除选中")
remove_btn.clicked.connect(self.remove_location)
list_btn_layout.addWidget(remove_btn)
clear_btn = QPushButton("🧹 清空列表")
clear_btn.clicked.connect(self.clear_locations)
list_btn_layout.addWidget(clear_btn)
list_layout.addLayout(list_btn_layout)
list_group.setLayout(list_layout)
control_layout.addWidget(list_group)
# 添加位置表单
form_group = QGroupBox("➕ 添加位置")
form_layout = QVBoxLayout()
name_layout = QHBoxLayout()
name_layout.addWidget(QLabel("名称:"))
self.name_entry = QLineEdit()
name_layout.addWidget(self.name_entry)
form_layout.addLayout(name_layout)
addr_layout = QHBoxLayout()
addr_layout.addWidget(QLabel("地址:"))
self.address_entry = QLineEdit()
addr_layout.addWidget(self.address_entry)
form_layout.addLayout(addr_layout)
add_btn = QPushButton("➕ 添加位置")
add_btn.clicked.connect(self.add_location)
form_layout.addWidget(add_btn)
form_group.setLayout(form_layout)
control_layout.addWidget(form_group)
# 地图操作按钮
map_btn_group = QGroupBox("🛠️ 地图操作")
map_btn_layout = QHBoxLayout()
create_btn = QPushButton("🖨️ 生成地图")
create_btn.clicked.connect(self.create_map)
map_btn_layout.addWidget(create_btn)
show_btn = QPushButton("👀 查看地图")
show_btn.clicked.connect(self.show_map)
map_btn_layout.addWidget(show_btn)
map_btn_group.setLayout(map_btn_layout)
control_layout.addWidget(map_btn_group)
control_layout.addStretch()
# 右侧地图预览
self.map_view = QWebEngineView()
self.map_view.setHtml(self.get_empty_html())
# 添加到主布局
main_layout.addWidget(control_panel)
main_layout.addWidget(self.map_view, stretch=1)
def get_empty_html(self):
"""返回初始空白HTML"""
return """
<!DOCTYPE html>
<html>
<head>
<title>地图预览</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<div id="map" style="height:100%;width:100%;"></div>
</body>
</html>
"""
def initialize_map(self):
"""初始化地图，确保Leaflet库正确加载"""
html = """
<!DOCTYPE html>
<html>
<head>
<title>地图预览</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
crossorigin=""/>
<style>
body { margin: 0; padding: 0; }
#map { height: 100vh; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo="
crossorigin=""></script>
<script>
var map = L.map('map').setView([39.9042, 116.4074], 4);
var osmLayer = L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
attribution: '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
});
osmLayer.addTo(map);
// 存储标记的数组
var markers = [];
var selectedMarkers = [];
var line = null;
function clearMarkers() {
for (var i = 0; i < markers.length; i++) {
map.removeLayer(markers[i]);
}
markers = [];
if (line) {
map.removeLayer(line);
line = null;
}
}
function addMarker(lat, lng, name, address) {
var marker = L.marker([lat, lng]).addTo(map)
.bindPopup('<b>' + name + '</b><br>' + address)
.bindTooltip(name);
markers.push(marker);
return marker;
}
function setView(lat, lng, zoom) {
map.setView([lat, lng], zoom);
}
function highlightMarkers(markerIndices) {
// 重置所有标记样式
for (var i = 0; i < markers.length; i++) {
markers[i].setIcon(L.icon({
iconUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/images/marker-icon.png',
iconSize: [25, 41],
iconAnchor: [12, 41],
popupAnchor: [1, -34],
shadowUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/images/marker-shadow.png',
shadowSize: [41, 41]
}));
}
// 清除之前的线
if (line) {
map.removeLayer(line);
line = null;
}
// 高亮选中的标记
selectedMarkers = [];
for (var i = 0; i < markerIndices.length; i++) {
var idx = markerIndices[i];
if (idx >= 0 && idx < markers.length) {
markers[idx].setIcon(L.icon({
iconUrl: 'https://raw.githubusercontent.com/pointhi/leaflet-color-markers/master/img/marker-icon-red.png',
iconSize: [25, 41],
iconAnchor: [12, 41],
popupAnchor: [1, -34],
shadowUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/images/marker-shadow.png',
shadowSize: [41, 41]
}));
selectedMarkers.push(markers[idx]);
}
}
// 如果选中了两个点，绘制连线
if (selectedMarkers.length === 2) {
var latlngs = [
selectedMarkers[0].getLatLng(),
selectedMarkers[1].getLatLng()
];
line = L.polyline(latlngs, {
color: 'red',
weight: 3,
opacity: 0.7,
dashArray: '10, 10'
}).addTo(map);
}
}
</script>
</body>
</html>
"""
self.map_view.setHtml(html)
self.map_initialized = True
QTimer.singleShot(500, self.update_map_style)
def on_location_selection_changed(self):
"""当位置列表选择变化时触发"""
selected_items = self.location_list.selectedItems()
selected_indices = [self.location_list.indexOfTopLevelItem(item) for item in selected_items]
# 更新地图上的高亮标记
if self.map_initialized:
js = f"highlightMarkers({selected_indices});"
self.map_view.page().runJavaScript(js)
# 计算并显示距离
if len(selected_indices) == 2:
loc1 = self.locations[selected_indices[0]]
loc2 = self.locations[selected_indices[1]]
# 使用geodesic计算两点间距离
point1 = (loc1['latitude'], loc1['longitude'])
point2 = (loc2['latitude'], loc2['longitude'])
distance = geodesic(point1, point2).kilometers
self.distance_label.setText(f"两地距离: {distance:.2f} 公里")
else:
self.distance_label.setText("两地距离: 请选择两个地点")
def update_map_style(self):
"""更新地图样式"""
if not self.map_initialized:
return
for btn in self.style_buttons:
if btn.isChecked():
style_name = btn.text()
tiles = self.map_styles[style_name]
break
js = f"""
var newLayer = L.tileLayer('{tiles}', {{
attribution: '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
}});
// 先清除所有瓦片图层
map.eachLayer(function(layer) {{
if (layer instanceof L.TileLayer) {{
map.removeLayer(layer);
}}
}});
// 添加新图层
newLayer.addTo(map);
"""
self.map_view.page().runJavaScript(js)
self.update_embedded_map()
def geocode_location(self, address):
"""将地址转换为经纬度"""
try:
location = self.geolocator.geocode(address)
if location:
return (location.latitude, location.longitude)
return None
except (GeocoderTimedOut, GeocoderServiceError) as e:
QMessageBox.critical(self, "错误", f"地理编码错误: {e}")
return None
def add_location(self):
"""添加位置到列表"""
name = self.name_entry.text().strip()
address = self.address_entry.text().strip()
if not name or not address:
QMessageBox.warning(self, "警告", "请填写名称和地址")
return
coords = self.geocode_location(address)
if coords:
self.locations.append({
'name': name,
'address': address,
'latitude': coords[0],
'longitude': coords[1]
})
item = QTreeWidgetItem([name, address])
self.location_list.addTopLevelItem(item)
self.name_entry.clear()
self.address_entry.clear()
self.update_embedded_map()
else:
QMessageBox.critical(self, "错误", f"无法找到地址: {address}")
def remove_location(self):
"""删除选中的位置"""
selected = self.location_list.selectedItems()
if not selected:
QMessageBox.warning(self, "警告", "请先选择要删除的位置")
return
for item in selected:
index = self.location_list.indexOfTopLevelItem(item)
if 0 <= index < len(self.locations):
del self.locations[index]
self.location_list.takeTopLevelItem(index)
self.update_embedded_map()
self.distance_label.setText("两地距离: 未选择") # 清除距离显示
def clear_locations(self):
"""清空所有位置"""
if not self.locations:
return
reply = QMessageBox.question(
self, '确认',
'确定要清空所有位置吗?',
QMessageBox.Yes | QMessageBox.No,
QMessageBox.No
)
if reply == QMessageBox.Yes:
self.locations.clear()
self.location_list.clear()
self.update_embedded_map()
self.distance_label.setText("两地距离: 未选择") # 清除距离显示
def search_location(self):
"""搜索位置并定位"""
query = self.search_entry.text().strip()
if not query:
QMessageBox.warning(self, "警告", "请输入搜索内容")
return
try:
location = self.geolocator.geocode(query)
if location:
js = f"""
setView({location.latitude}, {location.longitude}, 15);
addMarker({location.latitude}, {location.longitude}, '{query.replace("'", "\\'")}', '');
"""
self.map_view.page().runJavaScript(js)
else:
QMessageBox.information(self, "提示", "未找到匹配的位置")
except Exception as e:
QMessageBox.critical(self, "搜索错误", str(e))
def create_map(self):
"""创建地图并添加所有位置标记"""
if not self.locations:
QMessageBox.warning(self, "警告", "没有可显示的位置")
return
# 使用folium创建地图
first_loc = self.locations[0]
map_obj = folium.Map(
location=[first_loc['latitude'], first_loc['longitude']],
zoom_start=12
)
# 根据当前选择的样式设置地图瓦片
for btn in self.style_buttons:
if btn.isChecked():
style_name = btn.text()
tiles = self.map_styles[style_name]
break
if style_name == "🌍 街道地图":
tiles = "OpenStreetMap"
attr = None
elif style_name == "🛰️ 卫星地图":
tiles = "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}"
attr = "Google Satellite"
elif style_name == "⛰️ 地形图":
tiles = "https://mt1.google.com/vt/lyrs=p&x={x}&y={y}&z={z}"
attr = "Google Terrain"
if attr:
folium.TileLayer(tiles=tiles, attr=attr, name=style_name).add_to(map_obj)
else:
folium.TileLayer(tiles=tiles, name=style_name).add_to(map_obj)
# 添加所有位置标记
for loc in self.locations:
folium.Marker(
location=[loc['latitude'], loc['longitude']],
popup=f"<b>{loc['name']}</b><br>{loc['address']}",
tooltip=loc['name']
).add_to(map_obj)
# 如果有两个点被选中，添加连线
selected_items = self.location_list.selectedItems()
if len(selected_items) == 2:
loc1 = self.locations[self.location_list.indexOfTopLevelItem(selected_items[0])]
loc2 = self.locations[self.location_list.indexOfTopLevelItem(selected_items[1])]
# 添加两点间连线
folium.PolyLine(
locations=[
[loc1['latitude'], loc1['longitude']],
[loc2['latitude'], loc2['longitude']]
],
color='red',
weight=3,
opacity=0.7,
dash_array='10, 10'
).add_to(map_obj)
# 计算并显示距离
distance = geodesic(
(loc1['latitude'], loc1['longitude']),
(loc2['latitude'], loc2['longitude'])
).kilometers
# 在两点中间添加距离标签
midpoint = [
(loc1['latitude'] + loc2['latitude']) / 2,
(loc1['longitude'] + loc2['longitude']) / 2
]
folium.Marker(
location=midpoint,
icon=folium.DivIcon(
icon_size=(150, 36),
icon_anchor=(75, 18),
html=f'<div style="font-size: 12pt; color: red; background: white; padding: 2px; border-radius: 3px;">{distance:.2f} km</div>'
),
tooltip=f"直线距离: {distance:.2f} 公里"
).add_to(map_obj)
# 保存地图
file_path, _ = QFileDialog.getSaveFileName(
self, "保存地图",
self.current_map_file,
"HTML Files (*.html)"
)
if file_path:
self.current_map_file = file_path
map_obj.save(self.current_map_file)
QMessageBox.information(self, "成功", f"地图已生成: {self.current_map_file}")
def show_map(self):
"""在浏览器中显示地图"""
if not os.path.exists(self.current_map_file):
QMessageBox.critical(self, "错误", "请先生成地图")
return
webbrowser.open('file://' + os.path.realpath(self.current_map_file))
def update_embedded_map(self):
"""更新内嵌地图视图"""
if not self.map_initialized or not hasattr(self, 'map_view'):
return
# 清除所有标记
self.map_view.page().runJavaScript("clearMarkers();")
if not self.locations:
# 如果没有位置，重置到默认视图
self.map_view.page().runJavaScript("setView(39.9042, 116.4074, 4);")
return
# 设置地图中心和缩放级别
first_loc = self.locations[0]
self.map_view.page().runJavaScript(f"setView({first_loc['latitude']}, {first_loc['longitude']}, 12);")
# 添加标记
for loc in self.locations:
js = f"""
addMarker({loc['latitude']}, {loc['longitude']},
'{loc['name'].replace("'", "\\'")}',
'{loc['address'].replace("'", "\\'")}');
"""
self.map_view.page().runJavaScript(js)
def main():
app = QApplication(sys.argv)
app.setStyle('Fusion') # 使用Fusion风格使UI更现代
window = SimpleMapViewerApp()
window.show()
sys.exit(app.exec_())
if __name__ == "__main__":
main()
🚀 扩展方向
- 数据持久化：集成SQLite存储位置数据
- 轨迹绘制：支持路径规划和导航功能
- POI搜索：接入更多地理编码服务提供商
- 3D视图：集成Cesium实现三维可视化
- 插件系统：支持功能模块动态加载
💡 总结
本文详细剖析了基于PyQt5和Folium的地图应用开发全流程，关键技术点包括：
- 混合渲染架构：巧妙结合桌面应用的性能优势和Web地图的灵活性
- 精确距离测量：使用geodesic算法实现专业级距离计算
- 响应式UI设计：通过PyQt5构建美观易用的交互界面
- 跨框架通信：实现Python逻辑与JavaScript渲染的无缝衔接
该解决方案特别适合以下场景：
- 企业内网GIS系统
- 科研数据可视化
- 物流路径规划
- 教学演示工具
未来展望：随着WebAssembly技术的发展，这类混合架构应用将获得更接近原生应用的性能表现，在地理信息领域具有广阔的应用前景。
版权声明：本文采用CC BY-NC-SA 4.0协议，转载请注明出处。商业转载请联系作者授权。
![[Dify] 如何应对明道云API数据过长带来的Token超限问题](https://i-blog.csdnimg.cn/direct/bc8af2b52f824fc8b23621e6504fc4be.png)
