folium MousePosition 插件实战：在地图上实时显示鼠标经纬度坐标-开发者社区

数据可视化
数据分析
GIS

【免费下载链接】folium

Python Data. Leaflet.js Maps.

项目地址：https://gitcode.com/gh_mirrors/fo/folium

导读

本指南围绕 folium 的 MousePosition 插件展开，讲解如何在地图角落实时显示鼠标指针的经纬度坐标。读完本文你将掌握 MousePosition 的基础用法、全部可配置选项（位置、分隔符、小数位数、自定义格式化函数等），以及该插件在源码层面的渲染原理，并能在 Jupyter Notebook 或 Web 应用中直接落地使用。

MousePosition 是 folium 官方封装的一个 Leaflet 外部插件，源码位于 folium/plugins/mouse_position.py，并从 folium/plugins/init.py 中导出。它的典型应用场景是：交互式地图中需要实时读取鼠标所在位置的坐标，用于数据核对、坐标拾取、空间分析演示等。官方示例 Notebook 位于 examples/plugin-MousePosition.ipynb，对应的用户指南即本文所依据的 docs/user_guide/plugins/mouse_position.md。

插件简介与默认行为

MousePosition 会在地图上添加一个小型字段控件，实时显示鼠标所在位置的坐标。按照插件源码 docstring 的说明，它基于 Ardhi Lukianto 编写的 Leaflet.MousePosition 插件（MIT 协议）封装而成。

默认情况下：

控件显示在地图右下角（bottomright）；
坐标格式为“纬度 : 经度”，默认分隔符是" : "；
鼠标尚未移动时显示占位文本"Unavailable"；
经纬度默认保留5 位小数；
默认不添加前缀文本。

快速上手

创建地图并直接添加 MousePosition 控件即可。最小化用法如下（与官方文档保持一致）：

import folium from folium.plugins import MousePosition m = folium.Map() MousePosition().add_to(m) m

在 Jupyter Notebook / IPython 环境中，最后一行m会渲染出地图；在地图右下角即可看到实时坐标字段。插件同时加载了 Leaflet 侧所需的 JavaScript 与 CSS 资源，因此无需手动引入任何额外脚本。

若想在独立的 HTML 文件或 Web 服务中使用，只需调用m.save("map.html")或将m._repr_html_()嵌入页面即可，控件渲染逻辑完全一致。

可配置选项（Options）详解

MousePosition的构造函数签名与各参数默认值，可直接从源码 folium/plugins/mouse_position.py 确认。所有参数在实例化时被统一收集到self.options字典中，再通过模板序列化为 Leaflet 配置。

参数	默认值	类型	说明
`position`	`"bottomright"`	str	Leaflet 标准 Control 位置参数，决定控件停靠角落
`separator`	`" : "`	str	用于分隔纬度和经度值的字符
`empty_string`	`"Unavailable"`	str	鼠标未移动时显示的初始文本
`lng_first`	`False`	bool	是否把经度放在纬度之前显示
`num_digits`	`5`	int	显示的经纬度小数位数
`prefix`	`""`	str	前置在坐标前面的字符串
`lat_formatter`	`None`	str	自定义格式化纬度的 JavaScript 函数字符串
`lng_formatter`	`None`	str	自定义格式化经度的 JavaScript 函数字符串

各参数的行为要点如下：

position：接受 Leaflet 控件标准位置值，如"topleft"、"topright"、"bottomleft"、"bottomright"。
num_digits：控制默认坐标显示精度（十进制小数位）。传入较大的值（如20）可显示近似完整的浮点精度。
lng_first：默认顺序为“纬度 : 经度”；设为True后切换为“经度 : 纬度”。
lat_formatter / lng_formatter：以字符串形式传入 JavaScript 函数体，用于完全自定义经纬度的显示格式。源码中二者在构造时被存入独立属性，未提供时分别回退为字符串"undefined"（见 folium/plugins/mouse_position.py），即在 JS 侧保持插件默认格式化行为。

需要注意的是，构造方法中多余的**kwargs也会被收集进options（源码 folium/plugins/mouse_position.py），因此传入插件底层支持的其他选项同样会被透传到 Leaflet 控件。

一个细节：None 值的过滤

self.options通过remove_empty(...)构建（源码 folium/plugins/mouse_position.py）。该工具函数定义于 folium/utilities.py，实现很简单：过滤掉值为None的键，避免把空配置项序列化进 HTML。

自定义坐标显示格式

当默认的“纬度 : 经度”格式无法满足需求时，可通过formatter与prefix等参数定制显示效果。官方文档给出的完整示例如下：

