expo-gaode-map-navigation 1.1.5 → 1.1.7

package/build/map/utils/OfflineMapManager.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * 离线地图便捷 API
+ * 提供更友好的 API 接口和事件监听
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineMapManager = void 0;
+const ExpoGaodeMapOfflineModule_1 = __importDefault(require("../ExpoGaodeMapOfflineModule"));
+/**
+ * 离线地图管理类
+ */
+class OfflineMapManager {
+    // ==================== 地图列表管理 ====================
+    /**
+     * 获取所有可下载的城市列表
+     */
+    static async getAvailableCities() {
+        return ExpoGaodeMapOfflineModule_1.default.getAvailableCities();
+    }
+    /**
+     * 获取所有省份列表
+     */
+    static async getAvailableProvinces() {
+        return ExpoGaodeMapOfflineModule_1.default.getAvailableProvinces();
+    }
+    /**
+     * 根据省份代码获取城市列表
+     */
+    static async getCitiesByProvince(provinceCode) {
+        return ExpoGaodeMapOfflineModule_1.default.getCitiesByProvince(provinceCode);
+    }
+    /**
+     * 获取已下载的地图列表
+     */
+    static async getDownloadedMaps() {
+        return ExpoGaodeMapOfflineModule_1.default.getDownloadedMaps();
+    }
+    // ==================== 下载管理 ====================
+    /**
+     * 开始下载离线地图
+     */
+    static async startDownload(config) {
+        return ExpoGaodeMapOfflineModule_1.default.startDownload(config);
+    }
+    /**
+     * 暂停下载
+     */
+    static async pauseDownload(cityCode) {
+        return ExpoGaodeMapOfflineModule_1.default.pauseDownload(cityCode);
+    }
+    /**
+     * 恢复下载
+     */
+    static async resumeDownload(cityCode) {
+        return ExpoGaodeMapOfflineModule_1.default.resumeDownload(cityCode);
+    }
+    /**
+     * 取消下载
+     */
+    static async cancelDownload(cityCode) {
+        return ExpoGaodeMapOfflineModule_1.default.cancelDownload(cityCode);
+    }
+    /**
+     * 删除离线地图
+     */
+    static async deleteMap(cityCode) {
+        return ExpoGaodeMapOfflineModule_1.default.deleteMap(cityCode);
+    }
+    /**
+     * 更新离线地图
+     */
+    static async updateMap(cityCode) {
+        return ExpoGaodeMapOfflineModule_1.default.updateMap(cityCode);
+    }
+    /**
+     * 检查是否有可用更新
+     */
+    static async checkUpdate(cityCode) {
+        return ExpoGaodeMapOfflineModule_1.default.checkUpdate(cityCode);
+    }
+    // ==================== 状态查询 ====================
+    /**
+     * 检查地图是否已下载
+     */
+    static async isMapDownloaded(cityCode) {
+        return ExpoGaodeMapOfflineModule_1.default.isMapDownloaded(cityCode);
+    }
+    /**
+     * 获取地图下载状态
+     */
+    static async getMapStatus(cityCode) {
+        return ExpoGaodeMapOfflineModule_1.default.getMapStatus(cityCode);
+    }
+    /**
+     * 获取所有下载任务的总进度
+     */
+    static async getTotalProgress() {
+        return ExpoGaodeMapOfflineModule_1.default.getTotalProgress();
+    }
+    /**
+     * 获取当前正在下载的城市列表
+     */
+    static async getDownloadingCities() {
+        return ExpoGaodeMapOfflineModule_1.default.getDownloadingCities();
+    }
+    // ==================== 存储管理 ====================
+    /**
+     * 获取离线地图占用的存储空间（字节）
+     */
+    static async getStorageSize() {
+        return ExpoGaodeMapOfflineModule_1.default.getStorageSize();
+    }
+    /**
+     * 获取详细的存储信息
+     */
+    static async getStorageInfo() {
+        return ExpoGaodeMapOfflineModule_1.default.getStorageInfo();
+    }
+    /**
+     * 清理所有离线地图
+     */
+    static async clearAllMaps() {
+        return ExpoGaodeMapOfflineModule_1.default.clearAllMaps();
+    }
+    /**
+     * 设置离线地图存储路径
+     */
+    static setStoragePath(path) {
+        ExpoGaodeMapOfflineModule_1.default.setStoragePath(path);
+    }
+    /**
+     * 获取离线地图存储路径
+     */
+    static async getStoragePath() {
+        return ExpoGaodeMapOfflineModule_1.default.getStoragePath();
+    }
+    // ==================== 批量操作 ====================
+    /**
+     * 批量下载地图
+     */
+    static async batchDownload(cityCodes, allowCellular = false) {
+        return ExpoGaodeMapOfflineModule_1.default.batchDownload(cityCodes, allowCellular);
+    }
+    /**
+     * 批量删除地图
+     */
+    static async batchDelete(cityCodes) {
+        return ExpoGaodeMapOfflineModule_1.default.batchDelete(cityCodes);
+    }
+    /**
+     * 批量更新地图
+     */
+    static async batchUpdate(cityCodes) {
+        return ExpoGaodeMapOfflineModule_1.default.batchUpdate(cityCodes);
+    }
+    /**
+     * 暂停所有下载任务
+     */
+    static async pauseAllDownloads() {
+        return ExpoGaodeMapOfflineModule_1.default.pauseAllDownloads();
+    }
+    /**
+     * 恢复所有下载任务
+     */
+    static async resumeAllDownloads() {
+        return ExpoGaodeMapOfflineModule_1.default.resumeAllDownloads();
+    }
+    // ==================== 事件监听 ====================
+    /**
+     * 监听下载进度事件
+     */
+    static addDownloadProgressListener(listener) {
+        return ExpoGaodeMapOfflineModule_1.default.addListener('onDownloadProgress', listener);
+    }
+    /**
+     * 监听下载完成事件
+     */
+    static addDownloadCompleteListener(listener) {
+        return ExpoGaodeMapOfflineModule_1.default.addListener('onDownloadComplete', listener);
+    }
+    /**
+     * 监听下载错误事件
+     */
+    static addDownloadErrorListener(listener) {
+        return ExpoGaodeMapOfflineModule_1.default.addListener('onDownloadError', listener);
+    }
+    /**
+     * 监听下载暂停事件
+     */
+    static addDownloadPausedListener(listener) {
+        return ExpoGaodeMapOfflineModule_1.default.addListener('onDownloadPaused', listener);
+    }
+    /**
+     * 监听下载取消事件
+     */
+    static addDownloadCancelledListener(listener) {
+        return ExpoGaodeMapOfflineModule_1.default.addListener('onDownloadCancelled', listener);
+    }
+    /**
+     * 移除所有监听器
+     */
+    static removeAllListeners() {
+        ExpoGaodeMapOfflineModule_1.default.removeAllListeners('onDownloadProgress');
+        ExpoGaodeMapOfflineModule_1.default.removeAllListeners('onDownloadComplete');
+        ExpoGaodeMapOfflineModule_1.default.removeAllListeners('onDownloadError');
+        ExpoGaodeMapOfflineModule_1.default.removeAllListeners('onDownloadPaused');
+        ExpoGaodeMapOfflineModule_1.default.removeAllListeners('onDownloadCancelled');
+    }
+}
+exports.OfflineMapManager = OfflineMapManager;
+/**
+ * 默认导出管理类
+ */
+exports.default = OfflineMapManager;

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

