@dsh-gis/dsh-opengis-skill 0.1.3 → 0.3.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.
Files changed (117) hide show
  1. package/CHANGELOG.md +95 -0
  2. package/README.md +68 -28
  3. package/THIRD_PARTY_NOTICES.md +9 -0
  4. package/adaptations/brutile.md +8 -0
  5. package/adaptations/cesiumjs.md +8 -0
  6. package/adaptations/common.md +19 -0
  7. package/adaptations/deck-gl.md +8 -0
  8. package/adaptations/duckdb-spatial.md +8 -0
  9. package/adaptations/gdal-api.md +8 -0
  10. package/adaptations/gdal.md +8 -0
  11. package/adaptations/geolibre.md +8 -0
  12. package/adaptations/geometry-api-java.md +8 -0
  13. package/adaptations/geometry-api-net.md +8 -0
  14. package/adaptations/geonode.md +8 -0
  15. package/adaptations/geopandas.md +8 -0
  16. package/adaptations/geopipe-agent.md +8 -0
  17. package/adaptations/geoserver-cloud.md +8 -0
  18. package/adaptations/geoserver-rest-api.md +8 -0
  19. package/adaptations/geoserver.md +8 -0
  20. package/adaptations/geotools.md +8 -0
  21. package/adaptations/grass-gis.md +8 -0
  22. package/adaptations/jts.md +8 -0
  23. package/adaptations/kepler-gl.md +8 -0
  24. package/adaptations/leaflet.md +8 -0
  25. package/adaptations/mapbox-gl-js.md +8 -0
  26. package/adaptations/mapserver.md +8 -0
  27. package/adaptations/mapsui.md +8 -0
  28. package/adaptations/nettopologysuite.md +8 -0
  29. package/adaptations/opengis-all.md +9 -0
  30. package/adaptations/opengis-daf.md +9 -0
  31. package/adaptations/opengis-utils-for-java.md +8 -0
  32. package/adaptations/opengis-utils-for-net.md +8 -0
  33. package/adaptations/openlayers.md +8 -0
  34. package/adaptations/pdal.md +8 -0
  35. package/adaptations/postgis.md +8 -0
  36. package/adaptations/proj.md +8 -0
  37. package/adaptations/projnet4geoapi.md +8 -0
  38. package/adaptations/pyqgis.md +8 -0
  39. package/adaptations/qgis-process.md +8 -0
  40. package/adaptations/qgis-server.md +8 -0
  41. package/adaptations/shapely.md +8 -0
  42. package/adaptations/sharpmap.md +8 -0
  43. package/adaptations/spatialite.md +8 -0
  44. package/adaptations/whitebox-tools.md +8 -0
  45. package/assets/brutile/SKILL.md +283 -0
  46. package/assets/cesiumjs/SKILL.md +81 -35
  47. package/assets/deck-gl/SKILL.md +26 -34
  48. package/assets/duckdb-spatial/SKILL.md +363 -0
  49. package/assets/gdal/SKILL.md +55 -33
  50. package/assets/gdal/reference/raster-tools.md +14 -0
  51. package/assets/gdal/reference/vector-tools.md +5 -0
  52. package/assets/gdal-api/SKILL.md +12 -18
  53. package/assets/gdal-api/reference/raster-api.md +7 -0
  54. package/assets/gdal-api/reference/vector-api.md +9 -0
  55. package/assets/geolibre/SKILL.md +357 -0
  56. package/assets/geometry-api-java/SKILL.md +10 -16
  57. package/assets/geometry-api-net/SKILL.md +70 -32
  58. package/assets/geometry-api-net/reference/geometry-types.md +5 -0
  59. package/assets/geonode/SKILL.md +340 -0
  60. package/assets/geopandas/SKILL.md +21 -24
  61. package/assets/geopandas/reference/core-api.md +4 -0
  62. package/assets/geopipe-agent/SKILL.md +29 -31
  63. package/assets/geopipe-agent/reference/steps-reference.md +12 -0
  64. package/assets/geopipe-agent/reference/workflows.md +8 -0
  65. package/assets/geoserver/SKILL.md +10 -15
  66. package/assets/geoserver-cloud/SKILL.md +25 -33
  67. package/assets/geoserver-rest-api/SKILL.md +17 -19
  68. package/assets/geoserver-rest-api/reference/endpoints.md +16 -0
  69. package/assets/geotools/SKILL.md +12 -17
  70. package/assets/geotools/reference/raster-rendering.md +5 -0
  71. package/assets/geotools/reference/vector-io.md +7 -0
  72. package/assets/grass-gis/SKILL.md +26 -33
  73. package/assets/jts/SKILL.md +12 -16
  74. package/assets/jts/reference/geometry-operations.md +13 -0
  75. package/assets/kepler-gl/SKILL.md +306 -0
  76. package/assets/leaflet/SKILL.md +58 -40
  77. package/assets/mapbox-gl-js/SKILL.md +26 -33
  78. package/assets/mapserver/SKILL.md +21 -29
  79. package/assets/mapsui/SKILL.md +109 -63
  80. package/assets/nettopologysuite/SKILL.md +96 -31
  81. package/assets/opengis-all/SKILL.md +91 -289
  82. package/assets/opengis-all/reference/data-stages.md +269 -4
  83. package/assets/opengis-all/reference/workflow-cheatsheets.md +7 -0
  84. package/assets/opengis-daf/SKILL.md +10 -17
  85. package/assets/opengis-utils-for-java/SKILL.md +58 -49
  86. package/assets/opengis-utils-for-java/reference/common-tasks.md +16 -12
  87. package/assets/opengis-utils-for-net/SKILL.md +109 -48
  88. package/assets/opengis-utils-for-net/reference/code-patterns.md +15 -11
  89. package/assets/opengis-utils-for-net/reference/util-classes.md +35 -26
  90. package/assets/openlayers/SKILL.md +81 -28
  91. package/assets/pdal/SKILL.md +25 -27
  92. package/assets/postgis/SKILL.md +80 -35
  93. package/assets/proj/SKILL.md +32 -41
  94. package/assets/projnet4geoapi/SKILL.md +293 -0
  95. package/assets/pyqgis/SKILL.md +33 -30
  96. package/assets/pyqgis/reference/processing-rendering.md +6 -0
  97. package/assets/pyqgis/reference/vector-raster-layers.md +6 -0
  98. package/assets/qgis-process/SKILL.md +75 -33
  99. package/assets/qgis-process/reference/algorithm-cheatsheet.md +6 -0
  100. package/assets/qgis-server/SKILL.md +25 -31
  101. package/assets/shapely/SKILL.md +136 -84
  102. package/assets/shapely/reference/operations-reference.md +12 -0
  103. package/assets/sharpmap/SKILL.md +97 -60
  104. package/assets/spatialite/SKILL.md +358 -0
  105. package/assets/whitebox-tools/SKILL.md +262 -0
  106. package/lib/adaptations.d.ts +53 -0
  107. package/lib/adaptations.js +343 -0
  108. package/lib/catalog.d.ts +7 -1
  109. package/lib/catalog.js +9 -1
  110. package/lib/index.d.ts +10 -1
  111. package/lib/index.js +34 -3
  112. package/lib/skill-file.d.ts +12 -0
  113. package/lib/skill-file.js +133 -18
  114. package/locale/en.json +1 -1
  115. package/locale/zh.json +1 -1
  116. package/package.json +12 -2
  117. package/upstream.json +73 -57
