uni-leaflet 1.0.0

package/engine/tile-manager.ts

@@ -0,0 +1,192 @@
+import { formatTileUrl } from '../utils/tile';
+
+export interface TileImageRecord {
+  image: any;
+  status: 'loading' | 'loaded' | 'error';
+  lastUsed: number;
+}
+
+export interface ParentFallbackInfo {
+  image: any;
+  // Sub-rectangle in parent tile (0..256)
+  srcX: number;
+  srcY: number;
+  srcSize: number;
+}
+
+export class TileManager {
+  private cache: Map<string, TileImageRecord> = new Map();
+  private maxCacheSize: number;
+  private canvasNode: any;
+  private onTileLoadedCallback?: (key: string) => void;
+
+  constructor(maxCacheSize = 250) {
+    this.maxCacheSize = maxCacheSize;
+  }
+
+  public setCanvasNode(canvasNode: any) {
+    this.canvasNode = canvasNode;
+  }
+
+  public setOnTileLoaded(cb: (key: string) => void) {
+    this.onTileLoadedCallback = cb;
+  }
+
+  /**
+   * Create an Image instance (supports mini-program Canvas 2D and Web)
+   */
+  private createImageInstance(): any {
+    if (this.canvasNode && typeof this.canvasNode.createImage === 'function') {
+      return this.canvasNode.createImage();
+    }
+    if (typeof Image !== 'undefined') {
+      try {
+        const img = new Image();
+        img.crossOrigin = 'Anonymous';
+        return img;
+      } catch (e) {}
+    }
+    return null;
+  }
+
+  /**
+   * Request a tile. If cached and loaded, returns the image record.
+   * If not cached, initiates image loading across Web, Mini-Program, and App-Plus.
+   */
+  public requestTile(key: string, url: string): TileImageRecord | null {
+    const existing = this.cache.get(key);
+    if (existing) {
+      existing.lastUsed = Date.now();
+      return existing;
+    }
+
+    const img = this.createImageInstance();
+    if (img) {
+      const record: TileImageRecord = {
+        image: img,
+        status: 'loading',
+        lastUsed: Date.now(),
+      };
+
+      this.evictIfNeeded();
+      this.cache.set(key, record);
+
+      img.onload = () => {
+        record.status = 'loaded';
+        if (this.onTileLoadedCallback) {
+          this.onTileLoadedCallback(key);
+        }
+      };
+
+      img.onerror = () => {
+        record.status = 'error';
+      };
+
+      img.src = url;
+      return record;
+    }
+
+    // Fallback for App-Plus / non-DOM environments using uni.getImageInfo
+    if (typeof uni !== 'undefined' && typeof uni.getImageInfo === 'function') {
+      const record: TileImageRecord = {
+        image: url,
+        status: 'loading',
+        lastUsed: Date.now(),
+      };
+
+      this.evictIfNeeded();
+      this.cache.set(key, record);
+
+      uni.getImageInfo({
+        src: url,
+        success: (res: any) => {
+          record.image = res.path || url;
+          record.status = 'loaded';
+          if (this.onTileLoadedCallback) {
+            this.onTileLoadedCallback(key);
+          }
+        },
+        fail: () => {
+          record.status = 'error';
+        },
+      });
+
+      return record;
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if a parent tile (from lower zoom levels) is already loaded to serve as fallback
+   */
+  public getParentFallback(
+    z: number,
+    x: number,
+    y: number,
+    tileUrlTemplate: string,
+    subdomains: string[] = ['a', 'b', 'c'],
+    minZ = 0,
+    tileSize = 256
+  ): ParentFallbackInfo | null {
+    for (let pz = z - 1; pz >= minZ; pz--) {
+      const zoomDiff = z - pz;
+      const factor = 1 << zoomDiff;
+      const px = Math.floor(x / factor);
+      const py = Math.floor(y / factor);
+
+      const parentUrl = formatTileUrl(tileUrlTemplate, px, py, pz, subdomains);
+      const parentKey = `${pz}_${px}_${py}_${parentUrl}`;
+      const record = this.cache.get(parentKey);
+
+      if (record && record.status === 'loaded' && record.image) {
+        const subTileSize = tileSize / factor;
+        const subX = (x % factor) * subTileSize;
+        const subY = (y % factor) * subTileSize;
+
+        return {
+          image: record.image,
+          srcX: subX,
+          srcY: subY,
+          srcSize: subTileSize,
+        };
+      }
+    }
+    return null;
+  }
+
+  private evictIfNeeded() {
+    if (this.cache.size < this.maxCacheSize) return;
+
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+
+    for (const [k, v] of this.cache.entries()) {
+      if (v.lastUsed < oldestTime) {
+        oldestTime = v.lastUsed;
+        oldestKey = k;
+      }
+    }
+
+    if (oldestKey) {
+      const item = this.cache.get(oldestKey);
+      if (item && item.image) {
+        item.image.onload = null;
+        item.image.onerror = null;
+        item.image.src = '';
+      }
+      this.cache.delete(oldestKey);
+    }
+  }
+
+  public clear() {
+    for (const [, v] of this.cache.entries()) {
+      if (v.image) {
+        v.image.onload = null;
+        v.image.onerror = null;
+        v.image.src = '';
+      }
+    }
+    this.cache.clear();
+  }
+}

package/index.ts

@@ -0,0 +1,19 @@
+import type { App, Plugin } from 'vue';
+import UniLeafletMap from './UniLeafletMap.vue';
+
+export * from './types';
+export * from './utils/crs';
+export * from './utils/tile';
+export * from './engine/factory';
+export { UniLeafletMap };
+
+/**
+ * Vue 3 Plugin installation helper (app.use(UniLeaflet))
+ */
+const UniLeaflet: Plugin = {
+  install(app: App) {
+    app.component('UniLeafletMap', UniLeafletMap);
+  },
+};
+
+export default UniLeaflet;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "uni-leaflet",
+  "version": "1.0.0",
+  "description": "Cross-platform Leaflet and Native Canvas 2D Map Component for Uni-App (Vue 3, H5, WeChat Mini-Program, App)",
+  "main": "index.ts",
+  "module": "index.ts",
+  "types": "index.ts",
+  "files": [
+    "**/*"
+  ],
+  "keywords": [
+    "uniapp",
+    "leaflet",
+    "map",
+    "canvas",
+    "canvas-2d",
+    "wechat-miniprogram",
+    "wechat",
+    "h5",
+    "gis",
+    "tianditu",
+    "gaode",
+    "vue3",
+    "typescript"
+  ],
+  "author": "jikekaifa@qq.com",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yyylrrr/uniapp-helper"
+  },
+  "peerDependencies": {
+    "@dcloudio/uni-app": ">=3.0.0",
+    "leaflet": "^1.9.4",
+    "vue": "^3.0.0"
+  },
+  "uni_modules": {
+    "scripts": {},
+    "dcloudext": {
+      "category": [
+        "前端组件",
+        "地图组件"
+      ]
+    }
+  }
+}

