bluestar-maplibre 1.0.24

package/dist/blue-star/maplibre/src/bluestar.d.ts

@@ -0,0 +1,312 @@
+import { ComponentInternalInstance } from 'vue';
+import { WegFile, EventListenControl } from 'bluestar-util';
+import { XMap, XMapOptions } from './xmap/xmap';
+import { WegRenderer, WegRenderOption } from './components/wegRender/wegRender';
+import { WegRenderer2, WegRender2Options } from './components/wegRender2/wegRender2';
+import { ImageRender, ImageRenderData, ImageRenderOptions } from './components/imageRender/imageRender';
+import { BlueStarLoaded } from './vue/hook';
+/**
+ * BlueStar 配置接口
+ *
+ * @example
+ * ```typescript
+ * // 基本配置
+ * const config: BlueStarConfig = {
+ *   domId: 'map-container',
+ *   config: {
+ *     center: [120, 30],
+ *     zoom: 4
+ *   }
+ * };
+ *
+ * // 使用 Vue ref
+ * const mapDom = ref<HTMLDivElement>();
+ * const config: BlueStarConfig = {
+ *   domId: mapDom,
+ *   incomponent: false,  // 非组件模式
+ *   config: { /* ... *\/ }
+ * };
+ * ```
+ */
+export interface BlueStarConfig {
+    /** 地图容器 DOM 元素或 ID */
+    domId: HTMLDivElement | string;
+    /** 是否在 Vue 组件内使用（默认 true） */
+    incomponent?: boolean;
+    /** MapLibre GL 地图配置项 */
+    config: XMapOptions;
+}
+/** 地图事件控制器（已废弃，使用 listener 替代） */
+export declare const mapController: EventListenControl;
+/**
+ * BlueStar 核心类
+ *
+ * 基于 MapLibre GL JS 的高级封装，提供气象数据可视化功能
+ *
+ * @remarks
+ * **核心功能：**
+ * - 地图初始化和生命周期管理
+ * - Weg 气象数据渲染
+ * - 图片叠加渲染
+ * - 图层管理和排序
+ * - 事件监听系统
+ * - Vue 组件集成
+ *
+ * **使用示例：**
+ * ```typescript
+ * // 示例 1：独立使用（非 Vue 组件）
+ * const blueStar = new BlueStar({
+ *   domId: 'map-container',
+ *   incomponent: false,
+ *   config: {
+ *     center: [120, 30],
+ *     zoom: 4
+ *   }
+ * }, (blueStar, interceptor‌) => {
+ *   console.log('地图已加载');
+ *
+ *   // 渲染 Weg 数据
+ *   const renderer = blueStar.renderWeg(wegFile, {
+ *     colorRamp: [...],
+ *     gridValue: true
+ *   });
+ * });
+ *
+ * // 示例 2：在 Vue 组件中使用
+ * import { Map } from 'bluestar-maplibre';
+ *
+ * <template>
+ *   <Map :config="mapConfig" @load="onMapLoad" />
+ * </template>
+ *
+ * <script setup lang="ts">
+ * const onMapLoad = (blueStar: BlueStar, interceptor‌) => {
+ *   // 地图操作
+ *   blueStar.viewer.flyTo({ center: [116.4, 39.9] });
+ * };
+ * </script>
+ *
+ * // 示例 3：图层排序控制
+ * const blueStar = new BlueStar(config, callback);
+ * blueStar.setLayerLevelRule(['baselayer', 'heatmap', 'contour', 'vector']);
+ * ```
+ */
+export declare class BlueStar {
+    /** MapLibre GL 地图实例（通过 viewer 访问） */
+    viewer: XMap;
+    /** 地图容器 DOM 元素或 ID */
+    domId: HTMLDivElement | string;
+    /** 地图是否已准备就绪 */
+    ready: boolean;
+    /** 事件监听器注册表 */
+    listener: any;
+    /** 浮窗组件实例列表 */
+    bubbleList: ComponentInternalInstance[];
+    /**
+     * 创建 BlueStar 实例
+     *
+     * @param blueStarConfig - BlueStar 配置对象
+     * @param onLoaded - 地图加载完成后的回调函数
+     *
+     * @remarks
+     * **重要注意事项：**
+     * - 如果在 Vue 组件中使用（incomponent=true），会自动处理挂载和卸载
+     * - onLoaded 回调会传入 BlueStar 实例和请求拦截器
+     * - 地图加载是异步的，回调会在地图完全初始化后执行
+     */
+    constructor(blueStarConfig: BlueStarConfig, onLoaded: any);
+    /**
+     * 初始化浮窗点击事件处理
+     * @internal
+     */
+    private initBubbleClick;
+    /**
+     * 销毁地图实例并释放资源
+     *
+     * @example
+     * ```typescript
+     * // 手动销毁
+     * blueStar.destroy();
+     *
+     * // Vue 组件中会自动调用
+     * onUnmounted(() => {
+     *   blueStar.destroy();
+     * });
+     * ```
+     */
+    destroy(): void;
+    /**
+     * 渲染 Weg 气象网格数据
+     *
+     * @param weg - Weg 格式的气象数据
+     * @param config - 渲染配置选项
+     * @returns WegRenderer 实例，用于后续控制
+     *
+     * @example
+     * ```typescript
+     * // 温度场渲染
+     * const tempRenderer = blueStar.renderWeg(tempData, {
+     *   colorRamp: [
+     *     { value: -20, color: '#0000ff' },
+     *     { value: 40,  color: '#ff0000' }
+     *   ],
+     *   contour: [0, 5, 10, 15, 20],
+     *   gridValue: true,
+     *   alpha: 0.7
+     * });
+     *
+     * // 风场渲染（带粒子）
+     * const windRenderer = blueStar.renderWeg(windData, {
+     *   colorRamp: [...],
+     *   direction: true,
+     *   particle: true,
+     *   particleSpeed: 0.5
+     * });
+     *
+     * // 动态调整
+     * tempRenderer.fillFulling = true;
+     * windRenderer.particle = false;
+     * ```
+     */
+    renderWeg(weg: WegFile, config: WegRenderOption): WegRenderer;
+    /**
+     * 渲染 Weg 气象网格数据（xmap 原生参数版）
+     *
+     * 与 renderWeg 功能相同，但配置接口直接暴露 xmap 原生图层参数。
+     *
+     * @param weg - Weg 格式的气象数据
+     * @param config - 渲染配置选项（xmap 原生参数）
+     * @returns WegRenderer2 实例
+     *
+     * @example
+     * ```typescript
+     * const renderer = blueStar.renderWeg2(windData, {
+     *   fillFulling: true,
+     *   direction: true,
+     *   heatmap: {
+     *     colorRamp: [{ value: 0, color: '#00f' }, { value: 10, color: '#f00' }],
+     *     opacity: 0.8,
+     *   },
+     *   vector: {
+     *     color: '#0aa1ed',
+     *     cell: 4,
+     *   },
+     *   particleConfig: {
+     *     size: 2,
+     *     speed: 0.3,
+     *   },
+     * });
+     */
+    renderWeg2(weg: WegFile, config: WegRender2Options): WegRenderer2;
+    /**
+     * 渲染图片叠加层
+     *
+     * @param data - 图片数据或 WegFile
+     * @param option - 可选的渲染选项
+     * @returns ImageRender 实例
+     *
+     * @example
+     * ```typescript
+     * // 渲染雷达图
+     * const radarRender = blueStar.renderImage({
+     *   url: 'https://example.com/radar.png',
+     *   west: 115.0,
+     *   south: 39.0,
+     *   east: 117.0,
+     *   north: 41.0
+     * }, {
+     *   alpha: 0.7,
+     *   linerValue: true
+     * });
+     *
+     * // 从 WegFile 生成图片
+     * const imageRender = blueStar.renderImage(wegFile, {
+     *   alpha: 0.8
+     * });
+     *
+     * // 动态更换图片
+     * radarRender.setImage('new-radar.png');
+     *
+     * // 调整透明度
+     * radarRender.alpha = 0.5;
+     * ```
+     */
+    renderImage(data: ImageRenderData | WegFile, option?: ImageRenderOptions): ImageRender;
+    /**
+     * 添加事件监听器
+     *
+     * @param event - 事件名称
+     * @param callback - 回调函数
+     * @param loadResult - 可选的加载结果对象
+     *
+     * @example
+     * ```typescript
+     * // 监听地图就绪事件
+     * blueStar.addEventListener('BlueStar:ready', (blueStar, interceptor‌) => {
+     *   console.log('地图已就绪');
+     * });
+     *
+     * // 监听其他自定义事件
+     * blueStar.addEventListener('custom:event', (data) => {
+     *   console.log('自定义事件', data);
+     * });
+     * ```
+     */
+    addEventListener(event: string, callback: (...arg: any[]) => void, loadResult?: BlueStarLoaded): void;
+    /**
+     * 设置图层层级规则
+     *
+     * 控制不同类型图层的渲染顺序，规则越靠前越先渲染（在底层）
+     *
+     * @param levelRule - 层级规则数组，每项为图层名称前缀
+     *
+     * @example
+     * ```typescript
+     * // 设置图层顺序：底图 -> 色斑图 -> 等值线 -> 矢量箭头 -> 粒子
+     * blueStar.setLayerLevelRule([
+     *   'baselayer',      // 底图图层
+     *   'heatmap',        // 热力图/色斑图
+     *   'contour',        // 等值线
+     *   'vector',         // 矢量箭头
+     *   'particle'        // 粒子效果
+     * ]);
+     *
+     * // 获取当前规则
+     * const rules = blueStar.getLayerLevelRule();
+     * ```
+     *
+     * @remarks
+     * **重要注意事项：**
+     * - 图层 ID 格式：`{name}__{uuid}`
+     * - 规则匹配使用前缀匹配（startsWith）
+     * - 未匹配的图层保持原有顺序
+     * - 调用此方法会立即触发图层排序
+     */
+    setLayerLevelRule(levelRule: string[]): void;
+    /**
+     * 执行图层排序
+     *
+     * 根据设置的层级规则重新排列图层顺序
+     *
+     * @remarks
+     * **内部实现：**
+     * - 过滤出所有自定义图层（包含 '__' 且不包含 'baselayer__'）
+     * - 按照 levelRule 的顺序重新排列
+     * - 使用 moveLayer 方法调整图层顺序
+     *
+     * @internal
+     */
+    sortLayer(): void;
+    /**
+     * 获取当前图层层级规则
+     *
+     * @returns 层级规则数组的副本
+     *
+     * @example
+     * ```typescript
+     * const rules = blueStar.getLayerLevelRule();
+     * console.log('当前规则:', rules);
+     * ```
+     */
+    getLayerLevelRule(): string[];
+}

