@movk/maplibre 1.2.0 → 1.2.1

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@movk/maplibre",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "configKey": "maplibre",
   "compatibility": {
     "nuxt": ">=4.0.0"

package/dist/module.mjs

@@ -3,7 +3,7 @@ import { defineNuxtModule, createResolver, addComponentsDir, addImportsDir, addP
 import { defu } from 'defu';
 
 const name = "@movk/maplibre";
-const version = "1.2.0";
+const version = "1.2.1";
 
 const OPTIONAL_DEPS = ["lottie-web", "pmtiles", "@geomatico/maplibre-cog-protocol", "maplibre-contour"];
 const module$1 = defineNuxtModule({

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

@@ -0,0 +1,60 @@
+import type { FitBoundsOptions } from 'maplibre-gl';
+import type { RasterLayerSpecification } from '@maplibre/maplibre-gl-style-spec';
+import type { MaskInput } from '../../utils/mask';
+/** ZZTS 二维动态切片影像：经 zzts:// 协议拼合为 512 墨卡托瓦片，支持多边形裁剪、定位与高分屏出图，可用于 globe 与地形场景。 */
+type __VLS_Props = {
+    /** media 接口地址（不含协议前缀），查询参数（`layerName`、`dictCode`、`token` 等）原样带给服务端 */
+    url: string;
+    /**
+     * 协议名；需自定义请求时先以该名称调用 `registerZztsProtocol`，否则按缺省配置自动注册
+     * @defaultValue 'zzts'
+     */
+    scheme?: string;
+    /** source/layer id；省略时自动生成，变更需配合 `:key` 重建 */
+    layerId?: string;
+    /** 显示范围：仅保留区域内的影像像素，区域外露出下层底图；孔洞（飞地）同样挖空 */
+    clip?: MaskInput;
+    /**
+     * 拼合画布倍率（1-4），设为 `devicePixelRatio` 可在高分屏下取更细一级网格
+     * @defaultValue 1
+     */
+    pixelRatio?: number;
+    /**
+     * 元数据加载后自动定位到图层范围（与 `clip` 求交）
+     * @defaultValue false
+     */
+    autoFit?: boolean;
+    /**
+     * 定位动画选项，`autoFit` 与暴露的 `fit()` 共用
+     * @see https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/FitBoundsOptions/
+     */
+    fitOptions?: FitBoundsOptions;
+    /**
+     * 不透明度
+     * @defaultValue 1
+     */
+    opacity?: number;
+    /**
+     * raster 图层 paint（色相、饱和度、对比度、亮度等），与 `opacity` 合并
+     * @see https://maplibre.org/maplibre-style-spec/layers/#raster
+     */
+    paint?: RasterLayerSpecification['paint'];
+    /** 数据源最小缩放级别，缺省 0 */
+    minzoom?: number;
+    /** 数据源最大缩放级别，缺省按影像原始分辨率推算，更高级别自动超采样 */
+    maxzoom?: number;
+    /** 插入到该图层之前 */
+    beforeId?: string;
+};
+/** 定位到图层范围；元数据尚未加载时返回 false */
+declare function fit(options?: FitBoundsOptions): boolean;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    fit: typeof fit;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    pixelRatio: number;
+    opacity: number;
+    scheme: string;
+    autoFit: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,78 @@
+<script setup>
+import { computed, onUnmounted, ref, useId, watch } from "vue";
+import { omitUndefined } from "@movk/core";
+import MaplibreSource from "../Source.vue";
+import MaplibreLayer from "../Layer.vue";
+import { useMap } from "../../composables/useMap";
+import { registerZztsProtocol } from "../../utils/zzts";
+import { deleteZztsClip, setZztsClip } from "../../utils/zzts-clip";
+import { ZZTS_TILE_SIZE, zztsSourceUrl } from "../../utils/zzts-tile";
+const props = defineProps({
+  url: { type: String, required: true },
+  scheme: { type: String, required: false, default: "zzts" },
+  layerId: { type: String, required: false },
+  clip: { type: Object, required: false },
+  pixelRatio: { type: Number, required: false, default: 1 },
+  autoFit: { type: Boolean, required: false, default: false },
+  fitOptions: { type: Object, required: false },
+  opacity: { type: Number, required: false, default: 1 },
+  paint: { type: Object, required: false },
+  minzoom: { type: Number, required: false },
+  maxzoom: { type: Number, required: false },
+  beforeId: { type: String, required: false }
+});
+const id = props.layerId ?? `movk-zzts-${useId()}`;
+const ctx = useMap();
+let clipVersion = 0;
+const clipKey = ref(props.clip ? `${id}:0` : void 0);
+function registerClip() {
+  if (props.clip && clipKey.value) setZztsClip(clipKey.value, props.clip);
+}
+watch(() => props.clip, (clip) => {
+  if (clipKey.value) deleteZztsClip(clipKey.value);
+  clipKey.value = clip ? `${id}:${++clipVersion}` : void 0;
+  registerClip();
+}, { deep: true });
+const stopReady = ctx.onReady(() => {
+  registerZztsProtocol({ scheme: props.scheme });
+  registerClip();
+});
+const sourceUrl = computed(() => zztsSourceUrl(props.scheme, props.url, { pixelRatio: props.pixelRatio, clip: clipKey.value }));
+const source = computed(() => omitUndefined({
+  type: "raster",
+  url: sourceUrl.value,
+  tileSize: ZZTS_TILE_SIZE,
+  minzoom: props.minzoom,
+  maxzoom: props.maxzoom
+}));
+const layerPaint = computed(() => ({ ...props.paint, "raster-opacity": props.opacity }));
+function fit(options) {
+  const map = ctx.map.value;
+  const bounds = map?.getSource(id)?.bounds;
+  if (!map || !bounds) return false;
+  map.fitBounds(bounds, { ...props.fitOptions, ...options });
+  return true;
+}
+let fittedUrl;
+watch(ctx.map, (map, _, onCleanup) => {
+  if (!map) return;
+  const onSourceData = (event) => {
+    if (!props.autoFit || event.sourceId !== id || event.sourceDataType !== "metadata") return;
+    if (fittedUrl === sourceUrl.value) return;
+    if (fit()) fittedUrl = sourceUrl.value;
+  };
+  map.on("sourcedata", onSourceData);
+  onCleanup(() => map.off("sourcedata", onSourceData));
+}, { immediate: true });
+onUnmounted(() => {
+  stopReady();
+  if (clipKey.value) deleteZztsClip(clipKey.value);
+});
+defineExpose({ fit });
+</script>
+
+<template>
+  <MaplibreSource :source-id="id" :source="source">
+    <MaplibreLayer :layer-id="id" type="raster" :source="id" :paint="layerPaint" :before-id="beforeId" />
+  </MaplibreSource>
+</template>

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

@@ -0,0 +1,60 @@
+import type { FitBoundsOptions } from 'maplibre-gl';
+import type { RasterLayerSpecification } from '@maplibre/maplibre-gl-style-spec';
+import type { MaskInput } from '../../utils/mask';
+/** ZZTS 二维动态切片影像：经 zzts:// 协议拼合为 512 墨卡托瓦片，支持多边形裁剪、定位与高分屏出图，可用于 globe 与地形场景。 */
+type __VLS_Props = {
+    /** media 接口地址（不含协议前缀），查询参数（`layerName`、`dictCode`、`token` 等）原样带给服务端 */
+    url: string;
+    /**
+     * 协议名；需自定义请求时先以该名称调用 `registerZztsProtocol`，否则按缺省配置自动注册
+     * @defaultValue 'zzts'
+     */
+    scheme?: string;
+    /** source/layer id；省略时自动生成，变更需配合 `:key` 重建 */
+    layerId?: string;
+    /** 显示范围：仅保留区域内的影像像素，区域外露出下层底图；孔洞（飞地）同样挖空 */
+    clip?: MaskInput;
+    /**
+     * 拼合画布倍率（1-4），设为 `devicePixelRatio` 可在高分屏下取更细一级网格
+     * @defaultValue 1
+     */
+    pixelRatio?: number;
+    /**
+     * 元数据加载后自动定位到图层范围（与 `clip` 求交）
+     * @defaultValue false
+     */
+    autoFit?: boolean;
+    /**
+     * 定位动画选项，`autoFit` 与暴露的 `fit()` 共用
+     * @see https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/FitBoundsOptions/
+     */
+    fitOptions?: FitBoundsOptions;
+    /**
+     * 不透明度
+     * @defaultValue 1
+     */
+    opacity?: number;
+    /**
+     * raster 图层 paint（色相、饱和度、对比度、亮度等），与 `opacity` 合并
+     * @see https://maplibre.org/maplibre-style-spec/layers/#raster
+     */
+    paint?: RasterLayerSpecification['paint'];
+    /** 数据源最小缩放级别，缺省 0 */
+    minzoom?: number;
+    /** 数据源最大缩放级别，缺省按影像原始分辨率推算，更高级别自动超采样 */
+    maxzoom?: number;
+    /** 插入到该图层之前 */
+    beforeId?: string;
+};
+/** 定位到图层范围；元数据尚未加载时返回 false */
+declare function fit(options?: FitBoundsOptions): boolean;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    fit: typeof fit;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    pixelRatio: number;
+    opacity: number;
+    scheme: string;
+    autoFit: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/utils/zzts-cache.d.ts

@@ -0,0 +1,24 @@
+type Request = typeof globalThis.fetch;
+export interface Lru<K, V> {
+    get: (key: K) => V | undefined;
+    set: (key: K, value: V) => void;
+    delete: (key: K) => void;
+}
+/** 基于 Map 插入顺序的 LRU：读取即刷新，超出容量时淘汰最久未用的条目 */
+export declare function createLru<K, V>(size: number): Lru<K, V>;
+/** 网络错误与 5xx 视为临时故障，按指数退避重试；4xx（含 404 未生成）直接返回 */
+export declare function fetchWithRetry(request: Request, url: string, retry: number, signal?: AbortSignal): Promise<Response>;
+export interface ZztsImageStore {
+    /** 取元素图片位图；缺图或加载失败时为 undefined。每次调用都须配对一次 release */
+    acquire: (url: string) => Promise<ImageBitmap | undefined>;
+    release: (url: string) => void;
+}
+/**
+ * 元素图片仓库：压缩数据（Blob）按 url 做 LRU 缓存，404 结果同样缓存以免重复请求，其余失败不缓存；
+ * 解码后的位图按引用计数在并发拼合的瓦片间共享，最后一次释放时 close，避免位图常驻内存。
+ */
+export declare function createImageStore(request: Request, { size, retry }: {
+    size: number;
+    retry: number;
+}): ZztsImageStore;
+export {};

package/dist/runtime/utils/zzts-cache.js

@@ -0,0 +1,76 @@
+const RETRY_DELAY = 500;
+export function createLru(size) {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    get(key) {
+      if (!map.has(key)) return void 0;
+      const value = map.get(key);
+      map.delete(key);
+      map.set(key, value);
+      return value;
+    },
+    set(key, value) {
+      map.delete(key);
+      map.set(key, value);
+      if (map.size > size) map.delete(map.keys().next().value);
+    },
+    delete(key) {
+      map.delete(key);
+    }
+  };
+}
+function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }, { once: true });
+  });
+}
+export async function fetchWithRetry(request, url, retry, signal) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const res = await request(url, signal ? { signal } : void 0);
+      if (res.status < 500 || attempt >= retry) return res;
+    } catch (error) {
+      if (signal?.aborted || attempt >= retry) throw error;
+    }
+    await wait(RETRY_DELAY * 2 ** attempt, signal);
+  }
+}
+export function createImageStore(request, { size, retry }) {
+  const blobs = createLru(size);
+  const decoded = /* @__PURE__ */ new Map();
+  function loadBlob(url) {
+    const hit = blobs.get(url);
+    if (hit) return hit;
+    const pending = fetchWithRetry(request, url, retry).then(async (res) => {
+      if (res.status === 404) return void 0;
+      if (!res.ok) throw new Error(`ZZTS \u56FE\u7247\u52A0\u8F7D\u5931\u8D25\uFF1AHTTP ${res.status}`);
+      return await res.blob();
+    });
+    pending.catch(() => blobs.delete(url));
+    blobs.set(url, pending);
+    return pending;
+  }
+  return {
+    acquire(url) {
+      const entry = decoded.get(url);
+      if (entry) {
+        entry.refs++;
+        return entry.image;
+      }
+      const image = loadBlob(url).then((blob) => blob && createImageBitmap(blob)).catch(() => void 0);
+      decoded.set(url, { image, refs: 1 });
+      return image;
+    },
+    release(url) {
+      const entry = decoded.get(url);
+      if (!entry || --entry.refs > 0) return;
+      decoded.delete(url);
+      void entry.image.then((image) => image?.close());
+    }
+  };
+}