@@ -0,0 +1,91 @@
+/**
+ * 位置权限类型
+ */
+export declare enum LocationPermissionType {
+    /** 仅前台（使用时） */
+    FOREGROUND = "foreground",
+    /** 后台位置 */
+    BACKGROUND = "background",
+    /** 前台+后台 */
+    FOREGROUND_AND_BACKGROUND = "foreground_and_background"
+}
+/**
+ * 权限工具类
+ *
+ * 🔔 **重要说明**：
+ *
+ * 本工具类**不执行实际的权限请求**，仅提供：
+ * - 平台检测（Android 14+、iOS 17+）
+ * - 权限说明文案（适配新系统特性）
+ * - 最佳实践建议
+ * - 诊断信息
+ *
+ * **实际权限请求请使用**：
+ * ```typescript
+ * import ExpoGaodeMapModule from 'expo-gaode-map';
+ *
+ * // 检查权限
+ * const status = await ExpoGaodeMapModule.checkLocationPermission();
+ *
+ * // 请求权限
+ * const result = await ExpoGaodeMapModule.requestLocationPermission();
+ * ```
+ *
+ * 本工具类主要用于在请求权限**之前**向用户展示说明文案。
+ */
+export declare class PermissionUtils {
+    /**
+     * 检查当前平台的系统版本
+     */
+    static getSystemInfo(): {
+        platform: 'android' | 'ios';
+        version: number;
+        isAndroid14Plus: boolean;
+        isiOS17Plus: boolean;
+    };
+    /**
+     * 获取权限说明文案
+     */
+    static getPermissionRationale(type: LocationPermissionType): string;
+    /**
+     * Android 权限说明文案
+     */
+    private static getAndroidRationale;
+    /**
+     * iOS 权限说明文案
+     */
+    private static getiOSRationale;
+    /**
+     * 获取精确位置权限说明（iOS 14+）
+     */
+    static getAccuracyRationale(): string;
+    /**
+     * 获取权限请求的最佳实践建议
+     */
+    static getBestPractices(): {
+        android14: string[];
+        ios17: string[];
+        general: string[];
+    };
+    /**
+     * 验证 Info.plist 配置（仅 iOS）
+     */
+    static validateiOSConfiguration(): {
+        valid: boolean;
+        missingKeys: string[];
+        recommendations: string[];
+    };
+    /**
+     * 检查是否支持后台位置权限
+     */
+    static supportsBackgroundLocation(): boolean;
+    /**
+     * 打印权限诊断信息
+     */
+    static printDiagnostics(): void;
+}
+/**
+ * 向后兼容的别名
+ * @deprecated 请使用 PermissionUtils
+ */
+export declare const PermissionManager: typeof PermissionUtils;

