企业官网建设流程全解析

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

本篇指南以 folium 官方用户手册 docs/user_guide/vector_layers.rst 为骨架，系统讲解其矢量图层模块的全部五种核心对象：PolyLine（折线）、Polygon（多边形）、Rectangle（矩形）、Circle/CircleMarker（圆形）以及基于 FeatureGroup 的 ColorLine（分段着色线）。你将学会每种对象的坐标组织方式、全部可用的路径样式参数（Path Options）、平滑因子与日期变更线处理等高级技巧，并能对照 folium/vector_layers.py 与 folium/features.py 中的源码实现理解参数背后的底层逻辑，直接产出可运行的地图代码。

概览：五种矢量图层对象与对应源码

folium 将 Leaflet 的矢量图层封装在folium.vector_layers与folium.features两个模块中。从 folium/vector_layers.py 的类定义可以看到清晰的对应关系：

从源码的_template模板可见，每个类在渲染时都会生成对应的 Leaflet JavaScript 调用，例如PolyLine生成L.polyline(locations, options)，Polygon生成L.polygon(...)，Rectangle生成L.rectangle(...)等，然后addTo(parent)挂载到地图上。这意味着 folium 文档中所有样式参数最终都会原样传递给 Leaflet 的 Path 选项，掌握下面这份参数表就等于掌握了矢量图层的全部表现力。

公共基础：Path Options 路径样式参数

所有矢量图层（Polygon、Polyline、Circle、CircleMarker、Rectangle）共享同一套路径样式选项，由 folium/vector_layers.py 中的path_options()函数统一解析。该函数同时接受 snake_case 与 lowerCamelCase 两种写法（内部通过camelize转换），并有以下要点：

• fill_color会覆盖fill=False：源码中当fill_color存在时强制fill = True；当fill_color缺省时才回落到fill参数（默认False），且此时fill_color默认取color的值。官方文档 Circle 示例中fill=False被fill_color="green"覆盖正是这个逻辑。
• smoothFactor与noClip仅对线状对象生效（line=True分支，PolyLine/Polygon/Rectangle 走此分支）。
• 其余未识别的参数会原样透传给 Leaflet：从源码看，interactive、pane、renderer、className、tags、gradient等选项都会被透传，测试 tests/test_vector_layers.py 对此有专门验证（如test_circle_marker_forwards_interactive）。

Circle 与 CircleMarker：像素半径与米制半径的取舍

circle_and_circle_marker.md 的核心结论一句话可概括：CircleMarker的半径以像素为单位，Circle的半径以米为单位。因此CircleMarker在缩放时屏幕上大小不变，而Circle始终贴合真实地理范围。结合源码看，Circle的默认半径为50（米），CircleMarker的默认半径为10（像素）。

官方示例（circle_and_circle_marker.md）演示了三者的差异：