m = folium.Map() formatter = "function(num) {return L.Util.formatNum(num, 3) + ' &deg; ';};" MousePosition( position="topright", separator=" | ", empty_string="NaN", lng_first=True, num_digits=20, prefix="Coordinates:", lat_formatter=formatter, lng_formatter=formatter, ).add_to(m) m

该示例一次演示了大部分自定义能力：

position="topright"：将控件移到右上角；
separator=" | "：经纬度之间用竖线分隔；
empty_string="NaN"：初始占位文本改为NaN；
lng_first=True：先显示经度再显示纬度；
num_digits=20：保留 20 位小数（配合自定义 formatter 时，实际精度取决于 formatter 的formatNum第二参数）；
prefix="Coordinates:"：在坐标前加固定前缀；
lat_formatter/lng_formatter：传入同一个 JS 函数，将数值格式化为 3 位小数并附加°符号。

formatter必须是一段完整的 JavaScript 函数字符串，返回一个字符串作为该坐标分量的显示内容。常用写法是借助 Leaflet 的L.Util.formatNum(num, digits)控制小数位数。经纬度可以分别传入不同的 formatter，例如只对经度附加E、对纬度附加N等方向标记：

lat_fmt = "function(num) {return L.Util.formatNum(num, 4) + ' N';};" lng_fmt = "function(num) {return L.Util.formatNum(num, 4) + ' E';};"

源码视角：控件是如何渲染到地图上的

理解渲染链路有助于排查问题与扩展功能。MousePosition 的类继承结构为JSCSSMixin, MacroElement（源码 folium/plugins/mouse_position.py），渲染过程包含三个环节：

资源加载（JSCSSMixin）：default_js与default_css声明了插件所需的 Leaflet.MousePosition 资源。JSCSSMixin.render（见 folium/elements.py）会把它们以JavascriptLink/CssLink的形式注入地图页面的<head>中。源码中这两组资源分别以"Control_MousePosition_js"与"Control_MousePosition_css"命名（folium/plugins/mouse_position.py），通过 jsDelivr CDN 加载官方插件文件。
控件实例化（模板）：类内_template模板（folium/plugins/mouse_position.py）会生成如下 JavaScript：
```
var <控件变量名> = new L.Control.MousePosition(<options 对象>); <控件变量名>.options["latFormatter"] = <lat_formatter>; <控件变量名>.options["lngFormatter"] = <lng_formatter>; <父地图变量名>.addControl(<控件变量名>);
```
即：以序列化后的options构造 Leaflet 控件，再把两个自定义 formatter 单独写入options，最后通过 Leaflet 的map.addControl()挂载到地图上。
挂载到父元素（add_to）：MousePosition().add_to(m)走的是 folium 统一的add_child机制——控件作为子元素注册到Map上，渲染时模板中this._parent即指向父地图，从而获得地图变量名。

与其他插件的组合使用

MousePosition 是标准的MacroElement，可以自由与其他插件叠加。仓库的 Geoman 快照示例 tests/snapshots/modules/geoman_customizations.py 就展示了组合用法：

from folium.plugins import GeoMan, MousePosition m = folium.Map() MousePosition().add_to(m) # ... 其他 Geoman 配置

实际开发中常见的组合包括：与绘图插件（如 Draw）搭配用于数字化时实时读取顶点坐标，与 GeoMan 搭配用于编辑要素时核对位置，或与 MarkerCluster 等定位类插件配合完成坐标拾取工作流。

使用建议与注意事项

坐标顺序：默认显示顺序是“纬度 : 经度”，与 GeoJSON / GeoPandas 中常用的“经度, 纬度”顺序不同，若需与数据坐标直接对照，建议设置lng_first=True。
小数位数：展示坐标仅用于人工读取时可减小num_digits（如 3~6）；需要精细核对时可调大，或交给 formatter 统一控制。
自定义 formatter 是 JS 字符串：Python 端不会校验其语法，务必保证函数字符串合法；可复用官方示例中的L.Util.formatNum写法。
离线环境：插件的 JS/CSS 默认从 CDN 加载（定义于源码default_js/default_css），在完全离线的内网环境中需要自行本地化这两份资源。
初始占位文本：鼠标尚未在地图上移动时，控件显示empty_string指定的内容，可用于向用户提示“尚未取到坐标”的状态。

小结

MousePosition 是一个轻量但实用的 folium 插件：一行代码即可获得鼠标实时坐标，通过position、separator、num_digits、prefix等参数可快速调整显示方式，借助lat_formatter/lng_formatter还能完全自定义坐标文本格式。结合 folium/plugins/mouse_position.py 源码理解其渲染链路（CDN 资源注入 → options 序列化 →addControl挂载），即可在各种交互式地图场景中放心使用并自行扩展。