package/build/map/utils/PermissionUtils.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionManager = exports.PermissionUtils = exports.LocationPermissionType = void 0;
+const react_native_1 = require("react-native");
+const PlatformDetector_1 = require("./PlatformDetector");
+/**
+ * 位置权限类型
+ */
+var LocationPermissionType;
+(function (LocationPermissionType) {
+    /** 仅前台（使用时） */
+    LocationPermissionType["FOREGROUND"] = "foreground";
+    /** 后台位置 */
+    LocationPermissionType["BACKGROUND"] = "background";
+    /** 前台+后台 */
+    LocationPermissionType["FOREGROUND_AND_BACKGROUND"] = "foreground_and_background";
+})(LocationPermissionType || (exports.LocationPermissionType = LocationPermissionType = {}));
+/**
+ * 权限工具类
+ *
+ * 🔔 **重要说明**：
+ *
+ * 本工具类**不执行实际的权限请求**，仅提供：
+ * - 平台检测（Android 14+、iOS 17+）
+ * - 权限说明文案（适配新系统特性）
+ * - 最佳实践建议
+ * - 诊断信息
+ *
+ * **实际权限请求请使用**：
+ * ```typescript
+ * import ExpoGaodeMapModule from 'expo-gaode-map';
+ *
+ * // 检查权限
+ * const status = await ExpoGaodeMapModule.checkLocationPermission();
+ *
+ * // 请求权限
+ * const result = await ExpoGaodeMapModule.requestLocationPermission();
+ * ```
+ *
+ * 本工具类主要用于在请求权限**之前**向用户展示说明文案。
+ */
+class PermissionUtils {
+    /**
+     * 检查当前平台的系统版本
+     */
+    static getSystemInfo() {
+        const platform = react_native_1.Platform.OS;
+        const systemVersion = PlatformDetector_1.PlatformDetector.getSystemVersion();
+        return {
+            platform,
+            version: systemVersion.version,
+            isAndroid14Plus: PlatformDetector_1.PlatformDetector.needsAndroid14Permissions(),
+            isiOS17Plus: PlatformDetector_1.PlatformDetector.supportsiOS17Features(),
+        };
+    }
+    /**
+     * 获取权限说明文案
+     */
+    static getPermissionRationale(type) {
+        const { platform, isAndroid14Plus, isiOS17Plus } = this.getSystemInfo();
+        if (platform === 'android') {
+            return this.getAndroidRationale(type, isAndroid14Plus);
+        }
+        else {
+            return this.getiOSRationale(type, isiOS17Plus);
+        }
+    }
+    /**
+     * Android 权限说明文案
+     */
+    static getAndroidRationale(type, isAndroid14) {
+        switch (type) {
+            case LocationPermissionType.FOREGROUND:
+                if (isAndroid14) {
+                    return `为了在地图上显示您的位置，应用需要访问您的位置信息。
+
+您可以选择：
+• 仅在使用应用时允许
+• 每次询问
+
+我们不会在后台收集您的位置数据。`;
+                }
+                return '为了在地图上显示您的位置，应用需要访问您的位置信息。';
+            case LocationPermissionType.BACKGROUND:
+                if (isAndroid14) {
+                    return `为了在后台更新您的位置（如导航、轨迹记录），应用需要始终访问位置权限。
+
+您可以随时在设置中更改此权限。`;
+                }
+                return '为了在后台更新您的位置，应用需要始终访问位置权限。';
+            case LocationPermissionType.FOREGROUND_AND_BACKGROUND:
+                if (isAndroid14) {
+                    return `应用需要位置权限来提供以下功能：
+• 在地图上显示您的位置（前台）
+• 后台导航和轨迹记录（后台）
+
+我们会先请求前台权限，然后再请求后台权限。`;
+                }
+                return '应用需要位置权限来显示地图位置和后台导航功能。';
+        }
+    }
+    /**
+     * iOS 权限说明文案
+     */
+    static getiOSRationale(type, isiOS17) {
+        switch (type) {
+            case LocationPermissionType.FOREGROUND:
+                if (isiOS17) {
+                    return `为了在地图上显示您的位置，应用需要访问您的位置信息。
+
+您可以选择：
+• 使用 App 期间：仅在使用应用时访问位置
+• 一次：仅本次使用时访问位置
+
+我们不会在后台收集您的位置数据。`;
+                }
+                return '为了在地图上显示您的位置，应用需要访问您的位置信息。';
+            case LocationPermissionType.BACKGROUND:
+            case LocationPermissionType.FOREGROUND_AND_BACKGROUND:
+                if (isiOS17) {
+                    return `为了提供以下功能，应用需要始终访问位置权限：
+• 后台导航和路径规划
+• 轨迹记录
+• 位置提醒
+
+您可以随时在设置中更改此权限。`;
+                }
+                return '为了在后台更新您的位置，应用需要始终访问位置权限。';
+        }
+    }
+    /**
+     * 获取精确位置权限说明（iOS 14+）
+     */
+    static getAccuracyRationale() {
+        const { isiOS17Plus } = this.getSystemInfo();
+        if (isiOS17Plus) {
+            return `为了提供准确的导航和定位服务，应用需要访问精确位置。
+
+选择"模糊位置"可能会导致：
+• 地图定位不准确
+• 导航路线偏差
+• 搜索结果不精确`;
+        }
+        return '为了提供准确的导航和定位服务，应用需要访问精确位置。';
+    }
+    /**
+     * 获取权限请求的最佳实践建议
+     */
+    static getBestPractices() {
+        return {
+            android14: [
+                '先解释为什么需要权限，再发起请求',
+                '前台和后台权限分两步请求',
+                '永久拒绝后引导用户到设置页面',
+                '提供"仅本次"选项的说明',
+            ],
+            ios17: [
+                '在 Info.plist 中提供清晰的权限说明',
+                '使用 Privacy Manifest 声明位置访问原因',
+                '先请求"使用期间"，再请求"始终允许"',
+                '支持"仅一次"权限模式',
+            ],
+            general: [
+                '在用户需要使用功能时再请求权限',
+                '清晰解释权限用途和好处',
+                '提供拒绝后的替代方案',
+                '尊重用户的权限选择',
+            ],
+        };
+    }
+    /**
+     * 验证 Info.plist 配置（仅 iOS）
+     */
+    static validateiOSConfiguration() {
+        if (react_native_1.Platform.OS !== 'ios') {
+            return {
+                valid: true,
+                missingKeys: [],
+                recommendations: [],
+            };
+        }
+        const recommendations = [];
+        const { isiOS17Plus } = this.getSystemInfo();
+        if (isiOS17Plus) {
+            recommendations.push('建议在 Privacy Manifest (PrivacyInfo.xcprivacy) 中声明位置访问原因', '确保 NSLocationWhenInUseUsageDescription 文案清晰、具体', '如需后台位置，配置 NSLocationAlwaysAndWhenInUseUsageDescription');
+        }
+        return {
+            valid: true,
+            missingKeys: [],
+            recommendations,
+        };
+    }
+    /**
+     * 检查是否支持后台位置权限
+     */
+    static supportsBackgroundLocation() {
+        const { platform, version } = this.getSystemInfo();
+        if (platform === 'android') {
+            // Android 10 (API 29) 引入后台位置权限
+            return version >= 29;
+        }
+        else {
+            // iOS 8+ 支持
+            return version >= 8;
+        }
+    }
+    /**
+     * 打印权限诊断信息
+     */
+    static printDiagnostics() {
+        const info = this.getSystemInfo();
+        console.log('=== 权限管理诊断信息 ===');
+        console.log(`平台: ${info.platform}`);
+        console.log(`系统版本: ${info.version}`);
+        console.log(`Android 14+: ${info.isAndroid14Plus ? '是' : '否'}`);
+        console.log(`iOS 17+: ${info.isiOS17Plus ? '是' : '否'}`);
+        console.log(`支持后台位置: ${this.supportsBackgroundLocation() ? '是' : '否'}`);
+        const practices = this.getBestPractices();
+        console.log('\n💡 最佳实践建议:');
+        if (info.isAndroid14Plus) {
+            console.log('\nAndroid 14+ 特别注意:');
+            practices.android14.forEach((tip, index) => {
+                console.log(`  ${index + 1}. ${tip}`);
+            });
+        }
+        if (info.isiOS17Plus) {
+            console.log('\niOS 17+ 特别注意:');
+            practices.ios17.forEach((tip, index) => {
+                console.log(`  ${index + 1}. ${tip}`);
+            });
+        }
+        console.log('\n通用建议:');
+        practices.general.forEach((tip, index) => {
+            console.log(`  ${index + 1}. ${tip}`);
+        });
+        if (info.platform === 'ios') {
+            const validation = this.validateiOSConfiguration();
+            if (validation.recommendations.length > 0) {
+                console.log('\niOS 配置建议:');
+                validation.recommendations.forEach((rec, index) => {
+                    console.log(`  ${index + 1}. ${rec}`);
+                });
+            }
+        }
+        console.log('\n📌 实际权限请求：');
+        console.log('  使用 ExpoGaodeMapModule.checkLocationPermission()');
+        console.log('  使用 ExpoGaodeMapModule.requestLocationPermission()');
+    }
+}
+exports.PermissionUtils = PermissionUtils;
+/**
+ * 向后兼容的别名
+ * @deprecated 请使用 PermissionUtils
+ */
+exports.PermissionManager = PermissionUtils;

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

