folium BeautifyIcon 插件指南：打造 Font Awesome 图标与数字标记的自定义 Marker-育师

数据可视化
数据分析
GIS

【免费下载链接】folium

Python Data. Leaflet.js Maps.

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

BeautifyIcon 是 folium 内置插件之一，用于为地图 Marker 生成高度可定制的字体图标（基于 Font Awesome）与数字标记，支持自定义边框、文字、背景颜色、图标形状以及旋转动画。本文以官方用户指南 beautify_icon.md 为骨架，结合 beautify_icon.py 源码与 test_beautify_icon.py 测试用例，完整讲解其参数体系、底层渲染机制与实战用法，读完即可在交互地图中直接落地使用。

快速上手：两个典型标记

官方指南给出了最简洁的入门示例：先创建地图，再构造两个不同风格的 BeautifyIcon，最后将它们作为icon参数传给folium.Marker：

import folium import folium.plugins m = folium.Map([45.5, -122], zoom_start=3) icon_plane = folium.plugins.BeautifyIcon( icon="plane", border_color="#b3334f", text_color="#b3334f", icon_shape="triangle" ) icon_number = folium.plugins.BeautifyIcon( border_color="#00ABDC", text_color="#00ABDC", number=10, inner_icon_style="margin-top:0;", ) folium.Marker(location=[46, -122], popup="Portland, OR", icon=icon_plane).add_to(m) folium.Marker(location=[50, -122], popup="Portland, OR", icon=icon_number).add_to(m) m

运行效果是：波特兰附近出现一个玫红色三角形边框的飞机图标标记，以及一个天蓝色数字 "10" 的标记。该示例同时展示了 BeautifyIcon 的两大典型能力——字体图标渲染与数字徽章渲染。

构造参数全解析（以源码为准）

BeautifyIcon的所有构造参数及其默认值定义在 folium/plugins/beautify_icon.py 的__init__中，下表为完整清单：

参数	类型	默认值	说明
`icon`	str	`None`	Font Awesome 图标名称，如`"plane"`、`"arrow-down"`，用于渲染图标标记
`icon_shape`	str	`None`	图标形状。Python 侧预定义的形状见下方说明；指南示例中使用的`"triangle"`同样可直接传入
`border_width`	int	`3`	图标边框宽度（像素）
`border_color`	str（十六进制 RGB）	`"#000"`	边框颜色，也支持`"transparent"`
`text_color`	str（十六进制 RGB）	`"#000"`	文字（图标或数字）颜色
`background_color`	str（十六进制 RGB）	`"#FFF"`	背景颜色
`inner_icon_style`	str（CSS）	`""`	作用于图标内部的 CSS 样式，可微调字号、边距等
`spin`	bool	`False`	是否启用图标旋转动画
`number`	int	`None`	以数字作为标记内容（而非 Font Awesome 图标）

源码中还额外接收**kwargs，所有参数最终合并为一个options字典传给底层的 Leaflet 插件。

关于 icon_shape 的说明

源码中定义了成员ICON_SHAPE_TYPES = ["circle", "circle-dot", "doughnut", "rectangle-dot", "marker", None]，对应底层 BeautifyMarker 库的内置形状。需要说明的是，这个列表仅用于参考，构造时并不会对传入值做校验，因此官方指南示例中的icon_shape="triangle"以及库支持的其他形状都可以直接使用。若对形状语法不确定，可在 beautify_icon.py 查看预定义类型作为基准。

数字标记与样式微调实战

当设置了number参数时，插件会自动把isAlphaNumericIcon置为True，并将该数字作为标记的text内容——这在源码的remove_empty(...)字典构建处可见（beautify_icon.py）：

options = remove_empty( icon=icon, icon_shape=icon_shape, border_width=border_width, border_color=border_color, text_color=text_color, background_color=background_color, inner_icon_style=inner_icon_style, spin=spin, isAlphaNumericIcon=number is not None, text=number, **kwargs, )

也就是说，number与icon在语义上互斥：传了number就渲染数字，传了icon就渲染图标。

