expo-gaode-map-navigation 1.1.5 → 1.1.7

package/build/map/utils/ErrorHandler.js

@@ -0,0 +1,421 @@
+"use strict";
+/**
+ * 高德地图错误处理工具
+ * 提供友好的错误提示和解决方案指引
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorLogger = exports.ErrorHandler = exports.GaodeMapError = exports.ErrorType = void 0;
+/**
+ * 错误类型枚举
+ */
+var ErrorType;
+(function (ErrorType) {
+    /** SDK 未初始化 */
+    ErrorType["SDK_NOT_INITIALIZED"] = "SDK_NOT_INITIALIZED";
+    /** API Key 配置错误 */
+    ErrorType["INVALID_API_KEY"] = "INVALID_API_KEY";
+    /** 权限未授予 */
+    ErrorType["PERMISSION_DENIED"] = "PERMISSION_DENIED";
+    /** 定位失败 */
+    ErrorType["LOCATION_FAILED"] = "LOCATION_FAILED";
+    /** 原生模块不可用 */
+    ErrorType["NATIVE_MODULE_UNAVAILABLE"] = "NATIVE_MODULE_UNAVAILABLE";
+    /** 地图视图未初始化 */
+    ErrorType["MAP_VIEW_NOT_INITIALIZED"] = "MAP_VIEW_NOT_INITIALIZED";
+    /** 参数错误 */
+    ErrorType["INVALID_PARAMETER"] = "INVALID_PARAMETER";
+    /** 网络错误 */
+    ErrorType["NETWORK_ERROR"] = "NETWORK_ERROR";
+})(ErrorType || (exports.ErrorType = ErrorType = {}));
+/**
+ * 自定义错误类
+ */
+class GaodeMapError extends Error {
+    constructor(details) {
+        const fullMessage = `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🗺️  高德地图错误 [${details.type}]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❌ 错误信息：
+   ${details.message}
+
+💡 解决方案：
+   ${details.solution}
+
+${details.docUrl ? `📖 详细文档：\n   ${details.docUrl}\n` : ''}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+        super(fullMessage);
+        this.name = 'GaodeMapError';
+        this.type = details.type;
+        this.solution = details.solution;
+        this.docUrl = details.docUrl;
+        this.originalError = details.originalError;
+    }
+}
+exports.GaodeMapError = GaodeMapError;
+/**
+ * 错误处理器类
+ */
+class ErrorHandler {
+    /**
+     * SDK 未初始化错误
+     */
+    static sdkNotInitialized() {
+        return new GaodeMapError({
+            type: ErrorType.SDK_NOT_INITIALIZED,
+            message: '高德地图 SDK 尚未初始化',
+            solution: `请在使用地图功能前先调用 initSDK()：
+
+import ExpoGaodeMapModule from 'expo-gaode-map';
+
+useEffect(() => {
+  // 在组件挂载时初始化
+  ExpoGaodeMapModule.initSDK({
+    androidKey: 'your-android-key',
+    iosKey: 'your-ios-key',
+  });
+}, []);
+
+⚠️  常见原因：
+1. 忘记调用 initSDK() 就使用了定位或地图功能
+2. initSDK() 调用时机过晚（应在 useEffect 中尽早调用）
+3. 使用 Config Plugin 但未重新构建原生代码`,
+            docUrl: `${this.docBaseUrl}/guide/initialization.html`,
+        });
+    }
+    /**
+     * API Key 配置错误
+     */
+    static invalidApiKey(platform) {
+        const platformText = {
+            android: 'Android',
+            ios: 'iOS',
+            both: 'Android 和 iOS',
+        }[platform];
+        return new GaodeMapError({
+            type: ErrorType.INVALID_API_KEY,
+            message: `${platformText} API Key 配置错误或未配置`,
+            solution: `⚠️  API Key 与 Bundle ID 不匹配是最常见的原因！
+
+请检查以下步骤：
+
+1️⃣  确认 API Key 的配置：
+   • 访问高德开放平台：https://lbs.amap.com/
+   • 检查您的应用配置中的 Bundle ID 是否与当前项目一致
+   • iOS Bundle ID：在 Xcode → Target → General → Bundle Identifier 查看
+   • Android 包名：在 android/app/build.gradle → applicationId 查看
+
+2️⃣  重新创建正确的 API Key（如果 Bundle ID 不同）：
+   • 在高德开放平台创建新应用
+   • 填写正确的 Bundle ID（iOS）或包名（Android）
+   • 获取新的 API Key
+
+3️⃣  配置 API Key（推荐使用 Config Plugin）：
+
+在 app.json 中配置：
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-gaode-map",
+        {
+          "androidKey": "your-android-key",
+          "iosKey": "your-ios-key"
+        }
+      ]
+    ]
+  }
+}
+
+然后重新构建：
+npx expo prebuild --clean
+npx expo run:${platform === 'ios' ? 'ios' : 'android'}
+
+4️⃣  或在代码中配置：
+ExpoGaodeMapModule.initSDK({
+  androidKey: 'your-android-key',
+  iosKey: 'your-ios-key',
+});`,
+            docUrl: `${this.docBaseUrl}/guide/initialization.html`,
+        });
+    }
+    /**
+     * 权限未授予错误
+     */
+    static permissionDenied(permissionType) {
+        return new GaodeMapError({
+            type: ErrorType.PERMISSION_DENIED,
+            message: '定位权限未授予，无法使用定位功能',
+            solution: `请按以下步骤授予权限：
+
+1️⃣  请求权限：
+import ExpoGaodeMapModule from 'expo-gaode-map';
+
+const checkPermission = async () => {
+  // 检查权限状态
+  const status = await ExpoGaodeMapModule.checkLocationPermission();
+  
+  if (!status.granted) {
+    // 请求权限
+    const result = await ExpoGaodeMapModule.requestLocationPermission();
+    
+    if (!result.granted) {
+      // 用户拒绝授权，引导用户去设置
+      Alert.alert(
+        '需要定位权限',
+        '请在设置中开启定位权限以使用地图功能',
+        [
+          { text: '取消', style: 'cancel' },
+          { text: '去设置', onPress: () => Linking.openSettings() }
+        ]
+      );
+    }
+  }
+};
+
+2️⃣  iOS 配置（在 app.json 中）：
+{
+  "expo": {
+    "ios": {
+      "infoPlist": {
+        "NSLocationWhenInUseUsageDescription": "需要获取您的位置信息以显示地图",
+        "NSLocationAlwaysAndWhenInUseUsageDescription": "需要获取您的位置信息"
+      }
+    }
+  }
+}
+
+3️⃣  Android 配置（Config Plugin 会自动添加）：
+使用 expo-gaode-map 的 Config Plugin 会自动添加必要的权限声明`,
+            docUrl: `${this.docBaseUrl}/guide/getting-started.html#权限配置`,
+        });
+    }
+    /**
+     * 定位失败错误
+     */
+    static locationFailed(reason) {
+        return new GaodeMapError({
+            type: ErrorType.LOCATION_FAILED,
+            message: `定位失败${reason ? `：${reason}` : ''}`,
+            solution: `⚠️  最常见原因：API Key 与 Bundle ID 不匹配！
+
+请按以下顺序排查：
+
+1️⃣  检查 API Key 配置（最常见问题）：
+   • 访问高德开放平台：https://lbs.amap.com/
+   • 确认您的应用的 Bundle ID 与当前项目一致
+   • iOS Bundle ID：在 Xcode → Target → General → Bundle Identifier
+   • Android 包名：在 android/app/build.gradle → applicationId
+   
+   如果 Bundle ID 不同，必须在高德平台重新创建应用并获取新 Key
+
+2️⃣  检查设备 GPS 和网络：
+   • 确认设备 GPS 已开启
+   • 检查网络连接是否正常
+   • 尝试在室外空旷处测试
+
+3️⃣  检查定位权限：
+   • iOS：设置 → 隐私 → 定位服务 → 允许应用访问
+   • Android：设置 → 应用 → 权限管理 → 位置信息
+
+4️⃣  配置定位参数（如果 API Key 正确但定位仍失败）：
+ExpoGaodeMapModule.setLocationTimeout(30); // 增加超时时间
+ExpoGaodeMapModule.setInterval(2000); // 设置定位间隔
+
+// Android 特有配置
+ExpoGaodeMapModule.setLocationMode(2); // 高精度模式
+ExpoGaodeMapModule.setGpsFirst(true);  // GPS 优先
+
+// iOS 特有配置
+ExpoGaodeMapModule.setDesiredAccuracy(0); // 最佳精度`,
+            docUrl: `${this.docBaseUrl}/api/location.html`,
+        });
+    }
+    /**
+     * 原生模块不可用错误
+     */
+    static nativeModuleUnavailable() {
+        return new GaodeMapError({
+            type: ErrorType.NATIVE_MODULE_UNAVAILABLE,
+            message: 'expo-gaode-map 原生模块不可用',
+            solution: `请检查以下步骤：
+
+1️⃣  确认已正确安装：
+npm install expo-gaode-map
+# 或
+bun install expo-gaode-map
+
+2️⃣  重新构建原生代码：
+npx expo prebuild --clean
+npx expo run:android
+npx expo run:ios
+
+3️⃣  检查 Expo 版本兼容性：
+• expo-gaode-map 需要 Expo SDK 49+
+• 不支持 Expo Go，必须使用 Development Build
+
+4️⃣  检查是否与其他包冲突：
+• 不能同时安装 expo-gaode-map 和 expo-gaode-map-navigation
+• 两个包选择其一使用
+
+5️⃣  清理缓存后重试：
+cd android && ./gradlew clean && cd ..
+cd ios && pod deintegrate && pod install && cd ..`,
+            docUrl: `${this.docBaseUrl}/guide/getting-started.html`,
+        });
+    }
+    /**
+     * 地图视图未初始化错误
+     */
+    static mapViewNotInitialized(methodName) {
+        return new GaodeMapError({
+            type: ErrorType.MAP_VIEW_NOT_INITIALIZED,
+            message: `无法调用 ${methodName}：地图视图尚未初始化`,
+            solution: `请确保：
+
+1️⃣  MapView 已经渲染完成
+2️⃣  使用 ref 获取地图实例后再调用方法
+
+正确用法：
+import { MapView, MapViewRef } from 'expo-gaode-map';
+
+const App = () => {
+  const mapRef = useRef<MapViewRef>(null);
+  
+  // ❌ 错误：在渲染前调用
+  // mapRef.current?.moveCamera(...);
+  
+  // ✅ 正确：等待地图加载完成
+  const handleMapReady = () => {
+    mapRef.current?.moveCamera({
+      target: { latitude: 39.9, longitude: 116.4 },
+      zoom: 15,
+    });
+  };
+  
+  return (
+    <MapView
+      ref={mapRef}
+      onMapReady={handleMapReady}
+    />
+  );
+};`,
+            docUrl: `${this.docBaseUrl}/api/mapview.html`,
+        });
+    }
+    /**
+     * 参数错误
+     */
+    static invalidParameter(paramName, expected, received) {
+        return new GaodeMapError({
+            type: ErrorType.INVALID_PARAMETER,
+            message: `参数 "${paramName}" 类型错误`,
+            solution: `期望类型：${expected}
+实际接收：${typeof received} (${JSON.stringify(received)})
+
+请检查传入的参数是否符合要求。
+
+💡 提示：
+• 使用 TypeScript 可以在编译时发现类型错误
+• 参考 API 文档了解正确的参数类型`,
+            docUrl: `${this.docBaseUrl}/api/`,
+        });
+    }
+    /**
+     * 网络错误
+     */
+    static networkError(originalError) {
+        return new GaodeMapError({
+            type: ErrorType.NETWORK_ERROR,
+            message: '网络请求失败',
+            solution: `请检查：
+
+1️⃣  网络连接是否正常
+2️⃣  API Key 是否有效
+3️⃣  是否超出配额限制
+
+💡 如果问题持续，请：
+• 检查高德开放平台控制台
+• 查看 API 调用量和配额
+• 确认 Key 的服务是否已开通`,
+            docUrl: `${this.docBaseUrl}/guide/troubleshooting.html`,
+            originalError,
+        });
+    }
+    /**
+     * 包装原生错误，提供更友好的提示
+     */
+    static wrapNativeError(error, context) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // SDK 未初始化相关错误
+        if (errorMessage.includes('not initialized') ||
+            errorMessage.includes('未初始化') ||
+            errorMessage.includes('SDK未设置')) {
+            return this.sdkNotInitialized();
+        }
+        // API Key 相关错误
+        if (errorMessage.includes('key') ||
+            errorMessage.includes('invalid') ||
+            errorMessage.includes('鉴权失败')) {
+            return this.invalidApiKey('both');
+        }
+        // 权限相关错误
+        if (errorMessage.includes('permission') ||
+            errorMessage.includes('权限')) {
+            return this.permissionDenied('location');
+        }
+        // 定位相关错误
+        if (errorMessage.includes('location') ||
+            errorMessage.includes('定位')) {
+            return this.locationFailed(errorMessage);
+        }
+        // 通用错误
+        return new GaodeMapError({
+            type: ErrorType.INVALID_PARAMETER,
+            message: `${context} 失败`,
+            solution: `原始错误信息：${errorMessage}
+
+如果问题持续，请：
+1. 查看完整的错误堆栈
+2. 检查 API 调用参数
+3. 提交 Issue：https://github.com/TomWq/expo-gaode-map/issues`,
+            originalError: error instanceof Error ? error : undefined,
+        });
+    }
+}
+exports.ErrorHandler = ErrorHandler;
+ErrorHandler.docBaseUrl = 'https://TomWq.github.io/expo-gaode-map';
+/**
+ * 错误日志工具
+ */
+class ErrorLogger {
+    /**
+     * 启用/禁用错误日志
+     */
+    static setEnabled(enabled) {
+        this.isEnabled = enabled;
+    }
+    /**
+     * 记录错误
+     */
+    static log(error) {
+        if (!this.isEnabled)
+            return;
+        console.error(error.message);
+        if (error.originalError) {
+            console.error('原始错误：', error.originalError);
+        }
+    }
+    /**
+     * 记录警告
+     */
+    static warn(message, details) {
+        if (!this.isEnabled)
+            return;
+        console.warn(`⚠️  expo-gaode-map: ${message}`, details || '');
+    }
+}
+exports.ErrorLogger = ErrorLogger;
+// 兼容不同环境：Bun/Jest/Node
+ErrorLogger.isEnabled = typeof __DEV__ !== 'undefined' ? __DEV__ : true;

