企业官网建设流程全解析

• 数据可视化
• 数据分析
• GIS

导读

FloatImage 是 folium 内置插件之一，用于在 Leaflet 地图的 HTML 画布上叠加一张"悬浮"于所有图层之上的图片（如罗盘、比例尺、Logo、图例等），并通过百分比定位控制其在屏幕中的位置。读完本文，你将掌握 FloatImage 的实例化参数、CSS 扩展方式、渲染原理，以及如何用仓库中的测试用例验证渲染结果。

一、FloatImage 是什么

根据 docs/user_guide/plugins.rst 中的官方功能表，FloatImage 的作用是：

Add a floating image in the HTML canvas on top of the map.

（在地图顶部的 HTML 画布上添加一张浮动图片。）

它适用于任何需要"常驻地图上方"的静态图形：风向玫瑰图、指北针、版权水印、操作提示图等。与 Marker 或图层不同，它不参与地图坐标系定位，而是直接挂在 HTML 文档层上，因此缩放、平移地图都不会改变它在视口中的相对位置。

二、快速上手：官方示例

原文档 docs/user_guide/plugins/float_image.md 给出的最小可用示例非常简洁，核心只需三步：创建地图、实例化 FloatImage、把它 add_to 地图：

import folium from folium.plugins import FloatImage url = ( "https://raw.githubusercontent.com/ocefpaf/secoora_assets_map/" "a250729bbcf2ddd12f46912d36c33f7539131bec/secoora_icons/rose.png" ) m = folium.Map([-13, -38.15], zoom_start=10) FloatImage(url, bottom=40, left=65).add_to(m) m

在 Jupyter Notebook / IPython 环境中，最后一行m会调用地图对象的_repr_html_()（定义见 folium/folium.py）渲染出完整 HTML，页面右上（left=65, bottom=40）即可看到浮动的玫瑰图。

注意：FloatImage(...).add_to(m)与m.add_child(FloatImage(...))等价——Map.add_child位于 folium/map.py，负责把插件元素挂到地图的 DOM 树中。

三、参数详解：定位与样式

从源码 folium/plugins/float_image.py 的类签名与 docstring 中，可以提取出完整参数语义：

这三个参数在__init__中被原样保存为实例属性（folium/plugins/float_image.py），而kwargs被存入self.css字典：

def __init__(self, image, bottom=75, left=75, **kwargs): super().__init__() self._name = "FloatImage" self.image = image self.bottom = bottom self.left = left self.css = kwargs

定位规则

• bottom与left均为视口百分比，组合起来决定图片锚点位置：bottom=0贴底、bottom=100贴顶；left=0靠左、left=100靠右。典型组合如bottom=100, left=100表示右上角，bottom=0, left=0表示左下角。
• 定位由内联<style>块实现，position: absolute使图片脱离文档流、以视口为参照：

#FloatImage_xxx { position: absolute; bottom: 40%; left: 65%; }

通过 kwargs 追加 CSS

kwargs 适合控制尺寸、透明度、边框等视觉效果，例如：

FloatImage( url, bottom=40, left=65, width="180px", # 限制显示宽度 opacity="0.9", # 半透明叠加，减少遮挡 border="2px solid #333", ).add_to(m)

这些键值对会在模板渲染时被循环写入样式块（folium/plugins/float_image.py），因此凡是合法的 CSS 属性名都可以直接使用。

四、渲染原理：模板与层级

FloatImage 继承自 branca 的MacroElement，通过 folium 自定义的 Jinja2Template（定义见 folium/template.py）渲染两段内容：

1. header 宏——生成<style>块，写入定位与 CSS 属性；
2. html 宏——生成实际的<img>标签，且带style="z-index: 999999"（folium/plugins/float_image.py）：

<img id="FloatImage_xxx" alt="float_image" src="https://..." style="z-index: 999999"> </img>

z-index: 999999是理解"浮动"的关键：它保证图片几乎总在其他地图控件与图层之上（除非页面另有更高层级的元素）。同时alt="float_image"也为图片提供了无障碍描述文本。

关于本地图片与内联图片

docstring 明确说明image参数除常规 URL 外，还支持：

• data URI：将图片 Base64 编码后内联，适合离线或单 HTML 文件分发场景；
• file://协议：指向本地文件的路径，适合在本地调试时使用（浏览器同源策略下需注意访问限制）。

五、测试用例验证：渲染结果可断言

仓库为 FloatImage 提供了单元测试 tests/plugins/test_float_image.py，它验证了两个关键事实，可作为你理解渲染输出的依据：

1. <img>标签正确生成：测试用Template渲染期望的<img>结构（含src、alt="float_image"、z-index: 999999），断言其包含在地图的整体渲染输出中；
2. <style>样式正确生成：测试以bottom=60, left=70, width="20%"实例化，断言输出样式块中出现了bottom: 60%;、left: 70%;、width: 20%;，即 kwargs 中的 CSS 确实被写入。

szt = plugins.FloatImage(url, bottom=60, left=70, width="20%") m.add_child(szt) out = normalize(m._parent.render()) # 断言 img 与 style 均在输出中

注意该测试还调用了m.get_bounds()并断言边界为[[None, None], [None, None]]——说明 FloatImage 不向地图贡献任何数据边界，印证了它"纯 DOM 层叠加、不参与地理坐标"的特性。

六、常见问题与注意事项

• 位置数值含义：bottom/left是百分比整数，非法范围（如负值或大于 100）不会被源码校验，最终由浏览器按 CSS 规则解释，建议保持在 0~100。
• 图片遮挡交互：由于z-index: 999999极高，置于中心位置的大图可能遮挡地图拖拽；建议用width控制尺寸、opacity降低遮挡，或把图片放到角落。
• 与图层控制器的关系：FloatImage 不受 LayerControl 管辖，无法像普通图层那样开/关切换；如需可切换的图片，可考虑使用 ImageOverlay（见 docs/user_guide/raster_layers/image_overlay.md）。
• 导入路径：FloatImage已通过 folium/plugins/init.py 从folium.plugins.float_image导出，因此from folium.plugins import FloatImage即可直接使用。

七、小结

FloatImage 是 folium 中实现"地图悬浮图片"最直接的方式：三个核心参数（image、bottom、left）加上自由的 CSS kwargs，配合z-index: 999999的高层级与position: absolute的视口定位，即可在不干扰地图坐标体系的前提下放置常驻图形。从 folium/plugins/float_image.py 的实现与 tests/plugins/test_float_image.py 的断言中，我们可以确认它的全部渲染行为都集中在<style>与<img>两块输出中，行为简单、可预测，非常适合需要"叠加而非铺设"的视觉元素场景。

• 数据可视化
• 数据分析
• GIS