expo-gaode-map-navigation 2.0.3 → 2.0.4

package/build/map/ExpoGaodeMapModule.d.ts

@@ -1,13 +1,254 @@
-import type { ExpoGaodeMapModule } from './types/native-module.types';
-import { SDKConfig } from './types/common.types';
+import { LatLng, Coordinates, ReGeocode, LocationListener, LatLngPoint, CoordinateType } from './types';
+import type { ExpoGaodeMapModule as NativeExpoGaodeMapModule } from './types/native-module.types';
+import { PrivacyConfig, PrivacyStatus, SDKConfig, PermissionStatus } from './types/common.types';
+declare const helperMethods: {
+    /**
+     * 初始化 SDK，并缓存配置（包含 webKey）
+     * 注意：允许不提供任何 API Key，因为原生端可能已通过 Config Plugin 配置
+     */
+    initSDK(config: SDKConfig): void;
+    isSDKInitialized(): boolean;
+    /**
+     * 设置是否显示隐私政策弹窗
+     * @deprecated 请优先使用 `setPrivacyConfig`
+     */
+    setPrivacyShow(hasShow: boolean, hasContainsPrivacy: boolean): void;
+    /**
+     * 设置用户是否同意隐私政策
+     * @deprecated 请优先使用 `setPrivacyConfig`
+     */
+    setPrivacyAgree(hasAgree: boolean): void;
+    /**
+     * 设置当前隐私协议版本
+     * 当版本号变化时，之前的同意状态会失效
+     */
+    setPrivacyVersion(version: string): void;
+    /**
+     * 清空已持久化的隐私同意状态
+     */
+    resetPrivacyConsent(): void;
+    /**
+     * 一次性同步完整的隐私状态
+     * 推荐业务层只调用这个方法
+     */
+    setPrivacyConfig(config: PrivacyConfig): void;
+    getPrivacyStatus(): PrivacyStatus;
+    calculateDistanceBetweenPoints(p1: LatLngPoint, p2: LatLngPoint): number;
+    calculateDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+    setLoadWorldVectorMap(enabled: boolean): void;
+    getVersion(): string;
+    start(): void;
+    stop(): void;
+    isStarted(): Promise<boolean>;
+    getCurrentLocation(): Promise<Coordinates | ReGeocode>;
+    coordinateConvert(coordinate: LatLngPoint, type: CoordinateType): Promise<LatLng>;
+    setLocatingWithReGeocode(isReGeocode: boolean): void;
+    readonly isBackgroundLocationEnabled: boolean;
+    /**
+     * 检查位置权限状态
+     */
+    checkLocationPermission(): Promise<PermissionStatus>;
+    /**
+     * 请求前台位置权限（增强版）
+     */
+    requestLocationPermission(): Promise<PermissionStatus>;
+    /**
+     * 请求后台位置权限
+     * 注意：必须在前台权限已授予后才能请求
+     */
+    requestBackgroundLocationPermission(): Promise<PermissionStatus>;
+    /**
+     * 打开应用设置页面
+     * 引导用户手动授予权限
+     */
+    openAppSettings(): void;
+    setAllowsBackgroundLocationUpdates(allows: boolean): void;
+    /**
+     * 添加定位监听器（便捷方法）
+     * 自动订阅 onLocationUpdate 事件，提供容错处理
+     * @param listener 定位回调函数
+     * @returns 订阅对象，调用 remove() 取消监听
+     * 注意：如果使用 Config Plugin 配置了 API Key，无需调用 initSDK()
+     */
+    addLocationListener(listener: LocationListener): {
+        remove: () => void;
+    };
+    /**
+     * 计算两个坐标点之间的距离
+     * @param coordinate1 第一个坐标点
+     * @param coordinate2 第二个坐标点
+     * @returns 两点之间的距离（单位：米）
+     */
+    distanceBetweenCoordinates(coordinate1: LatLngPoint, coordinate2: LatLngPoint): number;
+    /**
+     * 判断点是否在圆内
+     * @param point 要判断的点
+     * @param center 圆心坐标
+     * @param radius 圆半径（单位：米）
+     * @returns 是否在圆内
+     */
+    isPointInCircle(point: LatLngPoint, center: LatLngPoint, radius: number): boolean;
+    /**
+     * 判断点是否在多边形内
+     * @param point 要判断的点
+     * @param polygon 多边形的顶点坐标数组
+     * @returns 是否在多边形内
+     */
+    isPointInPolygon(point: LatLngPoint, polygon: LatLngPoint[]): boolean;
+    /**
+     * 计算多边形面积
+     * @param polygon 多边形的顶点坐标数组
+     * @returns 面积（单位：平方米）
+     */
+    calculatePolygonArea(polygon: LatLngPoint[]): number;
+    /**
+     * 计算矩形面积
+     * @param southWest 西南角坐标
+     * @param northEast 东北角坐标
+     * @returns 面积（单位：平方米）
+     */
+    calculateRectangleArea(southWest: LatLngPoint, northEast: LatLngPoint): number;
+    /**
+     * 获取路径上距离目标点最近的点
+     * @param path 路径点集合
+     * @param target 目标点
+     * @returns 最近点信息，包含坐标、索引和距离
+     */
+    getNearestPointOnPath(path: LatLngPoint[], target: LatLngPoint): {
+        latitude: number;
+        longitude: number;
+        index: number;
+        distanceMeters: number;
+    } | null;
+    /**
+     * 计算多边形质心
+     * @param polygon 多边形顶点坐标数组
+     * @returns 质心坐标
+     */
+    calculateCentroid(polygon: LatLngPoint[]): LatLng | null;
+    /**
+     * 计算路径边界和中心点
+     * @param points 路径点集合
+     * @returns 边界信息，包含 north, south, east, west 和 center
+     */
+    calculatePathBounds(points: LatLngPoint[]): {
+        north: number;
+        south: number;
+        east: number;
+        west: number;
+        center: LatLngPoint;
+    } | null;
+    /**
+     * GeoHash 编码
+     * @param coordinate 坐标点
+     * @param precision 精度 (1-12)
+     * @returns GeoHash 字符串
+     */
+    encodeGeoHash(coordinate: LatLngPoint, precision: number): string;
+    /**
+     * 轨迹抽稀 (RDP 算法)
+     * @param points 原始轨迹点
+     * @param tolerance 允许误差(米)
+     * @returns 简化后的轨迹点
+     */
+    simplifyPolyline(points: LatLngPoint[], tolerance: number): LatLng[];
+    /**
+     * 计算路径总长度
+     * @param points 路径点
+     * @returns 长度(米)
+     */
+    calculatePathLength(points: LatLngPoint[]): number;
+    /**
+     * 解析高德地图 API 返回的 Polyline 字符串
+     * 格式: "lng,lat;lng,lat;..."
+     * @param polylineStr 高德原始 polyline 字符串，或包含 polyline 属性的对象
+     * @returns 解析后的点集
+     */
+    parsePolyline(polylineStr: string | {
+        polyline: string;
+    }): LatLng[];
+    /**
+     * 获取路径上指定距离的点
+     * @param points 路径点
+     * @param distance 距离起点的米数
+     * @returns 点信息(坐标+角度)
+     */
+    getPointAtDistance(points: LatLngPoint[], distance: number): {
+        latitude: number;
+        longitude: number;
+        angle: number;
+    } | null;
+    /**
+     * 经纬度转换为地图瓦片坐标
+     * @param coordinate 经纬度点
+     * @param zoom 缩放级别
+     * @returns 瓦片坐标(x, y, z)
+     */
+    latLngToTile(coordinate: LatLngPoint, zoom: number): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /**
+     * 地图瓦片坐标转换为经纬度
+     * @param tile 瓦片坐标(x, y, z)
+     * @returns 经纬度点
+     */
+    tileToLatLng(tile: {
+        x: number;
+        y: number;
+        z: number;
+    }): LatLng | null;
+    /**
+     * 经纬度转换为地图像素坐标
+     * @param coordinate 经纬度点
+     * @param zoom 缩放级别
+     * @returns 像素坐标(x, y)
+     */
+    latLngToPixel(coordinate: LatLngPoint, zoom: number): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * 地图像素坐标转换为经纬度
+     * @param pixel 像素坐标(x, y)
+     * @param zoom 缩放级别
+     * @returns 经纬度点
+     */
+    pixelToLatLng(pixel: {
+        x: number;
+        y: number;
+    }, zoom: number): LatLng | null;
+    /**
+     * 批量地理围栏检测
+     * @param point 待检查的点
+     * @param polygons 多边形数组，格式为 LatLngPoint[][] 或 LatLngPoint[][][]
+     * @returns 包含点索引的数组（-1 表示不在任何多边形内）
+     */
+    findPointInPolygons(point: LatLngPoint, polygons: LatLngPoint[][] | LatLngPoint[][][]): number;
+    /**
+     * 生成网格聚合数据 (常用于展示网格聚合图或大规模点数据处理)
+     * @param points 包含经纬度和权重的点数组
+     * @param gridSizeMeters 网格大小（米）
+     * @returns 包含经纬度和强度的网格点数组
+     */
+    generateHeatmapGrid(points: Array<LatLngPoint & {
+        weight?: number;
+    }>, gridSizeMeters: number): Array<{
+        latitude: number;
+        longitude: number;
+        intensity: number;
+    }>;
+};
 /**
 * 获取最近一次 initSDK 的配置
 */
 export declare function getSDKConfig(): SDKConfig | null;