package/types.ts

@@ -0,0 +1,159 @@
+export type LatLngTuple = [number, number]; // [latitude, longitude]
+
+export interface LatLng {
+  lat: number;
+  lng: number;
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface TileCoordinate {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface MapBounds {
+  minLat: number;
+  maxLat: number;
+  minLng: number;
+  maxLng: number;
+}
+
+export interface TileLayerConfig {
+  id?: string;
+  url: string;
+  subdomains?: string[];
+  opacity?: number;
+  minZoom?: number;
+  maxZoom?: number;
+  zIndex?: number;
+}
+
+export interface MarkerLabelOptions {
+  text: string;
+  offset?: [number, number]; // [offsetX, offsetY] in px
+  color?: string;
+  fontSize?: number;
+  backgroundColor?: string;
+  borderColor?: string;
+  borderRadius?: number;
+  padding?: [number, number]; // [paddingY, paddingX] in px
+  show?: boolean;
+}
+
+export interface MarkerIconOptions {
+  /** Image URL for PNG/JPG/WebP/SVG or data URI (e.g. '/static/icons/pin-blue.png', 'data:image/png;base64,...') */
+  url?: string;
+  /** Raw SVG string markup (e.g. '<svg viewBox="0 0 24 24">...</svg>') */
+  svg?: string;
+  /** Custom HTML markup string (H5 and App renderjs) */
+  html?: string;
+  /** Emoji or single character e.g. '📍', '🏛️', '🚩', '☕' */
+  text?: string;
+  /** Default pin fill color or tint color (e.g. '#3b82f6', '#ef4444') */
+  color?: string;
+  /** Icon size in px: [width, height], default [32, 32] */
+  size?: [number, number];
+  /** Icon anchor point in px: [anchorX, anchorY], default [width/2, height] */
+  anchor?: [number, number];
+}
+
+export interface MarkerOptions {
+  id?: string | number;
+  latLng: LatLngTuple;
+  title?: string;
+  icon?: MarkerIconOptions;
+  label?: string | MarkerLabelOptions;
+  data?: any;
+}
+
+export interface PolylineOptions {
+  id?: string | number;
+  latLngs: LatLngTuple[];
+  color?: string;
+  width?: number;
+  dashArray?: number[];
+  opacity?: number;
+  label?: string | MarkerLabelOptions;
+  data?: any;
+}
+
+export interface PolygonOptions {
+  id?: string | number;
+  latLngs: LatLngTuple[];
+  color?: string; // stroke border color
+  fillColor?: string; // fill color
+  fillOpacity?: number;
+  width?: number; // stroke width
+  label?: string | MarkerLabelOptions;
+  data?: any;
+}
+
+export interface CircleOptions {
+  id?: string | number;
+  latLng: LatLngTuple;
+  radius: number; // in meters
+  color?: string;
+  fillColor?: string;
+  fillOpacity?: number;
+  width?: number;
+  label?: string | MarkerLabelOptions;
+  data?: any;
+}
+
+export interface MapOverlays {
+  markers?: MarkerOptions[];
+  polylines?: PolylineOptions[];
+  polygons?: PolygonOptions[];
+  circles?: CircleOptions[];
+}
+
+export interface OverlayClickEvent {
+  type: 'marker' | 'polyline' | 'polygon' | 'circle';
+  data: MarkerOptions | PolylineOptions | PolygonOptions | CircleOptions;
+}
+
+export interface MapOptions {
+  center: LatLngTuple;
+  zoom: number;
+  minZoom?: number;
+  maxZoom?: number;
+  tileUrl?: string;
+  subdomains?: string[];
+  layers?: Array<string | TileLayerConfig>;
+  overlays?: MapOverlays;
+  showControls?: boolean;
+}
+
+export interface MapChangeEvent {
+  center: LatLngTuple;
+  zoom: number;
+}
+
+/**
+ * Unified Map Engine Interface (Strategy / Adapter Pattern)
+ */
+export interface IMapEngine {
+  setCenter(center: LatLngTuple, animate?: boolean): void;
+  setZoom(zoom: number): void;
+  zoomIn(): void;
+  zoomOut(): void;
+  panTo(center: LatLngTuple, duration?: number): void;
+  setTileUrl(url: string, subdomains?: string[]): void;
+  setLayers(layers: Array<string | TileLayerConfig>): void;
+  setOverlays(overlays: MapOverlays): void;
+  setMarkers(markers: MarkerOptions[]): void;
+  setPolylines(polylines: PolylineOptions[]): void;
+  setPolygons(polygons: PolygonOptions[]): void;
+  setCircles(circles: CircleOptions[]): void;
+  clearOverlays(): void;
+  getCenter(): LatLngTuple;
+  getZoom(): number;
+  resize(width?: number, height?: number): void;
+  destroy(): void;
+  getNativeInstance?(): any;
+}

package/utils/crs.ts

@@ -0,0 +1,60 @@
+import type { LatLng, Point } from '../types';
+
+const MAX_LATITUDE = 85.0511287798;
+const DEG_TO_RAD = Math.PI / 180;
+const RAD_TO_DEG = 180 / Math.PI;
+
+/**
+ * Limit value within [min, max]
+ */
+export function clamp(val: number, min: number, max: number): number {
+  return Math.min(Math.max(val, min), max);
+}
+
+/**
+ * Convert Latitude & Longitude to world pixel coordinates at a given zoom level (EPSG:3857)
+ */
+export function latLngToWorldPixel(
+  lat: number,
+  lng: number,
+  zoom: number,
+  tileSize = 256
+): Point {
+  const clampedLat = clamp(lat, -MAX_LATITUDE, MAX_LATITUDE);
+  const scale = tileSize * Math.pow(2, zoom);
+
+  // X coordinate
+  const x = ((lng + 180) / 360) * scale;
+
+  // Y coordinate
+  const sin = Math.sin(clampedLat * DEG_TO_RAD);
+  const y = (0.5 - Math.log((1 + sin) / (1 - sin)) / (4 * Math.PI)) * scale;
+
+  return { x, y };
+}
+
+/**
+ * Convert world pixel coordinates back to Latitude & Longitude at a given zoom level (EPSG:3857)
+ */
+export function worldPixelToLatLng(
+  x: number,
+  y: number,
+  zoom: number,
+  tileSize = 256
+): LatLng {
+  const scale = tileSize * Math.pow(2, zoom);
+
+  // Longitude
+  let lng = (x / scale) * 360 - 180;
+  // Normalize longitude to [-180, 180]
+  lng = (((lng + 180) % 360) + 360) % 360 - 180;
+
+  // Latitude
+  const normY = 0.5 - y / scale;
+  const lat = RAD_TO_DEG * (2 * Math.atan(Math.exp(normY * 2 * Math.PI)) - Math.PI / 2);
+
+  return {
+    lat: clamp(lat, -MAX_LATITUDE, MAX_LATITUDE),
+    lng,
+  };
+}

package/utils/tile.ts

@@ -0,0 +1,118 @@
+import type { Point } from '../types';
+import { latLngToWorldPixel } from './crs';
+
+export interface VisibleTile {
+  key: string;
+  x: number;
+  y: number;
+  z: number;
+  url: string;
+  screenX: number;
+  screenY: number;
+  screenSize: number;
+}
+
+/**
+ * Format tile URL with template string {z}, {x}, {y}, {s}, {-y}
+ */
+export function formatTileUrl(
+  template: string,
+  x: number,
+  y: number,
+  z: number,
+  subdomains: string[] = ['a', 'b', 'c']
+): string {
+  const maxTile = 1 << z;
+  // Normalize x (wrap around longitude)
+  const normalizedX = ((x % maxTile) + maxTile) % maxTile;
+  
+  // Calculate subdomain
+  const subdomain =
+    subdomains.length > 0
+      ? subdomains[Math.abs(normalizedX + y) % subdomains.length]
+      : '';
+
+  // TMS inverted y
+  const invertedY = maxTile - 1 - y;
+
+  return template
+    .replace('{z}', String(z))
+    .replace('{x}', String(normalizedX))
+    .replace('{y}', String(y))
+    .replace('{-y}', String(invertedY))
+    .replace('{s}', subdomain);
+}
+
+/**
+ * Calculate all visible tiles in current viewport
+ */
+export function getVisibleTiles(
+  centerLat: number,
+  centerLng: number,
+  zoom: number,
+  viewWidth: number,
+  viewHeight: number,
+  tileUrlTemplate: string,
+  subdomains: string[] = ['a', 'b', 'c'],
+  tileSize = 256
+): { tiles: VisibleTile[]; centerWorldPixel: Point } {
+  // Determine base integer zoom for tile fetching
+  const baseZoom = Math.floor(zoom);
+  const zoomFraction = zoom - baseZoom;
+  const zoomScale = Math.pow(2, zoomFraction);
+  const currentTileSize = tileSize * zoomScale;
+
+  // World pixel position of center at baseZoom
+  const centerWorldPixel = latLngToWorldPixel(centerLat, centerLng, baseZoom, tileSize);
+
+  // Viewport half dimensions scaled
+  const halfW = viewWidth / 2;
+  const halfH = viewHeight / 2;
+
+  // World pixel bounds visible in viewport (relative to baseZoom)
+  const minWorldX = centerWorldPixel.x - halfW / zoomScale;
+  const maxWorldX = centerWorldPixel.x + halfW / zoomScale;
+  const minWorldY = centerWorldPixel.y - halfH / zoomScale;
+  const maxWorldY = centerWorldPixel.y + halfH / zoomScale;
+
+  // Tile index bounds
+  const minTileX = Math.floor(minWorldX / tileSize);
+  const maxTileX = Math.floor(maxWorldX / tileSize);
+  const minTileY = Math.floor(minWorldY / tileSize);
+  const maxTileY = Math.floor(maxWorldY / tileSize);
+
+  const maxTileCount = 1 << baseZoom;
+  const tiles: VisibleTile[] = [];
+
+  for (let tileY = minTileY; tileY <= maxTileY; tileY++) {
+    // Y tile index must be within [0, 2^z - 1]
+    if (tileY < 0 || tileY >= maxTileCount) continue;
+
+    for (let tileX = minTileX; tileX <= maxTileX; tileX++) {
+      // Calculate tile top-left in world pixels at baseZoom
+      const tileWorldX = tileX * tileSize;
+      const tileWorldY = tileY * tileSize;
+
+      // Project into screen coordinates
+      const screenX = halfW + (tileWorldX - centerWorldPixel.x) * zoomScale;
+      const screenY = halfH + (tileWorldY - centerWorldPixel.y) * zoomScale;
+
+      const normX = ((tileX % maxTileCount) + maxTileCount) % maxTileCount;
+      const url = formatTileUrl(tileUrlTemplate, normX, tileY, baseZoom, subdomains);
+      const key = url;
+
+      tiles.push({
+        key,
+        x: normX,
+        y: tileY,
+        z: baseZoom,
+        url,
+        screenX,
+        screenY,
+        screenSize: currentTileSize,
+      });
+    }
+  }
+
+  return { tiles, centerWorldPixel };
+}