@caoguo/maplibre 0.0.2 → 0.0.5

package/dist/index.d.ts

@@ -181,16 +181,89 @@ declare class ThemeSwitcher {
     remove(): void;
 }
 
+/**
+ * 图例控件（通用）。
+ *
+ * 行业专题图（水深色阶 / 光缆利用率 / 闸站状态 / 故障告警等）渲染后，
+ * 需要用户可读的图例说明。本控件接收数据驱动的图例项（label + color），
+ * 以「色块 + 文案」形式渲染；支持运行时 setItems 随图层切换更新。
+ *
+ * 设计为「纯函数 renderLegendHtml + 薄 DOM 绑定」：renderLegendHtml 不依赖浏览器，可独立单测。
+ */
+interface LegendItem {
+    /** 文案，如「水深 > 3m」「利用率高」 */
+    label: string;
+    /** 色值（CSS color，可与渲染层 paint 配色保持一致） */
+    color: string;
+    /** 标记形状：color 色块（默认）/ line 线段 */
+    shape?: 'color' | 'line';
+}
+interface LegendOptions {
+    /** 图例标题（可选） */
+    title?: string;
+    /** 图例项 */
+    items: LegendItem[];
+    /** 挂载容器（可选；不传则自动创建） */
+    container?: HTMLElement;
+}
+/** 纯函数：根据图例项生成 HTML 字符串（可单测） */
+declare function renderLegendHtml(items: LegendItem[], title?: string): string;
+/** 图例控件 */
+declare class LegendControl {
+    private el;
+    private bodyEl;
+    private opts;
+    constructor(options: LegendOptions);
+    private render;
+    /** 运行时更新图例项（随图层切换重新渲染） */
+    setItems(items: LegendItem[], title?: string): void;
+    /** 挂载到容器 */
+    addTo(container: HTMLElement): this;
+    remove(): void;
+}
+
+/**
+ * 地图导出控件（通用）。
+ *
+ * 行业专题图渲染后，常需导出当前视图为成果图（PNG）。
+ * 基于 maplibre-gl 画布 `toDataURL('image/png')` 生成截图并触发浏览器下载。
+ *
+ * 设计为「纯函数 triggerDownload + 薄 DOM 绑定」：triggerDownload 不依赖地图，可独立单测。
+ */
+interface ExportOptions {
+    /** 下载文件名（不含扩展名） */
+    filename?: string;
+    /** 挂载容器（可选；不传则自动创建） */
+    container?: HTMLElement;
+    /** 按钮文案 */
+    buttonText?: string;
+}
+/** 纯函数：触发浏览器下载（data URL） */
+declare function triggerDownload(dataUrl: string, filename: string): void;
+/** 导出控件 */
+declare class ExportControl {
+    private el;
+    private map;
+    private filename;
+    private onClick;
+    constructor(map: ExportControl['map'], options?: ExportOptions);
+    /** 导出当前地图视图为 PNG 并下载 */
+    export(): void;
+    /** 挂载到容器 */
+    addTo(container: HTMLElement): this;
+    remove(): void;
+}
+
 /**
  * 辉光线几何构建（T6 / F-1.3 纯逻辑部分）。
  *
- * 把 GeoJSON LineString 集合转换为「多遍辉光描边」所需的几何描述。
- * 渲染层（CustomLineLayer）再据此在 WebGL 中绘制：每遍一个宽度档 + 透明度档，
- * 叠加形成管线/路网/水系的辉光效果。
+ * 把 GeoJSON LineString 集合转换为「多遍描边」所需的三角形带几何。
+ * 渲染层（CustomLineLayer）据此在 WebGL 中以屏幕像素宽度的三角面叠加绘制，
+ * 每遍一个宽度档 + 透明度档，加法混合形成管线/路网/水系的辉光效果。
  *
  * 设计：本模块**不依赖 WebGL / maplibre**，纯函数可在 Node 单测。
  * 坐标投影使用简化 Web Mercator（经度→x、纬度→y 的归一化世界坐标），
- * 真实渲染时由 CustomLayer 的 matrix 变换到屏幕。
+ * 真实渲染时由 CustomLayer 的 matrix 变换到屏幕；线宽在屏幕空间计算。
  */
 interface GlowLine {
     /** 线坐标 [lng, lat][] */
@@ -199,54 +272,61 @@ interface GlowLine {
     group?: string;
 }
 interface GlowPass {
-    /** 相对基础宽度的倍数（核心线=1，外晕逐遍增大） */
-    widthScale: number;
+    /** 该遍屏幕像素宽度 */
+    width: number;
     /** 该遍不透明度（核心线高、外晕低） */
     opacity: number;
 }
 interface GlowGeometry {
-    /** 所有线（含分组标记）的归一化坐标序列 */
-    lines: {
-        points: [number, number][];
-        group?: string;
+    /**
+     * 扁平化顶点缓冲。每个顶点 5 个 float：
+     * [worldX, worldY, dirX, dirY, side]
+     * - worldX/worldY：该端点的归一化世界坐标
+     * - dirX/dirY：所在线段的世界空间方向（用于屏幕空间法线）
+     * - side：±1，左/右扩展符号
+     */
+    vertices: Float32Array;
+    /** 每遍在 vertices 中的顶点区间 [start, count]（按顶点数，非 float 数） */
+    passRanges: {
+        start: number;
+        count: number;
     }[];
-    /** 辉光多遍参数（从外晕到核心，或反之，由渲染层决定） */
+    /** 每遍参数（从最外晕到核心，由宽到窄） */
     passes: GlowPass[];
-    /** 总顶点数（用于缓冲分配） */
-    vertexCount: number;
+    /** 顶点属性跨距（float 数） */
+    stride: number;
 }
 /**
  * 生成辉光多遍档位。
  * @param passes 遍数（默认 4：3 层外晕 + 1 核心）
- * @param coreOpacity 核心线不透明度
+ * @param baseWidth 核心线像素宽度（默认 3）
  */
-declare function glowPasses(passes?: number, coreOpacity?: number): GlowPass[];
+declare function glowPasses(passes?: number, baseWidth?: number): GlowPass[];
 /**
- * 简化 Web Mercator 归一化（经度→x∈[-1,1]，纬度→y∈[-1,1]）。
+ * 简化 Web Mercator 归一化（经度→x∈[-1,1]，纬度→y 经墨卡托压缩）。
  * 仅用于几何构建与单测，真实投影在渲染层用 map 的 matrix。
  */
 declare function projectSimple(lng: number, lat: number): [number, number];
 /**
- * 构建辉光几何：投影每条线并统计顶点。
- * 顶点数 = 各线（点数-1）*2（线段两端），用于 Line 绘制。
+ * 构建辉光几何：对每条线、每遍、每段生成三角面（2 三角形 = 6 顶点）。
  */
 declare function buildGlowGeometry(lines: GlowLine[], opts?: {
     passes?: number;
-    coreOpacity?: number;
+    baseWidth?: number;
 }): GlowGeometry;
 
 /**
  * 辉光管线 Custom Layer（T6 / F-1.3 WebGL 渲染层）。
  *
  * 实现 MapLibre v4 `CustomLayerInterface`：在地图之上叠加绘制 GeoJSON 线，
- * 用多遍（glowPasses）描边形成管线/路网/水系的辉光效果。
+ * 用多遍（glowPasses）三角面描边形成管线/路网/水系的辉光效果。
  *
- * 设计：几何构建（投影/档位）在 `./glowGeometry` 纯函数中完成（可单测）；
+ * 设计：几何构建（投影/三角带）在 `./glowGeometry` 纯函数中完成（可单测）；
  * 本文件仅负责 WebGL 状态机与绘制，仅在浏览器执行。
+ * 线宽在屏幕空间按像素计算（标准 Mapbox line shader 思路），因此可随缩放保持视觉宽度。
  * 通过 `Map.addGlowLayer` 注入，调用方无需感知 WebGL 细节。
  *
- * 依赖 MapLibre 注入的 `matrix`（map 的 projectionMatrix * modelViewMatrix），
- * 与官方 CustomLayer 示例一致。
+ * 依赖 MapLibre 注入的 `matrix`（map 的 projectionMatrix * modelViewMatrix）。
  */
 
 /** MapLibre v4 CustomLayerInterface 最小子集（避免强类型耦合） */
@@ -278,7 +358,6 @@ declare class CustomLineLayer implements CustomLayerInterface {
     private lines;
     private colors;
     private baseWidth;
-    private passes;
     private program?;
     private buffer?;
     private geometry;
@@ -350,8 +429,93 @@ declare class LodController<T = unknown> {
     remove(): void;
 }
 
+/**
+ * 原生 MapLibre 地图 source 操作的幂等工具。
+ *
+ * 各业务 System（grid/water/pipeline/telecom/compute/transport）的 render()
+ * 通过 `this.map.instance` 直接调用原生 MapLibre，而非经 CaoguoMap 包装类的
+ * 幂等 addSource。为避免在每个 System 内重复书写 `if (!mlMap.getSource(id))`
+ * 样板，并根治「层级切换重渲染崩溃」（Source already exists），统一在此提供
+ * 幂等 upsert 与安全的 removeSource。
+ *
+ * 仅依赖原生 MapLibre 的 source 子集接口，便于各 System 直接传入 instance。
+ */
+/**
+ * 原生 MapLibre source 操作的子集接口。
+ *
+ * 仅 `getSource` 为必填——它是所有 helper 判断「source 是否存在」的统一探针。
+ * 其余方法全部可选，因为各业务 System 对 `this.map.instance` 的局部类型断言
+ * 只声明了实际用到的若干方法（如 topology 只取 getSource/removeSource，
+ * traffic 只取 addSource/addLayer），强制统一必填字段会与这些子集冲突。
+ * helper 内部对每个要调用的方法做存在性检查，缺失时安全跳过或回退，
+ * 保证类型与运行时都安全（真实 MapLibre 实例始终具备全部方法）。
+ */
+interface MlMapSourceApi {
+    getSource: (id: string) => unknown;
+    addSource?: (id: string, source: unknown) => void;
+    addLayer?: (layer: unknown) => void;
+    setData?: (id: string, data: unknown) => void;
+    removeSource?: (id: string) => void;
+}
+/**
+ * 幂等地确保一个 GeoJSON source 存在并持有给定数据。
+ *
+ * - 若 source 已存在且具备 setData：setData 更新（避免重复 addSource 抛错）。
+ * - 若 source 已存在但无 setData：回退为 addSource（MapLibre 对重复 id 会忽略/覆盖，
+ *   不抛错，仍可达成渲染目标）。
+ * - 若 source 不存在且具备 addSource：addSource 创建。
+ *
+ * 注意：若传入对象既无 setData 又无 addSource，则无法创建/更新 source。
+ * 各 System 传入的 `this.map.instance` 为真实 MapLibre 实例，始终具备这些方法。
+ *
+ * @param mlMap 原生 MapLibre 实例（或任意满足 MlMapSourceApi 的对象）
+ * @param id    source 唯一标识
+ * @param data  GeoJSON 数据（或 addSource 所需的 source spec）
+ */
+declare function upsertSource(mlMap: MlMapSourceApi, id: string, data: unknown): void;
+/**
+ * 安全地移除 source：仅当存在且具备 removeSource 时才移除，避免不存在时抛错。
+ *
+ * @param mlMap 原生 MapLibre 实例
+ * @param id    source 唯一标识
+ */
+declare function removeSourceSafe(mlMap: MlMapSourceApi, id: string): void;
+/**
+ * 安全地批量移除 source。
+ *
+ * @param mlMap 原生 MapLibre 实例
+ * @param ids   source 标识数组
+ */
+declare function removeSourcesSafe(mlMap: MlMapSourceApi, ids: string[]): void;
+
 type MapInstance = Map$1;
+/**
+ * WebGL 不可用时抛出（如无 GPU 的沙箱/无头环境、老旧浏览器）。
+ * 调用方应捕获并向用户展示降级提示，而非让页面崩溃。
+ */
+declare class WebGLUnavailableError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 探测当前环境是否可创建真正可用的 WebGL 上下文。
+ * 某些沙箱/无头浏览器会返回 canvas，且 getContext 也返回一个「伪对象」，
+ * 但上下文实际不可用（渲染时崩溃）。因此除了非 null 判断，还进一步验证
+ * 上下文确实能工作：能读出 VENDOR、能取到必要扩展，并捕获
+ * webglcontextcreationerror 事件。
+ */
+declare function isWebGLAvailable(): boolean;
 
+/**
+ * 全局配置（由应用入口注入一次，所有 Map 实例共享）。
+ * 用于把敏感 token（如天地图 key）从库内部解耦到应用侧，
+ * 避免硬编码、避免库 dist 中无法替换 import.meta.env 的问题。
+ */
+interface CaoguoMapGlobalConfig {
+    /** 天地图 token；未显式给 Map 传 tianditu 时自动生效 */
+    tiandituToken?: string;
+}
+declare function setGlobalConfig(cfg: CaoguoMapGlobalConfig): void;
+declare function getGlobalConfig(): CaoguoMapGlobalConfig;
 interface MapOptions {
     container: string | HTMLElement;
     center?: [number, number];
@@ -365,6 +529,19 @@ interface MapOptions {
      * 设定后可通过 `transformToMap` 在入图前自动纠偏。
      */
     dataCRS?: CRS;
+    /**
+     * 天地图（Tianditu）底图选项。传入后，**默认底图从 OSM 切换为天地图**
+     * （国内权威底图，CGCS2000 / Web Mercator，适配国内网络与坐标系）。
+     * token 由调用方注入，缺失时抛出 MissingTokenError。
+     */
+    tianditu?: {
+        token: string;
+        type?: TiandituType;
+        lang?: 'zh' | 'en';
+        subdomains?: number[];
+        tileSize?: number;
+        maxzoom?: number;
+    };
 }
 /**
  * 草果地图引擎封装（展示层骨架）。
@@ -414,6 +591,8 @@ declare class Map {
     removeLayer(id: string): void;
     on(event: string, layerId?: string, cb?: (e: unknown) => void): void;
     addSource(id: string, source: object): void;
+    /** 安全移除 source（不存在时静默忽略） */
+    removeSource(id: string): void;
     getSource(id: string): unknown;
     flyTo(opts: {
         center?: [number, number];
@@ -435,6 +614,26 @@ declare class Map {
      * 返回控件实例，可调用 .toggle() / .setTheme() / .remove()。
      */
     addThemeSwitcher(initial?: ThemeName): ThemeSwitcher;
+    /**
+     * 挂载图例控件（通用）：渲染数据驱动的色块/线段图例，说明专题图层语义。
+     * 返回控件实例，可调用 .setItems() 随图层切换更新、.remove() 卸载。
+     */
+    addLegendControl(options: {
+        title?: string;
+        items: {
+            label: string;
+            color: string;
+            shape?: 'color' | 'line';
+        }[];
+    }): LegendControl;
+    /**
+     * 挂载地图导出控件（通用）：点击按钮将当前视图导出为 PNG 下载。
+     * 返回控件实例，可调用 .remove() 卸载。
+     */
+    addExportControl(options?: {
+        filename?: string;
+        buttonText?: string;
+    }): ExportControl;
     /**
      * 挂载辉光管线 Custom Layer（T6 / F-1.3）。
      * 传入 GeoJSON 线集合，叠加渲染管线/路网/水系辉光效果。
@@ -453,7 +652,27 @@ declare class Map {
      * @returns LodController 实例（可 .getLevel() / .remove()）
      */
     addLodController<T = unknown>(levels: LodLevel<T>[], onLod: (e: LodChangeEvent<T>) => void): LodController<T>;
+    /**
+     * 启用 3D 地形渲染（F-1.5）。
+     *
+     * 注入 raster-dem 高程源并调用 maplibre-gl 原生 `setTerrain`，使地图呈现地形起伏。
+     * DEM 瓦片默认使用公共 Terrarium 源（elevation-tiles-prod，Terrain-RGB 编码，支持 CORS），
+     * 可在 opts.tiles 覆盖为私有瓦片服务（如 MinIO / 本地 MBTiles 服务）。
+     *
+     * @param opts.exaggeration 地形夸张系数（默认 1.5）
+     * @param opts.tiles DEM 瓦片模板，{z}/{x}/{y} 占位
+     * @param opts.encoding 'terrarium'（默认，Mapzen）| 'mapbox'
+     */
+    enableTerrain(opts?: {
+        sourceId?: string;
+        tiles?: string[];
+        encoding?: 'terrarium' | 'mapbox';
+        exaggeration?: number;
+        maxzoom?: number;
+    }): void;
+    /** 关闭 3D 地形渲染（F-1.5），并移除 DEM 源 */
+    disableTerrain(sourceId?: string): void;
     get instance(): Map$1;
 }
 
-export { type Bounds, type CRS, type CustomLayerInterface, CustomLineLayer, type GlowGeometry, type GlowLayerOptions, type GlowLine, type GlowPass, type GridShiftProvider, type LngLat, type LodChangeEvent, LodController, type LodLevel, Map, type MapInstance, type MapOptions, type Point, type ScaleBar, ScaleControl, type ScaleControlOptions, ThemeSwitcher, type ThemeSwitcherOptions, TiandituOptions, TiandituType, TileStoreBackend, type Transformer, buildGlowGeometry, cgcs2000ToWgs84, computeScaleBar, createTransformer, Map as default, fromWgs84, gcj02ToWgs84, glowPasses, isInChina, oppositeTheme, packGeoJSONToStore, projectSimple, resolveLod, setCgcs2000GridShift, suggestDensity, themeFromStyle, toWgs84, transformBounds, transformPoint, wgs84ToCgcs2000, wgs84ToGcj02 };
+export { type Bounds, type CRS, type CaoguoMapGlobalConfig, type CustomLayerInterface, CustomLineLayer, ExportControl, type ExportOptions, type GlowGeometry, type GlowLayerOptions, type GlowLine, type GlowPass, type GridShiftProvider, LegendControl, type LegendItem, type LegendOptions, type LngLat, type LodChangeEvent, LodController, type LodLevel, Map, type MapInstance, type MapOptions, type MlMapSourceApi, type Point, type ScaleBar, ScaleControl, type ScaleControlOptions, ThemeSwitcher, type ThemeSwitcherOptions, TiandituOptions, TiandituType, TileStoreBackend, type Transformer, WebGLUnavailableError, buildGlowGeometry, cgcs2000ToWgs84, computeScaleBar, createTransformer, Map as default, fromWgs84, gcj02ToWgs84, getGlobalConfig, glowPasses, isInChina, isWebGLAvailable, oppositeTheme, packGeoJSONToStore, projectSimple, removeSourceSafe, removeSourcesSafe, renderLegendHtml, resolveLod, setCgcs2000GridShift, setGlobalConfig, suggestDensity, themeFromStyle, toWgs84, transformBounds, transformPoint, triggerDownload, upsertSource, wgs84ToCgcs2000, wgs84ToGcj02 };