📌 学习目标
- 掌握向地图添加图标的实现方法
- 理解相关API的使用
- 能够独立完成类似功能开发
⭕️MapLibre GL JS全部课时目录⭕️
🎯 核心概念
向地图添加图标。
💻 完 整 代 码
代码示例
constmap=newmaplibregl.Map({container:'map',style:'https://demotiles.maplibre.org/style.json'});map.on('load',async()=>{image=awaitmap.loadImage('https://upload.wikimedia.org/wikipedia/commons/7/7c/201408_cat.png');map.addImage('cat',image.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':'cat','icon-size':0.25}});});代码示例
<!DOCTYPEhtml><htmllang="en"><head><title>Add an icon to the map</title><metaproperty="og:description"content="从外部 URL 向地图添加图标并在符号图层中使用它。"/><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',async()=>{image=awaitmap.loadImage('https://upload.wikimedia.org/wikipedia/commons/7/7c/201408_cat.png');map.addImage('cat',image.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':'cat','icon-size':0.25}});});</script></body></html>🔍 代码解析
初始化地图
使用new maplibregl.Map()创建地图实例，配置基本参数。本示例的核心特色是展示如何从外部URL加载图标并添加到地图上。
关键配置项
- container: 地图容器的 DOM 元素 ID
- style: 使用 MapLibre 官方样式
https://demotiles.maplibre.org/style.json
加载外部图标
map.on('load',async()=>{image=awaitmap.loadImage('https://upload.wikimedia.org/wikipedia/commons/7/7c/201408_cat.png');map.addImage('cat',image.data);});添加符号图层
map.addLayer({'id':'points','type':'symbol','source':'point','layout':{'icon-image':'cat','icon-size':0.25}});⚙️ 参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| container | string | 是 | - | 地图容器元素的 ID |
| style | string/object | 是 | - | 地图样式 URL 或内联样式对象 |
icon-image 布局属性
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| icon-image | string | 是 | 图标的唯一标识名称 |
| icon-size | number | 否 | 图标缩放比例，默认 1 |
🎨 效果说明
运行代码后，地图上会在坐标[0, 0]（赤道和本初子午线交点）处显示一个猫咪图标：
- 图标显示: 猫咪图标以 25% 的原始大小显示（
icon-size: 0.25） - 交互功能: 支持鼠标拖拽、滚轮缩放、右键旋转等标准交互
- 地图默认: 显示全球视图，无特定中心点和缩放级别
💡 常 见 问 题
Q1: 图标不显示怎么办？
A:按以下步骤排查：
- 确保图片 URL 可访问
- 确认
map.loadImage()返回的数据有效 - 检查
addImage()的 ID 与icon-image引用的名称一致 - 确保在
load事件回调中操作
Q2: 如何调整图标大小？
A:使用icon-size属性调整图标缩放比例：
'icon-size':0.5// 50% 大小Q3: 可以使用本地图片吗？
A:可以。使用相对路径或绝对路径引用本地图片文件。
Q4: 支持哪些图片格式？
A:支持 PNG、JPEG、WebP 和 SVG 格式的图片。
📝 练习任务
- 基础练习：修改图标 URL，使用其他图片作为地图标记
- 进阶挑战：添加多个不同位置的图标点
- 拓展思考：如何根据不同属性显示不同的图标？
🌟 最佳实践
- 图片格式: 优先使用 PNG 或 WebP 格式，支持透明背景
- 图片大小: 使用适当尺寸的图标，避免过大影响性能
- 异步加载: 使用
await确保图片加载完成后再添加图层 - 错误处理: 添加图片加载失败的降级方案
- 缓存策略: 对于重复使用的图标，考虑缓存
- 图标命名: 使用清晰的图标 ID 命名规范
🔗 延伸阅读
Map API文档
MapLibre GL JS 官方文档
[下一课预告]：将继续学习地图图层的基础知识
本文是MapLibre GL JS实践课程系列的一部分，欢迎关注收藏