+export type ExpoGaodeMapModule = typeof helperMethods & NativeExpoGaodeMapModule;
+declare const ExpoGaodeMapModuleWithHelpers: ExpoGaodeMapModule;
 /**
 * 获取用于 Web API 的 webKey（若未初始化或未提供则返回 undefined）
 */
 export declare function getWebKey(): string | undefined;
-declare const _default: ExpoGaodeMapModule;
-export default _default;
+export default ExpoGaodeMapModuleWithHelpers;
 //# sourceMappingURL=ExpoGaodeMapModule.d.ts.map

package/build/map/ExpoGaodeMapModule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoGaodeMapModule.d.ts","sourceRoot":"","sources":["../../src/map/ExpoGaodeMapModule.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,OAAO,EAAE,SAAS,EAAoB,MAAM,sBAAsB,CAAC;AAqpBnE;;EAEE;AACF,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAE/C;AAED;;EAEE;AACF,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;wBAE0D,kBAAkB;AAA7E,wBAA8E"}
+{"version":3,"file":"ExpoGaodeMapModule.d.ts","sourceRoot":"","sources":["../../src/map/ExpoGaodeMapModule.ts"],"names":[],"mappings":"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"}

package/build/map/ExpoGaodeMapModule.js

@@ -2,30 +2,91 @@ import { requireNativeModule } from 'expo';
 import { Platform } from 'react-native';
 import { ErrorHandler, ErrorLogger } from './utils/ErrorHandler';
 import { normalizeLatLng, normalizeLatLngList } from './utils/GeoUtils';
