csk-gis-frame-work 4.0.0

package/mapboxgl/utils/mapboxgl.md

@@ -0,0 +1,138 @@
+# Mapbox GIS 工具集 API 文档
+
+> 本文档基于 `mapbox.js` 源码整理，供二次开发人员快速查阅。该工具集封装了 Mapbox GL JS 及 AntV L7 的常用操作，统一了坐标系转换、图层管理与交互绘制逻辑。
+
+## 📦 核心配置属性
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `workspace` | String | GeoServer 工作空间名称 |
+| `mapType` | String | 当前底图类型 (`'vector'` / `'image'`) |
+| `map_srid` | String | 地图坐标系 (如 `EPSG:3857`) |
+| `business_srid` | String | 业务数据坐标系 |
+| `mbMap` | Object | 原生 Mapbox GL Map 实例引用 |
+| `styleUrl` | String | 样式服务基础 URL |
+| `opts` | Object | 创建地图时传入的配置项缓存 |
+
+---
+
+## 一、地图初始化与生命周期
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `create` | `(opts, callback)` | void | 创建并初始化地图实例。自动处理资源加载、主题切换及 AntV L7 Scene 创建。回调返回 `(map, antv7Scene)`。 |
+| `getMap` | - | MapboxMap | 获取原生 Mapbox GL Map 实例。 |
+| `getAntV7Scene` | - | L7.Scene | 获取 AntV L7 Scene 实例，用于高级可视化扩展。 |
+| `disposeMap` | - | void | 销毁地图实例，释放 DOM 事件监听器及 WebGL 上下文。 |
+
+---
+
+## 二、底图与图层管理
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `changeMap` | `(type)` | void | 切换底图类型。支持 `'vector'`(矢量) 和 `'image'`(影像)。 |
+| `updateBaseMapVisibility` | `(type)` | void | 在线模式下更新天地图底图注记层的可见性。 |
+| `switchLayerVisible` | `(layerIdArray)` | void | 批量控制业务图层显隐。传空数组则显示全部业务图层；传 ID 数组则仅显示指定图层。 |
+| `addGeojsonSourceToMap` | `(sourceId, geojson)` | void | 向地图动态添加或更新 GeoJSON 数据源。 |
+| `clearOverlays` | - | void | 清除所有 ID 包含 `patrol-track-` 前缀的动态巡检图层及关联弹窗。 |
+
+---
+
+## 三、样式与主题
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `changeStyle` | `(theme)` | void | 动态切换亮/暗色主题样式。支持 `'dark'` 和 `'light'`。 |
+| `setFog` | - | void | 启用大气雾效，增强三维场景纵深感。 |
+| `setDEM` | `(hillshade?)` | void | 加载 DEM 地形数据。可选开启山体阴影(`hillshade`)。 |
+| `setLayoutProperty` | `(layerId, name, value)` | void | 安全地修改图层布局属性（如 visibility, text-field）。 |
+| `setPaintProperty` | `(layerId, name, value)` | void | 安全地修改图层绘制属性（如 color, opacity, width）。 |
+
+---
+
+## 四、点位标记与交互
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `addMarker` | `(data, customIcon, customIconName)` | Marker | 在指定经纬度添加自定义图标标记，并自动飞行定位到该点。 |
+| `addCustomPopup` | `(lngLat, content, className, addOnOffset)` | Popup | 添加自定义 DOM 内容弹窗。内置默认偏移量 `[37, -107]`，可通过 `addOnOffset` 微调。 |
+| `hitPoint` | `(map, points, disableDrag, onDragEnd)` | void | 渲染可交互点位集合。支持拖拽编辑模式，拖拽结束后通过回调返回更新后的点位坐标。 |
+
+---
+
+## 五、绘制工具 (点/线/面)
+
+> 💡 **编辑提示**: 所有绘制方法均支持 `enableEditing` 配置。开启后图形顶点可被鼠标拖拽，编辑完成触发 `onEditComplete` 回调。
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `renderPoint` | `(map, point, options)` | void | 绘制或更新点要素。支持颜色、半径配置及编辑模式。 |
+| `renderLine` | `(map, points, options)` | void | 绘制或更新线要素。支持描边颜色、宽度及顶点编辑。 |
+| `renderPolygon` | `(map, points, options)` | void | 绘制或更新面要素（自动闭合首尾点）。支持填充色、透明度及边框编辑。 |
+| `removePoint` | `(map, sourceId)` | void | 清除指定点绘制图层及其编辑状态监听器。 |
+| `removeLine` | `(map, sourceId)` | void | 清除指定线绘制图层及其编辑状态监听器。 |
+| `removePolygon` | `(map, sourceId)` | void | 清除指定面绘制图层及其编辑状态监听器。 |
+
+---
+
+## 六、巡检业务专用
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `drawPatrolTask` | `(map, data)` | void | 绘制单条巡检任务计划。使用固定 ID，重复调用会覆盖旧轨迹。自动处理点状态着色。 |
+| `drawPatrol` | `(map, data)` | void | 绘制巡检执行轨迹。使用动态唯一 ID，支持多任务叠加显示。 |
+| `placePoint` | `(map, location, callback)` | void | 定位到指定坐标；若未传坐标则触发浏览器地理定位 API。 |
+
+---
+
+## 七、POI 搜索
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `addSearch` | `(containerId, bounds, callback)` | void | 为指定输入框绑定天地图 POI 搜索。自动创建结果列表、处理回车搜索及失焦隐藏逻辑。 |
+| `focusOnPOI` | `(poi)` | void | 飞行定位到指定 POI 并在地图上显示临时高亮弹窗。 |
+| `clearSearchResults` | `(containerId)` | void | 清空搜索结果列表 DOM 及地图上的 POI 高亮图层。 |
+
+---
+
+## 八、相机与视角控制
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `flyTo` | `(target)` | void | 平滑飞行至指定视角。支持 center, zoom, pitch, bearing 参数。 |
+| `flyToOrigin` | - | void | 飞行至配置文件定义的初始原点视角。 |
+| `flyToTarget` | - | void | 飞行至预设的目标点视角。 |
+| `overlook` | `(is2D)` | void | 切换 2D 俯视 / 3D 倾斜视角。 |
+| `locationArea` | `(target)` | void | 直接跳转至指定视角（无动画），内置参数校验防止非法值。 |
+| `enableScrollWheelZoom` | `(isOpen)` | void | 启用或禁用滚轮缩放交互。 |
+
+---
+
+## 九、辅助工具
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `setZoom` | `(map, points, zoomLevel?)` | void | 根据点集自适应视野边界，或设置指定缩放级别。兼容扁平数组与对象数组格式。 |
+| `_drawGridWithCenterLabels` | `(map, options)` | void | 绘制经纬度网格及中心区间标签（调试/辅助用）。 |
+| `clearGridWithCenterLabels` | `(map)` | void | 清除经纬度网格图层。 |
+| `resetCenterAndZoom` | `(map)` | void | 重置地图至配置文件定义的初始中心和缩放级。 |
+
+---
+
+## 十、地图导出
+
+| 函数名 | 参数 | 返回值 | 功能简介 |
+| :--- | :--- | :--- | :--- |
+| `exportBlob` | - | Promise<Blob> | 异步导出当前视图为 PNG Blob。自动合成 Mapbox 主画布与 AntV L7 叠加层。 |
+| `exportBase64` | - | Promise<String> | 异步导出当前视图为 Base64 字符串。自动合成多图层画布。 |
+
+---
+
+## ⚠️ 二开注意事项
+
+1.  **坐标系转换**：高德相关方法内部已自动执行 WGS84 → GCJ02 转换，请勿在外部重复转换。
+2.  **编辑状态清理**：调用 `render*` 更新图形时会自动先禁用旧编辑状态；手动移除图层请务必使用对应的 `remove*` 方法以确保事件监听器被正确清理。
+3.  **瓦片节流**：内置 300ms 瓦片请求节流机制，避免短时间内重复请求相同瓦片。
+4.  **弹窗偏移**：`addCustomPopup` 基础偏移为 `[37, -107]`，不同尺寸弹窗需通过 `addOnOffset` 参数微调。
+5.  **在线/离线模式**：底图来源由 `mapConfig.isOnline` 决定。离线模式使用本地 GeoServer 瓦片，在线模式使用天地图服务，切换时需确保对应服务可用。