📌 学习目标
- 掌握向地图添加图标的实现方法
- 理解相关API的使用
- 能够独立完成类似功能开发
🎯 核心概念
向地图添加图标。
💻 完 整 代 码
代码示例
js
const map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json'
});
map.on('load', async () => {
image = await map.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
}
});
});代码示例
html
<!DOCTYPE html>
<html lang="en">
<head>
<title>Add an icon to the map</title>
<meta property="og:description" content="从外部 URL 向地图添加图标并在符号图层中使用它。" />
<meta property="og:created" content="2025-06-25" />
<meta charset='utf-8'>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel='stylesheet' href='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css' />
<script src='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>
<div id="map"></div>
<script>
const map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json'
});
map.on('load', async () => {
image = await map.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
加载外部图标
javascript
map.on('load', async () => {
image = await map.loadImage('https://upload.wikimedia.org/wikipedia/commons/7/7c/201408_cat.png');
map.addImage('cat', image.data);
});添加符号图层
javascript
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 属性调整图标缩放比例：
javascript
'icon-size': 0.5 // 50% 大小Q3: 可以使用本地图片吗？
A: 可以。使用相对路径或绝对路径引用本地图片文件。
Q4: 支持哪些图片格式？
A: 支持 PNG、JPEG、WebP 和 SVG 格式的图片。
📝 练习任务
- 基础练习：修改图标 URL，使用其他图片作为地图标记
- 进阶挑战：添加多个不同位置的图标点
- 拓展思考：如何根据不同属性显示不同的图标？
🌟 最佳实践
- 图片格式: 优先使用 PNG 或 WebP 格式，支持透明背景
- 图片大小: 使用适当尺寸的图标，避免过大影响性能
- 异步加载 : 使用
await确保图片加载完成后再添加图层 - 错误处理: 添加图片加载失败的降级方案
- 缓存策略: 对于重复使用的图标，考虑缓存
- 图标命名: 使用清晰的图标 ID 命名规范
🔗 延伸阅读
-
下一课预告：将继续学习地图图层的基础知识
本文是MapLibre GL JS实践课程系列的一部分，欢迎关注收藏