package/dist/runtime/utils/zzts-clip.d.ts

@@ -0,0 +1,14 @@
+import type { Position } from 'geojson';
+import type { MaskInput } from './mask';
+import type { LngLatBBox } from './zzts-tile';
+/** 裁剪区域：全部环（外环与孔洞，按 evenodd 规则填充）及其包围盒 */
+export interface ZztsClip {
+    rings: Position[][];
+    bbox: LngLatBBox;
+}
+/** 收集面状几何的全部环；非面状要素被忽略 */
+export declare function clipRings(input: MaskInput): Position[][];
+/** 登记裁剪区域；无面状要素时登记为空区域，图层整体不可见 */
+export declare function setZztsClip(key: string, input: MaskInput): void;
+export declare function getZztsClip(key: string): ZztsClip | undefined;
+export declare function deleteZztsClip(key: string): void;

package/dist/runtime/utils/zzts-clip.js

@@ -0,0 +1,27 @@
+import { defineGlobalSingleton } from "@movk/core";
+const clips = defineGlobalSingleton("movk-maplibre:zzts-clips", () => /* @__PURE__ */ new Map());
+function polygonRings(geometry) {
+  if (geometry?.type === "Polygon") return geometry.coordinates;
+  if (geometry?.type === "MultiPolygon") return geometry.coordinates.flat();
+  return [];
+}
+export function clipRings(input) {
+  const rings = input.type === "FeatureCollection" ? input.features.flatMap((feature) => polygonRings(feature.geometry)) : polygonRings(input.type === "Feature" ? input.geometry : input);
+  return rings.filter((ring) => ring.length >= 3);
+}
+function ringsBBox(rings) {
+  const points = rings.flat();
+  const lngs = points.map(([lng = 0]) => lng);
+  const lats = points.map(([, lat = 0]) => lat);
+  return [Math.min(...lngs), Math.min(...lats), Math.max(...lngs), Math.max(...lats)];
+}
+export function setZztsClip(key, input) {
+  const rings = clipRings(input);
+  clips.set(key, { rings, bbox: rings.length ? ringsBBox(rings) : [0, 0, 0, 0] });
+}
+export function getZztsClip(key) {
+  return clips.get(key);
+}
+export function deleteZztsClip(key) {
+  clips.delete(key);
+}