package/dist/blue-star/maplibre/src/components/imageRender/imageRender.d.ts

@@ -0,0 +1,239 @@
+import { WegFile } from 'bluestar-util';
+import { RectangleRange } from '../../interface/position';
+import { BlueStar } from '../../bluestar';
+/**
+ * 图片渲染数据配置
+ * 定义在地图上渲染图片所需的地理范围和资源信息
+ *
+ * @example
+ * ```typescript
+ * // 使用 URL 加载图片
+ * const imageData: ImageRenderData = {
+ *     url: 'https://example.com/weather-map.png',
+ *     west: 115.0,
+ *     south: 39.0,
+ *     east: 117.0,
+ *     north: 41.0
+ * };
+ *
+ * // 使用本地 Blob URL
+ * const blobImageData: ImageRenderData = {
+ *     uri: 'blob:http://localhost:3000/xxx',
+ *     west: 120.0,
+ *     south: 30.0,
+ *     east: 122.0,
+ *     north: 32.0
+ * };
+ * ```
+ */
+export interface ImageRenderData {
+    /**
+     * 图片 URI 资源位置
+     * 可以是 DataURL、Blob URL 或本地文件路径
+     */
+    uri?: string;
+    /**
+     * 图片 URL 地址
+     * 网络图片或本地图片的 HTTP/HTTPS 链接
+     */
+    url?: string;
+    /**
+     * 西边界经度（最小经度）
+     */
+    west: number;
+    /**
+     * 南边界纬度（最小纬度）
+     */
+    south: number;
+    /**
+     * 东边界经度（最大经度）
+     */
+    east: number;
+    /**
+     * 北边界纬度（最大纬度）
+     */
+    north: number;
+}
+/**
+ * 图片渲染选项配置
+ */
+export interface ImageRenderOptions {
+    /**
+     * 图片透明度（0.0-1.0）
+     * @defaultValue 1.0
+     */
+    alpha?: number;
+    /**
+     * 是否使用线性插值渲染
+     * - true: 线性插值，图像更平滑
+     * - false: 最近邻插值，保持像素化效果
+     * @defaultValue true
+     */
+    linerValue?: boolean;
+}
+/**
+ * 图片渲染器类
+ * 用于在地图上叠加地理参考图片
+ *
+ * @example
+ * ```typescript
+ * // 创建图片渲染器
+ * const imageRender = new ImageRender(blueStar, {
+ *     url: 'https://example.com/radar.png',
+ *     west: 115.0,
+ *     south: 39.0,
+ *     east: 117.0,
+ *     north: 41.0
+ * }, {
+ *     alpha: 0.7,
+ *     linerValue: true
+ * });
+ *
+ * // 更换图片
+ * imageRender.setImage('new-image.png');
+ *
+ * // 调整透明度
+ * imageRender.alpha = 0.5;
+ *
+ * // 销毁渲染器
+ * imageRender.destroy();
+ * ```
+ *
+ * @remarks
+ * **重要注意事项：**
+ * - 支持 WegFile 格式自动转换为图片
+ * - 使用 MapLibre GL 的 image source 类型
+ * - 图片会根据地理坐标进行投影变换
+ * - 使用后应调用 destroy() 释放资源
+ */
+export declare class ImageRender {
+    private bluestar;
+    /**
+     * MapLibre GL 地图实例
+     */
+    private map;
+    /**
+     * 图片透明度（内部存储）
+     */
+    private _alpha;
+    /**
+     * 图片源唯一标识符
+     */
+    sourceId: string;
+    /**
+     * 图片图层唯一标识符
+     */
+    imageLayerId: string;
+    /**
+     * 图片显示地理范围
+     */
+    bound: RectangleRange;
+    /**
+     * 是否使用线性插值
+     */
+    linerValue: boolean;
+    /**
+     * 当前图片 URI（用于内存管理）
+     */
+    private uri;
+    /**
+     * 创建图片渲染器实例
+     * @param bluestar - BlueStar 实例
+     * @param imageRenderData - 图片渲染数据配置或 WegFile 对象
+     * @param imageRenderOptions - 可选的渲染选项配置
+     */
+    constructor(bluestar: BlueStar, imageRenderData: ImageRenderData | WegFile, imageRenderOptions?: ImageRenderOptions);
+    /**
+     * 初始化图片渲染
+     * @param imageRenderData - 图片数据或 WegFile
+     * @internal
+     */
+    private init;
+    /**
+     * 更换显示的图片
+     *
+     * @param imageUrl - 新图片的 URL 地址
+     * @param bound - 可选的新显示范围，不传则使用原有范围
+     *
+     * @example
+     * ```typescript
+     * // 仅更换图片
+     * imageRender.setImage('new-radar-image.png');
+     *
+     * // 同时更换图片和范围
+     * imageRender.setImage('new-image.png', {
+     *     west: 116.0,
+     *     south: 39.5,
+     *     east: 117.5,
+     *     north: 40.5
+     * });
+     * ```
+     *
+     * @remarks
+     * **重要注意事项：**
+     * - 如果之前使用的是 Blob URL，会自动调用 URL.revokeObjectURL() 释放内存
+     * - bound 参数是可选的，不传则保持原有地理范围
+     */
+    setImage(imageUrl: string, bound?: RectangleRange): void;
+    /**
+     * 设置 WegFile 数据（setter 语法糖）
+     * @param wegFile - WegFile 对象
+     */
+    set data(wegFile: WegFile);
+    /**
+     * 设置 WegFile 数据并重新渲染
+     *
+     * @param wegFile - WegFile 格式的气象网格数据
+     *
+     * @example
+     * ```typescript
+     * // 方式 1：使用 setter 语法
+     * imageRender.data = wegFile;
+     *
+     * // 方式 2：直接调用方法
+     * await imageRender.setWegData(wegFile);
+     * ```
+     */
+    setWegData(wegFile: WegFile): Promise<void>;
+    /**
+     * 设置图片透明度
+     * @param alpha - 透明度值（0.0-1.0）
+     *
+     * @example
+     * ```typescript
+     * // 半透明效果
+     * imageRender.alpha = 0.5;
+     *
+     * // 完全不透明
+     * imageRender.alpha = 1.0;
+     *
+     * // 完全透明（隐藏）
+     * imageRender.alpha = 0.0;
+     * ```
+     */
+    set alpha(alpha: number);
+    /**
+     * 获取当前透明度值
+     * @returns 透明度值（0.0-1.0）
+     */
+    get alpha(): number;
+    /**
+     * 销毁图片图层和源
+     * 释放相关资源
+     *
+     * @example
+     * ```typescript
+     * // 组件卸载时清理资源
+     * onUnmounted(() => {
+     *     imageRender.destroy();
+     * });
+     * ```
+     *
+     * @remarks
+     * **重要注意事项：**
+     * - 会移除对应的图层和源
+     * - 如果使用了 Blob URL，会自动释放内存
+     * - 销毁后不应再使用该实例
+     */
+    destroy(): void;
+}

