@dsh-gis/dsh-opengis-skill 0.3.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +89 -1
- package/README.md +78 -21
- package/adaptations/brutile.md +19 -6
- package/adaptations/cesiumjs.md +14 -5
- package/adaptations/common.md +49 -16
- package/adaptations/deck-gl.md +19 -6
- package/adaptations/duckdb-spatial.md +20 -6
- package/adaptations/gdal-api.md +24 -6
- package/adaptations/gdal.md +22 -6
- package/adaptations/geolibre.md +20 -6
- package/adaptations/geometry-api-java.md +14 -6
- package/adaptations/geometry-api-net.md +17 -6
- package/adaptations/geonode.md +17 -6
- package/adaptations/geopandas.md +21 -6
- package/adaptations/geopipe-agent.md +21 -6
- package/adaptations/geos.md +23 -0
- package/adaptations/geoserver-cloud.md +17 -6
- package/adaptations/geoserver-rest-api.md +17 -6
- package/adaptations/geoserver.md +18 -6
- package/adaptations/geotools.md +19 -6
- package/adaptations/grass-gis.md +24 -6
- package/adaptations/jts.md +18 -6
- package/adaptations/kepler-gl.md +18 -5
- package/adaptations/leaflet.md +25 -6
- package/adaptations/mapbox-gl-js.md +23 -6
- package/adaptations/maplibre-gl-js.md +20 -0
- package/adaptations/maplibre-native.md +19 -0
- package/adaptations/mapserver.md +22 -6
- package/adaptations/mapsui.md +22 -6
- package/adaptations/nettopologysuite.md +19 -6
- package/adaptations/opendronemap.md +21 -0
- package/adaptations/opengis-all.md +16 -5
- package/adaptations/opengis-daf.md +16 -5
- package/adaptations/opengis-utils-for-java.md +20 -6
- package/adaptations/opengis-utils-for-net.md +23 -6
- package/adaptations/openlayers.md +20 -6
- package/adaptations/pdal.md +26 -6
- package/adaptations/postgis.md +20 -6
- package/adaptations/proj.md +20 -6
- package/adaptations/projnet4geoapi.md +21 -6
- package/adaptations/pyqgis.md +18 -6
- package/adaptations/qgis-process.md +21 -6
- package/adaptations/qgis-server.md +18 -6
- package/adaptations/shapely.md +22 -6
- package/adaptations/sharpmap.md +19 -6
- package/adaptations/spatialite.md +23 -6
- package/adaptations/stac-cog-titiler.md +23 -0
- package/adaptations/whitebox-tools.md +19 -6
- package/assets/deck-gl/SKILL.md +1 -0
- package/assets/duckdb-spatial/SKILL.md +36 -13
- package/assets/gdal/SKILL.md +6 -6
- package/assets/gdal-api/SKILL.md +2 -2
- package/assets/geolibre/SKILL.md +1 -0
- package/assets/geonode/SKILL.md +3 -3
- package/assets/geopandas/SKILL.md +42 -8
- package/assets/geopandas/reference/core-api.md +51 -0
- package/assets/geos/SKILL.md +372 -0
- package/assets/geoserver/SKILL.md +1 -1
- package/assets/geoserver-cloud/SKILL.md +0 -2
- package/assets/grass-gis/SKILL.md +31 -7
- package/assets/kepler-gl/SKILL.md +1 -0
- package/assets/leaflet/SKILL.md +2 -2
- package/assets/mapbox-gl-js/SKILL.md +1 -0
- package/assets/maplibre-gl-js/SKILL.md +478 -0
- package/assets/maplibre-native/SKILL.md +383 -0
- package/assets/mapserver/SKILL.md +7 -5
- package/assets/mapsui/SKILL.md +4 -2
- package/assets/opendronemap/SKILL.md +309 -0
- package/assets/opengis-all/SKILL.md +1 -0
- package/assets/pdal/SKILL.md +9 -1
- package/assets/projnet4geoapi/SKILL.md +1 -1
- package/assets/shapely/SKILL.md +24 -4
- package/assets/shapely/reference/operations-reference.md +30 -0
- package/assets/spatialite/SKILL.md +8 -2
- package/assets/stac-cog-titiler/SKILL.md +420 -0
- package/assets/whitebox-tools/SKILL.md +20 -4
- package/lib/adaptations.d.ts +22 -1
- package/lib/adaptations.js +166 -20
- package/lib/index.d.ts +13 -9
- package/lib/index.js +58 -12
- package/lib/taxonomy.d.ts +41 -0
- package/lib/taxonomy.js +332 -0
- package/locale/en.json +1 -1
- package/locale/zh.json +1 -1
- package/package.json +10 -4
- package/upstream.json +36 -26
|
@@ -0,0 +1,478 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: maplibre-gl-js
|
|
3
|
+
description: "Use when building open-source vector web maps with maplibre-gl 6.17.0 — Map/addSource/addLayer, Style Spec v25 layers, data-driven expressions, raster-dem terrain with setTerrain, setSky, setMissingStyleImageResolver, addProtocol for PMTiles, or debugging v6 ESM-only import errors, 'WebGL2 is required', blank maps after setStyle and style-spec expression warnings. MapLibre GL JS is the BSD-3-Clause fork of Mapbox GL JS and needs no access token."
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
category: gis
|
|
7
|
+
tags: "javascript, web, map, vector-tiles, webgl, style-spec, expressions, pmtiles, terrain, open-source"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
> **项目地址:** <https://github.com/maplibre/maplibre-gl-js>
|
|
11
|
+
>
|
|
12
|
+
> **官方文档:** <https://maplibre.org/maplibre-gl-js/docs/>
|
|
13
|
+
>
|
|
14
|
+
> **API 参考:** <https://maplibre.org/maplibre-gl-js/docs/API/>
|
|
15
|
+
>
|
|
16
|
+
> **样式规范:** <https://maplibre.org/maplibre-style-spec/>
|
|
17
|
+
>
|
|
18
|
+
> **最新版本:** 6.17.0(截至 2026-11,[npm `maplibre-gl`](https://registry.npmjs.org/maplibre-gl/latest) dist-tag `latest`;[GitHub Releases](https://github.com/maplibre/maplibre-gl-js/releases) 同步)
|
|
19
|
+
>
|
|
20
|
+
> **许可证:** BSD-3-Clause(v6 起的发行物为 ESM-only,UMD 构建已移除)
|
|
21
|
+
|
|
22
|
+
## 概述
|
|
23
|
+
|
|
24
|
+
MapLibre GL JS 是基于 WebGL2 的矢量瓦片地图渲染库,源自 Mapbox GL JS v1 的 BSD 分支,现由 MapLibre 社区独立维护。样式由 Style Spec JSON 驱动,客户端按需请求矢量瓦片、字体与精灵图,再用 GPU 逐帧绘制,因此缩放平滑、样式可运行时改动,且不需要任何商业 token。
|
|
25
|
+
|
|
26
|
+
- **矢量瓦片渲染**:MVT 瓦片 + 客户端样式,任意缩放级别清晰;同时支持栅格瓦片与 GeoJSON 源
|
|
27
|
+
- **Style Spec 样式规范**:sources / layers / expressions 全部 JSON 化,可版本化、可服务端下发
|
|
28
|
+
- **数据驱动样式**:表达式按要素属性、`zoom`、`feature-state` 动态计算颜色、宽度、透明度
|
|
29
|
+
- **三维能力**:`raster-dem` 地形源 + `setTerrain`,配 `setSky` 做天空与大气;globe 投影可直接切换
|
|
30
|
+
- **可扩展协议**:`addProtocol` 注册自定义加载器,PMTiles、COG 等单文件瓦片方案由此接入
|
|
31
|
+
- **开源免 token**:底图可用公共 demotiles、自建 tile server 或 PMTiles,不受 Mapbox 配额与 TOS 约束
|
|
32
|
+
|
|
33
|
+
与相邻技术的差异:Mapbox GL JS 是同一血统的闭源商业版本(v2 起专有许可、必须 token);OpenLayers 偏全能型二维 GIS(投影、WMS/WMTS 更强);deck.gl 负责大规模数据图层,通常叠在 MapLibre 底图之上。
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 环境准备
|
|
38
|
+
|
|
39
|
+
### npm 安装
|
|
40
|
+
|
|
41
|
+
v6 是 **ESM-only** 发行方式,包内只有 `dist/maplibre-gl.mjs`,不再提供 `maplibre-gl.js` 这类 UMD 文件:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npm install maplibre-gl
|
|
45
|
+
npm ls maplibre-gl # 验证:应显示 maplibre-gl@6.17.0
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
```javascript
|
|
49
|
+
// v6:用命名空间导入或具名导入,没有 default export
|
|
50
|
+
import * as maplibregl from 'maplibre-gl';
|
|
51
|
+
import 'maplibre-gl/dist/maplibre-gl.css';
|
|
52
|
+
|
|
53
|
+
const map = new maplibregl.Map({
|
|
54
|
+
container: 'map',
|
|
55
|
+
style: 'https://demotiles.maplibre.org/style.json',
|
|
56
|
+
center: [116.39, 39.91],
|
|
57
|
+
zoom: 4
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
```html
|
|
62
|
+
<!-- 容器必须有显式高度,否则地图不可见 -->
|
|
63
|
+
<style>#map { height: 500px; }</style>
|
|
64
|
+
<div id="map"></div>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### CDN(无构建步骤)
|
|
68
|
+
|
|
69
|
+
由于 UMD 已移除,CDN 场景也必须走 ES module:
|
|
70
|
+
|
|
71
|
+
```html
|
|
72
|
+
<link href="https://cdn.jsdelivr.net/npm/maplibre-gl@6.17.0/dist/maplibre-gl.css" rel="stylesheet">
|
|
73
|
+
<script type="module">
|
|
74
|
+
import * as maplibregl from 'https://cdn.jsdelivr.net/npm/maplibre-gl@6.17.0/dist/maplibre-gl.mjs';
|
|
75
|
+
const map = new maplibregl.Map({
|
|
76
|
+
container: 'map',
|
|
77
|
+
style: 'https://demotiles.maplibre.org/style.json',
|
|
78
|
+
center: [0, 20],
|
|
79
|
+
zoom: 1
|
|
80
|
+
});
|
|
81
|
+
window.__map = map; // 便于控制台调试
|
|
82
|
+
</script>
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### 验证
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
# 包与入口存在性(v6 只有 .mjs,查 .js 得到 404 是正常的)
|
|
89
|
+
npm ls maplibre-gl
|
|
90
|
+
curl -s -o /dev/null -w '%{http_code}\n' https://cdn.jsdelivr.net/npm/maplibre-gl@6.17.0/dist/maplibre-gl.mjs
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
页面能显示 demotiles 世界地图、拖拽缩放正常,即环境就绪。浏览器控制台出现 `WebGL2 is required` 说明运行环境不支持 WebGL2,换浏览器或开启硬件加速。
|
|
94
|
+
|
|
95
|
+
### v5 升 v6 的破坏性变更
|
|
96
|
+
|
|
97
|
+
| 变更 | 影响与改法 |
|
|
98
|
+
|------|-----------|
|
|
99
|
+
| ESM-only,UMD 构建移除 | `<script src=".../maplibre-gl.js">` 改为 `<script type="module">`;`import maplibregl from 'maplibre-gl'` 改为 `import * as maplibregl from 'maplibre-gl'` 或具名导入 |
|
|
100
|
+
| 只支持 WebGL2 | WebGL1 路径删除;失败信息可通过 `map.on('error')` 捕获 |
|
|
101
|
+
| `Map` 改为组合 `Camera` 而非继承 | 相机 API 仍由 Map 转发;内部 `map.transform` 已移除,不要再访问 |
|
|
102
|
+
| `styleimagemissing` 变为只通知 | 不能再在该事件里同步补图,改用 `map.setMissingStyleImageResolver(fn)`(支持 async) |
|
|
103
|
+
| `GeoJSONSource#setData` 去掉第二个参数与返回值 | `setData(data)` 只传数据,不要再用 `waitForCompletion` |
|
|
104
|
+
| Style Spec 升到 v25 | 遗留表达式写法会以 warning 级错误抛出,需按新版表达式改写 |
|
|
105
|
+
| 事件改为真实类,`MapDataEvent` 移除 | 源码数据事件是 `MapSourceDataEvent` 或 `MapStyleDataEvent`;`MapLibreZoomEvent` 更名 `MapBoxZoomEvent` |
|
|
106
|
+
| 着色器指令 `#pragma mapbox` 改为 `#pragma maplibre` | 自定义图层若依赖该指令需同步改 |
|
|
107
|
+
| `zoomLevelsToOverscale` 默认改为 4 | 高缩放密集标注更自然,但 `queryRenderedFeatures` 结果可能变化;要还原设为 `undefined` |
|
|
108
|
+
| TypeScript 目标升到 ES2022 | 需要转译 MapLibre 或升级构建链的旧工程会报语法错误 |
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## 核心 API
|
|
113
|
+
|
|
114
|
+
### Map 与生命周期
|
|
115
|
+
|
|
116
|
+
```javascript
|
|
117
|
+
import * as maplibregl from 'maplibre-gl';
|
|
118
|
+
import 'maplibre-gl/dist/maplibre-gl.css';
|
|
119
|
+
|
|
120
|
+
const map = new maplibregl.Map({
|
|
121
|
+
container: 'map',
|
|
122
|
+
style: 'https://demotiles.maplibre.org/style.json',
|
|
123
|
+
center: [116.39, 39.91],
|
|
124
|
+
zoom: 5,
|
|
125
|
+
pitch: 0,
|
|
126
|
+
bearing: 0,
|
|
127
|
+
minZoom: 0,
|
|
128
|
+
maxZoom: 18,
|
|
129
|
+
attributionControl: { compact: true },
|
|
130
|
+
hash: true // 把视图同步到 URL #zoom/lat/lng
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
map.on('load', () => { /* 样式与初始瓦片就绪后再加图层 */ });
|
|
134
|
+
map.on('error', (e) => console.error(e.error));
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
| 阶段 | 判断方式 | 可做什么 |
|
|
138
|
+
|------|---------|---------|
|
|
139
|
+
| 构造完成 | `new Map()` 返回 | 绑定事件、加控件 |
|
|
140
|
+
| 样式就绪 | `map.isStyleLoaded()` / `load` / `style.load` | `addSource` / `addLayer` |
|
|
141
|
+
| 瓦片渲染完 | `map.areTilesLoaded()` / `idle` | 截图、批量查询 |
|
|
142
|
+
| 销毁 | `map.remove()` | 释放 WebGL 上下文与 Worker |
|
|
143
|
+
|
|
144
|
+
### 数据源 Source
|
|
145
|
+
|
|
146
|
+
| `type` | 用途 | 关键字段 |
|
|
147
|
+
|--------|------|---------|
|
|
148
|
+
| `geojson` | 要素集合,可运行时 `setData` | `data`、`cluster`、`generateId` |
|
|
149
|
+
| `vector` | MVT 矢量瓦片 | `tiles` / `url`、`minzoom`、`maxzoom` |
|
|
150
|
+
| `raster` | 栅格瓦片底图 | `tiles`、`tileSize`、`attribution` |
|
|
151
|
+
| `raster-dem` | 地形高程(Terrarium/Mapbox DEM) | `encoding`、`tileSize` |
|
|
152
|
+
| `image` | 单张地理配准图片 | `url`、`coordinates` |
|
|
153
|
+
|
|
154
|
+
```javascript
|
|
155
|
+
map.addSource('pois', { type: 'geojson', data: '/data/poi.geojson' });
|
|
156
|
+
map.addSource('dem', {
|
|
157
|
+
type: 'raster-dem',
|
|
158
|
+
url: 'https://demotiles.maplibre.org/terrain-tiles/tiles.json',
|
|
159
|
+
tileSize: 256
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
const src = map.getSource('pois');
|
|
163
|
+
src.setData(newGeoJson); // v6:只传数据,无第二参数
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### 图层 Layer
|
|
167
|
+
|
|
168
|
+
图层按 `type` 分类,通过 `filter`、`paint`、`layout` 控制外观。绘制顺序即数组顺序,后加的在上。
|
|
169
|
+
|
|
170
|
+
```javascript
|
|
171
|
+
map.addLayer({
|
|
172
|
+
id: 'pois-circle',
|
|
173
|
+
type: 'circle',
|
|
174
|
+
source: 'pois',
|
|
175
|
+
filter: ['==', ['get', 'kind'], 'station'],
|
|
176
|
+
paint: {
|
|
177
|
+
'circle-radius': ['interpolate', ['linear'], ['zoom'], 6, 3, 14, 12],
|
|
178
|
+
'circle-color': ['match', ['get', 'level'], 'high', '#d7301f', 'mid', '#fc8d59', '#fee08b'],
|
|
179
|
+
'circle-stroke-width': 1,
|
|
180
|
+
'circle-stroke-color': '#ffffff'
|
|
181
|
+
}
|
|
182
|
+
});
|
|
183
|
+
|
|
184
|
+
map.addLayer({
|
|
185
|
+
id: 'pois-label',
|
|
186
|
+
type: 'symbol',
|
|
187
|
+
source: 'pois',
|
|
188
|
+
layout: {
|
|
189
|
+
'text-field': ['get', 'name'],
|
|
190
|
+
'text-size': 12,
|
|
191
|
+
'text-offset': [0, 1.2]
|
|
192
|
+
},
|
|
193
|
+
paint: { 'text-halo-color': '#fff', 'text-halo-width': 1 }
|
|
194
|
+
});
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
常用图层类型:`background`、`fill`、`line`、`symbol`、`circle`、`heatmap`、`fill-extrusion`(3D 建筑)、`raster`、`hillshade`、`clip`。
|
|
198
|
+
|
|
199
|
+
### 表达式与数据驱动样式
|
|
200
|
+
|
|
201
|
+
表达式是 JSON 数组,第一个元素是操作符。它是 Style Spec 的核心,替换了早期的 `stops` 写法。
|
|
202
|
+
|
|
203
|
+
```javascript
|
|
204
|
+
// 缩放插值
|
|
205
|
+
['interpolate', ['linear'], ['zoom'], 4, 1, 10, 6]
|
|
206
|
+
|
|
207
|
+
// 属性分支
|
|
208
|
+
['case', ['>', ['get', 'pop'], 1000000], '#800026', '#feb24c']
|
|
209
|
+
|
|
210
|
+
// 算术与颜色
|
|
211
|
+
map.setPaintProperty('buildings', 'fill-extrusion-height',
|
|
212
|
+
['*', ['coalesce', ['get', 'height'], 10], 1.0]);
|
|
213
|
+
|
|
214
|
+
// feature-state 联动(悬停高亮)
|
|
215
|
+
map.setPaintProperty('pois-circle', 'circle-opacity',
|
|
216
|
+
['case', ['boolean', ['feature-state', 'hover'], false], 1, 0.5]);
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### 控件、Marker 与 Popup
|
|
220
|
+
|
|
221
|
+
```javascript
|
|
222
|
+
map.addControl(new maplibregl.NavigationControl({ visualizePitch: true }), 'top-right');
|
|
223
|
+
map.addControl(new maplibregl.ScaleControl({ unit: 'metric' }), 'bottom-left');
|
|
224
|
+
map.addControl(new maplibregl.GeolocateControl({ trackUserLocation: true }));
|
|
225
|
+
map.addControl(new maplibregl.FullscreenControl());
|
|
226
|
+
|
|
227
|
+
const marker = new maplibregl.Marker({ color: '#d7301f' })
|
|
228
|
+
.setLngLat([116.39, 39.91])
|
|
229
|
+
.setPopup(new maplibregl.Popup().setHTML('<b>北京</b>'))
|
|
230
|
+
.addTo(map);
|
|
231
|
+
|
|
232
|
+
marker.togglePopup();
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### 三维地形与天空
|
|
236
|
+
|
|
237
|
+
```javascript
|
|
238
|
+
map.addSource('dem', {
|
|
239
|
+
type: 'raster-dem',
|
|
240
|
+
url: 'https://demotiles.maplibre.org/terrain-tiles/tiles.json',
|
|
241
|
+
tileSize: 256
|
|
242
|
+
});
|
|
243
|
+
map.setTerrain({ source: 'dem', exaggeration: 1.5 });
|
|
244
|
+
map.setSky({
|
|
245
|
+
'sky-color': '#88c6fc',
|
|
246
|
+
'horizon-color': '#ffffff',
|
|
247
|
+
'fog-color': '#ffffff',
|
|
248
|
+
'sky-horizon-blend': 0.5
|
|
249
|
+
});
|
|
250
|
+
|
|
251
|
+
// 三维建筑
|
|
252
|
+
map.addLayer({
|
|
253
|
+
id: 'buildings-3d',
|
|
254
|
+
type: 'fill-extrusion',
|
|
255
|
+
source: 'buildings',
|
|
256
|
+
paint: {
|
|
257
|
+
'fill-extrusion-height': ['get', 'height'],
|
|
258
|
+
'fill-extrusion-base': ['get', 'min_height'],
|
|
259
|
+
'fill-extrusion-color': '#a0a0a0',
|
|
260
|
+
'fill-extrusion-opacity': 0.85
|
|
261
|
+
}
|
|
262
|
+
});
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### 投影切换(含 globe)
|
|
266
|
+
|
|
267
|
+
样式里写 `projection` 即可切换,无需插件:
|
|
268
|
+
|
|
269
|
+
```javascript
|
|
270
|
+
map.setProjection({ type: 'globe' });
|
|
271
|
+
map.setProjection({ type: 'mercator' });
|
|
272
|
+
|
|
273
|
+
// 实验能力:注册自定义 CRS 平面投影(6.15 起)
|
|
274
|
+
maplibregl.addProjection({
|
|
275
|
+
name: 'EPSG:2193',
|
|
276
|
+
projection: /* proj4 转换函数 */ customProjection
|
|
277
|
+
});
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
自定义 CRS 属于实验 API,生产环境优先用 Mercator 或 globe。
|
|
281
|
+
|
|
282
|
+
### 自定义协议与 PMTiles
|
|
283
|
+
|
|
284
|
+
`addProtocol` 让 `sources` 里的伪协议 URL 由自定义函数加载,PMTiles 就靠它把单文件瓦片包当作任意 z/x/y 请求的源:
|
|
285
|
+
|
|
286
|
+
```javascript
|
|
287
|
+
import { Protocol } from 'pmtiles';
|
|
288
|
+
|
|
289
|
+
const protocol = new Protocol();
|
|
290
|
+
maplibregl.addProtocol('pmtiles', protocol.tile);
|
|
291
|
+
|
|
292
|
+
map.addSource('basemap', {
|
|
293
|
+
type: 'vector',
|
|
294
|
+
url: 'pmtiles://https://example.com/tiles.pmtiles',
|
|
295
|
+
attribution: 'PMTiles'
|
|
296
|
+
});
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
同理可接入 COG 栅格源。协议注册是全局的,同一页面多个 Map 共享;不再使用时 `maplibregl.removeProtocol('pmtiles')`。
|
|
300
|
+
|
|
301
|
+
### 交互查询与要素状态
|
|
302
|
+
|
|
303
|
+
```javascript
|
|
304
|
+
map.on('click', 'pois-circle', (e) => {
|
|
305
|
+
const feature = e.features[0];
|
|
306
|
+
new maplibregl.Popup()
|
|
307
|
+
.setLngLat(e.lngLat)
|
|
308
|
+
.setHTML(`<b>${feature.properties.name}</b>`)
|
|
309
|
+
.addTo(map);
|
|
310
|
+
});
|
|
311
|
+
|
|
312
|
+
map.on('mousemove', 'pois-circle', (e) => {
|
|
313
|
+
map.getCanvas().style.cursor = 'pointer';
|
|
314
|
+
if (e.features.length) {
|
|
315
|
+
map.setFeatureState(
|
|
316
|
+
{ source: 'pois', id: e.features[0].id },
|
|
317
|
+
{ hover: true }
|
|
318
|
+
);
|
|
319
|
+
}
|
|
320
|
+
});
|
|
321
|
+
|
|
322
|
+
// 屏幕坐标查要素
|
|
323
|
+
const hits = map.queryRenderedFeatures({ layers: ['pois-circle'] });
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
## 典型工作流
|
|
329
|
+
|
|
330
|
+
### 链路一:自建矢量瓦片 + 属性联动样式
|
|
331
|
+
|
|
332
|
+
输入:tile server 上的 `{z}/{x}/{y}.mvt` 与属性字段 `level`;输出:按等级着色的可点击地图。
|
|
333
|
+
|
|
334
|
+
1. 加载空样式骨架:`new maplibregl.Map({ style: { version: 8, sources: {}, layers: [] } })`
|
|
335
|
+
2. `map.addSource('base', { type: 'vector', tiles: ['https://tiles.example.com/{z}/{x}/{y}.mvt'], minzoom: 0, maxzoom: 14 })`
|
|
336
|
+
3. 用 `source-layer` 指定 MVT 内的图层名,加 `fill` + `line` 两个图层
|
|
337
|
+
4. 用 `match` 表达式按 `level` 着色,用 `filter` 拆不同业务图层
|
|
338
|
+
5. 绑定 `click` / `mousemove` 事件,配合 `setFeatureState` 做悬停高亮
|
|
339
|
+
6. 校验:缩放各级别瓦片正常、控制台无 404、`map.areTilesLoaded()` 为 true
|
|
340
|
+
|
|
341
|
+
```javascript
|
|
342
|
+
map.addSource('base', {
|
|
343
|
+
type: 'vector',
|
|
344
|
+
tiles: ['https://tiles.example.com/{z}/{x}/{y}.mvt'],
|
|
345
|
+
minzoom: 0,
|
|
346
|
+
maxzoom: 14
|
|
347
|
+
});
|
|
348
|
+
|
|
349
|
+
map.addLayer({
|
|
350
|
+
id: 'parcel-fill',
|
|
351
|
+
type: 'fill',
|
|
352
|
+
source: 'base',
|
|
353
|
+
'source-layer': 'parcel',
|
|
354
|
+
paint: {
|
|
355
|
+
'fill-color': ['match', ['get', 'level'], 'A', '#2b8cbe', 'B', '#a6bddb', '#ece7f2'],
|
|
356
|
+
'fill-opacity': 0.75
|
|
357
|
+
}
|
|
358
|
+
});
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
### 链路二:GeoJSON 热力 + 地形 + 点击详情
|
|
362
|
+
|
|
363
|
+
输入:`/data/events.geojson`;输出:带地形与热力的分析视图。
|
|
364
|
+
|
|
365
|
+
1. 加 `raster-dem` 源并 `setTerrain`,再做 `setSky` 补天空
|
|
366
|
+
2. 加载 GeoJSON 源,加 `heatmap` 图层(`heatmap-weight` 用属性字段)
|
|
367
|
+
3. 叠加 `circle` 图层用于精确点击,`filter` 限定可点要素
|
|
368
|
+
4. `click` 回调里用 `Popup` 展示属性,`closeOnClick` 默认 true
|
|
369
|
+
5. 校验:地形起伏可见、热力随缩放变化、点击有弹窗
|
|
370
|
+
|
|
371
|
+
```javascript
|
|
372
|
+
map.addSource('events', { type: 'geojson', data: '/data/events.geojson' });
|
|
373
|
+
|
|
374
|
+
map.addLayer({
|
|
375
|
+
id: 'events-heat',
|
|
376
|
+
type: 'heatmap',
|
|
377
|
+
source: 'events',
|
|
378
|
+
paint: {
|
|
379
|
+
'heatmap-weight': ['get', 'count'],
|
|
380
|
+
'heatmap-radius': ['interpolate', ['linear'], ['zoom'], 5, 8, 13, 40],
|
|
381
|
+
'heatmap-opacity': 0.7
|
|
382
|
+
}
|
|
383
|
+
});
|
|
384
|
+
|
|
385
|
+
map.addLayer({
|
|
386
|
+
id: 'events-point',
|
|
387
|
+
type: 'circle',
|
|
388
|
+
source: 'events',
|
|
389
|
+
paint: { 'circle-radius': 3, 'circle-color': '#ffffff', 'circle-opacity': 0 }
|
|
390
|
+
});
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
### 链路三:样式热切换与图片按需补全
|
|
394
|
+
|
|
395
|
+
输入:用户切换主题;输出:不重建地图、仅替换样式,且缺失图标自动补。
|
|
396
|
+
|
|
397
|
+
1. 用 `map.setStyle(nextStyle)` 整体换样式,不要销毁重建 Map
|
|
398
|
+
2. 用 `transformStyle` 在构造或 `setStyle` 时注入通用改动(如统一字体、加业务图层)
|
|
399
|
+
3. 缺失图标不再靠 `styleimagemissing` 补,改用 `setMissingStyleImageResolver` 异步取图
|
|
400
|
+
4. 监听 `style.load` 后再补加自定义图层与数据源
|
|
401
|
+
5. 校验:切换后业务图层仍在、图标不缺、无重复图层报错
|
|
402
|
+
|
|
403
|
+
```javascript
|
|
404
|
+
map.setMissingStyleImageResolver(async (id) => {
|
|
405
|
+
const response = await fetch(`/icons/${id}.png`);
|
|
406
|
+
if (!response.ok) return;
|
|
407
|
+
const image = await createImageBitmap(await response.blob());
|
|
408
|
+
map.addImage(id, image, { pixelRatio: 2 });
|
|
409
|
+
});
|
|
410
|
+
|
|
411
|
+
map.on('style.load', () => {
|
|
412
|
+
map.addSource('pois', { type: 'geojson', data: geojson });
|
|
413
|
+
map.addLayer({ id: 'pois', type: 'circle', source: 'pois' });
|
|
414
|
+
});
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
---
|
|
418
|
+
|
|
419
|
+
## 性能优化与最佳实践
|
|
420
|
+
|
|
421
|
+
1. **GeoJSON 源走瓦片化**:超过约 10 万要素改用 `vector` 源或服务端切片,GeoJSON 源在浏览器内做 `geojson-vt` 索引会占用主线程
|
|
422
|
+
2. **保持数据引用稳定**:`setData` 传新对象才触发重绘,但要避免每帧调用,节流到重绘帧率
|
|
423
|
+
3. **用 `feature-state` 而非改 paint**:悬停/选中用 feature-state,避免整层 `setPaintProperty` 造成全量重绘
|
|
424
|
+
4. **控制同时可见图层数**:图层越多每帧绘制开销越大,非当前视野的图层用 `layout.visibility = 'none'`
|
|
425
|
+
5. **合理设 `maxzoom`**:源声明真实 `maxzoom`,让客户端复用父级瓦片过度缩放,而不是请求不存在的瓦片
|
|
426
|
+
6. **关闭不必要的开销**:`canvasContextAttributes` 里默认 `antialias: false`、`preserveDrawingBuffer: false`,只有截图需求才开
|
|
427
|
+
7. **预初始化 Worker**:多地图页面可用 `prewarm()` 提前创建共享 Worker(需在 `setWorkerUrl()` 之后调用)
|
|
428
|
+
8. **及时销毁**:`map.remove()` 释放上下文;SPA 路由切换务必调用,否则 WebGL 上下文会累积到浏览器上限
|
|
429
|
+
|
|
430
|
+
---
|
|
431
|
+
|
|
432
|
+
## 常见问题
|
|
433
|
+
|
|
434
|
+
| 问题 | 原因 | 处置 |
|
|
435
|
+
|------|------|------|
|
|
436
|
+
| 报 `WebGL2 is required` 或地图不渲染 | v6 移除了 WebGL1 支持,运行环境(无头浏览器、远程桌面软件渲染、旧驱动)没有 WebGL2 | 开启浏览器硬件加速;无头环境改用带 GPU 的容器或接受无法渲染;用 `map.on('error')` 捕获具体原因 |
|
|
437
|
+
| `import maplibregl from 'maplibre-gl'` 后 `new maplibregl.Map` 报 undefined | v6 无 default export(ESM-only 改造的一部分) | 改为 `import * as maplibregl from 'maplibre-gl'` 或 `import { Map } from 'maplibre-gl'` |
|
|
438
|
+
| 引入 CDN 后报 `Unexpected token 'export'` | v6 不再发布 UMD,旧的 `<script src>` 方式加载了 ESM 文件 | 改用 `<script type="module">`,并直接从 CDN 导入 `.mjs` |
|
|
439
|
+
| 地图空白但无报错 | 容器没有高度,或 `addLayer` 早于样式就绪 | 给容器设显式高度;在 `load` 或 `isStyleLoaded()` 之后再 `addSource`/`addLayer` |
|
|
440
|
+
| 升级后控制台出现表达式 warning | Style Spec v25 把遗留表达式从静默失败改为 warning 级错误 | 按新版表达式重写;确认自定义样式里没有旧 `stops` 残留写法 |
|
|
441
|
+
| `styleimagemissing` 里补图不生效 | v6 起该事件只通知,不再允许同步提供图片 | 改用 `map.setMissingStyleImageResolver(async (id) => { ... })` |
|
|
442
|
+
| `setData(data, true)` 行为异常 | v6 移除了第二参数与返回值 | 只调用 `setData(data)`;需要等渲染用 `idle` 事件 |
|
|
443
|
+
| 自定义图层 shader 编译失败 | v6 把 `#pragma mapbox` 改为 `#pragma maplibre` | 同步修改自定义图层的着色器指令 |
|
|
444
|
+
| 截图空白 | `preserveDrawingBuffer` 默认 false,WebGL 缓冲在呈现后丢弃 | 构造时设 `canvasContextAttributes: { preserveDrawingBuffer: true }`,或改用 `map.triggerRepaint()` 后立即抓取 |
|
|
445
|
+
| 切换路由后地图越来越多内存 | 未调用 `map.remove()`,WebGL 上下文不断累积 | 组件卸载时 `map.remove()`,并移除 `addProtocol` 注册的全局协议 |
|
|
446
|
+
|
|
447
|
+
---
|
|
448
|
+
|
|
449
|
+
## AI 使用建议
|
|
450
|
+
|
|
451
|
+
- **执行环境**:`npm install`、`npm run build` 在终端执行;Windows 下 npm 实际是 `npm.cmd`,脚本里写 `cmd /c npm run build` 更稳;装包与大构建放后台,输出重定向到文件再分段读。
|
|
452
|
+
- **先探测版本**:`npm ls maplibre-gl`(未安装时 `npm view maplibre-gl version`),本技能按 6.17.0 编写。遇到 `new maplibregl.Map is not a constructor` 先怀疑是否还在用 v5 的 default import 写法。
|
|
453
|
+
- **验证产物**:`npm run build` 后 `npx serve dist`,用 `curl -s -o /dev/null -w '%{http_code}'` 检查入口与 `maplibre-gl.css` 返回 200;WebGL 是否真出图只能由浏览器确认,AI 助手通常看不到画面,请用户看画面与控制台,环境支持读图时用截图核对。
|
|
454
|
+
- **无 GPU 环境**:无头/CI 无法验证 WebGL2,构建通过不等于渲染正确,不要据此报告"已渲染"。
|
|
455
|
+
- **坐标顺序**:所有经纬度都是 `[lng, lat]`(经度在前),与 Leaflet 相反;`LngLatBounds` 用 `[[west, south], [east, north]]`。
|
|
456
|
+
- **样式调试顺序**:先确认 `style` 可访问(404 会导致整图空白且只有 error 事件),再确认 `source-layer` 与 MVT 内的图层名一致,最后才怀疑表达式。
|
|
457
|
+
- **常见症状**:空白图先查容器高度与样式 URL;瓦片 404 查 `minzoom/maxzoom` 与 tile URL 模板;点击无反应查图层 `id` 是否与事件绑定的一致。
|
|
458
|
+
- **安全与权限**:装包、起 dev server、改端口前先征得用户同意;`addProtocol` 与第三方瓦片 URL 要确认来源可信,避免把内网地址写进样式。
|
|
459
|
+
|
|
460
|
+
## 相关技能
|
|
461
|
+
|
|
462
|
+
- **mapbox-gl-js** — 同源商业版本,API 高度相似,迁移时对照:[../mapbox-gl-js/SKILL.md](../mapbox-gl-js/SKILL.md)
|
|
463
|
+
- **maplibre-native** — 同一体系的 C++ 原生渲染引擎(Android/iOS/Node):[../maplibre-native/SKILL.md](../maplibre-native/SKILL.md)
|
|
464
|
+
- **openlayers** — 全能型二维 WebGIS,WMS/WMTS 与投影能力更强:[../openlayers/SKILL.md](../openlayers/SKILL.md)
|
|
465
|
+
- **deck-gl** — 大规模数据图层,常叠加在 MapLibre 底图之上:[../deck-gl/SKILL.md](../deck-gl/SKILL.md)
|
|
466
|
+
- **leaflet** — 更轻量的二维瓦片地图方案:[../leaflet/SKILL.md](../leaflet/SKILL.md)
|
|
467
|
+
- **stac-cog-titiler** — 为地图提供动态影像瓦片的后端链路:[../stac-cog-titiler/SKILL.md](../stac-cog-titiler/SKILL.md)
|
|
468
|
+
|
|
469
|
+
## 参考资源
|
|
470
|
+
|
|
471
|
+
- 官方文档:<https://maplibre.org/maplibre-gl-js/docs/>
|
|
472
|
+
- API 参考:<https://maplibre.org/maplibre-gl-js/docs/API/>
|
|
473
|
+
- 样式规范:<https://maplibre.org/maplibre-style-spec/>
|
|
474
|
+
- 示例集:<https://maplibre.org/maplibre-gl-js/docs/examples/>
|
|
475
|
+
- v5 到 v6 迁移指南:<https://github.com/maplibre/maplibre-gl-js/blob/main/docs/guides/v5-to-v6-migration-guide.md>
|
|
476
|
+
- 发布记录:<https://github.com/maplibre/maplibre-gl-js/releases>
|
|
477
|
+
- 演示样式(demotiles):<https://demotiles.maplibre.org/style.json>
|
|
478
|
+
- 中文教程:<https://znlgis.github.io/gis/tutorial/maplibre-gl-js/>
|