import folium m = folium.Map(location=[-27.5717, -48.6256], zoom_start=9) radius = 50 folium.CircleMarker( location=[-27.55, -48.8], radius=radius, color="cornflowerblue", stroke=False, # 不绘制描边 fill=True, # 开启填充 fill_opacity=0.6, opacity=1, popup="{} pixels".format(radius), tooltip="I am in pixels", ).add_to(m) radius = 25 folium.CircleMarker( location=[-27.35, -48.8], radius=radius, color="black", weight=3, # 3 像素宽的黑色描边 fill=False, fill_opacity=0.6, opacity=1, ).add_to(m) radius = 10000 folium.Circle( location=[-27.551667, -48.478889], radius=radius, # 10000 米 color="black", weight=1, fill_opacity=0.6, opacity=1, fill_color="green", fill=False, # 注意：会被 fill_color 覆盖为 True popup="{} meters".format(radius), tooltip="I am in meters", ).add_to(m) m

使用要点：

• 需要地图缩放时保持标记大小稳定（如点状标注），选CircleMarker；
• 需要表达真实地理范围（如 10 公里缓冲区），选Circle；
• 源码注释指出Circle是真实圆的近似，越靠近两极，投影变形导致的偏差越大；
• Circle与CircleMarker都继承自folium.map.Marker（见 folium/vector_layers.py），因此也支持popup、tooltip以及 Marker 相关能力。

PolyLine 折线：坐标组织、样式与平滑

PolyLine 文档 是矢量图层章节篇幅最大的部分，覆盖了从入门到进阶的四个主题。

基础用法：大圆航线示例

官方示例使用波士顿到旧金山的大圆航线上 15 个坐标点：

import folium # Coordinates are 15 points on the great circle from Boston to San Francisco. coordinates = [ [42.3581, -71.0636], [42.82995815, -74.78991444], [43.17929819, -78.56603306], [43.40320216, -82.37774519], [43.49975489, -86.20965845], [43.46811941, -90.04569087], [43.30857071, -93.86961818], [43.02248456, -97.66563267], [42.61228259, -101.41886832], [42.08133868, -105.11585198], [41.4338549, -108.74485069], [40.67471747, -112.29609954], [39.8093434, -115.76190821], [38.84352776, -119.13665678], [37.7833, -122.4167], ] # Create the map and add the line m = folium.Map(location=[41.9, -97.3], zoom_start=4) folium.PolyLine( locations=coordinates, color="#FF0000", weight=5, tooltip="From Boston to San Francisco", ).add_to(m) m

locations接受形如[[lat, lon], ...]或[(lat, lon), ...]的点序列。源码中PolyLine通过validate_multi_locations校验坐标，因此既支持扁平的二维点表，也支持嵌套的三维点表（多段线）。

平滑因子（smoothing / smooth_factor）

Leaflet 中的 PolyLine 默认开启平滑（简化）：移除部分点以减轻浏览器绘制负担，平滑程度由smooth_factor控制。官方示例将smooth_factor设为 50，形成夸张的平滑效果：

m = folium.Map(location=[41.9, -97.3], zoom_start=4) folium.PolyLine( smooth_factor=50, locations=coordinates, color="grey", tooltip="Too much smoothing?", weight=5, ).add_to(m) m

源码层面，path_options(line=True, **kwargs)会取出smoothFactor（默认1.0）与noClip（默认False）放入extra_options（folium/vector_layers.py）。文档对smooth_factor的语义描述是：每个缩放级别上对折线的简化程度——值越大性能越好、外观越平滑，值越小表示越精确。相关主题还可参考 docs/user_guide/geojson/smoothing.md，其中说明该参数同样适用于 GeoJson、TopoJson 和 Choropleth，Leaflet 默认值为 1，且没有上下界限制。

跨越日期变更线（Crossing the date line）

这是 PolyLine 最容易踩坑的场景。官方文档用四条线对比了正确与错误的经度写法：

lon = lat = 0 zoom_start = 1 m = folium.Map(location=[lat, lon], zoom_start=zoom_start) kw = {"opacity": 1.0, "weight": 6} # 错误：179 → -179，Leaflet 会沿 0° 经线方向“绕远路”绘制 folium.PolyLine( locations=[(2, 179), (2, -179)], tooltip="Wrong", color="red", line_cap="round", **kw, ).add_to(m) # 正确：用 179 → 181 表达跨越 +180° 经线 folium.PolyLine( locations=[(-2, 179), (-2, 181)], tooltip="Correct", line_cap="butt", color="blue", **kw, ).add_to(m) # 正确：用 -179 → 179 表达跨越 -180° 经线 folium.PolyLine( locations=[(-6, -179), (-6, 179)], line_cap="square", color="green", tooltip="Correct", **kw, ).add_to(m) # 边界情况：超出 180 太多（190°）会产生意外结果 folium.PolyLine( locations=[(12, -179), (12, 190)], color="orange", tooltip="Artifact?", **kw, ).add_to(m) m

核心规则：当一条线需要跨越国际日期变更线时，不应使用 −179 → 179 这样的“反向”坐标对，而应使用 179 → 181 或 −179 → −181 这样单调递增/递减的经度，让 Leaflet 沿最短路径绘制。此示例还展示了line_cap三种取值（round、butt、square）的视觉差异。

多段线（Multi-PolyLine）

通过向单个PolyLine传入多组坐标（三维列表），可以一次创建多条独立的线：

lat = +38.89399 lon = -77.03659 zoom_start = 17 m = folium.Map(location=[lat, lon], zoom_start=zoom_start) kw = {"color": "red", "fill": True, "radius": 20} folium.CircleMarker([38.89415, -77.03738], **kw).add_to(m) folium.CircleMarker([38.89415, -77.03578], **kw).add_to(m) locations = [ [ (38.893596444352134, -77.03814983367920), (38.893379333722040, -77.03792452812195), ], [ (38.893379333722040, -77.03792452812195), (38.893162222428310, -77.03761339187622), ], [ (38.893162222428310, -77.03761339187622), (38.893028615148424, -77.03731298446655), ], [ (38.893028615148424, -77.03731298446655), (38.892920059048464, -77.03691601753235), ], [ (38.892920059048464, -77.03691601753235), (38.892903358095296, -77.03637957572937), ], [ (38.892903358095296, -77.03637957572937), (38.893011914220770, -77.03592896461487), ], [ (38.893011914220770, -77.03592896461487), (38.893162222428310, -77.03549981117249), ], [ (38.893162222428310, -77.03549981117249), (38.893404384982480, -77.03514575958252), ], [ (38.893404384982480, -77.03514575958252), (38.893596444352134, -77.03496336936950), ], ] folium.PolyLine( locations=locations, color="orange", weight=8, opacity=1, smooth_factor=0, # 关闭平滑，保留全部顶点 ).add_to(m) m

此例同时展示了smooth_factor=0的用法——完全关闭简化，保证高精度细节（常用于要求顶点无丢失的路径展示）。测试 tests/test_vector_layers.py 中的test_mulyipolyline对多段线渲染进行了验证。

Polygon 多边形：单多边形与多多边形

Polygon 文档 包含两种用法：普通多边形与带洞的多个多边形。

普通多边形

官方示例在东京绘制一个五边形区域，并展示了填充参数的组合：

import folium m = folium.Map(location=[35.67, 139.78], zoom_start=13) locations = [ [35.6762, 139.7795], [35.6718, 139.7831], [35.6767, 139.7868], [35.6795, 139.7824], [35.6787, 139.7791], ] folium.Polygon( locations=locations, color="blue", weight=6, fill_color="red", fill_opacity=0.5, fill=True, popup="Tokyo, Japan", tooltip="Click me!", ).add_to(m) m

注意：Polygon 的坐标无需重复首尾点（Leaflet 会自动闭合），文档与源码 docstring 都明确说明了这一点（folium/vector_layers.py）。

多多边形（Multi-Polygon）

传入三维坐标列表即可一次绘制多个多边形，每个子列表代表一个独立环：

locations = [ [ [7.577794326946673, 8.998503901433935], [7.577851434795945, 8.998572430673164], [7.577988491475764, 8.998652380403087], [7.578105560723088, 8.998426807051544], [7.577891409660878, 8.998289750371725], [7.577794326946673, 8.998503901433935], ], [ [7.578139824893071, 8.999291979141560], [7.578359687549607, 8.999414759083890], [7.578456769364435, 8.999266281014116], [7.578471046101925, 8.999197181604700], [7.578247331649095, 8.999094883721964], [7.578139824893071, 8.99929197914156], ], [ [7.577851730672876, 8.997811268775080], [7.578012579816743, 8.997460464828633], [7.577798113991832, 8.997311104523930], [7.577667902951418, 8.997663440915119], [7.577851730672876, 8.997811268775080], ], [ [7.578562417221803, 8.999551816663029], [7.578688052511666, 8.999654609172921], [7.578813688700849, 8.999443313458185], [7.578670920426703, 8.999369073523950], [7.578562417221803, 8.999551816663029], ], [ [7.577865711533433, 8.998252059784761], [7.577989601239152, 8.998002756022402], [7.577648754586391, 8.997784460884190], [7.577545911714481, 8.998069316645683], [7.577865711533433, 8.998252059784761], ], ] m = folium.Map(location=[7.577798113991832, 8.997311104523930], zoom_start=16) folium.Polygon( locations=locations, smooth_factor=2, color="crimson", no_clip=True, tooltip="Hi there!", ).add_to(m) m

此例同时演示了no_clip=True：源码中noClip属于线状对象专属选项（folium/vector_layers.py），设为True可禁用 Leaflet 对超出视口区域的裁剪行为。

Rectangle 矩形：bounds、线帽与虚线样式

Rectangle 文档 展示了矩形图层的核心特征——只用两个对角坐标（bounds）定义范围，并横向对比了三种line_join与三种虚线模式：

import folium m = folium.Map(location=[35.685, 139.76], zoom_start=15) kw = { "color": "blue", "line_cap": "round", "fill": True, "fill_color": "red", "weight": 5, "popup": "Tokyo, Japan", "tooltip": "<strong>Click me!</strong>", } folium.Rectangle( bounds=[[35.681, 139.766], [35.691, 139.776]], line_join="round", dash_array="5, 5", **kw, ).add_to(m) dx = 0.012 folium.Rectangle( bounds=[[35.681, 139.766 - dx], [35.691, 139.776 - dx]], line_join="mitter", dash_array="5, 10", **kw, ).add_to(m) folium.Rectangle( bounds=[[35.681, 139.766 - 2 * dx], [35.691, 139.7762 - 2 * dx]], line_join="bevel", dash_array="15, 10, 5, 10, 15", **kw, ).add_to(m) m

要点：

• bounds必须恰好包含两个[lat, lon]点；源码中Rectangle.__init__通过assert len(self.locations) == 2强制校验，传入数量错误会直接抛异常（folium/vector_layers.py）；
• line_join的可选值为mitter、round、bevel（示例中分别展示），对应 SVGstroke-linejoin；
• dash_array可设置复杂的多段虚线模式，如"15, 10, 5, 10, 15"表示 15 长线、10 空、5 短线、10 空、15 长线的循环；
• tooltip支持 HTML 字符串（示例中使用了<strong>Click me!</strong>），tooltip 与 popup 的具体机制可参考 docs/user_guide/ui_elements/popups.md。

ColorLine：按数值分段着色的折线

ColorLine 文档 介绍了一个矢量图层中非常实用的扩展对象——根据每个线段的数值给整条折线着色。官方示例用 NumPy 生成圆形轨迹并附上随角度变化的颜色值：

import numpy as np import folium x = np.linspace(0, 2 * np.pi, 300) lats = 20 * np.cos(x) lons = 20 * np.sin(x) colors = np.sin(5 * x) m = folium.Map([0, 0], zoom_start=3) color_line = folium.ColorLine( positions=list(zip(lats, lons)), colors=colors, colormap=["y", "orange", "r"], weight=10, ).add_to(m) m

从源码实现看，ColorLine继承自folium.map.FeatureGroup（folium/features.py），其工作原理是：

1. positions中的相邻点对组成一条条线段，colors的取值与线段一一对应（长度必须等于len(positions) - 1）；
2. 根据colormap把每个颜色值映射为具体颜色：不传时默认使用["green", "yellow", "red"]的 LinearColormap，若传入 list/tuple 则由 branca 自动构造LinearColormap，也可直接传入现成的LinearColormap或StepColormap对象；
3. 映射的色阶由nb_steps（默认 12）离散化；
4. 最终把相同颜色的相邻线段合并，为每种颜色生成一个PolyLine子对象挂载到 FeatureGroup 上。

因此ColorLine实际上是“多个着色 PolyLine 的组合”，适合表达海拔、温度、流量等沿路径连续变化的数值字段。weight（线宽，默认 2）与opacity（透明度，默认 1）控制所有子线段的外观。

实战小结与测试佐证

• 选型：屏幕恒定大小用CircleMarker，地理真实范围用Circle，单条路径用PolyLine，闭合区域用Polygon，规则区域框选用Rectangle，数值渐变路径用ColorLine。
• 公共参数：所有对象共享 path_options 的样式体系，支持 snake_case 与 lowerCamelCase 两种写法；fill_color会强制开启填充。
• 坐标校验：folium 在folium/utilities.py中通过validate_locations/validate_multi_locations对坐标做规范化校验，非法输入会在 Python 侧直接报错而非生成坏地图。
• 测试验证：仓库测试 tests/test_vector_layers.py 覆盖了 Circle、CircleMarker、Rectangle、Polygon、PolyLine 与多段线的渲染，以及 Path 选项 camelCase 转换与额外 Leaflet 选项透传行为，可作为参数行为的第一手参考。

将上述示例在 Jupyter Notebook 中运行（m直接输出交互地图），即可逐一验证每种图层在缩放、悬停与点击时的真实表现。若需将矢量图层与 GeoJSON 数据结合使用（如 Choropleth 分级着色），可继续阅读 docs/user_guide/geojson/geojson.md 与 docs/user_guide/geojson/choropleth.md。

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