folium PolyLineTextPath 插件实战:让文字与符号沿折线路径流动

原创2026-09-28 15:31:151,730 阅读
文章标签:数据可视化

folium PolyLineTextPath 插件实战:让文字与符号沿折线路径流动

本文基于 folium 官方文档 docs/user_guide/plugins/polyline_textpath.md 与插件源码 folium/plugins/polyline_text_path.py,系统讲解 PolyLineTextPath 插件的用法、全部参数语义与底层实现原理。读完你将能够把任意文字、方向箭头、飞机符号等"贴"在折线路径上,实现航线标注、风向指示、路径方向标识等地图可视化效果。

一、插件定位与适用场景

PolyLineTextPath 是 folium 官方插件之一,对应 Leaflet 生态中的 Leaflet.TextPath 库。它的核心能力是:把一段文本(或由 Unicode 字符构成的符号串)沿着一条折线(PolyLine)的走向渲染出来,并且可以设置是否重复铺满整条线、偏移量、旋转角度以及 SVG 文本样式。

典型应用场景包括:

  • 航线/路径标注:沿飞行航线写出 To New Delhi、To Hanoi 这样的目的地文字,无需额外放置 Marker;
  • 方向与流向指示:在风向线、洋流线、迁徙路径上重复放置 )、►(U+25BA)等符号,形成箭头般的流动感;
  • 路径语义增强:把 ✈(U+2708 飞机符号)沿航点连线重复排列,直观表达"这是一条航线"。

在 folium 中该插件通过 folium.plugins.PolyLineTextPath 暴露,已在 folium/plugins/init.py 中完成导入并列入 __all__(导入语句位于该文件第 26 行,导出声明位于第 71 行),因此使用 from folium import plugins 后即可直接访问。

二、核心参数详解

根据源码 folium/plugins/polyline_text_path.py 中的 __init__ 签名,PolyLineTextPath 支持以下参数:

参数 类型 默认值 说明
polyline folium.features.PolyLine 必填 要附着文字的 PolyLine 对象
text str 必填 沿折线显示的文字内容(支持 Unicode 符号)
repeat bool False 是否沿折线重复铺设文字,True 时文字铺满整条路径
center bool False 是否根据折线的包围盒(bounding box)居中文本
below bool False 是否将文字显示在路径下方
offset int 0 文本相对折线的位置偏移(沿路径方向的像素偏移量)
orientation int 0 将文本旋转到指定角度
attributes dict None 作用于 SVG <text> 标签的属性字典,如 {"fill": "#007DEF", "font-weight": "bold", "font-size": "24"}
**kwargs — — 其余选项,会与上述参数合并进 Leaflet 的 options 对象

其中 attributes 接受的是 SVG <text> 元素的合法属性,常用的包括 fill(文字颜色)、fill-opacity、stroke / stroke-width(描边)、font-family、font-size、font-style、font-weight、letter-spacing、text-anchor、dominant-baseline 等,你可以自由组合。

值得注意的实现细节:所有参数在构造函数中通过 remove_empty(...) 组装成 self.options(见 folium/plugins/polyline_text_path.py)。remove_empty 定义在 folium/utilities.py,作用是剔除所有值为 None 的键,只把显式给出的配置序列化进前端 JS。这意味着一组默认值为 False/0 的布尔和整数参数会原样传入,而 attributes=None、未传入的 **kwargs 不会出现在最终生成的地图脚本中。

三、完整实战:风向线、危险线与航线

官方文档使用一张以 [30, 0] 为中心的全球地图,依次演示了三种"符号沿路径流动"的写法。核心代码结构为:先创建并 add_to 一条 folium.PolyLine,再创建 PolyLineTextPath 并同样 add_to。

3.1 初始化地图

import folium
import folium.plugins

m = folium.Map([30, 0], zoom_start=3)

3.2 风向线:) 符号沿路径重复

一条由 16 个经纬度点构成的风向轨迹线,线宽 15、颜色 #8EE9FF(浅蓝),再把 ") "(右括号加空格)以 repeat=True 的方式沿路径重复铺排,配合 offset=7 与加粗蓝色样式,形成一串沿风向流动的标记:

wind_locations = [
    [59.35560, -31.992190],
    [55.178870, -42.89062],
    [47.754100, -43.94531],
    [38.272690, -37.96875],
    [27.059130, -41.13281],
    [16.299050, -36.56250],
    [8.4071700, -30.23437],
    [1.0546300, -22.50000],
    [-8.754790, -18.28125],
    [-21.61658, -20.03906],
    [-31.35364, -24.25781],
    [-39.90974, -30.93750],
    [-43.83453, -41.13281],
    [-47.75410, -49.92187],
    [-50.95843, -54.14062],
    [-55.97380, -56.60156],
]