package/build/map/utils/GeoUtils.d.ts

@@ -0,0 +1,20 @@
+import { LatLng, LatLngPoint } from '../types/common.types';
+/**
+ * 将坐标点归一化为对象格式
+ * 支持 [longitude, latitude] 数组或 { latitude, longitude } 对象
+ * 注意：数组格式遵循 GeoJSON 标准，即 [经度, 纬度]
+ *
+ * @param point 坐标点
+ * @returns { latitude, longitude } 对象
+ */
+export declare function normalizeLatLng(point: LatLngPoint): LatLng;
+/**
+ * 将坐标点数组归一化为对象数组
+ * 支持一维数组 [p1, p2, ...] 或二维嵌套数组 [[p1, p2, ...], [p3, p4, ...]]
+ *
+ * @param points 坐标点数组或嵌套数组
+ * @returns 归一化后的坐标数组
+ */
+export declare function normalizeLatLngList(points: LatLngPoint[]): LatLng[];
+export declare function normalizeLatLngList(points: LatLngPoint[][]): LatLng[][];
+export declare function normalizeLatLngList(points: LatLngPoint[] | LatLngPoint[][]): LatLng[] | LatLng[][];

package/build/map/utils/GeoUtils.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeLatLng = normalizeLatLng;
+exports.normalizeLatLngList = normalizeLatLngList;
+/**
+ * 将坐标点归一化为对象格式
+ * 支持 [longitude, latitude] 数组或 { latitude, longitude } 对象
+ * 注意：数组格式遵循 GeoJSON 标准，即 [经度, 纬度]
+ *
+ * @param point 坐标点
+ * @returns { latitude, longitude } 对象
+ */
+function normalizeLatLng(point) {
+    if (Array.isArray(point)) {
+        let longitude = point[0];
+        let latitude = point[1];
+        // 智能纠错：如果纬度超出范围 [-90, 90] 且交换后在范围内，则认为是用户传反了
+        if (Math.abs(latitude) > 90 && Math.abs(longitude) <= 90) {
+            console.warn(`[expo-gaode-map] 检测到坐标数组格式可能为 [latitude, longitude] (${point})，已自动纠正为 [longitude, latitude]。建议显式使用 [经度, 纬度] 格式以遵循 GeoJSON 标准。`);
+            return {
+                latitude: longitude,
+                longitude: latitude
+            };
+        }
+        return {
+            longitude,
+            latitude,
+        };
+    }
+    // 对象格式直接返回
+    return point;
+}
+function normalizeLatLngList(points) {
+    if (!points || points.length === 0)
+        return [];
+    // 检查是否为嵌套数组 (检查第一项是否也是数组或对象，且不符合 LatLngPoint 的基本判断)
+    // 如果第一项是数组且长度 > 2，或者第一项的第一个元素也是数组/对象，则认为是嵌套数组
+    const firstItem = points[0];
+    if (Array.isArray(firstItem)) {
+        // 如果第一项是 [number, number]，则这可能是一个一维坐标点数组 (LatLngPoint[])
+        // 除非所有元素都是数组且至少有一个子数组长度不等于2，或者我们明确知道这是嵌套的
+        // 为了支持 Polygon 的嵌套格式，我们需要递归处理
+        // 启发式判断：如果第一项是数组且它的第一个元素也是数组或对象，那么它一定是嵌套的
+        if (Array.isArray(firstItem[0]) || (typeof firstItem[0] === 'object' && firstItem[0] !== null && 'latitude' in firstItem[0])) {
+            return points.map(ring => ring.map(normalizeLatLng));
+        }
+        // 另一种情况：用户传入的是 [[lng, lat], [lng, lat]]，这既可以看作 LatLngPoint[]，
+        // 也可以看作 LatLngPoint[][] (只有一个外轮廓)。
+        // 在 Polygon 组件中，我们希望统一处理。
+        // 如果是 Polygon 传入的，我们希望保留嵌套结构。
+        // 但 normalizeLatLngList 是通用的。
+        // 改进逻辑：如果 data[0] 是一个点，我们把它当作一维数组处理。
+        // 如果 data[0] 不是一个点（即它是点的集合），我们当作二维处理。
+        if (isPoint(firstItem)) {
+            return points.map(normalizeLatLng);
+        }
+        else {
+            return points.map(ring => ring.map(normalizeLatLng));
+        }
+    }
+    return points.map(normalizeLatLng);
+}
+/**
+ * 判断一个对象是否为坐标点 (LatLngPoint)
+ */
+function isPoint(item) {
+    if (!item || typeof item !== 'object')
+        return false;
+    // { latitude, longitude } 格式
+    if ('latitude' in item && 'longitude' in item)
+        return true;
+    // [longitude, latitude] 格式
+    if (Array.isArray(item) && item.length >= 2 && typeof item[0] === 'number' && typeof item[1] === 'number')
+        return true;
+    return false;
+}

