📌 学习目标
- 掌握添加生成的图标的实现方法
- 理解相关API的使用
- 能够独立完成类似功能开发
🎯 核心概念
向地图添加运行时生成的图标,也就是程序生产一个图标，动态生成的图标，作为要素图标。
💻 完 整 代 码
代码示例
constmap=newmaplibregl.Map({container:'map',style:'https://demotiles.maplibre.org/style.json'});map.on('load',()=>{constwidth=64;// 图像将为64像素正方形constbytesPerPixel=4;// 每个像素由4字节表示：红色、绿色、蓝色、透明度constdata=newUint8Array(width*width*bytesPerPixel);for(letx=0;x<width;x++){for(lety=0;y<width;y++){constoffset=(y*width+x)*bytesPerPixel;data[offset+0]=(y/width)*255;// 红色通道data[offset+1]=(x/width)*255;// 绿色通道data[offset+2]=128;// 蓝色通道data[offset+3]=255;// 透明度通道}}map.addImage('gradient',{width,height:width,data});map.addSource('point',{'type':'geojson','data':{'type':'FeatureCollection','features':[{'type':'Feature','geometry':{'type':'Point','coordinates':[0,0]}}]}});map.addLayer({'id':'points','type':'symbol','source':'point','layout':{'icon-image':'gradient'}});});代码示例
<!DOCTYPEhtml><htmllang="en"><head><title>Add a generated icon to the map</title><metaproperty="og:description"content="添加在运行时生成的图标到地图。"/><metaproperty="og:created"content="2025-06-25"/><metacharset='utf-8'><metaname="viewport"content="width=device-width, initial-scale=1"><linkrel='stylesheet'href='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css'/><scriptsrc='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js'></script><style>body{margin:0;padding:0;}html, body, #map{height:100%;}</style></head><body><divid="map"></div><script>constmap=newmaplibregl.Map({container:'map',style:'https://demotiles.maplibre.org/style.json'});map.on('load',()=>{constwidth=64;// 图像将是64像素的正方形constbytesPerPixel=4;// 每个像素由4个字节表示：红、绿、蓝和透明度。constdata=newUint8Array(width*width*bytesPerPixel);for(letx=0;x<width;x++){for(lety=0;y<width;y++){constoffset=(y*width+x)*bytesPerPixel;data[offset+0]=(y/width)*255;// 红色data[offset+1]=(x/width)*255;// 绿色data[offset+2]=128;// 蓝色data[offset+3]=255;// 透明度}}map.addImage('gradient',{width,height:width,data});map.addSource('point',{'type':'geojson','data':{'type':'FeatureCollection','features':[{'type':'Feature','geometry':{'type':'Point','coordinates':[0,0]}}]}});map.addLayer({'id':'points','type':'symbol','source':'point','layout':{'icon-image':'gradient'}});});</script></body></html>🔍 代码解析
初始化地图
使用new maplibregl.Map()创建地图实例，配置基本参数。本示例的核心特色是展示如何在运行时生成图标并添加到地图上。
关键配置项
- container: 地图容器的 DOM 元素 ID
- style: 使用 MapLibre 官方样式
https://demotiles.maplibre.org/style.json
生成渐变图标
constwidth=64;// 图像大小为 64x64 像素constbytesPerPixel=4;// RGBA 四个通道constdata=newUint8Array(width*width*bytesPerPixel);for(letx=0;x<width;x++){for(lety=0;y<width;y++){constoffset=(y*width+x)*bytesPerPixel;data[offset+0]=(y/width)*255;// 红色通道（垂直渐变）data[offset+1]=(x/width)*255;// 绿色通道（水平渐变）data[offset+2]=128;// 蓝色通道（固定值）data[offset+3]=255;// 透明度通道（完全不透明）}}map.addImage('gradient',{width,height:width,data});添加符号图层
map.addLayer({'id':'points','type':'symbol','source':'point','layout':{'icon-image':'gradient'}});⚙️ 参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| container | string | 是 | - | 地图容器元素的 ID |
| style | string/object | 是 | - | 地图样式 URL 或内联样式对象 |
addImage 数据格式
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| width | number | 是 | 图像宽度（像素） |
| height | number | 是 | 图像高度（像素） |
| data | Uint8Array | 是 | 像素数据，RGBA 格式 |
🎨 效果说明
运行代码后，地图上会在坐标[0, 0]处显示一个 64x64 像素的渐变图标：
- 颜色渐变: 从左上角（紫色）到右下角（黄色）的渐变效果
- 红色通道: 从顶部到底部线性增加（0 → 255）
- 绿色通道: 从左到右线性增加（0 → 255）
- 蓝色通道: 固定为 128（中等蓝色）
- 交互功能: 支持鼠标拖拽、滚轮缩放等标准交互
💡 常 见 问 题
Q1: 生成的图像数据格式是什么？
A:使用Uint8Array存储 RGBA 像素数据，每个像素占 4 字节：红、绿、蓝、透明度，每个通道值范围 0-255。
Q2: 如何计算像素偏移量？
A:使用公式offset = (y * width + x) * bytesPerPixel计算每个像素在数组中的起始位置。
Q3: 可以生成透明图像吗？
A:可以。修改透明度通道（第4个字节）的值，0 表示完全透明，255 表示完全不透明。
Q4: 图像大小有限制吗？
A:建议不要生成过大的图像，会影响性能和内存使用。通常 64x64 或 128x128 像素足够。
📝 练习任务
- 基础练习：修改颜色通道的值，创建不同的渐变效果
- 进阶挑战：生成一个圆形图标，边缘透明
- 拓展思考：如何动态生成带有文字的图标？
🌟 最佳实践
- 性能优化: 避免在频繁回调中生成图像，考虑缓存已生成的图像
- 内存管理: 对于临时使用的生成图像，使用后及时清理
- 图像大小: 保持生成图像尺寸适中，平衡视觉效果和性能
- 代码复用: 将图像生成逻辑封装为可复用的函数
- 类型安全: 使用
Uint8Array确保类型正确 - 测试验证: 在不同设备上测试生成图像的显示效果
🔗 延伸阅读
Map API文档
MapLibre GL JS 官方文档
[下一课预告]：将继续学习地图图层的基础知识
本文是MapLibre GL JS实践课程系列的一部分，欢迎关注收藏