数字徽章示例

number_icon = folium.plugins.BeautifyIcon( text_color="#000", border_color="transparent", background_color="#FFF", number=10, inner_icon_style="font-size:12px;padding-top:-5px;", ) folium.Marker( location=[45.5, -122.3], popup=folium.Popup("Portland, OR"), icon=number_icon, ).add_to(m)

这里通过inner_icon_style调整字号与内边距，是控制数字在徽章内对齐的常用手段（官方 docstring 中给出的标准用法，见 beautify_icon.py）。

图标样式示例

arrow_icon = folium.plugins.BeautifyIcon( icon="arrow-down", icon_shape="marker" ).add_to(marker)

其他常用定制

颜色主题：border_color、text_color、background_color三者配合即可快速改变整体配色；border_color="transparent"可去掉边框。
旋转动画：设置spin=True即可让图标持续旋转，适合表达“加载中”或风向等动态语义。
内联 CSS 微调：inner_icon_style接收任意 CSS 片段，如"margin-top:0;"（官方指南示例即用此写法解决数字垂直偏移）。

底层工作原理：模板渲染与资源注入

BeautifyIcon 继承自JSCSSMixin, MacroElement，其渲染逻辑可以拆成三层来看：

1. 外部 JS/CSS 自动注入

default_js与default_css指向 jsDelivr 上的 BeautifyMarker 库文件：

default_js = [ ( "beautify_icon_js", "https://cdn.jsdelivr.net/gh/marslan390/BeautifyMarker/leaflet-beautify-marker-icon.min.js", ) ] default_css = [ ( "beautify_icon_css", "https://cdn.jsdelivr.net/gh/marslan390/BeautifyMarker/leaflet-beautify-marker-icon.min.css", ) ]

JSCSSMixin.render（folium/elements.py）会在渲染阶段把这些链接作为JavascriptLink/CssLink注入到地图Figure的header中。因此使用 BeautifyIcon 时无需手动加载任何资源，folium 会自动完成 CDN 脚本注入。

2. 通过 MacroElement 模板生成 Leaflet 代码

_template中定义了一段 Jinja2 宏，负责生成真正的 Leaflet 调用：

var {{ this.get_name() }} = new L.BeautifyIcon.icon( {{ this.options|tojavascript }} ) {{ this._parent.get_name() }}.setIcon({{ this.get_name() }});

即：先用options构造一个L.BeautifyIcon.icon实例，再通过父级元素（通常是 Marker）的setIcon()应用到对应标记上。

3. options 字典的序列化

options先经remove_empty（folium/utilities.py）剔除所有None值，避免向 JS 传递空参数；再经tojavascript过滤器（folium/template.py）序列化为 JS 对象字面量，字典键自动转为 lowerCamelCase（例如border_width→borderWidth、inner_icon_style→innerIconStyle），并完成必要的 HTML 字符转义。

测试用例如何验证渲染结果

test_beautify_icon.py 对该插件做了三重断言，可作为理解行为与排查问题的依据：

JS 脚本注入：断言渲染出的 HTML 包含leaflet-beautify-marker-icon.min.js的<script>标签；
CSS 样式注入：断言包含leaflet-beautify-marker-icon.min.css的<link>标签；
图标对象生成：断言输出中包含var <name> = new L.BeautifyIcon.icon({...})与.setIcon(...)模板片段。

测试中用到的ic1（icon="plane"）与ic2（number=10）恰好对应官方指南示例中的两种用法，说明该示例是经过持续回归验证的稳定写法。

与其他 Map / Marker 能力的组合

BeautifyIcon 就是一个icon对象，可以替换folium.Marker的默认Icon，与popup、tooltip天然兼容（指南示例即为popup="Portland, OR"的组合）。
也可以配合FeatureGroup、LayerControl等组织批量标记，此时只需在每个Marker上分别挂载各自的BeautifyIcon实例。
关于 Marker、Popup、Tooltip 的基础用法，可参考 user_guide/features.rst 与 user_guide/map.md；插件总览见 user_guide/plugins.rst。