package/dist/blue-star/maplibre/src/components/render.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 渲染器基类
+ * 为所有渲染器提供统一的 ID 生成机制
+ *
+ * @example
+ * ```typescript
+ * // 创建带名称的渲染器
+ * const renderer = new Render('wegRenderer');
+ * const id1 = renderer.createId(); // "wegRenderer__xxx-xxx-xxx"
+ *
+ * // 创建不带名称的渲染器
+ * const anonymousRenderer = new Render();
+ * const id2 = anonymousRenderer.createId(); // "yyy-yyy-yyy"
+ * ```
+ *
+ * @remarks
+ * **重要注意事项：**
+ * - 子类应该继承此类以获得唯一的图层/源 ID
+ * - ID 格式：`{name}__{uuid}` 或 `{uuid}`（当 name 为空时）
+ * - 使用 UUID v4 算法确保唯一性
+ */
+export declare class Render {
+    /**
+     * 渲染器名称标识
+     * 用于生成的 ID 前缀，便于调试和识别
+     */
+    name: string;
+    /**
+     * 创建渲染器实例
+     * @param name - 渲染器名称（可选），用作 ID 前缀
+     */
+    constructor(name?: string);
+    /**
+     * 创建唯一标识符
+     * 生成格式化的 UUID，带有可选的名称前缀
+     *
+     * @returns 唯一标识符字符串
+     *
+     * @example
+     * ```typescript
+     * const renderer = new Render('heatmap');
+     * const sourceId = renderer.createId();
+     * // 结果："heatmap__a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+     * ```
+     */
+    createId(): string;
+}