@movk/maplibre 1.0.0

package/dist/runtime/components/layers/RasterLayer.vue.d.ts

@@ -0,0 +1,35 @@
+type __VLS_Props = {
+    /** 图层 id；省略时自动生成 */
+    layerId?: string;
+    /** URL 模板瓦片地址（{z}/{x}/{y} 占位） */
+    tiles: string[];
+    /**
+     * 瓦片尺寸
+     * @defaultValue 256
+     */
+    tileSize?: number;
+    /**
+     * 瓦片坐标方案
+     * @defaultValue 'xyz'
+     */
+    scheme?: 'xyz' | 'tms';
+    /** 数据源最小缩放级别 */
+    minzoom?: number;
+    /** 数据源最大缩放级别 */
+    maxzoom?: number;
+    /** 版权信息 */
+    attribution?: string;
+    /**
+     * 不透明度
+     * @defaultValue 1
+     */
+    opacity?: number;
+    /** 插入到该图层之前 */
+    beforeId?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    opacity: number;
+    tileSize: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/layers/VideoLayer.d.vue.ts

@@ -0,0 +1,28 @@
+import type { VideoSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
+type __VLS_Props = {
+    /** 图层 id；省略时自动生成 */
+    layerId?: string;
+    /** 视频地址列表（多格式回退） */
+    urls: string[];
+    /** 四角经纬度：左上/右上/右下/左下 */
+    coordinates: VideoSourceSpecification['coordinates'];
+    /**
+     * 不透明度
+     * @defaultValue 1
+     */
+    opacity?: number;
+    /** 插入到该图层之前 */
+    beforeId?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    /** 播放视频 */
+    play: () => void | undefined;
+    /** 暂停视频 */
+    pause: () => void | undefined;
+    /** 底层 video 元素 */
+    video: () => HTMLVideoElement | undefined;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    opacity: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/layers/VideoLayer.vue

@@ -0,0 +1,38 @@
+<script setup>
+import { computed, useId } from "vue";
+import { useMap } from "../../composables/useMap";
+import MaplibreSource from "../Source.vue";
+import MaplibreLayer from "../Layer.vue";
+const props = defineProps({
+  layerId: { type: String, required: false },
+  urls: { type: Array, required: true },
+  coordinates: { type: Array, required: true },
+  opacity: { type: Number, required: false, default: 1 },
+  beforeId: { type: String, required: false }
+});
+const ctx = useMap();
+const id = props.layerId ?? `movk-video-${useId()}`;
+const source = computed(() => ({
+  type: "video",
+  urls: props.urls,
+  coordinates: props.coordinates
+}));
+const paint = computed(() => ({ "raster-opacity": props.opacity }));
+function videoSource() {
+  return ctx.map.value?.getSource(id);
+}
+defineExpose({
+  /** 播放视频 */
+  play: () => videoSource()?.play(),
+  /** 暂停视频 */
+  pause: () => videoSource()?.pause(),
+  /** 底层 video 元素 */
+  video: () => videoSource()?.getVideo()
+});
+</script>
+
+<template>
+  <MaplibreSource :source-id="id" :source="source">
+    <MaplibreLayer :layer-id="id" type="raster" :source="id" :paint="paint" :before-id="beforeId" />
+  </MaplibreSource>
+</template>

package/dist/runtime/components/layers/VideoLayer.vue.d.ts

@@ -0,0 +1,28 @@
+import type { VideoSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
+type __VLS_Props = {
+    /** 图层 id；省略时自动生成 */
+    layerId?: string;
+    /** 视频地址列表（多格式回退） */
+    urls: string[];
+    /** 四角经纬度：左上/右上/右下/左下 */
+    coordinates: VideoSourceSpecification['coordinates'];
+    /**
+     * 不透明度
+     * @defaultValue 1
+     */
+    opacity?: number;
+    /** 插入到该图层之前 */
+    beforeId?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    /** 播放视频 */
+    play: () => void | undefined;
+    /** 暂停视频 */
+    pause: () => void | undefined;
+    /** 底层 video 元素 */
+    video: () => HTMLVideoElement | undefined;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    opacity: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/composables/defineMaplibreControl.d.ts

@@ -0,0 +1,3 @@
+import type { IControl, Map as MaplibreMap } from 'maplibre-gl';
+/** 用回调式 onAdd/onRemove 快速定义一个自定义 MapLibre 控件。 */
+export declare function defineMaplibreControl(onAdd: (map: MaplibreMap) => HTMLElement, onRemove: (map: MaplibreMap) => void): IControl;

package/dist/runtime/composables/defineMaplibreControl.js

@@ -0,0 +1,6 @@
+export function defineMaplibreControl(onAdd, onRemove) {
+  return {
+    onAdd,
+    onRemove
+  };
+}

package/dist/runtime/composables/useFeatureState.d.ts

@@ -0,0 +1,35 @@
+import type { ShallowRef } from 'vue';
+import type { MapGeoJSONFeature } from 'maplibre-gl';
+export interface UseFeatureStateOptions {
+    /** 目标地图 id；在 MaplibreMap 子树外使用时必填 */
+    mapId?: string;
+    /**
+     * 维护 hover 状态
+     * @defaultValue true
+     */
+    hover?: boolean;
+    /**
+     * 维护 click 选中状态
+     * @defaultValue true
+     */
+    select?: boolean;
+    /**
+     * 悬浮时设置 pointer 指针
+     * @defaultValue true
+     */
+    cursor?: boolean;
+}
+export interface UseFeatureStateReturn {
+    /** 当前悬浮要素 */
+    hovered: ShallowRef<MapGeoJSONFeature | undefined>;
+    /** 当前选中要素 */
+    selected: ShallowRef<MapGeoJSONFeature | undefined>;
+    /** 清除选中 */
+    clearSelection: () => void;
+}
+/**
+ * 在目标图层上维护 feature-state 的 hover/selected 状态，
+ * 消费侧 paint 用 ['feature-state', 'hover' | 'selected'] 表达式驱动样式。
+ * 要素必须有 id（或 source 配置 promoteId / generateId）。
+ */
+export declare function useFeatureState(layerId: string, options?: UseFeatureStateOptions): UseFeatureStateReturn;

package/dist/runtime/composables/useFeatureState.js

@@ -0,0 +1,76 @@
+import { onMounted, onUnmounted, shallowRef } from "vue";
+import { useContextResolver } from "../domains/map/resolve.js";
+import { logger } from "../utils/logger.js";
+export function useFeatureState(layerId, options = {}) {
+  const { hover = true, select = true, cursor = true } = options;
+  const resolve = useContextResolver(options.mapId);
+  const hovered = shallowRef();
+  const selected = shallowRef();
+  let boundMap;
+  function clearState(map, feature, key) {
+    try {
+      map.removeFeatureState(feature, key);
+    } catch {
+    }
+  }
+  function setCursor(map, value) {
+    const canvas = map.getCanvas();
+    if (canvas) canvas.style.cursor = value;
+  }
+  function onMove(event) {
+    const map = boundMap;
+    const feature = event.features?.[0];
+    if (!map || !feature || feature.id === void 0) return;
+    if (cursor) setCursor(map, "pointer");
+    if (hovered.value?.id === feature.id) return;
+    if (hovered.value) clearState(map, hovered.value, "hover");
+    map.setFeatureState(feature, { hover: true });
+    hovered.value = feature;
+  }
+  function onLeave() {
+    const map = boundMap;
+    if (!map) return;
+    if (cursor) setCursor(map, "");
+    if (hovered.value) clearState(map, hovered.value, "hover");
+    hovered.value = void 0;
+  }
+  function onClick(event) {
+    const map = boundMap;
+    const feature = event.features?.[0];
+    if (!map || !feature || feature.id === void 0) return;
+    if (selected.value) clearState(map, selected.value, "selected");
+    map.setFeatureState(feature, { selected: true });
+    selected.value = feature;
+  }
+  function clearSelection() {
+    if (boundMap && selected.value) clearState(boundMap, selected.value, "selected");
+    selected.value = void 0;
+  }
+  onMounted(async () => {
+    const ctx = resolve();
+    if (!ctx) {
+      logger.warn("useFeatureState: no map context found; pass options.mapId or call inside <MaplibreMap>.");
+      return;
+    }
+    const map = await ctx.whenLoaded();
+    boundMap = map;
+    if (hover) {
+      map.on("mousemove", layerId, onMove);
+      map.on("mouseleave", layerId, onLeave);
+    }
+    if (select) map.on("click", layerId, onClick);
+  });
+  onUnmounted(() => {
+    const map = boundMap;
+    if (!map) return;
+    if (hover) {
+      map.off("mousemove", layerId, onMove);
+      map.off("mouseleave", layerId, onLeave);
+      onLeave();
+    }
+    if (select) map.off("click", layerId, onClick);
+    clearSelection();
+    boundMap = void 0;
+  });
+  return { hovered, selected, clearSelection };
+}

package/dist/runtime/composables/useFrameIcon.d.ts

@@ -0,0 +1,17 @@
+export interface UseFrameIconOptions {
+    /** 注册到样式的图片名(symbol 图层 icon-image 引用) */
+    imageName: string;
+    /** 纹理边长(像素) */
+    size: number;
+    /** 当前帧序列(响应式取值) */
+    frames: () => ImageData[];
+    /** 固定帧率,durations 缺省时生效 */
+    fps?: number;
+    /** 每帧时长 ms(响应式取值),优先于 fps */
+    durations?: () => number[] | undefined;
+}
+/**
+ * 帧动画图标生命周期:注册 StyleImageInterface、样式重载补回、styleimagemissing 兜底、卸载清理。
+ * SpriteImage / AnimatedImage 共用,确保纹理建立与缺图兜底逻辑一致。
+ */
+export declare function useFrameIcon(options: UseFrameIconOptions): void;

package/dist/runtime/composables/useFrameIcon.js

@@ -0,0 +1,36 @@
+import { onUnmounted } from "vue";
+import { useMap } from "./useMap.js";
+import { createFrameStyleImage } from "../utils/frame-icon.js";
+export function useFrameIcon(options) {
+  const ctx = useMap();
+  const { imageName } = options;
+  const image = createFrameStyleImage({
+    size: options.size,
+    frames: options.frames,
+    fps: options.fps,
+    durations: options.durations,
+    getMap: () => ctx.map.value
+  });
+  function ensureImage(map) {
+    if (!map.isStyleLoaded() || map.hasImage(imageName)) return;
+    map.addImage(imageName, image);
+  }
+  function onMissing(e) {
+    const map = ctx.map.value;
+    if (e.id === imageName && map && !map.hasImage(imageName)) {
+      map.addImage(imageName, image);
+    }
+  }
+  const stopReady = ctx.onReady((map) => {
+    ensureImage(map);
+    map.off("styleimagemissing", onMissing);
+    map.on("styleimagemissing", onMissing);
+  });
+  onUnmounted(() => {
+    stopReady();
+    const map = ctx.map.value;
+    if (!map) return;
+    map.off("styleimagemissing", onMissing);
+    if (map.hasImage(imageName)) map.removeImage(imageName);
+  });
+}

package/dist/runtime/composables/useMap.d.ts

@@ -0,0 +1,3 @@
+import type { MaplibreContext } from '../types';
+/** 注入当前 MaplibreMap 的上下文；必须在 MaplibreMap 子树内调用。 */
+export declare function useMap(): MaplibreContext;

package/dist/runtime/composables/useMap.js

@@ -0,0 +1,9 @@
+import { inject } from "vue";
+import { MaplibreContextKey } from "../domains/map/context.js";
+export function useMap() {
+  const context = inject(MaplibreContextKey, null);
+  if (!context) {
+    throw new Error("[movk-maplibre] useMap() must be called inside a <MaplibreMap> component.");
+  }
+  return context;
+}

package/dist/runtime/composables/useMapAnimation.d.ts

@@ -0,0 +1,21 @@
+import type { Ref } from 'vue';
+import type { Map as MaplibreMap } from 'maplibre-gl';
+export interface UseMapAnimationOptions {
+    /** 目标地图 id；在 MaplibreMap 子树外使用时必填 */
+    mapId?: string;
+    /**
+     * 创建后立即启动
+     * @defaultValue true
+     */
+    immediate?: boolean;
+}
+export interface UseMapAnimationReturn {
+    pause: () => void;
+    resume: () => void;
+    isActive: Readonly<Ref<boolean>>;
+}
+/**
+ * 地图帧动画原语：基于 useRafFn（组件卸载自动停止），
+ * 仅在地图存在且样式就绪时调用 frame，供动效组件与帧驱动图片复用。
+ */
+export declare function useMapAnimation(frame: (map: MaplibreMap, elapsedMs: number) => void, options?: UseMapAnimationOptions): UseMapAnimationReturn;

package/dist/runtime/composables/useMapAnimation.js

@@ -0,0 +1,13 @@
+import { useRafFn } from "@vueuse/core";
+import { useContextResolver } from "../domains/map/resolve.js";
+export function useMapAnimation(frame, options = {}) {
+  const resolve = useContextResolver(options.mapId);
+  let start;
+  const { pause, resume, isActive } = useRafFn(({ timestamp }) => {
+    const map = resolve()?.map.value;
+    if (!map || !map.isStyleLoaded()) return;
+    start ??= timestamp;
+    frame(map, timestamp - start);
+  }, { immediate: options.immediate ?? true });
+  return { pause, resume, isActive };
+}

package/dist/runtime/composables/useMapExport.d.ts

@@ -0,0 +1,34 @@
+export interface UseMapExportOptions {
+    /** 目标地图 id；在 MaplibreMap 子树外使用时必填 */
+    mapId?: string;
+}
+export interface ExportImageOptions {
+    /**
+     * 图像格式
+     * @defaultValue 'image/png'
+     */
+    format?: 'image/png' | 'image/jpeg' | 'image/webp';
+    /**
+     * 有损格式质量 0-1
+     * @defaultValue 0.92
+     */
+    quality?: number;
+}
+export interface DownloadOptions extends ExportImageOptions {
+    /**
+     * 下载文件名
+     * @defaultValue 'map.png'
+     */
+    fileName?: string;
+}
+export interface UseMapExportReturn {
+    /** 导出当前地图为 dataURL */
+    exportImage: (options?: ExportImageOptions) => Promise<string>;
+    /** 导出并触发浏览器下载 */
+    download: (options?: DownloadOptions) => Promise<void>;
+}
+/**
+ * 地图导出：在 render 回调内同步读画布，免 preserveDrawingBuffer 改造。
+ * WebGL 缓冲区在帧渲染后即被清空，故必须在 render 事件回调内取 toDataURL。
+ */
+export declare function useMapExport(options?: UseMapExportOptions): UseMapExportReturn;

package/dist/runtime/composables/useMapExport.js

@@ -0,0 +1,35 @@
+import { useContextResolver } from "../domains/map/resolve.js";
+import { logger } from "../utils/logger.js";
+export function useMapExport(options = {}) {
+  const resolve = useContextResolver(options.mapId);
+  async function exportImage(opts = {}) {
+    const ctx = resolve();
+    if (!ctx) {
+      throw new Error("[movk-maplibre] useMapExport: no map context found; pass options.mapId or call inside <MaplibreMap>.");
+    }
+    const map = await ctx.whenLoaded();
+    return new Promise((resolve2, reject) => {
+      map.once("render", () => {
+        try {
+          resolve2(map.getCanvas().toDataURL(opts.format ?? "image/png", opts.quality ?? 0.92));
+        } catch (error) {
+          reject(error instanceof Error ? error : new Error(String(error)));
+        }
+      });
+      map.triggerRepaint();
+    });
+  }
+  async function download(opts = {}) {
+    try {
+      const dataUrl = await exportImage(opts);
+      const link = document.createElement("a");
+      link.href = dataUrl;
+      link.download = opts.fileName ?? "map.png";
+      link.click();
+    } catch (error) {
+      logger.warn("Map export failed:", error);
+      throw error;
+    }
+  }
+  return { exportImage, download };
+}

package/dist/runtime/composables/useMaplibre.d.ts

@@ -0,0 +1,6 @@
+import type { MaplibreContext } from '../types';
+/**
+ * 按 id 从注册表获取地图上下文（逃生口）。
+ * 用于在组件树之外或跨路由访问已挂载的地图；未找到时返回 undefined。
+ */
+export declare function useMaplibre(id: string): MaplibreContext | undefined;

package/dist/runtime/composables/useMaplibre.js

@@ -0,0 +1,4 @@
+import { getMapContext } from "../domains/map/registry.js";
+export function useMaplibre(id) {
+  return getMapContext(id);
+}

package/dist/runtime/composables/useMaplibreCamera.d.ts

@@ -0,0 +1,15 @@
+import type { CameraOptions, EaseToOptions, FitBoundsOptions, FlyToOptions, LngLatBoundsLike } from 'maplibre-gl';
+import type { GeoJSON } from 'geojson';
+export interface UseMaplibreCameraOptions {
+    /** 目标地图 id；在 MaplibreMap 子树外使用时必填 */
+    mapId?: string;
+}
+export interface UseMaplibreCameraReturn {
+    flyTo: (options: FlyToOptions) => Promise<void>;
+    easeTo: (options: EaseToOptions) => Promise<void>;
+    jumpTo: (options: CameraOptions) => Promise<void>;
+    /** 缩放到目标范围；target 支持包围盒或任意 GeoJSON（自动求包围盒） */
+    fitBounds: (target: LngLatBoundsLike | GeoJSON, options?: FitBoundsOptions) => Promise<void>;
+}
+/** 相机操作助手；所有方法等待地图加载完成后执行。 */
+export declare function useMaplibreCamera(options?: UseMaplibreCameraOptions): UseMaplibreCameraReturn;

package/dist/runtime/composables/useMaplibreCamera.js

@@ -0,0 +1,32 @@
+import { useContextResolver } from "../domains/map/resolve.js";
+import { boundsOfGeoJSON } from "../utils/geometry.js";
+import { logger } from "../utils/logger.js";
+function isGeoJSON(target) {
+  return !Array.isArray(target) && typeof target === "object" && target !== null && typeof target.type === "string";
+}
+export function useMaplibreCamera(options = {}) {
+  const resolve = useContextResolver(options.mapId);
+  async function withMap(action) {
+    const ctx = resolve();
+    if (!ctx) {
+      logger.warn("useMaplibreCamera: no map context found; pass options.mapId or call inside <MaplibreMap>.");
+      return;
+    }
+    action(await ctx.whenLoaded());
+  }
+  return {
+    flyTo: (options2) => withMap((map) => map.flyTo(options2)),
+    easeTo: (options2) => withMap((map) => map.easeTo(options2)),
+    jumpTo: (options2) => withMap((map) => map.jumpTo(options2)),
+    fitBounds(target, fitOptions) {
+      return withMap((map) => {
+        const bounds = isGeoJSON(target) ? boundsOfGeoJSON(target) : target;
+        if (!bounds) {
+          logger.warn("fitBounds: target GeoJSON has no coordinates.");
+          return;
+        }
+        map.fitBounds(bounds, fitOptions);
+      });
+    }
+  };
+}

package/dist/runtime/composables/useMaplibreDraw.d.ts

@@ -0,0 +1,10 @@
+import type { MaplibreDrawContext } from '../types';
+export interface UseMaplibreDrawOptions {
+    /** 目标地图 id；在 MaplibreDrawControl 子树外使用时必填 */
+    mapId?: string;
+}
+/**
+ * 获取绘制上下文：省略 mapId 时注入最近的 MaplibreDrawControl，
+ * 传入 mapId 时按 id 查注册表，可在其子树外（如全局面板）驱动绘制。
+ */
+export declare function useMaplibreDraw(options?: UseMaplibreDrawOptions): MaplibreDrawContext;

package/dist/runtime/composables/useMaplibreDraw.js

@@ -0,0 +1,34 @@
+import { computed, inject } from "vue";
+import { DrawKey } from "../domains/map/draw.js";
+import { getDrawContext } from "../domains/map/draw-registry.js";
+import { logger } from "../utils/logger.js";
+function createRemoteContext(mapId) {
+  function resolve(action) {
+    const context = getDrawContext(mapId);
+    if (!context) logger.warn(`useMaplibreDraw: no <MaplibreDrawControl> registered for map "${mapId}"; ${action} ignored.`);
+    return context;
+  }
+  return {
+    mapId,
+    draw: computed(() => getDrawContext(mapId)?.draw.value),
+    whenReady() {
+      const context = getDrawContext(mapId);
+      return context ? context.whenReady() : Promise.reject(new Error(`[movk-maplibre] no <MaplibreDrawControl> registered for map "${mapId}".`));
+    },
+    changeMode: async (mode) => resolve("changeMode")?.changeMode(mode),
+    add: async (geojson) => await resolve("add")?.add(geojson) ?? [],
+    deleteAll: async () => resolve("deleteAll")?.deleteAll(),
+    setFeatureProperty: async (featureId, property, value) => resolve("setFeatureProperty")?.setFeatureProperty(featureId, property, value),
+    // 读操作静默降级：常在 computed 中反复求值，告警会刷屏
+    getAll: () => getDrawContext(mapId)?.getAll(),
+    getMode: () => getDrawContext(mapId)?.getMode()
+  };
+}
+export function useMaplibreDraw(options = {}) {
+  if (options.mapId) return createRemoteContext(options.mapId);
+  const context = inject(DrawKey, null);
+  if (!context) {
+    throw new Error("[movk-maplibre] useMaplibreDraw() must be called inside a <MaplibreDrawControl> component, or pass options.mapId.");
+  }
+  return context;
+}

package/dist/runtime/composables/useMaplibreImage.d.ts

@@ -0,0 +1,19 @@
+import type { Ref } from 'vue';
+export interface UseMaplibreImageOptions {
+    /** 目标地图 id；在 MaplibreMap 子树外使用时必填 */
+    mapId?: string;
+    /** 作为 SDF 图标（可经 icon-color 着色） */
+    sdf?: boolean;
+    /**
+     * 像素密度
+     * @defaultValue 1
+     */
+    pixelRatio?: number;
+}
+/**
+ * 注册 symbol 图层可用的命名图片。
+ * setStyle 清空样式图片后经 onReady 自动补回；卸载时移除。
+ */
+export declare function useMaplibreImage(name: string, url: string, options?: UseMaplibreImageOptions): {
+    loaded: Ref<boolean>;
+};

package/dist/runtime/composables/useMaplibreImage.js

@@ -0,0 +1,33 @@
+import { onMounted, onUnmounted, ref } from "vue";
+import { useContextResolver } from "../domains/map/resolve.js";
+import { logger } from "../utils/logger.js";
+export function useMaplibreImage(name, url, options = {}) {
+  const { mapId, ...imageOptions } = options;
+  const resolve = useContextResolver(mapId);
+  const loaded = ref(false);
+  let ctx;
+  let stopReady;
+  onMounted(() => {
+    ctx = resolve();
+    if (!ctx) {
+      logger.warn("useMaplibreImage: no map context found; pass options.mapId or call inside <MaplibreMap>.");
+      return;
+    }
+    stopReady = ctx.onReady((map) => {
+      if (map.hasImage(name)) {
+        loaded.value = true;
+        return;
+      }
+      map.loadImage(url).then(({ data }) => {
+        if (!map.hasImage(name)) map.addImage(name, data, imageOptions);
+        loaded.value = true;
+      }).catch((error) => logger.warn(`Failed to load image "${name}":`, error));
+    });
+  });
+  onUnmounted(() => {
+    stopReady?.();
+    const map = ctx?.map.value;
+    if (map?.hasImage(name)) map.removeImage(name);
+  });
+  return { loaded };
+}

package/dist/runtime/composables/useMeasure.d.ts

@@ -0,0 +1,25 @@
+import type { Ref } from 'vue';
+export type MeasureMode = 'distance' | 'area';
+export interface UseMeasureOptions {
+    /** 目标地图 id；在 MaplibreMap 子树外使用时必填 */
+    mapId?: string;
+    /**
+     * 主色
+     * @defaultValue '#f59e0b'
+     */
+    color?: string;
+}
+export interface UseMeasureReturn {
+    /** 进入测量：click 加点、mousemove 预览、dblclick 结束当前段 */
+    start: (mode: MeasureMode) => void;
+    /** 退出测量交互（保留已绘结果） */
+    stop: () => void;
+    /** 清空全部测量结果 */
+    clear: () => void;
+    mode: Ref<MeasureMode | undefined>;
+    active: Ref<boolean>;
+    /** 当前段（含光标预览）的格式化读数 */
+    result: Ref<string>;
+}
+/** 测距/测面工具：自管 geojson 源与展示图层，turf 计算实时读数。 */
+export declare function useMeasure(options?: UseMeasureOptions): UseMeasureReturn;