@@ -0,0 +1,102 @@
+/**
+ * 平台检测工具
+ * 用于检测设备特性、系统版本等
+ */
+/**
+ * 设备类型
+ */
+export declare enum DeviceType {
+    PHONE = "phone",
+    TABLET = "tablet",
+    FOLDABLE = "foldable",
+    UNKNOWN = "unknown"
+}
+/**
+ * 折叠状态
+ */
+export declare enum FoldState {
+    FOLDED = "folded",
+    UNFOLDED = "unfolded",
+    HALF_FOLDED = "half_folded",
+    UNKNOWN = "unknown"
+}
+/**
+ * 设备信息
+ */
+export interface DeviceInfo {
+    type: DeviceType;
+    isTablet: boolean;
+    isFoldable: boolean;
+    screenSize: {
+        width: number;
+        height: number;
+        scale: number;
+        fontScale: number;
+    };
+    aspectRatio: number;
+    isLandscape: boolean;
+}
+/**
+ * 系统版本信息
+ */
+export interface SystemVersion {
+    platform: 'ios' | 'android';
+    version: number;
+    isAndroid14Plus: boolean;
+    isIOS17Plus: boolean;
+}
+/**
+ * 平台检测器类
+ */
+export declare class PlatformDetector {
+    private static deviceInfo;
+    private static systemVersion;
+    /**
+     * 获取系统版本信息
+     */
+    static getSystemVersion(): SystemVersion;
+    /**
+     * 获取设备信息
+     */
+    static getDeviceInfo(): DeviceInfo;
+    /**
+     * 检测折叠屏设备
+     */
+    private static detectFoldable;
+    /**
+     * 检测当前折叠状态（需要原生支持）
+     */
+    static getFoldState(): FoldState;
+    /**
+     * 是否为 iPad
+     */
+    static isIPad(): boolean;
+    /**
+     * 是否支持多任务
+     */
+    static supportsMultitasking(): boolean;
+    /**
+     * 是否需要 Android 14+ 新权限流程
+     */
+    static needsAndroid14Permissions(): boolean;
+    /**
+     * 是否支持 iOS 17+ 新特性
+     */
+    static supportsiOS17Features(): boolean;
+    /**
+     * 监听屏幕尺寸变化（折叠屏展开/折叠）
+     */
+    static addDimensionChangeListener(callback: (info: DeviceInfo) => void): () => void;
+    /**
+     * 重置缓存（用于测试或强制刷新）
+     */
+    static resetCache(): void;
+}
+/**
+ * 便捷的导出函数
+ */
+export declare const isAndroid14Plus: () => boolean;
+export declare const isiOS17Plus: () => boolean;
+export declare const isTablet: () => boolean;
+export declare const isFoldable: () => boolean;
+export declare const isIPad: () => boolean;