wind_line = folium.PolyLine(wind_locations, weight=15, color="#8EE9FF").add_to(m)

attr = {"fill": "#007DEF", "font-weight": "bold", "font-size": "24"}

folium.plugins.PolyLineTextPath(
    wind_line, ") ", repeat=True, offset=7, attributes=attr
).add_to(m)

repeat=True 与 offset=7 的配合效果是:符号串沿折线每隔 7 像素重复一次,视觉上形成连续的方向指示带。

3.3 危险线:► 箭头符号

一条橙色半透明的两段式直线(权重 10、透明度 0.8),沿路径重复铺排 \u25BA(即 ►,黑色右向实心箭头),offset=6,颜色设为红色:

danger_line = folium.PolyLine(
    [[-40.311, -31.952], [-12.086, -18.727]], weight=10, color="orange", opacity=0.8
).add_to(m)

attr = {"fill": "red"}

folium.plugins.PolyLineTextPath(
    danger_line, "\u25BA", repeat=True, offset=6, attributes=attr
).add_to(m)

这里 attributes 只给了 fill: red,说明其他样式会回退到浏览器对 SVG 文本的默认渲染,可见样式属性完全按需配置。

3.4 航线:✈ 飞机符号

一条三航点的细黑线(权重 1、黑色),沿路径重复铺设 \u2708 (即 ✈ 飞机符号加 5 个空格,空格用于拉开相邻符号的间距),offset=8,加粗 24px 样式:

plane_line = folium.PolyLine(
    [[-49.38237, -37.26562], [-1.75754, -14.41406], [51.61802, -23.20312]],
    weight=1,
    color="black",
).add_to(m)

attr = {"font-weight": "bold", "font-size": "24"}

folium.plugins.PolyLineTextPath(
    plane_line, "\u2708     ", repeat=True, offset=8, attributes=attr
).add_to(m)

一个小技巧:在 text 中追加空格字符可以控制重复符号之间的间距——本例飞机符号后跟 5 个空格,使 ✈ 沿航线均匀分布而不粘连。

四、纯文字标签:To New Delhi / To Hanoi

当不需要重复铺排时,把 repeat 保持默认的 False,再用负的 offset 把单个文本标签放到路径上的合适位置。官方文档演示了两条通往新德里与河内的航线标注:

line_to_new_delhi = folium.PolyLine(
    [
        [46.67959447, 3.33984375],
        [46.5588603, 29.53125],
        [42.29356419, 51.328125],
        [35.74651226, 68.5546875],
        [28.65203063, 76.81640625],
    ]
).add_to(m)

line_to_hanoi = folium.PolyLine(
    [
        [28.76765911, 77.60742188],
        [27.83907609, 88.72558594],
        [25.68113734, 97.3828125],
        [21.24842224, 105.77636719],
    ]
).add_to(m)

folium.plugins.PolyLineTextPath(line_to_new_delhi, "To New Delhi", offset=-5).add_to(m)

folium.plugins.PolyLineTextPath(line_to_hanoi, "To Hanoi", offset=-5).add_to(m)