package/build/map/utils/OfflineMapManager.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 离线地图便捷 API
+ * 提供更友好的 API 接口和事件监听
+ */
+import type { OfflineMapInfo, OfflineMapDownloadConfig, OfflineMapDownloadEvent, OfflineMapCompleteEvent, OfflineMapErrorEvent, OfflineMapPausedEvent, OfflineMapCancelledEvent, OfflineMapStorageInfo } from '../types/offline.types';
+/**
+ * 离线地图管理类
+ */
+export declare class OfflineMapManager {
+    /**
+     * 获取所有可下载的城市列表
+     */
+    static getAvailableCities(): Promise<OfflineMapInfo[]>;
+    /**
+     * 获取所有省份列表
+     */
+    static getAvailableProvinces(): Promise<OfflineMapInfo[]>;
+    /**
+     * 根据省份代码获取城市列表
+     */
+    static getCitiesByProvince(provinceCode: string): Promise<OfflineMapInfo[]>;
+    /**
+     * 获取已下载的地图列表
+     */
+    static getDownloadedMaps(): Promise<OfflineMapInfo[]>;
+    /**
+     * 开始下载离线地图
+     */
+    static startDownload(config: OfflineMapDownloadConfig): Promise<void>;
+    /**
+     * 暂停下载
+     */
+    static pauseDownload(cityCode: string): Promise<void>;
+    /**
+     * 恢复下载
+     */
+    static resumeDownload(cityCode: string): Promise<void>;
+    /**
+     * 取消下载
+     */
+    static cancelDownload(cityCode: string): Promise<void>;
+    /**
+     * 删除离线地图
+     */
+    static deleteMap(cityCode: string): Promise<void>;
+    /**
+     * 更新离线地图
+     */
+    static updateMap(cityCode: string): Promise<void>;
+    /**
+     * 检查是否有可用更新
+     */
+    static checkUpdate(cityCode: string): Promise<boolean>;
+    /**
+     * 检查地图是否已下载
+     */
+    static isMapDownloaded(cityCode: string): Promise<boolean>;
+    /**
+     * 获取地图下载状态
+     */
+    static getMapStatus(cityCode: string): Promise<OfflineMapInfo>;
+    /**
+     * 获取所有下载任务的总进度
+     */
+    static getTotalProgress(): Promise<number>;
+    /**
+     * 获取当前正在下载的城市列表
+     */
+    static getDownloadingCities(): Promise<string[]>;
+    /**
+     * 获取离线地图占用的存储空间（字节）
+     */
+    static getStorageSize(): Promise<number>;
+    /**
+     * 获取详细的存储信息
+     */
+    static getStorageInfo(): Promise<OfflineMapStorageInfo>;
+    /**
+     * 清理所有离线地图
+     */
+    static clearAllMaps(): Promise<void>;
+    /**
+     * 设置离线地图存储路径
+     */
+    static setStoragePath(path: string): void;
+    /**
+     * 获取离线地图存储路径
+     */
+    static getStoragePath(): Promise<string>;
+    /**
+     * 批量下载地图
+     */
+    static batchDownload(cityCodes: string[], allowCellular?: boolean): Promise<void>;
+    /**
+     * 批量删除地图
+     */
+    static batchDelete(cityCodes: string[]): Promise<void>;
+    /**
+     * 批量更新地图
+     */
+    static batchUpdate(cityCodes: string[]): Promise<void>;
+    /**
+     * 暂停所有下载任务
+     */
+    static pauseAllDownloads(): Promise<void>;
+    /**
+     * 恢复所有下载任务
+     */
+    static resumeAllDownloads(): Promise<void>;
+    /**
+     * 监听下载进度事件
+     */
+    static addDownloadProgressListener(listener: (event: OfflineMapDownloadEvent) => void): {
+        remove: () => void;
+    };
+    /**
+     * 监听下载完成事件
+     */
+    static addDownloadCompleteListener(listener: (event: OfflineMapCompleteEvent) => void): {
+        remove: () => void;
+    };
+    /**
+     * 监听下载错误事件
+     */
+    static addDownloadErrorListener(listener: (event: OfflineMapErrorEvent) => void): {
+        remove: () => void;
+    };
+    /**
+     * 监听下载暂停事件
+     */
+    static addDownloadPausedListener(listener: (event: OfflineMapPausedEvent) => void): {
+        remove: () => void;
+    };
+    /**
+     * 监听下载取消事件
+     */
+    static addDownloadCancelledListener(listener: (event: OfflineMapCancelledEvent) => void): {
+        remove: () => void;
+    };
+    /**
+     * 移除所有监听器
+     */
+    static removeAllListeners(): void;
+}
+/**
+ * 默认导出管理类
+ */
+export default OfflineMapManager;