package/dist/runtime/utils/zzts-tile.d.ts

@@ -1,3 +1,4 @@
+import type { Position } from 'geojson';
 /** 经纬度包围盒 [west, south, east, north] */
 export type LngLatBBox = [number, number, number, number];
 export interface ZztsExtent {
@@ -27,20 +28,63 @@ export interface TileCoord {
     x: number;
     y: number;
 }
-/** 源矩形为元素图片的比例坐标 [x, y, w, h]（0-1），目标矩形为瓦片像素坐标 */
+/** 同一级别的连续瓦片区间，x1 / y1 不含 */
+export interface TileRange {
+    z: number;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** 图层级参数，经协议地址的 hash 传递，不发往服务端 */
+export interface ZztsLayerParams {
+    /** 拼合画布相对 512 的倍率，用于高分屏 */
+    pixelRatio?: number;
+    /** 裁剪表中的裁剪区域键 */
+    clip?: string;
+}
+export interface ZztsRequest {
+    mediaUrl: string;
+    pixelRatio: number;
+    clip?: string;
+    tile?: TileCoord;
+}
+/** 一次 elements 请求的参数 */
+export interface ZztsQuery {
+    bbox: LngLatBBox;
+    width: number;
+    height: number;
+    scale: number;
+}
+/** 源矩形为元素图片的比例坐标 [x, y, w, h]（0-1），目标矩形为画布像素坐标 */
 export interface ZztsDraw {
     source: [number, number, number, number];
     target: [number, number, number, number];
 }
 export declare const ZZTS_TILE_SIZE = 512;
-export declare function parseZztsUrl(url: string): {
-    mediaUrl: string;
-    tile?: TileCoord;
-};
-export declare function tileBBox({ z, x, y }: TileCoord): LngLatBBox;
+/** 解析 `<scheme>://<media 地址>#<图层参数>&tile=z/x/y`；scheme 任意，以首个 `://` 为界 */
+export declare function parseZztsUrl(url: string): ZztsRequest;
+/** 拼出 source 的协议地址，缺省参数不写入 hash */
+export declare function zztsSourceUrl(scheme: string, mediaUrl: string, { pixelRatio, clip }?: ZztsLayerParams): string;
+export declare function canvasSize(pixelRatio: number): number;
+export declare function tileRange({ z, x, y }: TileCoord): TileRange;
+export declare function rangeBBox({ z, x0, y0, x1, y1 }: TileRange): LngLatBBox;
+export declare function tileBBox(tile: TileCoord): LngLatBBox;
+export declare function extentBBox({ xmin, ymin, xmax, ymax }: ZztsExtent): LngLatBBox;
+export declare function intersectBBox(a: Readonly<LngLatBBox>, b: Readonly<LngLatBBox>): LngLatBBox | undefined;
+/**
+ * 瓦片所在的合并请求区间：k×k 个相邻瓦片共用一次 elements 请求。
+ * k 取不超过 size 的 2 的幂，并保证区间经度跨度不超过服务端上限，以便各级别分组对齐。
+ */
+export declare function metatileRange(tile: TileCoord, size: number): TileRange;
 /** 瓦片在给定纬度处的比例尺分母，与公司 Cesium 组件的取值口径一致，保证服务端选出相同的网格级别 */
 export declare function tileScale(z: number, lat: number): number;
-export declare function zztsTileJson(url: string, media: ZztsMedia): {
+/**
+ * 规划区间的 elements 请求：bbox 裁到图层范围，经度跨度超限时等分成多段；
+ * 画布尺寸按裁剪后的像素范围等比缩小。`coarser` 为向上取粗的级数，每级比例尺翻倍，服务端随之降一级网格。
+ */
+export declare function planQueries(range: TileRange, extent: Readonly<LngLatBBox>, pixelRatio: number, coarser?: number): ZztsQuery[];
+export declare function zztsTileJson(url: string, media: ZztsMedia, clip?: Readonly<LngLatBBox>): {
     tiles: string[];
     bounds: LngLatBBox;
     minzoom: number;
@@ -48,7 +92,8 @@ export declare function zztsTileJson(url: string, media: ZztsMedia): {
     tileSize: number;
     name: string;
 };
-/** `coarser` 为相对瓦片默认级别向上取粗的级数，每级比例尺翻倍，服务端随之降一级 GeoSOT 网格 */
-export declare function elementsUrl(mediaUrl: string, tile: TileCoord, coarser?: number): string;
-/** 规划元素图片在瓦片上的绘制：经向线性；纬向在低级别按等高条带分段，逐段换算墨卡托以消除拉伸误差 */
-export declare function planDraws(extent: ZztsExtent, tile: TileCoord): ZztsDraw[];
+export declare function elementsUrl(mediaUrl: string, { bbox, width, height, scale }: ZztsQuery): string;
+/** 规划元素图片在画布上的绘制：经向线性；纬向在低级别按等高条带分段，逐段换算墨卡托以消除拉伸误差 */
+export declare function planDraws(extent: ZztsExtent, tile: TileCoord, size?: number): ZztsDraw[];
+/** 把经纬度环投影为画布像素坐标，供裁剪路径使用 */
+export declare function projectRings(rings: Position[][], { z, x, y }: TileCoord, size: number): [number, number][][];

package/dist/runtime/utils/zzts-tile.js

@@ -1,60 +1,121 @@
 export const ZZTS_TILE_SIZE = 512;
-const PROTOCOL_PREFIX = "zzts://";
-const TILE_HASH = /#(\d+)\/(\d+)\/(\d+)$/;
+const SCHEME_SEPARATOR = "://";
 const EARTH_CIRCUMFERENCE = 2 * Math.PI * 6378137;
+const MAX_LAT = 85.0511287798;
 const METERS_PER_PIXEL_TO_SCALE = 96 / 0.0254;
 const MAX_BBOX_SPAN = 20;
+const MIN_REQUEST_ZOOM = Math.ceil(Math.log2(360 / MAX_BBOX_SPAN));
+const MAX_PIXEL_RATIO = 4;
 const LINEAR_ZOOM = 8;
 const STRIP_HEIGHT = 32;
+const clampLat = (lat) => Math.max(-MAX_LAT, Math.min(MAX_LAT, lat));
+const lngAt = (x, z) => x / 2 ** z * 360 - 180;
+const latAt = (y, z) => Math.atan(Math.sinh(Math.PI * (1 - 2 * y / 2 ** z))) * 180 / Math.PI;
+const colAt = (lng, z) => (lng + 180) / 360 * 2 ** z;
+const rowAt = (lat, z) => (1 - Math.asinh(Math.tan(clampLat(lat) * Math.PI / 180)) / Math.PI) / 2 * 2 ** z;
 export function parseZztsUrl(url) {
-  const raw = url.startsWith(PROTOCOL_PREFIX) ? url.slice(PROTOCOL_PREFIX.length) : url;
-  const match = raw.match(TILE_HASH);
-  if (!match) return { mediaUrl: raw };
+  const raw = url.slice(url.indexOf(SCHEME_SEPARATOR) + SCHEME_SEPARATOR.length);
+  const hashIndex = raw.indexOf("#");
+  const mediaUrl = hashIndex < 0 ? raw : raw.slice(0, hashIndex);
+  const params = new URLSearchParams(hashIndex < 0 ? "" : raw.slice(hashIndex + 1));
+  const ratio = Number(params.get("pixelRatio"));
+  const [z, x, y] = (params.get("tile") ?? "").split("/").map(Number);
+  const clip = params.get("clip");
   return {
-    mediaUrl: raw.slice(0, match.index),
-    tile: { z: Number(match[1]), x: Number(match[2]), y: Number(match[3]) }
+    mediaUrl,
+    pixelRatio: Number.isFinite(ratio) ? Math.min(MAX_PIXEL_RATIO, Math.max(1, ratio)) : 1,
+    ...clip ? { clip } : {},
+    ...[z, x, y].every(Number.isInteger) ? { tile: { z, x, y } } : {}
   };
 }
-const lngAt = (x, z) => x / 2 ** z * 360 - 180;
-function snapOut(x, y, w, h) {
-  const left = Math.floor(x);
-  const top = Math.floor(y);
-  return [left, top, Math.ceil(x + w) - left, Math.ceil(y + h) - top];
+export function zztsSourceUrl(scheme, mediaUrl, { pixelRatio, clip } = {}) {
+  const params = new URLSearchParams();
+  if (pixelRatio && pixelRatio !== 1) params.set("pixelRatio", String(pixelRatio));
+  if (clip) params.set("clip", clip);
+  const hash = params.toString();
+  return `${scheme}${SCHEME_SEPARATOR}${mediaUrl}${hash ? `#${hash}` : ""}`;
 }
-const latAt = (y, z) => Math.atan(Math.sinh(Math.PI * (1 - 2 * y / 2 ** z))) * 180 / Math.PI;
-const rowAt = (lat, z) => (1 - Math.asinh(Math.tan(lat * Math.PI / 180)) / Math.PI) / 2 * 2 ** z;
-export function tileBBox({ z, x, y }) {
-  return [lngAt(x, z), latAt(y + 1, z), lngAt(x + 1, z), latAt(y, z)];
+export function canvasSize(pixelRatio) {
+  return Math.round(ZZTS_TILE_SIZE * pixelRatio);
+}
+export function tileRange({ z, x, y }) {
+  return { z, x0: x, y0: y, x1: x + 1, y1: y + 1 };
+}
+export function rangeBBox({ z, x0, y0, x1, y1 }) {
+  return [lngAt(x0, z), latAt(y1, z), lngAt(x1, z), latAt(y0, z)];
+}
+export function tileBBox(tile) {
+  return rangeBBox(tileRange(tile));
+}
+export function extentBBox({ xmin, ymin, xmax, ymax }) {
+  return [xmin, ymin, xmax, ymax];
+}
+export function intersectBBox(a, b) {
+  const west = Math.max(a[0], b[0]);
+  const south = Math.max(a[1], b[1]);
+  const east = Math.min(a[2], b[2]);
+  const north = Math.min(a[3], b[3]);
+  return west < east && south < north ? [west, south, east, north] : void 0;
+}
+export function metatileRange(tile, size) {
+  const span = 360 / 2 ** tile.z;
+  const limit = Math.min(size, MAX_BBOX_SPAN / span, 2 ** tile.z);
+  const k = limit >= 1 ? 2 ** Math.floor(Math.log2(limit)) : 1;
+  const x0 = Math.floor(tile.x / k) * k;
+  const y0 = Math.floor(tile.y / k) * k;
+  return { z: tile.z, x0, y0, x1: x0 + k, y1: y0 + k };
 }
 export function tileScale(z, lat) {
   const metersPerPixel = EARTH_CIRCUMFERENCE * Math.cos(lat * Math.PI / 180) / (ZZTS_TILE_SIZE * 2 ** z);
   return metersPerPixel * METERS_PER_PIXEL_TO_SCALE;
 }
-export function zztsTileJson(url, media) {
-  const { xmin, ymin, xmax, ymax } = media.extent;
-  const centerLat = (ymin + ymax) / 2;
-  const minzoom = Math.ceil(Math.log2(360 / MAX_BBOX_SPAN));
-  const nativeZoom = Math.ceil(Math.log2(EARTH_CIRCUMFERENCE * Math.cos(centerLat * Math.PI / 180) / (ZZTS_TILE_SIZE * media.resolution)));
+export function planQueries(range, extent, pixelRatio, coarser = 0) {
+  const clipped = intersectBBox(rangeBBox(range), extent);
+  if (!clipped) return [];
+  const [west, south, east, north] = clipped;
+  const z = Math.max(range.z, MIN_REQUEST_ZOOM);
+  const density = ZZTS_TILE_SIZE * pixelRatio;
+  const scale = tileScale(z, (south + north) / 2) / pixelRatio * 2 ** coarser;
+  const height = Math.max(1, Math.round((rowAt(south, z) - rowAt(north, z)) * density));
+  const parts = Math.ceil((east - west) / MAX_BBOX_SPAN);
+  const step = (east - west) / parts;
+  return Array.from({ length: parts }, (_, i) => {
+    const left = west + step * i;
+    const right = i === parts - 1 ? east : left + step;
+    const width = Math.max(1, Math.round((colAt(right, z) - colAt(left, z)) * density));
+    return { bbox: [left, south, right, north], width, height, scale };
+  });
+}
+export function zztsTileJson(url, media, clip) {
+  const { pixelRatio } = parseZztsUrl(url);
+  const extent = extentBBox(media.extent);
+  const centerLat = (extent[1] + extent[3]) / 2;
+  const nativeZoom = Math.ceil(Math.log2(EARTH_CIRCUMFERENCE * Math.cos(centerLat * Math.PI / 180) / (canvasSize(pixelRatio) * media.resolution)));
+  const [base, hash] = url.split("#");
   return {
-    tiles: [`${url}#{z}/{x}/{y}`],
-    bounds: [xmin, ymin, xmax, ymax],
-    minzoom,
-    maxzoom: Math.max(minzoom, nativeZoom),
+    tiles: [`${base}#${hash ? `${hash}&` : ""}tile={z}/{x}/{y}`],
+    bounds: clip && intersectBBox(extent, clip) || extent,
+    minzoom: 0,
+    maxzoom: Math.max(0, nativeZoom),
     tileSize: ZZTS_TILE_SIZE,
     name: media.name
   };
 }
-export function elementsUrl(mediaUrl, tile, coarser = 0) {
-  const [west, south, east, north] = tileBBox(tile);
+export function elementsUrl(mediaUrl, { bbox, width, height, scale }) {
   const url = new URL(mediaUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/elements`;
-  url.searchParams.set("width", String(ZZTS_TILE_SIZE));
-  url.searchParams.set("height", String(ZZTS_TILE_SIZE));
-  url.searchParams.set("scale", String(tileScale(tile.z, (south + north) / 2) * 2 ** coarser));
-  url.searchParams.set("bbox", [west, south, east, north].join(","));
+  url.searchParams.set("width", String(width));
+  url.searchParams.set("height", String(height));
+  url.searchParams.set("scale", String(scale));
+  url.searchParams.set("bbox", bbox.join(","));
   return url.toString();
 }
-export function planDraws(extent, tile) {
+function snapOut(x, y, w, h) {
+  const left = Math.floor(x);
+  const top = Math.floor(y);
+  return [left, top, Math.ceil(x + w) - left, Math.ceil(y + h) - top];
+}
+export function planDraws(extent, tile, size = ZZTS_TILE_SIZE) {
   const [west, south, east, north] = tileBBox(tile);
   const left = Math.max(extent.xmin, west);
   const right = Math.min(extent.xmax, east);
@@ -66,13 +127,13 @@ export function planDraws(extent, tile) {
   const height = extent.ymax - extent.ymin;
   const sx = (left - extent.xmin) / width;
   const sw = (right - left) / width;
-  const dx = ((left + 180) / 360 * 2 ** z - x) * ZZTS_TILE_SIZE;
-  const dw = (right - left) / 360 * 2 ** z * ZZTS_TILE_SIZE;
-  const dyTop = (rowAt(top, z) - y) * ZZTS_TILE_SIZE;
-  const dyBottom = (rowAt(bottom, z) - y) * ZZTS_TILE_SIZE;
+  const dx = (colAt(left, z) - x) * size;
+  const dw = (right - left) / 360 * 2 ** z * size;
+  const dyTop = (rowAt(top, z) - y) * size;
+  const dyBottom = (rowAt(bottom, z) - y) * size;
   const strips = z >= LINEAR_ZOOM ? 1 : Math.max(1, Math.ceil((dyBottom - dyTop) / STRIP_HEIGHT));
   const stripHeight = (dyBottom - dyTop) / strips;
-  const latAtPixel = (py) => latAt(y + py / ZZTS_TILE_SIZE, z);
+  const latAtPixel = (py) => latAt(y + py / size, z);
   return Array.from({ length: strips }, (_, i) => {
     const dy = dyTop + i * stripHeight;
     const latTop = i === 0 ? top : latAtPixel(dy);
@@ -83,3 +144,6 @@ export function planDraws(extent, tile) {
     };
   });
 }
+export function projectRings(rings, { z, x, y }, size) {
+  return rings.map((ring) => ring.map(([lng = 0, lat = 0]) => [(colAt(lng, z) - x) * size, (rowAt(lat, z) - y) * size]));
+}

package/dist/runtime/utils/zzts.d.ts

@@ -1,14 +1,29 @@
 export interface ZztsProtocolOptions {
+    /**
+     * 协议名；为不同服务分别注册（如各自的鉴权）时取不同名称
+     * @defaultValue 'zzts'
+     */
+    scheme?: string;
     /** 自定义请求，元数据、元素列表与元素图片共用；用于附加鉴权头或改走代理 */
     fetch?: typeof globalThis.fetch;
     /**
-     * 元素图片缓存数量；相邻瓦片常共用同一网格图片，命中时不再重复下载
+     * 元素图片缓存数量（压缩数据）；相邻瓦片常共用同一网格图片，命中时不再重复下载
      * @defaultValue 256
      */
     cacheSize?: number;
+    /**
+     * 网络错误或 5xx 时的重试次数，按 500ms 起指数退避；404 视为未生成，不重试
+     * @defaultValue 2
+     */
+    retry?: number;
+    /**
+     * 合并请求的边长（瓦片数，取 2 的幂）：相邻 n×n 个瓦片共用一次元素列表请求；设为 1 关闭合并
+     * @defaultValue 2
+     */
+    metatileSize?: number;
 }
 /**
- * 注册 `zzts://` 协议（全局单例、幂等）：把 ZZTS 二维动态切片服务适配为 512 墨卡托栅格瓦片。
- * `MaplibreRasterLayer` 的 `url` 写成 `zzts://` + media 接口地址即可。
+ * 注册 ZZTS 协议（按协议名全局单例、幂等）：把 ZZTS 二维动态切片服务适配为 512 墨卡托栅格瓦片。
+ * `MaplibreZztsLayer` 或 `MaplibreRasterLayer` 的 `url` 写成 `zzts://` + media 接口地址即可。
  */
 export declare function registerZztsProtocol(options?: ZztsProtocolOptions): void;

package/dist/runtime/utils/zzts.js

@@ -1,72 +1,135 @@
 import { addProtocol } from "maplibre-gl";
 import { defineGlobalSingleton } from "@movk/core";
-import { ZZTS_TILE_SIZE, elementsUrl, parseZztsUrl, planDraws, zztsTileJson } from "./zzts-tile.js";
+import { logger } from "./logger.js";
+import { createImageStore, createLru, fetchWithRetry } from "./zzts-cache.js";
+import { getZztsClip } from "./zzts-clip.js";
+import {
+  canvasSize,
+  elementsUrl,
+  extentBBox,
+  intersectBBox,
+  metatileRange,
+  parseZztsUrl,
+  planDraws,
+  planQueries,
+  projectRings,
+  tileBBox,
+  tileRange,
+  zztsTileJson
+} from "./zzts-tile.js";
 const EMPTY_TILE = new ArrayBuffer(0);
 const MAX_FALLBACK_LEVELS = 3;
-async function getJson(request, url, signal) {
-  const res = await request(url, { signal });
-  if (!res.ok) throw new Error(`ZZTS \u8BF7\u6C42\u5931\u8D25\uFF1AHTTP ${res.status}`);
-  return await res.json();
-}
+const ELEMENT_LIST_CACHE_SIZE = 512;
 function imageElements(payload) {
   if (!Array.isArray(payload.elements)) throw new Error(payload.msg || "ZZTS \u5143\u7D20\u8BF7\u6C42\u5931\u8D25");
-  return payload.elements.filter(
-    (element, i, list) => element.type === "image" && list.findIndex((item) => item.id === element.id) === i
-  );
+  return dedupe(payload.elements.filter((element) => element.type === "image"));
 }
-function createImageCache(request, size) {
-  const cache = /* @__PURE__ */ new Map();
-  return (url) => {
-    const hit = cache.get(url);
-    if (hit) {
-      cache.delete(url);
-      cache.set(url, hit);
-      return hit;
-    }
-    const pending = request(url).then(async (res) => {
-      if (res.status === 404) return void 0;
-      if (!res.ok) throw new Error(`ZZTS \u56FE\u7247\u52A0\u8F7D\u5931\u8D25\uFF1AHTTP ${res.status}`);
-      return createImageBitmap(await res.blob());
-    });
-    pending.catch(() => cache.delete(url));
-    cache.set(url, pending);
-    if (cache.size > size) cache.delete(cache.keys().next().value);
-    return pending;
-  };
+function dedupe(elements) {
+  const seen = /* @__PURE__ */ new Set();
+  return elements.filter(({ id, extent: { xmin, ymin, xmax, ymax } }) => {
+    const keys = [`id:${id}`, `extent:${[xmin, ymin, xmax, ymax].map((value) => value.toFixed(8))}`];
+    if (keys.some((key) => seen.has(key))) return false;
+    keys.forEach((key) => seen.add(key));
+    return true;
+  });
 }
-function compose(tile, items) {
-  const canvas = new OffscreenCanvas(ZZTS_TILE_SIZE, ZZTS_TILE_SIZE);
+function compose(tile, items, size, clip) {
+  const canvas = new OffscreenCanvas(size, size);
   const context = canvas.getContext("2d");
   for (const { element, image } of items) {
-    for (const { source: [sx, sy, sw, sh], target: [dx, dy, dw, dh] } of planDraws(element.extent, tile)) {
+    for (const { source: [sx, sy, sw, sh], target: [dx, dy, dw, dh] } of planDraws(element.extent, tile, size)) {
       context.drawImage(image, sx * image.width, sy * image.height, sw * image.width, sh * image.height, dx, dy, dw, dh);
     }
   }
+  if (clip) {
+    const path = new Path2D();
+    for (const [first, ...rest] of projectRings(clip.rings, tile, size)) {
+      if (!first) continue;
+      path.moveTo(...first);
+      rest.forEach((point) => path.lineTo(...point));
+      path.closePath();
+    }
+    context.globalCompositeOperation = "destination-in";
+    context.fill(path, "evenodd");
+  }
   return canvas.transferToImageBitmap();
 }
-function createZztsProtocol({ fetch: request = globalThis.fetch.bind(globalThis), cacheSize = 256 } = {}) {
-  const loadImage = createImageCache(request, cacheSize);
-  async function loadLevel(mediaUrl, tile, coarser, signal) {
-    const elements = imageElements(await getJson(request, elementsUrl(mediaUrl, tile, coarser), signal));
-    const images = await Promise.all(elements.map((element) => loadImage(element.url).catch(() => void 0)));
-    const layers = elements.flatMap((element, i) => images[i] ? [{ element, image: images[i] }] : []);
+function createZztsProtocol({
+  fetch: request = globalThis.fetch.bind(globalThis),
+  cacheSize = 256,
+  retry = 2,
+  metatileSize = 2
+}) {
+  const images = createImageStore(request, { size: cacheSize, retry });
+  const medias = /* @__PURE__ */ new Map();
+  const lists = createLru(ELEMENT_LIST_CACHE_SIZE);
+  async function getJson(url) {
+    const res = await fetchWithRetry(request, url, retry);
+    if (!res.ok) throw new Error(`ZZTS \u8BF7\u6C42\u5931\u8D25\uFF1AHTTP ${res.status}`);
+    return await res.json();
+  }
+  function shared(cache, key, load) {
+    const hit = cache.get(key);
+    if (hit) return hit;
+    const pending = load();
+    pending.catch(() => cache.delete(key));
+    cache.set(key, pending);
+    return pending;
+  }
+  const getMedia = (mediaUrl) => shared(medias, mediaUrl, () => getJson(mediaUrl));
+  function rangeElements(mediaUrl, media, range, pixelRatio, coarser) {
+    const key = [mediaUrl, pixelRatio, coarser, range.z, range.x0, range.y0, range.x1, range.y1].join("|");
+    return shared(lists, key, async () => {
+      const queries = planQueries(range, extentBBox(media.extent), pixelRatio, coarser);
+      const payloads = await Promise.all(queries.map((query) => getJson(elementsUrl(mediaUrl, query))));
+      return dedupe(payloads.flatMap(imageElements));
+    });
+  }
+  async function tileElements(mediaUrl, media, tile, pixelRatio, coarser) {
+    const group = metatileRange(tile, metatileSize);
+    const single = tileRange(tile);
+    const merged = group.x1 - group.x0 > 1;
+    let elements = await rangeElements(mediaUrl, media, group, pixelRatio, coarser);
+    if (merged && !elements.length) elements = await rangeElements(mediaUrl, media, single, pixelRatio, coarser);
+    const bbox = tileBBox(tile);
+    return elements.filter((element) => intersectBBox(extentBBox(element.extent), bbox));
+  }
+  async function loadLevel(mediaUrl, media, tile, pixelRatio, coarser, acquired) {
+    const elements = await tileElements(mediaUrl, media, tile, pixelRatio, coarser);
+    const loaded = await Promise.all(elements.map((element) => {
+      acquired.push(element.url);
+      return images.acquire(element.url);
+    }));
+    const layers = elements.flatMap((element, i) => loaded[i] ? [{ element, image: loaded[i] }] : []);
     if (layers.length === elements.length || coarser >= MAX_FALLBACK_LEVELS) return layers;
-    return [...await loadLevel(mediaUrl, tile, coarser + 1, signal), ...layers];
+    return [...await loadLevel(mediaUrl, media, tile, pixelRatio, coarser + 1, acquired), ...layers];
   }
   return async ({ url }, { signal }) => {
-    const { mediaUrl, tile } = parseZztsUrl(url);
-    if (!tile) {
-      const media = await getJson(request, mediaUrl, signal);
-      return { data: zztsTileJson(url, media) };
-    }
-    const layers = await loadLevel(mediaUrl, tile, 0, signal);
+    const { mediaUrl, tile, pixelRatio, clip: clipKey } = parseZztsUrl(url);
+    const clip = clipKey ? getZztsClip(clipKey) : void 0;
+    const media = await getMedia(mediaUrl);
     signal.throwIfAborted();
-    return { data: layers.length ? compose(tile, layers) : EMPTY_TILE };
+    if (!tile) return { data: zztsTileJson(url, media, clip?.bbox) };
+    if (clipKey && (!clip || !intersectBBox(tileBBox(tile), clip.bbox))) return { data: EMPTY_TILE };
+    const acquired = [];
+    try {
+      const layers = await loadLevel(mediaUrl, media, tile, pixelRatio, 0, acquired);
+      signal.throwIfAborted();
+      return { data: layers.length ? compose(tile, layers, canvasSize(pixelRatio), clip) : EMPTY_TILE };
+    } finally {
+      acquired.forEach(images.release);
+    }
   };
 }
-export function registerZztsProtocol(options) {
-  defineGlobalSingleton("movk-maplibre:protocol:zzts", () => {
-    addProtocol("zzts", createZztsProtocol(options));
+export function registerZztsProtocol(options = {}) {
+  const scheme = options.scheme ?? "zzts";
+  let created = false;
+  defineGlobalSingleton(`movk-maplibre:protocol:${scheme}`, () => {
+    created = true;
+    addProtocol(scheme, createZztsProtocol(options));
     return true;
   });
+  if (!created && Object.keys(options).some((key) => key !== "scheme")) {
+    logger.warn(`ZZTS protocol "${scheme}" is already registered; the new options are ignored. Register a different scheme for another configuration.`);
+  }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/maplibre",
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "packageManager": "pnpm@12.10.1",
   "description": "声明式 MapLibre GL 封装库：MaplibreMap/Source/Layer 等组件与 composables，原生支持 Nuxt 4 模块，并通过 Vite 插件在纯 Vue + Vite 项目中可用。无需 access token，内置 3D 建筑、雷达/扩散/辉光等动态效果，sky/terrain 环境，绘制（terra-draw）、天地图、WMS/WMTS 与多坐标系本土化支持。",
   "author": "YiXuan <mhaibaraai@gmail.com>",