OpenLayers 热力图实现教程
在 OpenLayers 中实现热力图,直接使用内置的 ol/layer/Heatmap 图层,把 VectorSource 中的点要素(或线要素)按权重渲染成颜色渐变密度图即可。截至 2026 年 11 月,推荐稳定版 v10.11.0(2026 年 10 月 4 日发布),默认 radius 为 8 像素、blur 为 15 像素,weight 取值钳制在 0–1。配好 source、weight、radius、blur 和 gradient 后就能出图,适合地震、事件或人口密度等 GIS 可视化场景。
环境准备与版本要求
先解决“能跑起来”的问题。通过 npm 安装最新稳定包:执行 npm install ol。新项目可用官方脚手架 npm create ol-app my-app,再进入目录启动 Vite 开发服务器。生产环境务必用 bundler(Vite、Webpack 等)做 tree-shake,并引入 ol/ol.css。
浏览器需支持现代 HTML5 与 WebGL(Heatmap 基于 WebGLPointsLayerRenderer),覆盖全球使用率超过 1% 的 Chrome、Firefox、Safari、Edge;自 v7 起已不再支持 IE。默认地图投影为 EPSG:3857,数据源坐标系需与之匹配或做转换。开发机建议 Node.js 14+。完整安装包与 CDN 测试地址可在 OpenLayers 官方下载页 核对。
- 核心依赖:仅需 ol 包,无额外强制第三方。
- 数据前提:VectorSource 主要提供 Point 几何;LineString 也支持,线宽约为 radius 的两倍。
- 验收标准:控制台无 WebGL 报错,底图正常加载,热力图层 visible 为 true。

热力图实现的具体步骤
目标是把点数据变成可交互的热力图层。按下面顺序执行即可得到可运行结果。
- 导入必要模块:HeatmapLayer 来自 ol/layer/Heatmap.js,VectorSource 来自 ol/source/Vector.js,再配上 Feature、Point、Map、View、TileLayer(底图)以及 ol.css。
- 准备数据源。创建 VectorSource,向其中添加 Feature;每个 Feature 的几何为 Point(坐标与地图 CRS 一致),并带有 weight 属性(数值 0–1)或后续用函数计算。
- 实例化热力图层。new HeatmapLayer({ source: 你的 VectorSource, weight: ‘weight’ 或返回 0–1 数字的函数, radius: 8, blur: 15, gradient: [‘#00f’, ‘#0ff’, ‘#0f0’, ‘#ff0’, ‘#f00’], opacity: 1 })。任何选项都会作为可观察属性。
- 创建地图并添加图层。new Map({ target: ‘map’, layers: [底图图层, 热力图层], view: new View({ center: […], zoom: … }) })。
- 可选动态调节:给页面滑块绑定 input 事件,调用 layer.setRadius(value) 或 layer.setBlur(value),立即刷新视觉效果。官方“Earthquakes Heatmap”示例正是用震级提取 weight 并支持实时调参。
做完后缩放、平移地图,热点应随视图平滑重绘。若数据来自 GeoJSON/KML,用对应 format 解析后填入 VectorSource 即可。
关键参数配置与权重设置
参数直接决定热点大小、模糊程度和颜色过渡。下表列出最常用选项(与当前 v10.x API 一致),完整列表见 Heatmap 图层 API 文档。
| 参数 | 类型 | 默认值 | 说明与注意 |
|---|---|---|---|
| gradient | CSS 颜色字符串数组 | [‘#00f’, ‘#0ff’, ‘#0f0’, ‘#ff0’, ‘#f00’] | 从低到高密度的颜色渐变;alpha 通道基本无效,只用 RGB。 |
| radius | NumberExpression | 8 | 热点半径(像素)。对 LineString 线宽约为其两倍。 |
| blur | NumberExpression | 15 | 模糊大小(像素)。最终效果大小 ≈ radius + blur。 |
| weight | WeightExpression | ‘weight’ | 属性名、表达式或函数;返回值应在 0–1,超出自动钳制。 |
| source | VectorSource | — | 必须提供,主要为 Point 几何。 |
| opacity / visible | number / boolean | 1 / true | 控制整体透明度与显隐;频繁显隐优先用 setVisible。 |
权重函数示例思路:从要素属性取震级 mag,再映射为 (mag – 5) / 5 这类 0–1 值。可用 getBlur()/setBlur()、getRadius()/setRadius()、getGradient()/setGradient() 运行时修改,并触发 change:blur 等事件。

注意事项与常见踩坑
热力图依赖 WebGL,数据量大时性能优于纯 Canvas,但有几处容易出错:
- 坐标系必须对齐。点坐标若是经纬度,需确认 View 投影或先做变换,否则热点会偏移。
- weight 写错会导致全透明或全红。优先用属性名字符串,或写返回数字的函数并打印校验。
- 不要频繁 map.addLayer / removeLayer。WebGL 缓冲易报 “Insufficient buffer size” 或 GL_INVALID_OPERATION;改用 layer.setVisible(true/false)。
- 移除图层时可能闪烁(v10.6.1 及近期版本已知现象)。可先把对应 canvas.style.display 设为 ‘none’ 再 remove。
- 导出地图时 Heatmap 的独立 WebGL canvas 可能漏画。需开启 preserveDrawingBuffer,并按 pixelRatio 正确 drawImage。
- wrapX 对热力图支持不完整,世界环绕场景可能出现断裂。
- 用属性表达式设置 blur/radius(如 [‘get’, ‘blur’])时,部分版本 Fragment shader 会编译失败,建议先用固定数值。
验收标准:打开页面后热点颜色从蓝到红连续过渡;拖动滑块半径/模糊立即变化;缩放至不同级别热点密度合理;控制台无 WebGL 或 undeclared identifier 报错。
常见问题
热力图完全不显示怎么办?
先确认 VectorSource 里确有 Point 几何且坐标落在当前视图范围内,weight 返回值在 0–1,图层 visible 与 opacity 正常,浏览器开启了硬件加速。打开开发者工具看是否有 WebGL 上下文丢失提示。
添加或移除热力图层时报 WebGL 错误?
避免短时间内反复 addLayer/removeLayer,改用 setVisible 切换。若必须销毁,先隐藏对应 canvas 再移除,可减少缓冲冲突。
如何根据业务字段动态改权重和样式?
把 weight 写成函数,从 feature.get(‘你的字段’) 计算 0–1 值;半径和模糊用 setRadius/setBlur 响应界面控件。gradient 也可用 setGradient 整组替换。
gradient 里写了透明度却没效果?
Heatmap 渐变只取 RGB 分量,alpha 主要用于内部模糊计算。整体透明用图层 opacity,或结合 ol.source.Raster 做后期混合。
总结:OpenLayers 热力图核心就是 Heatmap 图层 + 带权重的点 VectorSource,调好 radius、blur、weight 和 gradient 就能快速出图。建议先按官方地震示例验证本机 WebGL 与版本(v10.11.0),再换成自己的业务数据并加上动态调参;生产环境坚持用 npm 包 + bundler,避免直接 CDN 完整构建。