这段代码展示了几点常见用法:

  • 两条 PolyLine 都使用默认样式(默认色 #3388ff、默认线宽 3,参见 folium/vector_layers.py 中 path_options 的默认值);
  • offset=-5 用于把单个文字标签沿路径反向(负方向)微调 5 像素,避免文字起点与折线端点完全重叠;
  • 文字内容直接写可读字符串即可,Leaflet 端会自动让文字贴合路径走向并随折线弯曲。

五、自定义文本样式:attributes 深入

attributes 是控制文本外观的核心手段,官方示例与文档给出两种写法:

# 多属性组合
attr = {"fill": "#007DEF", "font-weight": "bold", "font-size": "24"}

# 单属性
attr = {"fill": "red"}

这些键值会被原样写入生成的 SVG <text> 标签。在插件源码中,attributes 与其他参数一起进入 options,最终由模板渲染为 Leaflet setText 的第二个参数对象。常用的 SVG 文本属性还包括:

  • font-family:字体族,如 "Arial, sans-serif";
  • font-size:字号,如 "24";
  • font-weight:字重,如 "bold";
  • fill / fill-opacity:文字颜色与不透明度;
  • stroke / stroke-width:描边色与描边宽度;
  • letter-spacing:字符间距,可用于微调符号串疏密;
  • text-anchor:文本锚点(start / middle / end),影响文字相对路径起点的对齐方式。

六、源码级原理剖析

6.1 类结构与依赖注入

PolyLineTextPath 继承自 JSCSSMixin 与 MacroElement(见 folium/plugins/polyline_text_path.py):JSCSSMixin 负责把 default_js 中的脚本自动注入地图页面;MacroElement 负责把模板渲染进地图脚本。

default_js = [
    (
        "polylinetextpath",
        "https://cdn.jsdelivr.net/npm/leaflet-textpath@1.2.3/leaflet.textpath.min.js",
    )
]

从源码可以确认,插件运行时依赖 Leaflet.TextPath 1.2.3(即 leaflet-textpath),该脚本在生成地图 HTML 时自动从 jsdelivr CDN 引入,使用者无需手动添加 <script> 标签。需要注意的是:该插件的渲染完全依赖前端这个 CDN 脚本,离线环境或该 CDN 不可达时文字不会显示。

6.2 渲染模板:一行核心 JS

插件模板(folium/plugins/polyline_text_path.py)是理解其原理的关键:

{% macro script(this, kwargs) %}
    {{ this.polyline.get_name() }}.setText(
        {{ this.text|tojson }},
        {{ this.options|tojavascript }}
    );
{% endmacro %}

也就是说,PolyLineTextPath 本身不创建新的 Leaflet 图层,它只是对已有的 PolyLine 对象调用 .setText(text, options) 方法:

  • {{ this.polyline.get_name() }} 取的是目标 PolyLine 在生成的 Leaflet 脚本中的变量名(folium 会为每个元素生成形如 polyline_xxx 的全局变量),因此 PolyLineTextPath 必须绑定到一个已存在的 folium.PolyLine 实例;
  • {{ this.text|tojson }} 把文本序列化为合法的 JS 字符串字面量,\u25BA、\u2708 等转义在 Python 层已被解析为真实 Unicode 字符,再经 JSON 编码输出;
  • {{ this.options|tojavascript }} 调用 folium/template.py 中的 tojavascript 过滤器,把 options 字典递归转换为缩进的 JavaScript 对象字面量,并自动把 Python 风格的键名 camelize 为 JS 风格。

6.3 依赖注入与模板渲染流程

综合来看,一次完整的渲染链路是:Map.render() → 收集所有已添加元素的 default_js(PolyLineTextPath 贡献 leaflet-textpath 脚本)→ 依次渲染每个元素的模板宏 → 在浏览器中执行 polyline_xxx.setText("…", {…}) → Leaflet.TextPath 基于 SVG <text> 沿路径绘制文本。

七、测试验证与断言

仓库测试 tests/plugins/test_polyline_text_path.py 完整覆盖了本插件:

  • 使用与官方文档几乎一致的风向线数据构造 wind_line 与 PolyLineTextPath,并分别 add_child 到地图;
  • 断言 1:渲染结果中必须包含 leaflet-textpath@1.2.3/leaflet.textpath.min.js 的 <script src="..."> 引入(对应 default_js 的自动注入);
  • 断言 2:渲染结果中必须包含形如 polyline_x.setText(") ", {…}) 的调用片段(对应模板宏输出的 JS)。

这意味着"依赖自动注入 + 对既有 PolyLine 调用 setText"这两个行为是插件对外承诺的稳定接口,也是排查问题时的两条检查主线:渲染后的 HTML 是否引入了 Leaflet.TextPath 脚本、是否生成了对目标 PolyLine 变量名的 setText 调用。

八、实践要点与常见问题

  1. 先添加 PolyLine,再添加 PolyLineTextPath:虽然 Python 层不强制顺序,但生成的 JS 按元素添加顺序输出,setText 必须发生在目标 polyline 变量创建之后,所以务必将两者按"先线后文字"的顺序 add_to(m)。
  2. repeat 与 offset 的关系:repeat=True 时文本按 offset 的像素间隔沿路径重复铺满;repeat=False 时文本只出现一次,offset 用于微调其沿路径的位置(示例中正偏移用于重复符号间距,负偏移用于单标签反向微调)。
  3. 符号间距控制:在 text 中追加空格可以拉开重复符号之间的距离(如 "\u2708 "),这是官方示例直接使用的做法。
  4. 样式只配置需要的部分:attributes 可只给 fill,其余继承浏览器默认渲染;remove_empty 会丢弃 None 值,传 attributes=None 时该键不会进入前端 options。
  5. 依赖 CDN:插件依赖 leaflet-textpath@1.2.3 的 CDN 脚本,离线或网络受限环境下文字不会渲染,这是该插件的已知前提。
  6. 文本尽量短:沿路径渲染的文本会随折线弯曲,过长文本在急弯处可能出现重叠,建议配合 offset 与 letter-spacing 调整。

九、相关资源

登录后查看全文
folium