-// 获取原生模块实例 - 添加容错处理
-let nativeModule = null;
-try {
-    nativeModule = requireNativeModule('ExpoGaodeMap');
+let nativeModuleCache = null;
+function getNativeModule(optional = false) {
+    if (nativeModuleCache) {
+        return nativeModuleCache;
+    }
+    try {
+        nativeModuleCache = requireNativeModule('ExpoGaodeMap');
+        return nativeModuleCache;
+    }
+    catch (error) {
+        if (optional) {
+            return null;
+        }
+        const moduleError = ErrorHandler.nativeModuleUnavailable();
+        ErrorLogger.log(moduleError);
+        throw moduleError;
+    }
 }
-catch (error) {
-    console.error('Failed to load ExpoGaodeMap native module:', error);
-    const moduleError = ErrorHandler.nativeModuleUnavailable();
-    ErrorLogger.log(moduleError);
+function getBoundNativeValue(module, prop) {
+    const value = Reflect.get(module, prop, module);
+    if (typeof value === 'function') {
+        return (...args) => value.apply(module, args);
+    }
+    return value;
 }
+const nativeModule = new Proxy({}, {
+    get(_target, prop) {
+        const module = getNativeModule(true);
+        return module ? getBoundNativeValue(module, prop) : undefined;
+    },
+});
 // 记录最近一次 initSDK 的配置（含 webKey）
 let _sdkConfig = null;
 let _isSDKInitialized = false;
+const privacySensitiveMethodNames = new Set([
+    'start',
+    'stop',
+    'isStarted',
+    'getCurrentLocation',
+    'coordinateConvert',
+    'setLocatingWithReGeocode',
+    'setLocationMode',
+    'setInterval',
+    'setOnceLocation',
+    'setSensorEnable',
+    'setWifiScan',
+    'setGpsFirst',
+    'setOnceLocationLatest',
+    'setGeoLanguage',
+    'setLocationCacheEnable',
+    'setHttpTimeOut',
+    'setDesiredAccuracy',
+    'setLocationTimeout',
+    'setReGeocodeTimeout',
+    'setDistanceFilter',
+    'setPausesLocationUpdatesAutomatically',
+    'setAllowsBackgroundLocationUpdates',
+    'setLocationProtocol',
+    'startUpdatingHeading',
+    'stopUpdatingHeading',
+    'checkLocationPermission',
+    'requestLocationPermission',
+    'requestBackgroundLocationPermission',
+    'addLocationListener',
+]);
+function assertPrivacyReady(scene = 'sdk') {
+    const nativeModule = getNativeModule();
+    if (!nativeModule) {
+        throw ErrorHandler.nativeModuleUnavailable();
+    }
+    const status = nativeModule.getPrivacyStatus();
+    if (!status.isReady) {
+        throw ErrorHandler.privacyNotAgreed(scene);
+    }
+}
 // 扩展原生模块，添加便捷方法
-const ExpoGaodeMapModuleWithHelpers = {
-    ...(nativeModule || {}),
+const helperMethods = {
     /**
      * 初始化 SDK，并缓存配置（包含 webKey）
      * 注意：允许不提供任何 API Key，因为原生端可能已通过 Config Plugin 配置
      */
     initSDK(config) {
-        if (!nativeModule) {
+        const nativeModule = getNativeModule();
+        if (!nativeModule)
             throw ErrorHandler.nativeModuleUnavailable();
-        }
         try {
             // 检查是否有任何 key 被提供
             const hasJSKeys = !!(config.androidKey || config.iosKey);
@@ -54,19 +115,90 @@ const ExpoGaodeMapModuleWithHelpers = {
     isSDKInitialized() {
         return _isSDKInitialized;
     },
+    /**
+     * 设置是否显示隐私政策弹窗
+     * @deprecated 请优先使用 `setPrivacyConfig`
+     */
+    setPrivacyShow(hasShow, hasContainsPrivacy) {
+        const nativeModule = getNativeModule();
+        if (!nativeModule)
+            throw ErrorHandler.nativeModuleUnavailable();
+        nativeModule.setPrivacyShow(hasShow, hasContainsPrivacy);
+    },
+    /**
+     * 设置用户是否同意隐私政策
+     * @deprecated 请优先使用 `setPrivacyConfig`
+     */
+    setPrivacyAgree(hasAgree) {
+        const nativeModule = getNativeModule();
+        if (!nativeModule)
+            throw ErrorHandler.nativeModuleUnavailable();
+        nativeModule.setPrivacyAgree(hasAgree);
+    },
+    /**
+     * 设置当前隐私协议版本
+     * 当版本号变化时，之前的同意状态会失效
+     */
+    setPrivacyVersion(version) {
+        const nativeModule = getNativeModule();
+        if (!nativeModule)
+            throw ErrorHandler.nativeModuleUnavailable();
+        nativeModule.setPrivacyVersion(version);
+    },
+    /**
+     * 清空已持久化的隐私同意状态
+     */
+    resetPrivacyConsent() {
+        const nativeModule = getNativeModule();
+        if (!nativeModule)
+            throw ErrorHandler.nativeModuleUnavailable();
+        nativeModule.resetPrivacyConsent();
+    },
+    /**
+     * 一次性同步完整的隐私状态
+     * 推荐业务层只调用这个方法
+     */
+    setPrivacyConfig(config) {
+        const nativeModule = getNativeModule();
+        if (!nativeModule)
+            throw ErrorHandler.nativeModuleUnavailable();
+        if (typeof config.privacyVersion === 'string') {
+            nativeModule.setPrivacyVersion(config.privacyVersion);
+        }
+        nativeModule.setPrivacyShow(config.hasShow, config.hasContainsPrivacy);
+        nativeModule.setPrivacyAgree(config.hasAgree);
+    },
+    getPrivacyStatus() {
+        const nativeModule = getNativeModule();
+        if (!nativeModule) {
+            return {
+                hasShow: false,
+                hasContainsPrivacy: false,
+                hasAgree: false,
+                isReady: false,
+                privacyVersion: null,
+                agreedPrivacyVersion: null,
+                restoredFromStorage: false,
+            };
+        }
+        return nativeModule.getPrivacyStatus();
+    },
     calculateDistanceBetweenPoints(p1, p2) {
+        const nativeModule = getNativeModule();
         if (!nativeModule) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
         return nativeModule.distanceBetweenCoordinates(normalizeLatLng(p1), normalizeLatLng(p2));
     },
     calculateDistance(lat1, lon1, lat2, lon2) {
+        const nativeModule = getNativeModule();
         if (!nativeModule) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
         return nativeModule.distanceBetweenCoordinates({ latitude: lat1, longitude: lon1 }, { latitude: lat2, longitude: lon2 });
     },
     setLoadWorldVectorMap(enabled) {
+        const nativeModule = getNativeModule(true);
         if (!nativeModule)
             return;
         try {
@@ -77,6 +209,7 @@ const ExpoGaodeMapModuleWithHelpers = {
         }
     },
     getVersion() {
+        const nativeModule = getNativeModule(true);
         if (!nativeModule)
             return '0.0.0';
         try {
@@ -88,6 +221,8 @@ const ExpoGaodeMapModuleWithHelpers = {
         }
     },
     start() {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule(true);
         if (!nativeModule)
             return;
         try {
@@ -98,6 +233,8 @@ const ExpoGaodeMapModuleWithHelpers = {
         }
     },
     stop() {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule(true);
         if (!nativeModule)
             return;
         try {
@@ -108,6 +245,8 @@ const ExpoGaodeMapModuleWithHelpers = {
         }
     },
     isStarted() {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule(true);
         if (!nativeModule)
             return Promise.resolve(false);
         try {
@@ -119,6 +258,8 @@ const ExpoGaodeMapModuleWithHelpers = {
         }
     },
     async getCurrentLocation() {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule();
         if (!nativeModule) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
@@ -130,6 +271,8 @@ const ExpoGaodeMapModuleWithHelpers = {
         }
     },
     async coordinateConvert(coordinate, type) {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule();
         if (!nativeModule) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
@@ -141,6 +284,8 @@ const ExpoGaodeMapModuleWithHelpers = {
         }
     },
     setLocatingWithReGeocode(isReGeocode) {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule(true);
         if (!nativeModule)
             return;
         try {
@@ -151,6 +296,7 @@ const ExpoGaodeMapModuleWithHelpers = {
         }
     },
     get isBackgroundLocationEnabled() {
+        const nativeModule = getNativeModule(true);
         if (!nativeModule)
             return false;
         return nativeModule.isBackgroundLocationEnabled === true;
@@ -159,6 +305,8 @@ const ExpoGaodeMapModuleWithHelpers = {
      * 检查位置权限状态
      */
     async checkLocationPermission() {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule();
         if (!nativeModule) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
@@ -173,6 +321,8 @@ const ExpoGaodeMapModuleWithHelpers = {
      * 请求前台位置权限（增强版）
      */
     async requestLocationPermission() {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule();
         if (!nativeModule) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
@@ -192,6 +342,8 @@ const ExpoGaodeMapModuleWithHelpers = {
      * 注意：必须在前台权限已授予后才能请求
      */
     async requestBackgroundLocationPermission() {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule();
         if (!nativeModule) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
@@ -211,6 +363,7 @@ const ExpoGaodeMapModuleWithHelpers = {
      * 引导用户手动授予权限
      */
     openAppSettings() {
+        const nativeModule = getNativeModule();
         if (!nativeModule) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
@@ -222,6 +375,8 @@ const ExpoGaodeMapModuleWithHelpers = {
         }
     },
     setAllowsBackgroundLocationUpdates(allows) {
+        assertPrivacyReady('sdk');
+        const nativeModule = getNativeModule();
         if (!nativeModule) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
@@ -256,13 +411,18 @@ const ExpoGaodeMapModuleWithHelpers = {
      * 注意：如果使用 Config Plugin 配置了 API Key，无需调用 initSDK()
      */
     addLocationListener(listener) {
-        if (!nativeModule) {
+        assertPrivacyReady('sdk');
+        const module = getNativeModule();
+        if (!module) {
             throw ErrorHandler.nativeModuleUnavailable();
         }
-        if (!nativeModule?.addListener) {
+        if (!module.addListener) {
             ErrorLogger.warn('Native module does not support events');
+            return {
+                remove: () => { },
+            };
         }
-        return nativeModule?.addListener?.('onLocationUpdate', listener) || {
+        return module.addListener('onLocationUpdate', listener) || {
             remove: () => { },
         };
     },
@@ -617,6 +777,28 @@ const ExpoGaodeMapModuleWithHelpers = {
 export function getSDKConfig() {
     return _sdkConfig;
 }
+;
+const ExpoGaodeMapModuleWithHelpers = new Proxy(helperMethods, {
+    get(target, prop, receiver) {
+        if (Reflect.has(target, prop)) {
+            return Reflect.get(target, prop, receiver);
+        }
+        const nativeModule = getNativeModule(true);
+        if (!nativeModule) {
+            return undefined;
+        }
+        const value = Reflect.get(nativeModule, prop, nativeModule);
+        if (typeof prop === 'string' &&
+            privacySensitiveMethodNames.has(prop) &&
+            typeof value === 'function') {
+            return (...args) => {
+                assertPrivacyReady('sdk');
+                return value.apply(nativeModule, args);
+            };
+        }
+        return getBoundNativeValue(nativeModule, prop);
+    },
+});
 /**
 * 获取用于 Web API 的 webKey（若未初始化或未提供则返回 undefined）
 */