@@ -0,0 +1,306 @@
1
+ ---
2
+ name: kepler-gl
3
+ description: "Use when building React/Redux web apps or Jupyter notebooks for large-scale geospatial visual exploration with Kepler.gl 3.3.0-alpha.20 — @kepler.gl/components KeplerGl, @kepler.gl/actions addDataToMap, @kepler.gl/processors processGeojson/processCsvData, and the Python keplergl widget. Also for fixing blank maps from a missing reducer or wrong getState (react-redux 'Could not find ... in the context of Connect(...)'), Mapbox token basemap errors, and oversized addDataToMap payloads."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "javascript, react, redux, webgl, geospatial, data-visualization, map-layers, jupyter, python, maplibre"
8
+ ---
9
+
10
+ > **项目地址:** <https://github.com/keplergl/kepler.gl>
11
+ >
12
+ > **官方文档:** <https://docs.kepler.gl/>
13
+ >
14
+ > **最新版本:** 3.3.0-alpha.20(2026-11-08,npm `kepler.gl` `latest` 标签与 [GitHub Release v3.3.0-alpha.20](https://github.com/keplergl/kepler.gl/releases) 一致;仍为 3.3 预发布线,4.0 尚无稳定版)
15
+ >
16
+ > **PyPI:** `keplergl` 0.4.0(Jupyter 小组件,版本节奏落后于前端,截至 2026-11)
17
+ >
18
+ > **许可证:** MIT
19
+
20
+ ## 概述
21
+
22
+ Kepler.gl 是 Uber 开源(现由社区维护)的地理数据可视化应用,同时也是可嵌入 React 应用的组件库。它把数据抽象成「字段 + 行」的表格模型,通过图层、过滤器、交互配置渲染基于 MapLibre GL 与 deck.gl 的地图,百万级点位可直接在浏览器中做过场动画与空间聚合。核心是一个 Redux 应用:组件、reducer、action、处理器相互解耦,业务方只需把数据整理成 Kepler.gl 的数据集结构即可。
23
+
24
+ - **数据无关**:CSV、GeoJSON、Pandas DataFrame、GeoPandas GeoDataFrame、Arrow 表统一转为 fields/rows
25
+ - **图层体系**:点、弧线、线、多边形、Hexbin、网格、热力、3D 建筑、H3、S2、瓦片(含 MVT)
26
+ - **交互能力**:过滤器(时间、范围、选择)、tooltip、图层可见性、时间轴动画、分屏对比
27
+ - **配置可序列化**:整张地图的 `mapState` / `visState` / `mapStyle` 可导出 JSON,再通过 `addDataToMap` 还原
28
+ - **双形态**:React 组件库(npm)与 Jupyter 小组件(PyPI),共享同一套数据与配置格式
29
+
30
+ ---
31
+
32
+ ## 环境准备
33
+
34
+ ### 前端(npm)
35
+
36
+ Kepler.gl 3.x 的 peer 依赖由主包 `kepler.gl` 声明:`react` / `react-dom` >= 18.2,`styled-components` ^6.1.0。默认底图使用 MapLibre 与 CARTO 样式,不需要 Mapbox token。
37
+
38
+ ```bash
39
+ # 方式一:整包(含 UMD、全部子包,适合 demo 与不开包优化的项目)
40
+ npm install kepler.gl
41
+
42
+ # 方式二:按需子包(生产项目推荐,体积更小)
43
+ npm install @kepler.gl/components @kepler.gl/actions @kepler.gl/reducers \
44
+ @kepler.gl/processors @kepler.gl/schemas @kepler.gl/styles
45
+
46
+ # 若使用 Mapbox 官方样式(非 CARTO/MapLibre 样式)
47
+ npm install mapbox-gl
48
+ ```
49
+
50
+ 子包版本必须与主包一致,Kepler.gl 各包之间存在内部耦合,混版会出现难以定位的运行时错误:
51
+
52
+ ```bash
53
+ npm ls kepler.gl @kepler.gl/components @kepler.gl/actions
54
+ python -c "import keplergl; print(keplergl.__version__)"
55
+ ```
56
+
57
+ ### 免打包(UMD)
58
+
59
+ ```html
60
+ <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@^4/dist/maplibre-gl.css" />
61
+ <script src="https://unpkg.com/kepler.gl/umd/keplergl.min.js"></script>
62
+ ```
63
+
64
+ UMD 构建的库名为 `KeplerGl`,AMD 加载时同样以 `KeplerGl` 注册;页面可直接通过全局变量获取组件与 action,适合无构建环境的演示页。
65
+
66
+ ### Python(Jupyter)
67
+
68
+ ```bash
69
+ pip install keplergl==0.4.0
70
+
71
+ # 或使用 conda(注意:conda-forge 当前仍停在 0.3.2,需要 0.4.0 请用 pip)
72
+ conda install -c conda-forge keplergl
73
+ ```
74
+
75
+ `keplergl` 0.4.0 要求 Python >= 3.9、JupyterLab >= 4.0 或 Notebook >= 7.0,依赖 `anywidget`、`geopandas`、`pyarrow`、`geoarrow-pandas`。验证:
76
+
77
+ ```python
78
+ import keplergl
79
+ from keplergl import KeplerGl
80
+
81
+ print(keplergl.__version__) # 0.4.0
82
+ m = KeplerGl(height=300) # 无数据也能创建空地图
83
+ print(type(m).__name__) # KeplerGl
84
+ ```
85
+
86
+ ---
87
+
88
+ ## 核心 API
89
+
90
+ ### 数据模型:dataset 与 fields/rows
91
+
92
+ 所有数据最终都归一化为下面两种形态之一,`addDataToMap` 只认这个结构:
93
+
94
+ | 形态 | 结构 | 说明 |
95
+ |------|------|------|
96
+ | 表格 | `{fields: [{name, type, format}], rows: [[...]]}` | CSV / DataFrame / Arrow,行列索引对齐 |
97
+ | GeoJSON | `{type, features}` | 单要素或 FeatureCollection;属性进 fields |
98
+
99
+ `type` 取值包括 `string`、`integer`、`real`、`boolean`、`timestamp`、`date`、`geojson`;经纬度字段需为数值型且列名为 `latitude` / `longitude`(或手动指定图层当前列),`timestamp` 需配 `format`,否则时间轴与时间过滤器不生效。
100
+
101
+ ```javascript
102
+ import {processGeojson, processCsvData} from '@kepler.gl/processors';
103
+
104
+ const {fields, rows} = processCsvData(csvText);
105
+ const geo = processGeojson(geojsonObject); // 返回同样含 fields / rows 的对象
106
+ ```
107
+
108
+ ### Redux 接入
109
+
110
+ Kepler.gl 不是自治组件,它依赖挂载在 store 的 `keplerGl` 键下的 reducer,以及处理异步任务的 middleware。
111
+
112
+ ```javascript
113
+ import {createStore, combineReducers, applyMiddleware, compose} from 'redux';
114
+ import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';
115
+
116
+ const reducers = combineReducers({
117
+ keplerGl: keplerGlReducer,
118
+ // ...其余 reducer
119
+ });
120
+
121
+ const middlewares = enhanceReduxMiddleware([
122
+ // ...其余 middleware
123
+ ]);
124
+
125
+ export const store = createStore(reducers, {}, compose(applyMiddleware(...middlewares)));
126
+ ```
127
+
128
+ 若把 reducer 挂在别的键(例如 `state.maps`),挂载组件时必须同时传入 `getState={state => state.maps}`,否则组件取不到实例状态而渲染空白。
129
+
130
+ ### KeplerGl 组件
131
+
132
+ ```javascript
133
+ import KeplerGl from '@kepler.gl/components';
134
+
135
+ export default function MapPanel() {
136
+ return (
137
+ <KeplerGl
138
+ id="demo"
139
+ mapboxApiAccessToken="" // 仅 Mapbox 样式需要;CARTO/MapLibre 样式留空
140
+ width={window.innerWidth}
141
+ height={window.innerHeight}
142
+ appName="Traffic Explorer"
143
+ sidePanelWidth={420}
144
+ getState={state => state.keplerGl}
145
+ onViewStateChange={({longitude, latitude, zoom}) => console.log(longitude, latitude, zoom)}
146
+ />
147
+ );
148
+ }
149
+ ```
150
+
151
+ | Prop | 默认值 | 说明 |
152
+ |------|--------|------|
153
+ | `id` | `map` | 实例标识,对应 `state.keplerGl[id]`;多地图实例必须唯一 |
154
+ | `getState` | `state => state.keplerGl` | 从 store 取 Kepler.gl 子树的函数 |
155
+ | `mapboxApiAccessToken` | 无(类型上必填) | Mapbox 样式所需 token;只用 CARTO/MapLibre 样式时传空串 |
156
+ | `width` / `height` | `800` / `800` | 画布尺寸,常配合容器尺寸动态计算 |
157
+ | `appName` / `version` | `Kepler.Gl` / `v1.0` | 侧栏标题文字 |
158
+ | `sidePanelWidth` | `300` | 侧栏像素宽度 |
159
+ | `theme` | `{}` | 主题对象(覆盖默认主题变量),不是字符串;字符串 `'dark'`/`'light'` 只用于 Python 小组件 |
160
+ | `mapStyles` | 内置列表 | 自定义底图样式数组,配合 `mapStylesReplaceDefault` 替换默认列表 |
161
+ | `readOnly` | `false` | 隐藏侧栏,只读展示 |
162
+ | `onViewStateChange` | 无 | 视口变化回调,用于外部联动 |
163
+ | `getMapboxRef` | 无 | 拿到内部地图实例引用(分屏时按 index 区分) |
164
+
165
+ ### addDataToMap
166
+
167
+ ```javascript
168
+ import {addDataToMap, removeDataset} from '@kepler.gl/actions';
169
+
170
+ dispatch(addDataToMap({
171
+ datasets: {
172
+ info: {id: 'roads', label: '道路'},
173
+ data: {fields, rows}
174
+ },
175
+ options: {
176
+ centerMap: true,
177
+ padding: {left: 300, top: 24, right: 24, bottom: 24},
178
+ readOnly: false,
179
+ keepExistingConfig: false
180
+ },
181
+ config: savedConfig, // 可选:之前导出的整图配置
182
+ info: {title: '路网概览', description: '2026-10 快照'}
183
+ }));
184
+ ```
185
+
186
+ - `datasets` 可传单个 dataset 或数组;配置里的 `dataId` 必须与 `datasets.info.id` 对应
187
+ - `options.centerMap` 会覆盖 `config.mapState` 中的视口,需要保留原视口时设为 `false`
188
+ - `options.keepExistingConfig` 为 `false` 时清空旧图层与过滤器,做「换图」用;追加数据集改用数组形式并设为 `true`
189
+ - 增量更新行数据用 `addToDataset` / `removeFromDataset`,不必重建整图;Arrow/DuckDB 表暂不支持这两个 action
190
+
191
+ ### 配置导出与还原
192
+
193
+ ```javascript
194
+ import KeplerGlSchema from '@kepler.gl/schemas';
195
+
196
+ const saved = KeplerGlSchema.getConfigToSave(store.getState().keplerGl.demo);
197
+ const meta = KeplerGlSchema.getMapInfo(store.getState().keplerGl.demo);
198
+ localStorage.setItem('kepler-config', JSON.stringify(saved));
199
+ ```
200
+
201
+ 还原时把 `saved` 作为 `config` 传回 `addDataToMap`,并重新提供 `datasets`;配置中只保存图层与样式,不保存数据本身。
202
+
203
+ ### Python 小组件
204
+
205
+ ```python
206
+ from keplergl import KeplerGl
207
+ import geopandas as gpd
208
+
209
+ gdf = gpd.read_file("data/roads.gpkg")
210
+
211
+ m = KeplerGl(height=500, theme="dark", app_name="路网概览")
212
+ m.add_data(data=gdf, name="roads")
213
+ m
214
+
215
+ # 导出为独立 HTML(从 unpkg 加载 kepler.gl,无需本地构建)
216
+ m.save_to_html(file_name="roads_map.html", read_only=True, center_map=True)
217
+ ```
218
+
219
+ `KeplerGl.__init__` 关键参数:`data`(名称到数据的字典)、`config`(整图配置)、`height`、`mapbox_token`、`use_arrow`(DataFrame 用 Arrow IPC 序列化,大数据更快)、`theme`、`app_name`。`add_data(data, name="data", use_arrow=None)` 追加数据集,`save_to_html(...)` 支持 `read_only`、`center_map`、`json_encoder` 等参数。
220
+
221
+ ---
222
+
223
+ ## 典型工作流
224
+
225
+ 以「GeoPandas 预处理路网 → 发布为可分享的独立 HTML」为例:
226
+
227
+ 1. 用 GeoPandas 读取并裁剪数据,保持 WGS84(EPSG:4326),Kepler.gl 只认经纬度
228
+ 2. 在 Notebook 中创建 `KeplerGl` 实例并 `add_data`,检查字段类型是否被正确识别
229
+ 3. 在界面里调好图层颜色、半径、tooltip 字段
230
+ 4. 通过 `m.config` 取出配置,与数据一起 `save_to_html`,得到单文件地图
231
+
232
+ ```python
233
+ import geopandas as gpd
234
+ from keplergl import KeplerGl
235
+
236
+ roads = gpd.read_file("data/roads.gpkg").to_crs(4326)
237
+ roads = roads[roads["class"].isin(["motorway", "primary", "secondary"])]
238
+ roads["length_km"] = roads.length * 111.32 # 粗略换算,正式分析请用投影坐标系
239
+
240
+ m = KeplerGl(height=520, theme="dark", app_name="路网概览")
241
+ m.add_data(data=roads[["class", "length_km", "geometry"]], name="roads")
242
+
243
+ # 在 Notebook 中交互配置完成后,导出配置
244
+ config = m.config
245
+ m.save_to_html(file_name="roads_map.html", config=config, read_only=True)
246
+ print("written:", "roads_map.html")
247
+ ```
248
+
249
+ 输出是一个独立 HTML:内嵌数据与配置,从 unpkg 拉取 kepler.gl 运行时,可直接发给同事查看。
250
+
251
+ React 侧的等价流程是:`processGeojson` / `processCsvData` 解析 → `dispatch(addDataToMap(...))` → 用户交互 → `KeplerGlSchema.getConfigToSave` 落库 → 下次用同一 `config` 还原。
252
+
253
+ ---
254
+
255
+ ## 最佳实践
256
+
257
+ 1. **坐标系只保留 WGS84**:Kepler.gl 不做投影,其他坐标系先用 GeoPandas `to_crs(4326)` 或 GDAL 转换
258
+ 2. **规范字段类型**:数字列不要混入空字符串,时间列统一转 `datetime` 并设置 `format`,否则过滤器表现为「无数据」
259
+ 3. **大数据走 Arrow**:Python 侧 `use_arrow=True`,前端可先转 Arrow 表再 `processArrowTable`,比 JSON 行数组更省内存
260
+ 4. **控制单次 payload**:一次 `addDataToMap` 传入几十万行以上时应先做聚合或后端分页,浏览器主线程会卡在数据展开
261
+ 5. **配置与数据分离存储**:`getConfigToSave` 只存样式,数据另存;版本升级后旧配置可能引用不存在的字段,需要做字段名兜底
262
+ 6. **多实例用 id 隔离**:一个页面放两张地图时给不同 `id`,并确认 `getState` 指向同一个根
263
+ 7. **底图选型**:CARTO/MapLibre 样式免 token,适合内网与演示;Mapbox 官方样式需 token 且有计费风险
264
+
265
+ ---
266
+
267
+ ## 常见问题
268
+
269
+ | 问题 | 原因与解决 |
270
+ |------|------------|
271
+ | 组件渲染为空白,控制台提示 `Could not find ... in the context of Connect(...)` | reducer 未挂载或挂载键名不对:按 `combineReducers({keplerGl: keplerGlReducer})` 挂载,或给 `KeplerGl` 传正确的 `getState` |
272
+ | 数据已传入但地图没有图层 | `datasets.info.id` 与 `config` 里的 `dataId` 不匹配,或字段类型不是数值:先不传 `config`(`addDataToMap` 的 config 置空)确认能否自动建层 |
273
+ | 时间过滤器/时间轴不可用 | 时间字段未标记为 `timestamp` 或缺少 `format`:在 `fields` 中补 `{name, type: 'timestamp', format: 'YYYY-MM-DD HH:mm:ss'}` |
274
+ | 点位错位或全部堆在 (0,0) | 坐标不是经纬度,或列名不是 `latitude`/`longitude`:先转 EPSG:4326,并在图层里手动指定经纬度字段 |
275
+ | 底图不显示,提示需要 Mapbox token | 当前样式是 `mapbox://` 样式:换成默认的 CARTO/MapLibre 样式,或给 `mapboxApiAccessToken` 配置有效 token(有计费) |
276
+ | 导入时报 `Cannot find module '@kepler.gl/components'` | 只装了 `kepler.gl` 整包却按子包路径 import:整包用 `kepler.gl` 入口,或按需安装子包并保证版本一致 |
277
+ | `addDataToMap` 后页面卡死数秒 | 单次数据量过大:先聚合或抽样,或改走 Arrow 表;同时关闭不需要的图层(如六边形聚合) |
278
+ | Jupyter 中地图不显示 | 内核与前端版本不匹配:确认 JupyterLab >= 4 / Notebook >= 7,重启内核后重装 `keplergl==0.4.0` |
279
+ | `save_to_html` 报 JSON 序列化错误 | 数据中有 datetime 等非原生类型:保留默认 `json_encoder=str`,或自行传入可序列化编码函数 |
280
+
281
+ ---
282
+
283
+ ## AI 使用建议
284
+
285
+ - **执行环境**:`npm install` / `pnpm install`、`pip install keplergl` 在终端中执行 或 `ops_bash`,长输出重定向到文件再分段读。
286
+ - **先探测版本**:`npm ls kepler.gl @kepler.gl/components @kepler.gl/actions`,子包必须与主包同为 3.3.0-alpha.20;Python 侧 `python -c "import keplergl; print(keplergl.__version__)"` 应为 0.4.0。
287
+ - **验证产物**:前端用 `npm run build` 确认编译,再用 `npx serve dist` 起本地静态服务;是否真出图只能由浏览器确认,AI 助手通常看不到浏览器画面,请用户看画面与控制台,环境支持读图时用截图核对。
288
+ - **无 GPU 环境**:无头环境无法验证 WebGL 渲染,构建通过不等于地图可用,此时不要报告「已渲染」。
289
+ - **常见症状**:空白组件先查 reducer 与 `getState`;无图层查 `dataId` 与字段类型;token 报错查底图样式。
290
+ - **安全与权限**:装包、起服务、把数据写入 HTML 前先征得用户同意;配置里不要硬编码 Mapbox token。
291
+
292
+ ## 相关技能
293
+
294
+ - **deck-gl** — Kepler.gl 的渲染底座,自定义图层与拾取需直接操作 deck.gl:[../deck-gl/SKILL.md](../deck-gl/SKILL.md)
295
+ - **mapbox-gl-js** — 使用 Mapbox 官方样式与 token 时的对应技能:[../mapbox-gl-js/SKILL.md](../mapbox-gl-js/SKILL.md)
296
+ - **openlayers** — 传统 2D WebGIS 方案,适合与 Kepler.gl 做能力对比:[../openlayers/SKILL.md](../openlayers/SKILL.md)
297
+ - **geopandas** — Python 侧数据预处理与投影转换:[../geopandas/SKILL.md](../geopandas/SKILL.md)
298
+ - **gdal** — 大体量数据的格式转换与切片,为前端准备输入:[../gdal/SKILL.md](../gdal/SKILL.md)
299
+
300
+ ## 参考资源
301
+
302
+ - 官方文档与示例:<https://docs.kepler.gl/>
303
+ - 4.x 之前的旧版文档(API 名称有变化,注意甄别):<https://github.com/keplergl/kepler.gl/tree/master/docs>
304
+ - Jupyter 小组件指南:<https://docs.kepler.gl/docs/keplergl-jupyter>
305
+ - 示例工程目录:<https://github.com/keplergl/kepler.gl/tree/master/examples>
306
+ - 数据格式与处理函数:<https://docs.kepler.gl/docs/api-reference/processors/processors>
@@ -1,17 +1,10 @@
1
1
  ---
2
2
  name: leaflet
3
3
  description: "Use when adding lightweight 2D tile maps to web pages with leaflet 1.9.4 — L.map/L.tileLayer, markers, popups, GeoJSON overlays, layer control, [lat, lng] ordering, or debugging blank maps, broken default marker icons after bundling, and sizing fixed by invalidateSize()."
4
- tags:
5
- - javascript
6
- - web
7
- - 2d
8
- - map
9
- - geojson
10
- - tile-layer
11
- - markers
12
- - plugins
13
- - vue
14
- - react
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "javascript, web, 2d, map, geojson, tile-layer, markers, plugins, vue, react"
15
8
  ---
16
9
 
17
10
  > **项目地址:** <https://github.com/Leaflet/Leaflet>
@@ -22,7 +15,7 @@ tags:
22
15
  >
23
16
  > **示例:** <https://leafletjs.com/examples.html>
24
17
  >
25
- > **最新版本:** 1.9.4(截至2026-10,npm `leaflet`)
18
+ > **最新版本:** 1.9.4(截至 2026-11,[npm `leaflet`](https://www.npmjs.com/package/leaflet) 与 [GitHub Release](https://github.com/Leaflet/Leaflet/releases) 一致;1.9.4 发布于 2023-05,仍是当前稳定版)
26
19
  >
27
20
  > **许可证:** BSD-2-Clause
28
21
 
@@ -187,19 +180,42 @@ map.off('mousemove', handler); // 显式移除,避免内存泄漏
187
180
 
188
181
  ## 典型工作流
189
182
 
183
+ 以「底图 + GeoJSON 点位 + 弹窗 + 图层切换」为例:输入 `data/poi.geojson`(`[lng, lat]`),输出可缩放、可点选、可切层的单页地图。
184
+
190
185
  1. **初始化地图**:`L.map('map', { center, zoom })`,容器须有确定高度
191
186
  2. **添加底图**:`L.tileLayer(urlTemplate, { attribution }).addTo(map)`
192
- 3. **叠加数据**:`L.marker` 或 `L.geoJSON(data, { style, onEachFeature })`
187
+ 3. **叠加数据**:`L.geoJSON(data, { style, pointToLayer, onEachFeature })`
193
188
  4. **绑定交互**:`layer.bindPopup()` / `map.on('click', fn)`
194
189
  5. **图层管理**:`L.control.layers(baseLayers, overlays).addTo(map)`
195
190
  6. **自适应视图**:`map.fitBounds(layer.getBounds())`
196
191
  7. **销毁清理**:组件卸载时调用 `map.remove()`
197
192
 
198
193
  ```javascript
199
- const layer = L.geoJSON(data).addTo(map);
200
- map.fitBounds(layer.getBounds(), { padding: [20, 20] });
194
+ const map = L.map('map', { center: [39.9042, 116.4074], zoom: 11 });
195
+
196
+ const osm = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
197
+ maxZoom: 19,
198
+ attribution: '&copy; OpenStreetMap contributors'
199
+ }).addTo(map);
200
+
201
+ // GeoJSON 坐标是 [lng, lat],Leaflet 需要 [lat, lng]
202
+ fetch('/data/poi.geojson')
203
+ .then((r) => r.json())
204
+ .then((geojson) => {
205
+ const poiLayer = L.geoJSON(geojson, {
206
+ pointToLayer: (feature, latlng) => L.circleMarker(latlng, { radius: 6, color: '#e74c3c' }),
207
+ onEachFeature: (feature, layer) => {
208
+ layer.bindPopup(feature.properties.name);
209
+ }
210
+ }).addTo(map);
211
+
212
+ map.fitBounds(poiLayer.getBounds(), { padding: [20, 20] });
213
+ L.control.layers({ OSM: osm }, { POI: poiLayer }).addTo(map);
214
+ });
201
215
  ```
202
216
 
217
+ **验收**:页面先出现 OSM 底图,数据加载后视野自动收缩到点位范围,点击圆点弹出名称;右上角图层控件可切换 POI 显隐。
218
+
203
219
  ---
204
220
 
205
221
  ## 插件生态
@@ -314,26 +330,31 @@ export default function MapView() {
314
330
 
315
331
  ## 常见问题
316
332
 
317
- | 问题 | 原因与解决 |
318
- |------|------------|
319
- | 地图区域空白 / 不显示 | 容器缺少高度:为 `#map` 设置 `height`(如 `400px`),或地图初始化后调用 `map.invalidateSize()` |
320
- | 标记图标 404 / 显示为破图 | npm + 打包器下 `leaflet.css` 引用的默认图标路径失效,需手动设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl` 或改用 CDN 引入 CSS |
321
- | 地图在弹窗/隐藏容器中显示错乱 | 容器尺寸变化后调用 `map.invalidateSize()` 重算 |
322
- | `L is not defined` | CDN 脚本未加载或引入顺序错误:先加载 `leaflet.js` 再执行代码;npm 下确认 `import L from 'leaflet'` |
323
- | 经纬度颠倒导致点跑到别处 | 参数顺序为 `[lat, lng]`;GeoJSON 坐标是 `[lng, lat]`,必要时用 `coordsToLatLng` 转换 |
324
- | 组件切换后内存持续增长 | 卸载时未调用 `map.remove()`,或事件监听器未 `off` 解绑 |
325
- | 瓦片加载失败 / 跨域 | 检查瓦片服务 URL 模板与 CORS 头;WMS 需确认服务端允许跨域 |
326
- | 与 Vue/React 响应式冲突 | 不要把 `L.map` 实例放进 `reactive`/`useState`(会代理内部对象),用普通变量或 `useRef` 持有 |
333
+ | 报错 / 现象 | 原因 | 处置 |
334
+ |------|------|------|
335
+ | 报错 `Uncaught Error: Map container is already initialized.` | 同一个 DOM 容器被 `L.map()` 初始化两次(React StrictMode 双调用、热更新、路由复用组件最常见) | 复用前先 `map.remove()` 并把引用置空;React 在 `useEffect` 的 cleanup 里 `remove()`,初始化前判断容器是否已带 `_leaflet_id` |
336
+ | 报错 `Uncaught Error: Map container not found.` | `L.map(id)` 执行时容器 DOM 尚未挂载,或 id 与模板不一致 | 等 DOM 就绪再初始化(React `useEffect`、Vue `onMounted`),并核对传入的 id/元素 |
337
+ | 报错 `Uncaught Error: Map container is being reused by another instance` | 容器仍被一个未销毁的 `Map` 实例占用 | 先 `remove()` 旧实例再初始化;同一容器不要并存两个地图 |
338
+ | 报错 `Uncaught ReferenceError: L is not defined` | CDN 脚本未加载、加载失败,或自定义代码先于 `leaflet.js` 执行 | 先引 `leaflet.js` 再执行业务代码;npm 下确认 `import L from 'leaflet'` 且打包产物真的包含它 |
339
+ | 地图区域空白 / 不显示 | 容器没有显式高度(Leaflet 不自带尺寸),或初始化后容器尺寸才变化 | 给 `#map` 设 `height`(如 `400px`);尺寸变化后调用 `map.invalidateSize()` |
340
+ | 默认标记图标 404 / 显示为破图 | npm + 打包器下 `leaflet.css` 里相对的默认图标路径失效 | 显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`,或改用 CDN 引入 CSS 与图片 |
341
+ | 地图在弹窗 / 隐藏容器中显示错乱 | 容器尺寸在初始化时已知为零,或标签页切回后尺寸变化 | 容器可见后再初始化,并在可见性变化后调用 `map.invalidateSize()` |
342
+ | 点跑到别的位置 / 坐标颠倒 | 参数顺序是 `[lat, lng]`,而 GeoJSON 是 `[lng, lat]` | 统一在入口处用 `L.latLng(lat, lng)` 或 `coordsToLatLng` 转换,不要混用两种顺序 |
343
+ | 组件切换后内存持续增长 | 卸载时未调用 `map.remove()`,或自定义事件未 `off` 解绑 | cleanup 中 `map.remove()`;自定义监听器用具名函数并 `map.off(type, handler)` |
344
+ | 瓦片加载失败 / 跨域报错 | 瓦片 URL 模板错误,或瓦片服务未返回 CORS 头 | 核对 `{z}/{x}/{y}` 模板与该服务实际路径;WMS 需服务端放行跨域,前端 `crossOrigin` 选项按需设置 |
345
+ | 地图与 Vue/React 响应式冲突 | 把 `L.map` 实例放进 `reactive`/`useState`,代理了 Leaflet 内部对象 | 用普通变量或 `useRef` 持有实例,不要放进响应式容器 |
327
346
 
328
347
  ---
329
348
 
330
- ## 参考资源
349
+ ## AI 使用建议
331
350
 
332
- - 官方文档:<https://leafletjs.com/>
333
- - API 参考:<https://leafletjs.com/reference.html>
334
- - 官方示例:<https://leafletjs.com/examples.html>
335
- - 插件列表:<https://leafletjs.com/plugins.html>
336
- - 源码仓库:<https://github.com/Leaflet/Leaflet>
351
+ - **执行环境**:`npm install`、`npm run build` 在终端中执行;纯静态页面可用 `python -m http.server 5173` 起服务(`python` 不存在时用 `py -3`)。
352
+ - **先探测版本**:`npm ls leaflet`(未装则 `npm view leaflet version`);本技能按 1.9.4 编写,CDN 的 `integrity` SRI 哈希只对应 1.9.4,换版本必须同步换哈希。
353
+ - **验证产物**:构建后 `curl.exe -I http://localhost:5173/assets/<入口>.js` 确认 200;联网时还可 `curl.exe -I https://unpkg.com/leaflet@1.9.4/dist/leaflet.js` 核对 CDN 版本;AI 助手通常看不到浏览器画面,把 URL 和“应看到瓦片与标记”交给用户,环境支持读图时用截图核对。
354
+ - **图标与坐标**:npm + 打包器下默认 marker 图标会 404,需显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`;坐标一律 `[lat, lng]`,GeoJSON 是 `[lng, lat]`。
355
+ - **生命周期**:SPA 卸载必须 `map.remove()` 并解绑自定义事件;容器隐藏或尺寸变化后 `map.invalidateSize()`。
356
+ - **常见症状**:地图区域空白多为容器没设高度;`L is not defined` 是脚本顺序或 CDN 失败;漏引 `leaflet.css` 会导致控件错位。
357
+ - **安全与权限**:装包、起服务、改端口前先征得用户同意;天地图等瓦片服务的 `tk` 不要硬编码进提交的前端代码。
337
358
 
338
359
  ## 相关技能
339
360
 
@@ -341,13 +362,10 @@ export default function MapView() {
341
362
  - **cesiumjs** — 三维地球与 3D Tiles 可视化:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
342
363
  - **geoserver** — 发布 WMS/WFS/瓦片服务作为 Leaflet 数据源:[../geoserver/SKILL.md](../geoserver/SKILL.md)
343
364
 
344
- ## DeepSeek Harness 使用建议
365
+ ## 参考资源
345
366
 
346
- - **加载与引用**:用 `skill("leaflet")` 加载(用户也可输入 `/leaflet`);本技能无 reference 子目录,示例代码直接落到会话工作区工程,技能目录只读。
347
- - **执行环境**:`npm install`、`npm run build` 交给 `pwsh`;纯静态页面可用 `python -m http.server 5173` 起服务(`python` 不存在时用 `py -3`)。
348
- - **先探测版本**:`npm ls leaflet`(未装则 `npm view leaflet version`);本技能按 1.9.4 编写,CDN 的 `integrity` SRI 哈希只对应 1.9.4,换版本必须同步换哈希。
349
- - **验证产物**:构建后 `curl.exe -I http://localhost:5173/assets/<入口>.js` 确认 200;联网时还可 `curl.exe -I https://unpkg.com/leaflet@1.9.4/dist/leaflet.js` 核对 CDN 版本;DSH 不打开浏览器,把 URL 和“应看到瓦片与标记”交给用户,有截图再用 `read_image`。
350
- - **图标与坐标**:npm + 打包器下默认 marker 图标会 404,需显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`;坐标一律 `[lat, lng]`,GeoJSON 是 `[lng, lat]`。
351
- - **生命周期**:SPA 卸载必须 `map.remove()` 并解绑自定义事件;容器隐藏或尺寸变化后 `map.invalidateSize()`。
352
- - **常见症状**:地图区域空白多为容器没设高度;`L is not defined` 是脚本顺序或 CDN 失败;漏引 `leaflet.css` 会导致控件错位。
353
- - **安全与权限**:装包、起服务、改端口前先征得用户同意;天地图等瓦片服务的 `tk` 不要硬编码进提交的前端代码。
367
+ - 官方文档:<https://leafletjs.com/>
368
+ - API 参考:<https://leafletjs.com/reference.html>
369
+ - 官方示例:<https://leafletjs.com/examples.html>
370
+ - 插件列表:<https://leafletjs.com/plugins.html>
371
+ - 源码仓库:<https://github.com/Leaflet/Leaflet>
@@ -1,16 +1,10 @@
1
1
  ---
2
2
  name: mapbox-gl-js
3
- description: "Use when building vector web maps with mapbox-gl 3.33.0 — WebGL rendering, Style Spec layers, data-driven expressions, setTerrain raster-dem, fill-extrusion, or debugging 401 'A valid Mapbox access token is required', 'Style is not done loading', and pk./sk. token handling. Note: v2+ is proprietary under Mapbox TOS and requires a token; MapLibre GL JS is the open-source fork."
4
- tags:
5
- - javascript
6
- - web
7
- - map
8
- - vector-tiles
9
- - webgl
10
- - 3d-terrain
11
- - data-driven-styling
12
- - style-spec
13
- - access-token
3
+ description: "Use when building vector web maps with mapbox-gl 3.34.2 — WebGL rendering, Style Spec layers, data-driven expressions, setTerrain raster-dem, fill-extrusion, or debugging 401 'A valid Mapbox access token is required', 'Style is not done loading', and pk./sk. token handling. Note: v2+ is proprietary under Mapbox TOS and requires a token; MapLibre GL JS is the open-source fork."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "javascript, web, map, vector-tiles, webgl, 3d-terrain, data-driven-styling, style-spec, access-token"
14
8
  ---
15
9
 
16
10
  > **项目地址:** <https://github.com/mapbox/mapbox-gl-js>
@@ -19,7 +13,7 @@ tags:
19
13
  >
20
14
  > **API 参考:** <https://docs.mapbox.com/mapbox-gl-js/api/>
21
15
  >
22
- > **最新版本:** 3.33.0(截至2026-10,npm `mapbox-gl` 与 GitHub Release 一致)
16
+ > **最新版本:** 3.34.2(截至 2026-11,npm `mapbox-gl` 与 GitHub Release 一致;[CHANGELOG](https://github.com/mapbox/mapbox-gl-js/blob/main/CHANGELOG.md))
23
17
  >
24
18
  > **许可证:** v2+ 为 Mapbox 专有许可(v1.x 为 BSD-3-Clause;需 Mapbox 账号 access token)
25
19
 
@@ -67,8 +61,8 @@ v3 提供更小的 ESM 入口:`import * as mapboxgl from 'mapbox-gl/esm'`。
67
61
  <head>
68
62
  <meta charset="utf-8" />
69
63
  <meta name="viewport" content="width=device-width, initial-scale=1" />
70
- <link href="https://api.mapbox.com/mapbox-gl-js/v3.33.0/mapbox-gl.css" rel="stylesheet" />
71
- <script src="https://api.mapbox.com/mapbox-gl-js/v3.33.0/mapbox-gl.js"></script>
64
+ <link href="https://api.mapbox.com/mapbox-gl-js/v3.34.2/mapbox-gl.css" rel="stylesheet" />
65
+ <script src="https://api.mapbox.com/mapbox-gl-js/v3.34.2/mapbox-gl.js"></script>
72
66
  <style>
73
67
  /* 容器必须显式设置高度,否则地图不可见 */
74
68
  #map { height: 400px; }
@@ -382,7 +376,7 @@ map.on('load', () => {
382
376
  1. **token 安全**:前端只用 `pk.` public token,配置 URL restrictions;`sk.` secret token 仅限服务端
383
377
  2. **许可与费用**:v2+ 受 Mapbox TOS 约束,免费层每月 50,000 次地图加载(map loads),超出按量计费,额度与价格以 <https://www.mapbox.com/pricing> 为准;开源或零成本场景评估 MapLibre GL JS
384
378
  3. **等待样式加载**:`addSource` / `addLayer` / `setTerrain` 必须在 `load` 事件之后调用
385
- 4. **固定版本**:CDN 引用固定版本号(如 `v3.33.0`),JS 与 CSS 版本保持一致
379
+ 4. **固定版本**:CDN 引用固定版本号(如 `v3.34.2`),JS 与 CSS 版本保持一致
386
380
  5. **坐标顺序**:Mapbox GL JS 使用 `[经度, 纬度]`,与 GeoJSON 一致,与 Leaflet 的 `[lat, lng]` 相反
387
381
  6. **大数据量**:优先矢量瓦片而非大量 GeoJSON;GeoJSON 点数据开启 `cluster` 聚合
388
382
  7. **资源清理**:SPA 卸载组件时调用 `map.remove()`,注销自定义事件监听
@@ -406,16 +400,15 @@ map.on('load', () => {
406
400
 
407
401
  ---
408
402
 
409
- ## 参考资源
403
+ ## AI 使用建议
410
404
 
411
- - 官方文档:<https://docs.mapbox.com/mapbox-gl-js/>
412
- - API 参考:<https://docs.mapbox.com/mapbox-gl-js/api/>
413
- - 官方示例:<https://docs.mapbox.com/mapbox-gl-js/examples/>
414
- - Style Spec 样式规范:<https://docs.mapbox.com/style-spec/>
415
- - Expressions 表达式参考:<https://docs.mapbox.com/style-spec/reference/expressions/>
416
- - 源码仓库与发布记录:<https://github.com/mapbox/mapbox-gl-js>
417
- - 开源替代 MapLibre GL JS:<https://github.com/maplibre/maplibre-gl-js>
418
- - 价格说明:<https://www.mapbox.com/pricing>
405
+ - **执行环境**:`npm install`、`npm run build` 在终端中执行;Windows 下用 `npm.cmd`,长构建放后台运行。
406
+ - **先探测版本**:`npm ls mapbox-gl`(未装则 `npm view mapbox-gl version`);本技能按 3.34.2 编写,CDN 的 JS 与 CSS 必须同为 `v3.34.2`,联网时 `curl.exe -I https://api.mapbox.com/mapbox-gl-js/v3.34.2/mapbox-gl.js` 应为 200。
407
+ - **验证产物**:`npm run build` 后 `npx serve dist`,`curl.exe -I http://localhost:5173/` 确认入口;地图是否真加载、有没有 401 只能看浏览器 Network(`api.mapbox.com`),AI 助手通常看不到浏览器画面,请用户确认或提供截图后再判断。
408
+ - **token 安全**:前端只允许 `pk.` 公开 token,`sk.` 绝不能进构建产物;用 `VITE_MAPBOX_TOKEN` 等环境变量注入,提交前用 agent 的 `grep` 搜 `sk.` 与硬编码 `pk.`,回答和日志里不要回显 token。
409
+ - **许可提醒**:v2+ 是 Mapbox 专有许可并受配额计费约束;用户要求开源或免 token 时改写为 MapLibre(`maplibregl` 替代 `mapboxgl`,`mapbox://` 样式换成自建瓦片)。
410
+ - **常见症状**:`Style is not done loading` 是 `load` 事件前调了 `addSource`/`addLayer`;空白先查容器高度和 `map.resize()`;`e.features` 只在回调内有效。
411
+ - **安全与权限**:装包、起 dev server、调用计费接口前先征得用户同意,并说明可能产生费用。
419
412
 
420
413
  ## 相关技能
421
414
 
@@ -424,13 +417,13 @@ map.on('load', () => {
424
417
  - **cesiumjs** — 三维地球与 3D Tiles 可视化:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
425
418
  - **geoserver** — 发布 WMS/WFS/MVT 服务作为矢量瓦片数据源:[../geoserver/SKILL.md](../geoserver/SKILL.md)
426
419
 
427
- ## DeepSeek Harness 使用建议
420
+ ## 参考资源
428
421
 
429
- - **加载与引用**:用 `skill("mapbox-gl-js")` 加载(用户也可输入 `/mapbox-gl-js`);本技能无 reference 子目录,示例代码写入会话工作区工程,技能目录只读。
430
- - **执行环境**:`npm install`、`npm run build` 交给 `pwsh`;Windows 下用 `npm.cmd`,长构建用后台作业。
431
- - **先探测版本**:`npm ls mapbox-gl`(未装则 `npm view mapbox-gl version`);本技能按 3.33.0 编写,CDN 的 JS 与 CSS 必须同为 `v3.33.0`,联网时 `curl.exe -I https://api.mapbox.com/mapbox-gl-js/v3.33.0/mapbox-gl.js` 应为 200。
432
- - **验证产物**:`npm run build` 后 `npx serve dist`,`curl.exe -I http://localhost:5173/` 确认入口;地图是否真加载、有没有 401 只能看浏览器 Network(`api.mapbox.com`),DSH 不打开浏览器,请用户确认或提供截图后再 `read_image`。
433
- - **token 安全**:前端只允许 `pk.` 公开 token,`sk.` 绝不能进构建产物;用 `VITE_MAPBOX_TOKEN` 等环境变量注入,提交前用 dsh 的 `grep` 搜 `sk.` 与硬编码 `pk.`,回答和日志里不要回显 token。
434
- - **许可提醒**:v2+ 是 Mapbox 专有许可并受配额计费约束;用户要求开源或免 token 时改写为 MapLibre(`maplibregl` 替代 `mapboxgl`,`mapbox://` 样式换成自建瓦片)。
435
- - **常见症状**:`Style is not done loading` 是 `load` 事件前调了 `addSource`/`addLayer`;空白先查容器高度和 `map.resize()`;`e.features` 只在回调内有效。
436
- - **安全与权限**:装包、起 dev server、调用计费接口前先征得用户同意,并说明可能产生费用。
422
+ - 官方文档:<https://docs.mapbox.com/mapbox-gl-js/>
423
+ - API 参考:<https://docs.mapbox.com/mapbox-gl-js/api/>
424
+ - 官方示例:<https://docs.mapbox.com/mapbox-gl-js/examples/>
425
+ - Style Spec 样式规范:<https://docs.mapbox.com/style-spec/>
426
+ - Expressions 表达式参考:<https://docs.mapbox.com/style-spec/reference/expressions/>
427
+ - 源码仓库与发布记录:<https://github.com/mapbox/mapbox-gl-js>
428
+ - 开源替代 MapLibre GL JS:<https://github.com/maplibre/maplibre-gl-js>
429
+ - 价格说明:<https://www.mapbox.com/pricing>