@movk/maplibre 1.0.0 → 1.2.0

package/dist/runtime/components/extensions/Swipe.d.vue.ts

@@ -0,0 +1,48 @@
+import type { StyleSpecification } from 'maplibre-gl';
+import type { SwipeOrientation } from '../../utils/swipe';
+type __VLS_Props = {
+    /**
+     * 分隔方向：vertical 为竖直分隔条左右对比，horizontal 为水平分隔条上下对比
+     * @defaultValue 'vertical'
+     */
+    orientation?: SwipeOrientation;
+    /**
+     * 方向键每次移动的比例
+     * @defaultValue 0.05
+     */
+    step?: number;
+    /** 对照图的底图样式（对象或样式 URL）；省略时为空白样式，由插槽内图层提供内容 */
+    mapStyle?: StyleSpecification | string;
+};
+type __VLS_Slots = {
+    /** 对照内容：放置 MaplibreTiandituLayer、MaplibreLayer 等，作用于对照图 */
+    default?: () => unknown;
+};
+declare function revealed(point: {
+    x: number;
+    y: number;
+}): boolean;
+type __VLS_ModelProps = {
+    /** 分隔条位置，0..1 */
+    'position'?: number;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
+    /** 主图容器内的点是否落在对照图露出区域，供主图侧图层事件判断互斥 */
+    isPointRevealed: typeof revealed;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:position": (value: number) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:position"?: ((value: number) => any) | undefined;
+}>, {
+    step: number;
+    orientation: SwipeOrientation;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/extensions/Swipe.vue

@@ -0,0 +1,141 @@
+<script setup>
+import { computed, onMounted, onUnmounted, provide, ref, useId, useTemplateRef, watch, watchEffect } from "vue";
+import { clamp, omitUndefined } from "@movk/core";
+import { useMap } from "../../composables/useMap";
+import { createMaplibreContext, MaplibreContextKey } from "../../domains/map/context";
+import { createMaplibreGl } from "../../domains/map/create-map";
+import { blankStyle } from "../../domains/map/style";
+import { bindSwipeOverlay } from "../../domains/map/swipe";
+import { collectAttributions, isPointRevealed, positionFromPointer, swipeClipPath } from "../../utils/swipe";
+const props = defineProps({
+  orientation: { type: String, required: false, default: "vertical" },
+  step: { type: Number, required: false, default: 0.05 },
+  mapStyle: { type: [Object, String], required: false }
+});
+defineSlots();
+const position = defineModel("position", { type: Number, ...{ default: 0.5 } });
+const mainContext = useMap();
+const root = useTemplateRef("root");
+const container = useTemplateRef("container");
+const { context, attach } = createMaplibreContext(`${mainContext.id}-swipe-${useId()}`);
+provide(MaplibreContextKey, context);
+const attributions = ref([]);
+function revealed(point) {
+  const main = mainContext.map.value;
+  if (!main) return false;
+  const { clientWidth: width, clientHeight: height } = main.getContainer();
+  return isPointRevealed(point, { width, height }, position.value, props.orientation);
+}
+let unbind;
+let disposed = false;
+onMounted(async () => {
+  const main = await mainContext.whenAttached();
+  if (disposed || !container.value) return;
+  const overlay = createMaplibreGl(omitUndefined({
+    container: container.value,
+    style: props.mapStyle ?? blankStyle(),
+    center: main.getCenter(),
+    zoom: main.getZoom(),
+    bearing: main.getBearing(),
+    pitch: main.getPitch(),
+    interactive: false,
+    attributionControl: false
+  }));
+  attach(overlay);
+  unbind = bindSwipeOverlay(main, overlay, revealed);
+  const updateAttributions = () => {
+    attributions.value = collectAttributions(overlay);
+  };
+  overlay.on("sourcedata", updateAttributions);
+  overlay.on("style.load", updateAttributions);
+});
+onUnmounted(() => {
+  disposed = true;
+  unbind?.();
+  context.map.value?.remove();
+});
+watch(() => props.mapStyle, (style) => {
+  context.map.value?.setStyle(style ?? blankStyle(), { diff: false });
+});
+watchEffect(() => {
+  const overlay = context.map.value;
+  if (overlay) overlay.getCanvas().style.clipPath = swipeClipPath(position.value, props.orientation);
+});
+const offset = computed(() => `${clamp(position.value, 0, 1) * 100}%`);
+const handleStyle = computed(() => ({ [props.orientation === "vertical" ? "left" : "top"]: offset.value }));
+const attributionStyle = computed(() => props.orientation === "vertical" ? { left: offset.value, bottom: "0", maxWidth: `calc(100% - ${offset.value})` } : { top: offset.value, left: "0" });
+const attributionHtml = computed(() => attributions.value.join(" | "));
+const dragging = ref(false);
+function updateFromPointer(event) {
+  if (!root.value) return;
+  position.value = positionFromPointer(
+    root.value.getBoundingClientRect(),
+    { x: event.clientX, y: event.clientY },
+    props.orientation
+  );
+}
+function onPointerDown(event) {
+  dragging.value = true;
+  event.currentTarget.setPointerCapture?.(event.pointerId);
+  updateFromPointer(event);
+}
+function onPointerMove(event) {
+  if (dragging.value) updateFromPointer(event);
+}
+function onPointerUp() {
+  dragging.value = false;
+}
+const KEY_DELTA = {
+  ArrowLeft: -1,
+  ArrowUp: -1,
+  ArrowRight: 1,
+  ArrowDown: 1
+};
+function onKeydown(event) {
+  let next;
+  if (event.key === "Home") next = 0;
+  else if (event.key === "End") next = 1;
+  else if (event.key in KEY_DELTA) next = position.value + KEY_DELTA[event.key] * props.step;
+  if (next === void 0) return;
+  event.preventDefault();
+  position.value = clamp(next, 0, 1);
+}
+defineExpose({
+  /** 主图容器内的点是否落在对照图露出区域，供主图侧图层事件判断互斥 */
+  isPointRevealed: revealed
+});
+</script>
+
+<template>
+  <div
+    ref="root"
+    class="movk-maplibre-swipe"
+    :class="`movk-maplibre-swipe--${orientation}`"
+  >
+    <div ref="container" class="movk-maplibre-swipe__map" />
+    <!-- eslint-disable-next-line vue/no-v-html -->
+    <div v-if="attributionHtml" class="movk-maplibre-swipe__attribution" :style="attributionStyle" v-html="attributionHtml" />
+    <div
+      class="movk-maplibre-swipe__handle"
+      :class="{ 'is-dragging': dragging }"
+      :style="handleStyle"
+      role="slider"
+      tabindex="0"
+      aria-label="Swipe position"
+      :aria-orientation="orientation === 'vertical' ? 'horizontal' : 'vertical'"
+      aria-valuemin="0"
+      aria-valuemax="100"
+      :aria-valuenow="Math.round(clamp(position, 0, 1) * 100)"
+      @pointerdown="onPointerDown"
+      @pointermove="onPointerMove"
+      @pointerup="onPointerUp"
+      @pointercancel="onPointerUp"
+      @keydown="onKeydown"
+    />
+    <slot />
+  </div>
+</template>
+
+<style>
+.movk-maplibre-swipe{pointer-events:none;z-index:1}.movk-maplibre-swipe,.movk-maplibre-swipe>.movk-maplibre-swipe__map{inset:0;position:absolute}.movk-maplibre-swipe__attribution{background:hsla(0,0%,100%,.65);color:rgba(0,0,0,.75);font:12px/20px Helvetica Neue,Arial,Helvetica,sans-serif;max-width:100%;overflow:hidden;padding:0 5px;pointer-events:auto;position:absolute;text-overflow:ellipsis;white-space:nowrap}.movk-maplibre-swipe__attribution a{color:inherit;text-decoration:none}.movk-maplibre-swipe__handle{outline:none;pointer-events:auto;position:absolute;touch-action:none}.movk-maplibre-swipe__handle:before{background:#fff;box-shadow:0 0 4px rgba(0,0,0,.4);content:"";position:absolute}.movk-maplibre-swipe__handle:after{background:#fff;border-radius:9999px;box-shadow:0 1px 4px rgba(0,0,0,.4);content:"";height:28px;left:50%;position:absolute;top:50%;transform:translate(-50%,-50%);width:28px}.movk-maplibre-swipe__handle:focus-visible:after{box-shadow:0 0 0 3px rgba(59,130,246,.6)}.movk-maplibre-swipe--vertical>.movk-maplibre-swipe__handle{bottom:0;cursor:ew-resize;top:0;transform:translateX(-50%);width:24px}.movk-maplibre-swipe--vertical>.movk-maplibre-swipe__handle:before{bottom:0;left:50%;top:0;transform:translateX(-50%);width:2px}.movk-maplibre-swipe--horizontal>.movk-maplibre-swipe__handle{cursor:ns-resize;height:24px;left:0;right:0;transform:translateY(-50%)}.movk-maplibre-swipe--horizontal>.movk-maplibre-swipe__handle:before{height:2px;left:0;right:0;top:50%;transform:translateY(-50%)}
+</style>

package/dist/runtime/components/extensions/Swipe.vue.d.ts

@@ -0,0 +1,48 @@
+import type { StyleSpecification } from 'maplibre-gl';
+import type { SwipeOrientation } from '../../utils/swipe';
+type __VLS_Props = {
+    /**
+     * 分隔方向：vertical 为竖直分隔条左右对比，horizontal 为水平分隔条上下对比
+     * @defaultValue 'vertical'
+     */
+    orientation?: SwipeOrientation;
+    /**
+     * 方向键每次移动的比例
+     * @defaultValue 0.05
+     */
+    step?: number;
+    /** 对照图的底图样式（对象或样式 URL）；省略时为空白样式，由插槽内图层提供内容 */
+    mapStyle?: StyleSpecification | string;
+};
+type __VLS_Slots = {
+    /** 对照内容：放置 MaplibreTiandituLayer、MaplibreLayer 等，作用于对照图 */
+    default?: () => unknown;
+};
+declare function revealed(point: {
+    x: number;
+    y: number;
+}): boolean;
+type __VLS_ModelProps = {
+    /** 分隔条位置，0..1 */
+    'position'?: number;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
+    /** 主图容器内的点是否落在对照图露出区域，供主图侧图层事件判断互斥 */
+    isPointRevealed: typeof revealed;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:position": (value: number) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:position"?: ((value: number) => any) | undefined;
+}>, {
+    step: number;
+    orientation: SwipeOrientation;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -1,7 +1,7 @@
 import type { BuildingSourceOptions } from '../../utils/building';
 /** 3D 建筑：按要素高度属性拉伸的 fill-extrusion 图层。 */
 type __VLS_Props = BuildingSourceOptions & {
-    /** 图层 id；省略时自动生成 */
+    /** 图层 id；省略时自动生成，变更需配合 `:key` 重建 */
     layerId?: string;
     /**
      * 建筑颜色

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

@@ -1,7 +1,7 @@
 import type { BuildingSourceOptions } from '../../utils/building';
 /** 3D 建筑：按要素高度属性拉伸的 fill-extrusion 图层。 */
 type __VLS_Props = BuildingSourceOptions & {
-    /** 图层 id；省略时自动生成 */
+    /** 图层 id；省略时自动生成，变更需配合 `:key` 重建 */
     layerId?: string;
     /**
      * 建筑颜色

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

@@ -4,7 +4,7 @@ type PropBag = Record<string, unknown>;
 type __VLS_Props = {
     /** 点要素数据（GeoJSON 或其 URL） */
     data: GeoJSONSourceSpecification['data'];
-    /** source 与图层 id 前缀；省略时自动生成 */
+    /** source 与图层 id 前缀；省略时自动生成，变更需配合 `:key` 重建 */
     sourceId?: string;
     /**
      * 聚合半径（像素）

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

@@ -4,7 +4,7 @@ type PropBag = Record<string, unknown>;
 type __VLS_Props = {
     /** 点要素数据（GeoJSON 或其 URL） */
     data: GeoJSONSourceSpecification['data'];
-    /** source 与图层 id 前缀；省略时自动生成 */
+    /** source 与图层 id 前缀；省略时自动生成，变更需配合 `:key` 重建 */
     sourceId?: string;
     /**
      * 聚合半径（像素）

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

@@ -0,0 +1,59 @@
+/** 等高线：由 raster-dem 瓦片在浏览器端实时生成矢量等高线，主次线按间距区分，可沿线标注高程。 */
+type __VLS_Props = {
+    /** DEM 瓦片模板（含 {z}/{x}/{y}），可与 MaplibreTerrain 共用；变更需配合 `:key` 重建 */
+    demUrl: string;
+    /**
+     * DEM 高程编码；变更需配合 `:key` 重建
+     * @defaultValue 'terrarium'
+     */
+    encoding?: 'terrarium' | 'mapbox';
+    /**
+     * DEM 瓦片最大缩放级别；变更需配合 `:key` 重建
+     * @defaultValue 12
+     */
+    maxzoom?: number;
+    /**
+     * 缩放级别到 [次线间距, 主线间距] 的映射，未列出的级别沿用更低一级
+     * @defaultValue `{ 11: [200, 1000], 12: [100, 500], 14: [50, 200], 15: [20, 100] }`
+     */
+    thresholds?: Record<number, number | number[]>;
+    /**
+     * 高程换算系数，如 3.28084 将米换算为英尺
+     * @defaultValue 1
+     */
+    multiplier?: number;
+    /**
+     * 标注的高程单位后缀
+     * @defaultValue 'm'
+     */
+    unit?: string;
+    /** 图层 id 前缀；省略时自动生成，变更需配合 `:key` 重建 */
+    layerId?: string;
+    /**
+     * 线条颜色
+     * @defaultValue '#a0522d'
+     */
+    lineColor?: string;
+    /**
+     * 是否沿主线标注高程
+     * @defaultValue true
+     */
+    labels?: boolean;
+    /** 覆盖合并到等高线的 paint */
+    linePaint?: Record<string, unknown>;
+    /** 覆盖合并到标注的 layout */
+    labelLayout?: Record<string, unknown>;
+    /** 插入到该图层之前 */
+    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<{}>, {
+    maxzoom: number;
+    unit: string;
+    encoding: "terrarium" | "mapbox";
+    thresholds: Record<number, number | number[]>;
+    multiplier: number;
+    lineColor: string;
+    labels: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,84 @@
+<script setup>
+import { computed, onMounted, onUnmounted, shallowRef, useId } from "vue";
+import { addProtocol, removeProtocol } from "maplibre-gl";
+import mlcontour from "maplibre-contour";
+import MaplibreSource from "../Source.vue";
+import MaplibreLayer from "../Layer.vue";
+import { textFontLayout } from "../../domains/map/config";
+const props = defineProps({
+  demUrl: { type: String, required: true },
+  encoding: { type: String, required: false, default: "terrarium" },
+  maxzoom: { type: Number, required: false, default: 12 },
+  thresholds: { type: Object, required: false, default: () => ({ 11: [200, 1e3], 12: [100, 500], 14: [50, 200], 15: [20, 100] }) },
+  multiplier: { type: Number, required: false, default: 1 },
+  unit: { type: String, required: false, default: "m" },
+  layerId: { type: String, required: false },
+  lineColor: { type: String, required: false, default: "#a0522d" },
+  labels: { type: Boolean, required: false, default: true },
+  linePaint: { type: Object, required: false },
+  labelLayout: { type: Object, required: false },
+  beforeId: { type: String, required: false }
+});
+const CONTOUR_LAYER = "contours";
+const id = props.layerId ?? `movk-contour-${useId()}`;
+const demSource = shallowRef();
+onMounted(() => {
+  const source2 = new mlcontour.DemSource({ url: props.demUrl, encoding: props.encoding, maxzoom: props.maxzoom, worker: true });
+  source2.setupMaplibre({ addProtocol });
+  demSource.value = source2;
+});
+onUnmounted(() => {
+  if (!demSource.value) return;
+  removeProtocol(demSource.value.sharedDemProtocolId);
+  removeProtocol(demSource.value.contourProtocolId);
+});
+const source = computed(() => demSource.value && {
+  type: "vector",
+  tiles: [demSource.value.contourProtocolUrl({
+    thresholds: props.thresholds,
+    multiplier: props.multiplier,
+    elevationKey: "ele",
+    levelKey: "level",
+    contourLayer: CONTOUR_LAYER
+  })],
+  maxzoom: 15
+});
+const paint = computed(() => ({
+  "line-color": props.lineColor,
+  "line-width": ["match", ["get", "level"], 1, 1, 0.5],
+  ...props.linePaint
+}));
+const labelPaint = computed(() => ({ "text-color": props.lineColor, "text-halo-color": "#fff", "text-halo-width": 1 }));
+const layout = computed(() => ({
+  "symbol-placement": "line",
+  "text-field": ["concat", ["number-format", ["get", "ele"], {}], props.unit],
+  "text-size": 10,
+  ...textFontLayout(),
+  ...props.labelLayout
+}));
+const labelFilter = [">", ["get", "level"], 0];
+</script>
+
+<template>
+  <MaplibreSource v-if="source" :source-id="id" :source="source">
+    <MaplibreLayer
+      :layer-id="`${id}-line`"
+      type="line"
+      :source="id"
+      :source-layer="CONTOUR_LAYER"
+      :paint="paint"
+      :before-id="beforeId"
+    />
+    <MaplibreLayer
+      v-if="labels"
+      :layer-id="`${id}-label`"
+      type="symbol"
+      :source="id"
+      :source-layer="CONTOUR_LAYER"
+      :filter="labelFilter"
+      :layout="layout"
+      :paint="labelPaint"
+      :before-id="beforeId"
+    />
+  </MaplibreSource>
+</template>

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

@@ -0,0 +1,59 @@
+/** 等高线：由 raster-dem 瓦片在浏览器端实时生成矢量等高线，主次线按间距区分，可沿线标注高程。 */
+type __VLS_Props = {
+    /** DEM 瓦片模板（含 {z}/{x}/{y}），可与 MaplibreTerrain 共用；变更需配合 `:key` 重建 */
+    demUrl: string;
+    /**
+     * DEM 高程编码；变更需配合 `:key` 重建
+     * @defaultValue 'terrarium'
+     */
+    encoding?: 'terrarium' | 'mapbox';
+    /**
+     * DEM 瓦片最大缩放级别；变更需配合 `:key` 重建
+     * @defaultValue 12
+     */
+    maxzoom?: number;
+    /**
+     * 缩放级别到 [次线间距, 主线间距] 的映射，未列出的级别沿用更低一级
+     * @defaultValue `{ 11: [200, 1000], 12: [100, 500], 14: [50, 200], 15: [20, 100] }`
+     */
+    thresholds?: Record<number, number | number[]>;
+    /**
+     * 高程换算系数，如 3.28084 将米换算为英尺
+     * @defaultValue 1
+     */
+    multiplier?: number;
+    /**
+     * 标注的高程单位后缀
+     * @defaultValue 'm'
+     */
+    unit?: string;
+    /** 图层 id 前缀；省略时自动生成，变更需配合 `:key` 重建 */
+    layerId?: string;
+    /**
+     * 线条颜色
+     * @defaultValue '#a0522d'
+     */
+    lineColor?: string;
+    /**
+     * 是否沿主线标注高程
+     * @defaultValue true
+     */
+    labels?: boolean;
+    /** 覆盖合并到等高线的 paint */
+    linePaint?: Record<string, unknown>;
+    /** 覆盖合并到标注的 layout */
+    labelLayout?: Record<string, unknown>;
+    /** 插入到该图层之前 */
+    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<{}>, {
+    maxzoom: number;
+    unit: string;
+    encoding: "terrarium" | "mapbox";
+    thresholds: Record<number, number | number[]>;
+    multiplier: number;
+    lineColor: string;
+    labels: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,31 @@
+/** 经纬网：按缩放级别自动选择步长，平移缩放后按视口重算，球形投影下呈曲线。 */
+type __VLS_Props = {
+    /** 固定步长（度）；省略时按缩放级别自动选择 */
+    step?: number;
+    /** 图层 id 前缀；省略时自动生成，变更需配合 `:key` 重建 */
+    layerId?: string;
+    /**
+     * 线条与标注颜色
+     * @defaultValue '#888'
+     */
+    color?: string;
+    /**
+     * 线宽（像素）
+     * @defaultValue 0.5
+     */
+    width?: number;
+    /**
+     * 是否在视口边缘标注度数
+     * @defaultValue true
+     */
+    labels?: boolean;
+    /** 插入到该图层之前 */
+    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<{}>, {
+    color: string;
+    width: number;
+    labels: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,88 @@
+<script setup>
+import { computed, onUnmounted, shallowRef, useId, watch } from "vue";
+import MaplibreLayer from "../Layer.vue";
+import { useMap } from "../../composables/useMap";
+import { textFontLayout } from "../../domains/map/config";
+import { graticuleLabels, graticuleLines, graticuleStep } from "../../utils/graticule";
+const props = defineProps({
+  step: { type: Number, required: false },
+  layerId: { type: String, required: false },
+  color: { type: String, required: false, default: "#888" },
+  width: { type: Number, required: false, default: 0.5 },
+  labels: { type: Boolean, required: false, default: true },
+  beforeId: { type: String, required: false }
+});
+const WORLD = [-180, -85, 180, 85];
+const WORLD_ZOOM = 3;
+const id = props.layerId ?? `movk-graticule-${useId()}`;
+const ctx = useMap();
+const lines = shallowRef({ type: "FeatureCollection", features: [] });
+const labelData = shallowRef({ type: "FeatureCollection", features: [] });
+let current;
+function viewBounds(map) {
+  if (map.getZoom() < WORLD_ZOOM) return WORLD;
+  const bounds = map.getBounds();
+  return [bounds.getWest(), bounds.getSouth(), bounds.getEast(), bounds.getNorth()];
+}
+function labelAnchor(map, [west, south]) {
+  if (map.getZoom() >= WORLD_ZOOM) return [west, south];
+  const { lng, lat } = map.getCenter();
+  return [lng, lat];
+}
+function contains([west, south, east, north], [w, s, e, n]) {
+  return w >= west && s >= south && e <= east && n <= north;
+}
+function update(map) {
+  const bounds = viewBounds(map);
+  const step = props.step ?? graticuleStep(map.getZoom());
+  if (!current || current.step !== step || !contains(current.extent, bounds)) {
+    const next = graticuleLines(bounds, step);
+    current = { extent: next.extent, step };
+    lines.value = next.data;
+  }
+  if (props.labels) labelData.value = graticuleLabels(bounds, step, labelAnchor(map, bounds));
+}
+let boundMap;
+const onMoveEnd = () => boundMap && update(boundMap);
+const stopReady = ctx.onReady((map) => {
+  boundMap?.off("moveend", onMoveEnd);
+  boundMap = map;
+  map.on("moveend", onMoveEnd);
+  current = void 0;
+  update(map);
+});
+watch(() => [props.step, props.labels], () => {
+  current = void 0;
+  if (boundMap) update(boundMap);
+});
+onUnmounted(() => {
+  stopReady();
+  boundMap?.off("moveend", onMoveEnd);
+  boundMap = void 0;
+});
+const lineSource = computed(() => ({ type: "geojson", data: lines.value, tolerance: 0 }));
+const labelSource = computed(() => ({ type: "geojson", data: labelData.value }));
+const linePaint = computed(() => ({ "line-color": props.color, "line-width": props.width }));
+const labelPaint = computed(() => ({ "text-color": props.color, "text-halo-color": "#fff", "text-halo-width": 1 }));
+const labelLayout = {
+  "text-field": ["get", "label"],
+  "text-size": 10,
+  "text-anchor": ["match", ["get", "axis"], "lon", "bottom", "left"],
+  "text-offset": ["match", ["get", "axis"], "lon", ["literal", [0, -0.3]], ["literal", [0.3, 0]]],
+  "text-allow-overlap": true,
+  ...textFontLayout()
+};
+</script>
+
+<template>
+  <MaplibreLayer :layer-id="`${id}-line`" type="line" :source="lineSource" :paint="linePaint" :before-id="beforeId" />
+  <MaplibreLayer
+    v-if="labels"
+    :layer-id="`${id}-label`"
+    type="symbol"
+    :source="labelSource"
+    :layout="labelLayout"
+    :paint="labelPaint"
+    :before-id="beforeId"
+  />
+</template>

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

@@ -0,0 +1,31 @@
+/** 经纬网：按缩放级别自动选择步长，平移缩放后按视口重算，球形投影下呈曲线。 */
+type __VLS_Props = {
+    /** 固定步长（度）；省略时按缩放级别自动选择 */
+    step?: number;
+    /** 图层 id 前缀；省略时自动生成，变更需配合 `:key` 重建 */
+    layerId?: string;
+    /**
+     * 线条与标注颜色
+     * @defaultValue '#888'
+     */
+    color?: string;
+    /**
+     * 线宽（像素）
+     * @defaultValue 0.5
+     */
+    width?: number;
+    /**
+     * 是否在视口边缘标注度数
+     * @defaultValue true
+     */
+    labels?: boolean;
+    /** 插入到该图层之前 */
+    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<{}>, {
+    color: string;
+    width: number;
+    labels: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -1,6 +1,6 @@
 import type { ImageSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
 type __VLS_Props = {
-    /** 图层 id；省略时自动生成 */
+    /** 图层 id；省略时自动生成，变更需配合 `:key` 重建 */
     layerId?: string;
     /** 图片地址 */
     url: string;

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

@@ -1,6 +1,6 @@
 import type { ImageSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
 type __VLS_Props = {
-    /** 图层 id；省略时自动生成 */
+    /** 图层 id；省略时自动生成，变更需配合 `:key` 重建 */
     layerId?: string;
     /** 图片地址 */
     url: string;