expo-gaode-map 2.2.4-next.1 → 2.2.4

package/android/src/main/java/expo/modules/gaodemap/utils/PermissionHelper.kt

@@ -0,0 +1,247 @@
+package expo.modules.gaodemap.utils
+
+import android.Manifest
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.net.Uri
+import android.os.Build
+import android.provider.Settings
+import androidx.core.app.ActivityCompat
+import androidx.core.content.ContextCompat
+
+/**
+ * Android 14+ 权限适配助手
+ * 
+ * 主要变化：
+ * 1. Android 14 (API 34) 引入了更精细的位置权限
+ * 2. 需要同时请求前台和后台位置权限
+ * 3. 权限请求流程更加严格
+ */
+object PermissionHelper {
+    
+    /**
+     * 位置权限类型
+     */
+    enum class LocationPermissionType {
+        FOREGROUND,      // 仅前台位置
+        BACKGROUND,      // 后台位置
+        FOREGROUND_AND_BACKGROUND  // 前台+后台
+    }
+    
+    /**
+     * 权限状态
+     */
+    data class PermissionStatus(
+        val granted: Boolean,
+        val shouldShowRationale: Boolean,
+        val isPermanentlyDenied: Boolean,
+        val fineLocation: Boolean = false,
+        val coarseLocation: Boolean = false,
+        val backgroundLocation: Boolean = false
+    )
+    
+    /**
+     * 检查是否为 Android 14+
+     */
+    fun isAndroid14Plus(): Boolean {
+        return Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE // API 34
+    }
+    
+    /**
+     * 检查是否为 Android 10+（引入后台位置权限）
+     */
+    fun isAndroid10Plus(): Boolean {
+        return Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q // API 29
+    }
+    
+    /**
+     * 获取需要请求的前台位置权限列表
+     */
+    fun getForegroundLocationPermissions(): Array<String> {
+        return arrayOf(
+            Manifest.permission.ACCESS_FINE_LOCATION,
+            Manifest.permission.ACCESS_COARSE_LOCATION
+        )
+    }
+    
+    /**
+     * 获取后台位置权限
+     */
+    fun getBackgroundLocationPermission(): String? {
+        return if (isAndroid10Plus()) {
+            Manifest.permission.ACCESS_BACKGROUND_LOCATION
+        } else {
+            null
+        }
+    }
+    
+    /**
+     * 检查前台位置权限状态
+     */
+    fun checkForegroundLocationPermission(context: Context): PermissionStatus {
+        val fineGranted = ContextCompat.checkSelfPermission(
+            context,
+            Manifest.permission.ACCESS_FINE_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+        
+        val coarseGranted = ContextCompat.checkSelfPermission(
+            context,
+            Manifest.permission.ACCESS_COARSE_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+        
+        val granted = fineGranted && coarseGranted
+        
+        val activity = context as? Activity
+        val shouldShowRationale = if (activity != null && !granted) {
+            ActivityCompat.shouldShowRequestPermissionRationale(
+                activity,
+                Manifest.permission.ACCESS_FINE_LOCATION
+            )
+        } else {
+            false
+        }
+        
+        return PermissionStatus(
+            granted = granted,
+            shouldShowRationale = shouldShowRationale,
+            isPermanentlyDenied = !granted && !shouldShowRationale && activity != null,
+            fineLocation = fineGranted,
+            coarseLocation = coarseGranted
+        )
+    }
+    
+    /**
+     * 检查后台位置权限状态
+     */
+    fun checkBackgroundLocationPermission(context: Context): PermissionStatus {
+        val permission = getBackgroundLocationPermission()
+        if (permission == null) {
+            // Android 10 以下不支持后台位置权限
+            return PermissionStatus(
+                granted = true,
+                shouldShowRationale = false,
+                isPermanentlyDenied = false,
+                backgroundLocation = true
+            )
+        }
+        
+        val granted = ContextCompat.checkSelfPermission(
+            context,
+            permission
+        ) == PackageManager.PERMISSION_GRANTED
+        
+        val activity = context as? Activity
+        val shouldShowRationale = if (activity != null && !granted) {
+            ActivityCompat.shouldShowRequestPermissionRationale(activity, permission)
+        } else {
+            false
+        }
+        
+        return PermissionStatus(
+            granted = granted,
+            shouldShowRationale = shouldShowRationale,
+            isPermanentlyDenied = !granted && !shouldShowRationale && activity != null,
+            backgroundLocation = granted
+        )
+    }
+    
+    /**
+     * 检查完整位置权限状态（前台+后台）
+     */
+    fun checkFullLocationPermission(context: Context): PermissionStatus {
+        val foreground = checkForegroundLocationPermission(context)
+        val background = checkBackgroundLocationPermission(context)
+        
+        return PermissionStatus(
+            granted = foreground.granted && background.granted,
+            shouldShowRationale = foreground.shouldShowRationale || background.shouldShowRationale,
+            isPermanentlyDenied = foreground.isPermanentlyDenied || background.isPermanentlyDenied,
+            fineLocation = foreground.fineLocation,
+            coarseLocation = foreground.coarseLocation,
+            backgroundLocation = background.backgroundLocation
+        )
+    }
+    
+    /**
+     * 请求前台位置权限
+     * Android 14+ 推荐的请求流程
+     */
+    fun requestForegroundLocationPermission(activity: Activity, requestCode: Int) {
+        val permissions = getForegroundLocationPermissions()
+        ActivityCompat.requestPermissions(activity, permissions, requestCode)
+    }
+    
+    /**
+     * 请求后台位置权限
+     * 注意：必须在前台权限已授予后才能请求
+     */
+    fun requestBackgroundLocationPermission(activity: Activity, requestCode: Int): Boolean {
+        val permission = getBackgroundLocationPermission()
+        if (permission == null) {
+            return false
+        }
+        
+        // 检查前台权限是否已授予
+        val foregroundStatus = checkForegroundLocationPermission(activity)
+        if (!foregroundStatus.granted) {
+            return false
+        }
+        
+        ActivityCompat.requestPermissions(activity, arrayOf(permission), requestCode)
+        return true
+    }
+    
+    /**
+     * 打开应用设置页面
+     * 用于引导用户手动授予权限
+     */
+    fun openAppSettings(context: Context) {
+        val intent = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS).apply {
+            data = Uri.fromParts("package", context.packageName, null)
+            flags = Intent.FLAG_ACTIVITY_NEW_TASK
+        }
+        context.startActivity(intent)
+    }
+    
+    /**
+     * 获取权限请求的推荐提示文案（Android 14+ 优化）
+     */
+    fun getPermissionRationale(
+        type: LocationPermissionType,
+        isAndroid14: Boolean = isAndroid14Plus()
+    ): String {
+        return when (type) {
+            LocationPermissionType.FOREGROUND -> {
+                if (isAndroid14) {
+                    "为了在地图上显示您的位置，应用需要访问您的位置信息。\n\n" +
+                    "您可以选择：\n" +
+                    "• 仅在使用应用时允许\n" +
+                    "• 每次询问\n\n" +
+                    "我们不会在后台收集您的位置数据。"
+                } else {
+                    "为了在地图上显示您的位置，应用需要访问您的位置信息。"
+                }
+            }
+            LocationPermissionType.BACKGROUND -> {
+                if (isAndroid14) {
+                    "为了在后台更新您的位置（如导航、轨迹记录），应用需要始终访问位置权限。\n\n" +
+                    "您可以随时在设置中更改此权限。"
+                } else {
+                    "为了在后台更新您的位置，应用需要始终访问位置权限。"
+                }
+            }
+            LocationPermissionType.FOREGROUND_AND_BACKGROUND -> {
+                if (isAndroid14) {
+                    "应用需要位置权限来提供以下功能：\n" +
+                    "• 在地图上显示您的位置（前台）\n" +
+                    "• 后台导航和轨迹记录（后台）\n\n" +
+                    "我们会先请求前台权限，然后再请求后台权限。"
+                } else {
+                    "应用需要位置权限来显示地图位置和后台导航功能。"
+                }
+            }
+        }
+    }
+}

package/build/ExpoGaodeMapModule.d.ts

@@ -17,10 +17,10 @@ export interface SDKConfig {
     webKey?: string;
 }
 /**
- * 权限状态
+ * 权限状态（增强版，支持 Android 14+ 和 iOS 17+）
  */
 export interface PermissionStatus {
-    /** 是否已授权 */
+    /** 是否已授权（前台位置权限） */
     granted: boolean;
     /** iOS 权限状态字符串 */
     status?: 'notDetermined' | 'restricted' | 'denied' | 'authorizedAlways' | 'authorizedWhenInUse' | 'unknown';
@@ -28,6 +28,16 @@ export interface PermissionStatus {
     fineLocation?: boolean;
     /** Android 粗略位置权限 */
     coarseLocation?: boolean;
+    /** Android 后台位置权限（Android 10+） */
+    backgroundLocation?: boolean;
+    /** 是否应显示权限说明（Android） */
+    shouldShowRationale?: boolean;
+    /** 权限是否被永久拒绝（Android） */
+    isPermanentlyDenied?: boolean;
+    /** 是否为 Android 14+（Android） */
+    isAndroid14Plus?: boolean;
+    /** 额外的消息说明 */
+    message?: string;
 }
 /**
  * 高德地图原生模块类声明
@@ -37,6 +47,7 @@ declare class ExpoGaodeMapModule extends NativeModule<ExpoGaodeMapModuleEvents>
      * 更新隐私合规状态
      * 必须在用户同意隐私协议后调用
      * @param hasAgreed 用户是否已同意隐私协议
+     * @deprecated 已经弃用，原生里默认为已同意,不再需要调用
      */
     updatePrivacyCompliance(hasAgreed: boolean): void;
     /**
@@ -180,15 +191,26 @@ declare class ExpoGaodeMapModule extends NativeModule<ExpoGaodeMapModuleEvents>
      */
     stopUpdatingHeading(): void;
     /**
-     * 检查位置权限状态
-     * @returns Promise<PermissionStatus> 权限状态
+     * 检查前台位置权限状态（增强版，支持 Android 14+ 适配）
+     * @returns Promise<PermissionStatus> 详细的权限状态信息
      */
     checkLocationPermission(): Promise<PermissionStatus>;
     /**
-     * 请求位置权限
+     * 请求前台位置权限（增强版，支持 Android 14+ 适配）
      * @returns Promise<PermissionStatus> 请求后的权限状态
      */
     requestLocationPermission(): Promise<PermissionStatus>;
+    /**
+     * 请求后台位置权限（Android 10+、iOS）
+     * 注意：必须在前台权限已授予后才能请求
+     * @returns Promise<PermissionStatus> 请求后的权限状态
+     */
+    requestBackgroundLocationPermission(): Promise<PermissionStatus>;
+    /**
+     * 打开应用设置页面
+     * 引导用户手动授予权限（当权限被永久拒绝时使用）
+     */
+    openAppSettings(): void;
     /**
      * 开始预加载地图实例
      * 在后台预先初始化地图视图，提升首次显示速度

package/build/ExpoGaodeMapModule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoGaodeMapModule.d.ts","sourceRoot":"","sources":["../src/ExpoGaodeMapModule.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ExpoGaodeMapModule.d.ts","sourceRoot":"","sources":["../src/ExpoGaodeMapModule.ts"],"names":[],"mappings":"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"}

package/build/ExpoGaodeMapModule.js

@@ -3,20 +3,19 @@
  * 提供 SDK 初始化、定位、权限管理等功能
  */
 import { requireNativeModule } from 'expo';
+import { ErrorHandler, ErrorLogger } from './utils/ErrorHandler';
 // 获取原生模块实例 - 添加容错处理
 let nativeModule = null;
 try {
     nativeModule = requireNativeModule('ExpoGaodeMap');
 }
 catch (error) {
-    console.warn('ExpoGaodeMap 原生模块加载失败:', error);
-}
-// 如果模块加载失败，创建一个空的代理对象防止崩溃
-if (!nativeModule) {
-    console.error('ExpoGaodeMap: 原生模块不可用，请检查配置');
+    const moduleError = ErrorHandler.nativeModuleUnavailable();
+    ErrorLogger.log(moduleError);
 }
 // 记录最近一次 initSDK 的配置（含 webKey）
 let _sdkConfig = null;
+let _isSDKInitialized = false;
 // 扩展原生模块，添加便捷方法
 const ExpoGaodeMapModuleWithHelpers = {
     ...(nativeModule || {}),
@@ -24,17 +23,152 @@ const ExpoGaodeMapModuleWithHelpers = {
      * 初始化 SDK，并缓存配置（包含 webKey）
      */
     initSDK(config) {
-        _sdkConfig = config ?? null;
-        nativeModule?.initSDK?.(config);
+        if (!nativeModule) {
+            throw ErrorHandler.nativeModuleUnavailable();
+        }
+        // 验证 API Key 配置
+        if (!config.androidKey && !config.iosKey) {
+            throw ErrorHandler.invalidApiKey('both');
+        }
+        try {
+            _sdkConfig = config ?? null;
+            nativeModule.initSDK(config);
+            _isSDKInitialized = true;
+            ErrorLogger.warn('SDK 初始化成功', { config });
+        }
+        catch (error) {
+            _isSDKInitialized = false;
+            throw ErrorHandler.wrapNativeError(error, 'SDK 初始化');
+        }
+    },
+    /**
+     * 检查 SDK 是否已通过 JS 调用 initSDK() 初始化
+     * 注意：即使返回 false，原生端可能已通过 Config Plugin 自动初始化
+     */
+    isSDKInitialized() {
+        return _isSDKInitialized;
+    },
+    /**
+     * 开始连续定位
+     * 注意：如果使用 Config Plugin 配置了 API Key，无需调用 initSDK()
+     */
+    start() {
+        if (!nativeModule) {
+            throw ErrorHandler.nativeModuleUnavailable();
+        }
+        try {
+            nativeModule.start();
+        }
+        catch (error) {
+            throw ErrorHandler.wrapNativeError(error, '开始定位');
+        }
+    },
+    /**
+     * 停止定位
+     */
+    stop() {
+        if (!nativeModule) {
+            throw ErrorHandler.nativeModuleUnavailable();
+        }
+        try {
+            nativeModule.stop();
+        }
+        catch (error) {
+            throw ErrorHandler.wrapNativeError(error, '停止定位');
+        }
+    },
+    /**
+     * 获取当前位置（单次定位）
+     * 注意：如果使用 Config Plugin 配置了 API Key，无需调用 initSDK()
+     */
+    async getCurrentLocation() {
+        if (!nativeModule) {
+            throw ErrorHandler.nativeModuleUnavailable();
+        }
+        try {
+            return await nativeModule.getCurrentLocation();
+        }
+        catch (error) {
+            throw ErrorHandler.locationFailed(error?.message);
+        }
+    },
+    /**
+     * 检查位置权限状态
+     */
+    async checkLocationPermission() {
+        if (!nativeModule) {
+            throw ErrorHandler.nativeModuleUnavailable();
+        }
+        try {
+            return await nativeModule.checkLocationPermission();
+        }
+        catch (error) {
+            throw ErrorHandler.wrapNativeError(error, '检查权限');
+        }
+    },
+    /**
+     * 请求前台位置权限（增强版）
+     */
+    async requestLocationPermission() {
+        if (!nativeModule) {
+            throw ErrorHandler.nativeModuleUnavailable();
+        }
+        try {
+            const result = await nativeModule.requestLocationPermission();
+            if (!result.granted) {
+                ErrorLogger.warn('前台位置权限未授予', result);
+            }
+            return result;
+        }
+        catch (error) {
+            throw ErrorHandler.wrapNativeError(error, '请求前台权限');
+        }
+    },
+    /**
+     * 请求后台位置权限
+     * 注意：必须在前台权限已授予后才能请求
+     */
+    async requestBackgroundLocationPermission() {
+        if (!nativeModule) {
+            throw ErrorHandler.nativeModuleUnavailable();
+        }
+        try {
+            const result = await nativeModule.requestBackgroundLocationPermission();
+            if (!result.granted) {
+                ErrorLogger.warn('后台位置权限未授予', result);
+            }
+            return result;
+        }
+        catch (error) {
+            throw ErrorHandler.wrapNativeError(error, '请求后台权限');
+        }
+    },
+    /**
+     * 打开应用设置页面
+     * 引导用户手动授予权限
+     */
+    openAppSettings() {
+        if (!nativeModule) {
+            throw ErrorHandler.nativeModuleUnavailable();
+        }
+        try {
+            nativeModule.openAppSettings();
+        }
+        catch (error) {
+            throw ErrorHandler.wrapNativeError(error, '打开设置');
+        }
     },
     /**
      * 添加定位监听器（便捷方法）
      * 自动订阅 onLocationUpdate 事件，提供容错处理
      * @param listener 定位回调函数
      * @returns 订阅对象，调用 remove() 取消监听
-     * @throws 如果底层模块不可用，返回一个空操作的订阅对象
+     * 注意：如果使用 Config Plugin 配置了 API Key，无需调用 initSDK()
      */
     addLocationListener(listener) {
+        if (!nativeModule) {
+            throw ErrorHandler.nativeModuleUnavailable();
+        }
         // 使用可选链和空值合并，确保即使模块不可用也不会崩溃
         return nativeModule?.addListener?.('onLocationUpdate', listener) || {
             remove: () => { },

package/build/ExpoGaodeMapModule.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoGaodeMapModule.js","sourceRoot":"","sources":["../src/ExpoGaodeMapModule.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAgB,mBAAmB,EAAE,MAAM,MAAM,CAAC;AA2RzD,oBAAoB;AACpB,IAAI,YAAY,GAA8B,IAAI,CAAC;AAEnD,IAAI,CAAC;IACH,YAAY,GAAG,mBAAmB,CAAqB,cAAc,CAAC,CAAC;AACzE,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,OAAO,CAAC,IAAI,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,0BAA0B;AAC1B,IAAI,CAAC,YAAY,EAAE,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAC/C,CAAC;AAED,+BAA+B;AAC/B,IAAI,UAAU,GAAqB,IAAI,CAAC;AAExC,gBAAgB;AAChB,MAAM,6BAA6B,GAAG;IACrC,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC;IAEvB;;OAEG;IACH,OAAO,CAAC,MAAiB;QACvB,UAAU,GAAG,MAAM,IAAI,IAAI,CAAC;QAC5B,YAAY,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;OAMG;IACH,mBAAmB,CAAC,QAA0B;QAC5C,4BAA4B;QAC5B,OAAO,YAAY,EAAE,WAAW,EAAE,CAAC,kBAAkB,EAAE,QAAQ,CAAC,IAAI;YAClE,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC;SACjB,CAAC;IACJ,CAAC;CACD,CAAC;AAEF;;EAEE;AACF,MAAM,UAAU,YAAY;IAC3B,OAAO,UAAU,CAAC;AACnB,CAAC;AAED;;EAEE;AACF,MAAM,UAAU,SAAS;IACxB,OAAO,UAAU,EAAE,MAAM,CAAC;AAC3B,CAAC;AAED,eAAe,6BAAmD,CAAC","sourcesContent":["/**\n * 高德地图原生模块\n * 提供 SDK 初始化、定位、权限管理等功能\n */\n\nimport { NativeModule, requireNativeModule } from 'expo';\nimport type { ExpoGaodeMapModuleEvents } from './ExpoGaodeMap.types';\nimport type {\n  LatLng,\n  CoordinateType,\n  Coordinates,\n  ReGeocode,\n  LocationMode,\n  LocationAccuracy,\n  LocationListener,\n} from './types';\n\n/**\n * SDK 配置参数\n */\nexport interface SDKConfig {\n  /** Android 平台的高德地图 API Key */\n  androidKey?: string;\n  /** iOS 平台的高德地图 API Key */\n  iosKey?: string;\n  /** web api key 如果要使用expo-gaode-map-web-api相关的功能，需要配置web api key*/\n  webKey?: string;\n}\n\n/**\n * 权限状态\n */\nexport interface PermissionStatus {\n  /** 是否已授权 */\n  granted: boolean;\n  /** iOS 权限状态字符串 */\n  status?: 'notDetermined' | 'restricted' | 'denied' | 'authorizedAlways' | 'authorizedWhenInUse' | 'unknown';\n  /** Android 精确位置权限 */\n  fineLocation?: boolean;\n  /** Android 粗略位置权限 */\n  coarseLocation?: boolean;\n}\n\n/**\n * 高德地图原生模块类声明\n */\ndeclare class ExpoGaodeMapModule extends NativeModule<ExpoGaodeMapModuleEvents> {\n  // ==================== 隐私合规管理 ====================\n  \n  /**\n   * 更新隐私合规状态\n   * 必须在用户同意隐私协议后调用\n   * @param hasAgreed 用户是否已同意隐私协议\n   */\n  updatePrivacyCompliance(hasAgreed: boolean): void;\n  \n  // ==================== SDK 初始化 ====================\n  \n  /**\n   * 初始化高德地图 SDK\n   * @param config SDK 配置参数，包含 Android 和 iOS 的 API Key\n   */\n  initSDK(config: SDKConfig): void;\n  \n  /**\n   * 获取高德地图 SDK 版本号\n   * @returns SDK 版本字符串\n   */\n  getVersion(): string;\n  \n  // ==================== 定位控制 ====================\n  \n  /**\n   * 开始连续定位\n   * 启动后会持续接收位置更新，通过 onLocationUpdate 事件回调\n   */\n  start(): void;\n  \n  /**\n   * 停止定位\n   * 停止接收位置更新\n   */\n  stop(): void;\n  \n  /**\n   * 检查是否正在定位\n   * @returns Promise<boolean> 是否正在定位\n   */\n  isStarted(): Promise<boolean>;\n  \n  /**\n   * 获取当前位置（单次定位）\n   * @returns Promise<Coordinates | ReGeocode> 位置信息，包含坐标和可选的逆地理编码信息\n   */\n  getCurrentLocation(): Promise<Coordinates | ReGeocode>;\n  \n  /**\n   * 坐标转换\n   * 将其他坐标系的坐标转换为高德地图使用的 GCJ-02 坐标系\n   * @param coordinate 需要转换的坐标\n   * @param type 原坐标系类型\n   * @returns Promise<LatLng> 转换后的 GCJ-02 坐标\n   */\n  coordinateConvert(coordinate: LatLng, type: CoordinateType): Promise<LatLng>;\n  \n  // ==================== 定位配置 ====================\n  \n  /**\n   * 设置是否返回逆地理编码信息\n   * @param isReGeocode true: 返回地址信息; false: 只返回坐标\n   */\n  setLocatingWithReGeocode(isReGeocode: boolean): void;\n  \n  /**\n   * 设置定位模式（Android）\n   * @param mode 定位模式：0-低功耗, 1-仅设备, 2-高精度\n   */\n  setLocationMode(mode: LocationMode): void;\n  \n  /**\n   * 设置定位间隔（毫秒）\n   * @param interval 定位间隔时间，单位毫秒，默认 2000ms\n   */\n  setInterval(interval: number): void;\n  \n  /**\n   * 设置是否单次定位（Android）\n   * @param isOnceLocation true: 单次定位; false: 连续定位\n   */\n  setOnceLocation(isOnceLocation: boolean): void;\n  \n  /**\n   * 设置是否使用设备传感器（Android）\n   * @param sensorEnable true: 使用传感器; false: 不使用\n   */\n  setSensorEnable(sensorEnable: boolean): void;\n  \n  /**\n   * 设置是否允许 WiFi 扫描（Android）\n   * @param wifiScan true: 允许; false: 不允许\n   */\n  setWifiScan(wifiScan: boolean): void;\n  \n  /**\n   * 设置是否 GPS 优先（Android）\n   * @param gpsFirst true: GPS 优先; false: 网络优先\n   */\n  setGpsFirst(gpsFirst: boolean): void;\n  \n  /**\n   * 设置是否等待 WiFi 列表刷新（Android）\n   * @param onceLocationLatest true: 等待; false: 不等待\n   */\n  setOnceLocationLatest(onceLocationLatest: boolean): void;\n  \n  /**\n   * 设置逆地理编码语言\n   * @param language 语言代码，如 \"zh-CN\", \"en\"\n   */\n  setGeoLanguage(language: string): void;\n  \n  /**\n   * 设置是否使用缓存策略（Android）\n   * @param locationCacheEnable true: 使用缓存; false: 不使用\n   */\n  setLocationCacheEnable(locationCacheEnable: boolean): void;\n  \n  /**\n   * 设置网络请求超时时间（Android）\n   * @param httpTimeOut 超时时间，单位毫秒\n   */\n  setHttpTimeOut(httpTimeOut: number): void;\n  \n  /**\n   * 设置期望的定位精度（iOS）\n   * @param accuracy 精度级别：0-最佳, 1-10米, 2-100米, 3-1公里, 4-3公里\n   */\n  setDesiredAccuracy(accuracy: LocationAccuracy): void;\n  \n  /**\n   * 设置定位超时时间（秒）\n   * @param timeout 超时时间，单位秒，默认 10 秒\n   */\n  setLocationTimeout(timeout: number): void;\n  \n  /**\n   * 设置逆地理编码超时时间（秒）\n   * @param timeout 超时时间，单位秒，默认 5 秒\n   */\n  setReGeocodeTimeout(timeout: number): void;\n  \n  /**\n   * 设置距离过滤器（米）（iOS）\n   * 只有移动超过指定距离才会更新位置\n   * @param distance 距离阈值，单位米\n   */\n  setDistanceFilter(distance: number): void;\n  \n  /**\n   * 设置是否自动暂停位置更新（iOS）\n   * @param pauses true: 自动暂停; false: 不暂停\n   */\n  setPausesLocationUpdatesAutomatically(pauses: boolean): void;\n  \n  /**\n   * 设置是否允许后台定位（iOS）\n   * @param allows true: 允许; false: 不允许\n   */\n  setAllowsBackgroundLocationUpdates(allows: boolean): void;\n  \n  /**\n   * 设置定位协议\n   * @param protocol 协议类型\n   */\n  setLocationProtocol(protocol: string): void;\n  \n  // ==================== 方向更新 (iOS) ====================\n  \n  /**\n   * 开始更新设备方向（罗盘朝向）\n   * 通过 onHeadingUpdate 事件接收方向更新\n   * @platform ios\n   */\n  startUpdatingHeading(): void;\n  \n  /**\n   * 停止更新设备方向\n   * @platform ios\n   */\n  stopUpdatingHeading(): void;\n  \n  // ==================== 权限管理 ====================\n  \n  /**\n   * 检查位置权限状态\n   * @returns Promise<PermissionStatus> 权限状态\n   */\n  checkLocationPermission(): Promise<PermissionStatus>;\n  \n  /**\n   * 请求位置权限\n   * @returns Promise<PermissionStatus> 请求后的权限状态\n   */\n  requestLocationPermission(): Promise<PermissionStatus>;\n  \n  // ==================== 地图预加载 ====================\n  \n  /**\n   * 开始预加载地图实例\n   * 在后台预先初始化地图视图，提升首次显示速度\n   * @param config 预加载配置对象\n   * @param config.poolSize 预加载的地图实例数量，默认 2\n   */\n  startMapPreload(config: { poolSize?: number }): void;\n  \n  /**\n   * 获取预加载状态\n   * @returns 预加载状态信息，包含池大小、是否正在预加载等\n   */\n  getMapPreloadStatus(): {\n    poolSize: number;\n    isPreloading: boolean;\n    maxPoolSize: number;\n  };\n  \n  /**\n   * 清空预加载池\n   * 释放所有预加载的地图实例\n   */\n  clearMapPreloadPool(): void;\n  \n  /**\n   * 检查是否有可用的预加载实例\n   * @returns 是否有可用的预加载地图实例\n   */\n  hasPreloadedMapView(): boolean;\n  \n  // ==================== 便捷方法 ====================\n  \n  /**\n   * 添加定位监听器（便捷方法）\n   * 封装了 addListener，提供更简洁的 API\n   * @param listener 定位回调函数\n   * @returns 订阅对象，调用 remove() 取消监听\n   */\n  addLocationListener(listener: LocationListener): { remove: () => void };\n}\n\n// 获取原生模块实例 - 添加容错处理\nlet nativeModule: ExpoGaodeMapModule | null = null;\n\ntry {\n  nativeModule = requireNativeModule<ExpoGaodeMapModule>('ExpoGaodeMap');\n} catch (error) {\n  console.warn('ExpoGaodeMap 原生模块加载失败:', error);\n}\n\n// 如果模块加载失败，创建一个空的代理对象防止崩溃\nif (!nativeModule) {\n  console.error('ExpoGaodeMap: 原生模块不可用，请检查配置');\n}\n\n// 记录最近一次 initSDK 的配置（含 webKey）\nlet _sdkConfig: SDKConfig | null = null;\n\n// 扩展原生模块，添加便捷方法\nconst ExpoGaodeMapModuleWithHelpers = {\n ...(nativeModule || {}),\n\n /**\n  * 初始化 SDK，并缓存配置（包含 webKey）\n  */\n initSDK(config: SDKConfig): void {\n   _sdkConfig = config ?? null;\n   nativeModule?.initSDK?.(config);\n },\n\n /**\n  * 添加定位监听器（便捷方法）\n  * 自动订阅 onLocationUpdate 事件，提供容错处理\n  * @param listener 定位回调函数\n  * @returns 订阅对象，调用 remove() 取消监听\n  * @throws 如果底层模块不可用，返回一个空操作的订阅对象\n  */\n addLocationListener(listener: LocationListener): { remove: () => void } {\n   // 使用可选链和空值合并，确保即使模块不可用也不会崩溃\n   return nativeModule?.addListener?.('onLocationUpdate', listener) || {\n     remove: () => {},\n   };\n },\n};\n\n/**\n* 获取最近一次 initSDK 的配置\n*/\nexport function getSDKConfig(): SDKConfig | null {\n return _sdkConfig;\n}\n\n/**\n* 获取用于 Web API 的 webKey（若未初始化或未提供则返回 undefined）\n*/\nexport function getWebKey(): string | undefined {\n return _sdkConfig?.webKey;\n}\n\nexport default ExpoGaodeMapModuleWithHelpers as ExpoGaodeMapModule;\n"]}
+{"version":3,"file":"ExpoGaodeMapModule.js","sourceRoot":"","sources":["../src/ExpoGaodeMapModule.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 高德地图原生模块\n * 提供 SDK 初始化、定位、权限管理等功能\n */\n\nimport { NativeModule, requireNativeModule } from 'expo';\nimport type { ExpoGaodeMapModuleEvents } from './ExpoGaodeMap.types';\nimport type {\n  LatLng,\n  CoordinateType,\n  Coordinates,\n  ReGeocode,\n  LocationMode,\n  LocationAccuracy,\n  LocationListener,\n} from './types';\nimport { ErrorHandler, ErrorLogger } from './utils/ErrorHandler';\n\n/**\n * SDK 配置参数\n */\nexport interface SDKConfig {\n  /** Android 平台的高德地图 API Key */\n  androidKey?: string;\n  /** iOS 平台的高德地图 API Key */\n  iosKey?: string;\n  /** web api key 如果要使用expo-gaode-map-web-api相关的功能，需要配置web api key*/\n  webKey?: string;\n}\n\n/**\n * 权限状态（增强版，支持 Android 14+ 和 iOS 17+）\n */\nexport interface PermissionStatus {\n  /** 是否已授权（前台位置权限） */\n  granted: boolean;\n  \n  // iOS 专用字段\n  /** iOS 权限状态字符串 */\n  status?: 'notDetermined' | 'restricted' | 'denied' | 'authorizedAlways' | 'authorizedWhenInUse' | 'unknown';\n  \n  // Android 专用字段\n  /** Android 精确位置权限 */\n  fineLocation?: boolean;\n  /** Android 粗略位置权限 */\n  coarseLocation?: boolean;\n  /** Android 后台位置权限（Android 10+） */\n  backgroundLocation?: boolean;\n  /** 是否应显示权限说明（Android） */\n  shouldShowRationale?: boolean;\n  /** 权限是否被永久拒绝（Android） */\n  isPermanentlyDenied?: boolean;\n  /** 是否为 Android 14+（Android） */\n  isAndroid14Plus?: boolean;\n  \n  // 其他字段\n  /** 额外的消息说明 */\n  message?: string;\n}\n\n/**\n * 高德地图原生模块类声明\n */\ndeclare class ExpoGaodeMapModule extends NativeModule<ExpoGaodeMapModuleEvents> {\n  // ==================== 隐私合规管理 ====================\n  \n  /**\n   * 更新隐私合规状态\n   * 必须在用户同意隐私协议后调用\n   * @param hasAgreed 用户是否已同意隐私协议\n   * @deprecated 已经弃用，原生里默认为已同意,不再需要调用\n   */\n  updatePrivacyCompliance(hasAgreed: boolean): void;\n  \n  // ==================== SDK 初始化 ====================\n  \n  /**\n   * 初始化高德地图 SDK\n   * @param config SDK 配置参数，包含 Android 和 iOS 的 API Key\n   */\n  initSDK(config: SDKConfig): void;\n  \n  /**\n   * 获取高德地图 SDK 版本号\n   * @returns SDK 版本字符串\n   */\n  getVersion(): string;\n  \n  // ==================== 定位控制 ====================\n  \n  /**\n   * 开始连续定位\n   * 启动后会持续接收位置更新，通过 onLocationUpdate 事件回调\n   */\n  start(): void;\n  \n  /**\n   * 停止定位\n   * 停止接收位置更新\n   */\n  stop(): void;\n  \n  /**\n   * 检查是否正在定位\n   * @returns Promise<boolean> 是否正在定位\n   */\n  isStarted(): Promise<boolean>;\n  \n  /**\n   * 获取当前位置（单次定位）\n   * @returns Promise<Coordinates | ReGeocode> 位置信息，包含坐标和可选的逆地理编码信息\n   */\n  getCurrentLocation(): Promise<Coordinates | ReGeocode>;\n  \n  /**\n   * 坐标转换\n   * 将其他坐标系的坐标转换为高德地图使用的 GCJ-02 坐标系\n   * @param coordinate 需要转换的坐标\n   * @param type 原坐标系类型\n   * @returns Promise<LatLng> 转换后的 GCJ-02 坐标\n   */\n  coordinateConvert(coordinate: LatLng, type: CoordinateType): Promise<LatLng>;\n  \n  // ==================== 定位配置 ====================\n  \n  /**\n   * 设置是否返回逆地理编码信息\n   * @param isReGeocode true: 返回地址信息; false: 只返回坐标\n   */\n  setLocatingWithReGeocode(isReGeocode: boolean): void;\n  \n  /**\n   * 设置定位模式（Android）\n   * @param mode 定位模式：0-低功耗, 1-仅设备, 2-高精度\n   */\n  setLocationMode(mode: LocationMode): void;\n  \n  /**\n   * 设置定位间隔（毫秒）\n   * @param interval 定位间隔时间，单位毫秒，默认 2000ms\n   */\n  setInterval(interval: number): void;\n  \n  /**\n   * 设置是否单次定位（Android）\n   * @param isOnceLocation true: 单次定位; false: 连续定位\n   */\n  setOnceLocation(isOnceLocation: boolean): void;\n  \n  /**\n   * 设置是否使用设备传感器（Android）\n   * @param sensorEnable true: 使用传感器; false: 不使用\n   */\n  setSensorEnable(sensorEnable: boolean): void;\n  \n  /**\n   * 设置是否允许 WiFi 扫描（Android）\n   * @param wifiScan true: 允许; false: 不允许\n   */\n  setWifiScan(wifiScan: boolean): void;\n  \n  /**\n   * 设置是否 GPS 优先（Android）\n   * @param gpsFirst true: GPS 优先; false: 网络优先\n   */\n  setGpsFirst(gpsFirst: boolean): void;\n  \n  /**\n   * 设置是否等待 WiFi 列表刷新（Android）\n   * @param onceLocationLatest true: 等待; false: 不等待\n   */\n  setOnceLocationLatest(onceLocationLatest: boolean): void;\n  \n  /**\n   * 设置逆地理编码语言\n   * @param language 语言代码，如 \"zh-CN\", \"en\"\n   */\n  setGeoLanguage(language: string): void;\n  \n  /**\n   * 设置是否使用缓存策略（Android）\n   * @param locationCacheEnable true: 使用缓存; false: 不使用\n   */\n  setLocationCacheEnable(locationCacheEnable: boolean): void;\n  \n  /**\n   * 设置网络请求超时时间（Android）\n   * @param httpTimeOut 超时时间，单位毫秒\n   */\n  setHttpTimeOut(httpTimeOut: number): void;\n  \n  /**\n   * 设置期望的定位精度（iOS）\n   * @param accuracy 精度级别：0-最佳, 1-10米, 2-100米, 3-1公里, 4-3公里\n   */\n  setDesiredAccuracy(accuracy: LocationAccuracy): void;\n  \n  /**\n   * 设置定位超时时间（秒）\n   * @param timeout 超时时间，单位秒，默认 10 秒\n   */\n  setLocationTimeout(timeout: number): void;\n  \n  /**\n   * 设置逆地理编码超时时间（秒）\n   * @param timeout 超时时间，单位秒，默认 5 秒\n   */\n  setReGeocodeTimeout(timeout: number): void;\n  \n  /**\n   * 设置距离过滤器（米）（iOS）\n   * 只有移动超过指定距离才会更新位置\n   * @param distance 距离阈值，单位米\n   */\n  setDistanceFilter(distance: number): void;\n  \n  /**\n   * 设置是否自动暂停位置更新（iOS）\n   * @param pauses true: 自动暂停; false: 不暂停\n   */\n  setPausesLocationUpdatesAutomatically(pauses: boolean): void;\n  \n  /**\n   * 设置是否允许后台定位（iOS）\n   * @param allows true: 允许; false: 不允许\n   */\n  setAllowsBackgroundLocationUpdates(allows: boolean): void;\n  \n  /**\n   * 设置定位协议\n   * @param protocol 协议类型\n   */\n  setLocationProtocol(protocol: string): void;\n  \n  // ==================== 方向更新 (iOS) ====================\n  \n  /**\n   * 开始更新设备方向（罗盘朝向）\n   * 通过 onHeadingUpdate 事件接收方向更新\n   * @platform ios\n   */\n  startUpdatingHeading(): void;\n  \n  /**\n   * 停止更新设备方向\n   * @platform ios\n   */\n  stopUpdatingHeading(): void;\n  \n  // ==================== 权限管理（增强版） ====================\n  \n  /**\n   * 检查前台位置权限状态（增强版，支持 Android 14+ 适配）\n   * @returns Promise<PermissionStatus> 详细的权限状态信息\n   */\n  checkLocationPermission(): Promise<PermissionStatus>;\n  \n  /**\n   * 请求前台位置权限（增强版，支持 Android 14+ 适配）\n   * @returns Promise<PermissionStatus> 请求后的权限状态\n   */\n  requestLocationPermission(): Promise<PermissionStatus>;\n  \n  /**\n   * 请求后台位置权限（Android 10+、iOS）\n   * 注意：必须在前台权限已授予后才能请求\n   * @returns Promise<PermissionStatus> 请求后的权限状态\n   */\n  requestBackgroundLocationPermission(): Promise<PermissionStatus>;\n  \n  /**\n   * 打开应用设置页面\n   * 引导用户手动授予权限（当权限被永久拒绝时使用）\n   */\n  openAppSettings(): void;\n  \n  // ==================== 地图预加载 ====================\n  \n  /**\n   * 开始预加载地图实例\n   * 在后台预先初始化地图视图，提升首次显示速度\n   * @param config 预加载配置对象\n   * @param config.poolSize 预加载的地图实例数量，默认 2\n   */\n  startMapPreload(config: { poolSize?: number }): void;\n  \n  /**\n   * 获取预加载状态\n   * @returns 预加载状态信息，包含池大小、是否正在预加载等\n   */\n  getMapPreloadStatus(): {\n    poolSize: number;\n    isPreloading: boolean;\n    maxPoolSize: number;\n  };\n  \n  /**\n   * 清空预加载池\n   * 释放所有预加载的地图实例\n   */\n  clearMapPreloadPool(): void;\n  \n  /**\n   * 检查是否有可用的预加载实例\n   * @returns 是否有可用的预加载地图实例\n   */\n  hasPreloadedMapView(): boolean;\n  \n  // ==================== 便捷方法 ====================\n  \n  /**\n   * 添加定位监听器（便捷方法）\n   * 封装了 addListener，提供更简洁的 API\n   * @param listener 定位回调函数\n   * @returns 订阅对象，调用 remove() 取消监听\n   */\n  addLocationListener(listener: LocationListener): { remove: () => void };\n}\n\n// 获取原生模块实例 - 添加容错处理\nlet nativeModule: ExpoGaodeMapModule | null = null;\n\ntry {\n  nativeModule = requireNativeModule<ExpoGaodeMapModule>('ExpoGaodeMap');\n} catch (error) {\n  const moduleError = ErrorHandler.nativeModuleUnavailable();\n  ErrorLogger.log(moduleError);\n}\n\n// 记录最近一次 initSDK 的配置（含 webKey）\nlet _sdkConfig: SDKConfig | null = null;\nlet _isSDKInitialized = false;\n\n// 扩展原生模块，添加便捷方法\nconst ExpoGaodeMapModuleWithHelpers = {\n ...(nativeModule || {}),\n\n /**\n  * 初始化 SDK，并缓存配置（包含 webKey）\n  */\n initSDK(config: SDKConfig): void {\n   if (!nativeModule) {\n     throw ErrorHandler.nativeModuleUnavailable();\n   }\n\n   // 验证 API Key 配置\n   if (!config.androidKey && !config.iosKey) {\n     throw ErrorHandler.invalidApiKey('both');\n   }\n\n   try {\n     _sdkConfig = config ?? null;\n     nativeModule.initSDK(config);\n     _isSDKInitialized = true;\n     ErrorLogger.warn('SDK 初始化成功', { config });\n   } catch (error: any) {\n     _isSDKInitialized = false;\n     throw ErrorHandler.wrapNativeError(error, 'SDK 初始化');\n   }\n },\n\n /**\n  * 检查 SDK 是否已通过 JS 调用 initSDK() 初始化\n  * 注意：即使返回 false，原生端可能已通过 Config Plugin 自动初始化\n  */\n isSDKInitialized(): boolean {\n   return _isSDKInitialized;\n },\n\n /**\n  * 开始连续定位\n  * 注意：如果使用 Config Plugin 配置了 API Key，无需调用 initSDK()\n  */\n start(): void {\n   if (!nativeModule) {\n     throw ErrorHandler.nativeModuleUnavailable();\n   }\n   try {\n     nativeModule.start();\n   } catch (error: any) {\n     throw ErrorHandler.wrapNativeError(error, '开始定位');\n   }\n },\n\n /**\n  * 停止定位\n  */\n stop(): void {\n   if (!nativeModule) {\n     throw ErrorHandler.nativeModuleUnavailable();\n   }\n   try {\n     nativeModule.stop();\n   } catch (error: any) {\n     throw ErrorHandler.wrapNativeError(error, '停止定位');\n   }\n },\n\n /**\n  * 获取当前位置（单次定位）\n  * 注意：如果使用 Config Plugin 配置了 API Key，无需调用 initSDK()\n  */\n async getCurrentLocation(): Promise<Coordinates | ReGeocode> {\n   if (!nativeModule) {\n     throw ErrorHandler.nativeModuleUnavailable();\n   }\n   try {\n     return await nativeModule.getCurrentLocation();\n   } catch (error: any) {\n     throw ErrorHandler.locationFailed(error?.message);\n   }\n },\n\n /**\n  * 检查位置权限状态\n  */\n async checkLocationPermission(): Promise<PermissionStatus> {\n   if (!nativeModule) {\n     throw ErrorHandler.nativeModuleUnavailable();\n   }\n   try {\n     return await nativeModule.checkLocationPermission();\n   } catch (error: any) {\n     throw ErrorHandler.wrapNativeError(error, '检查权限');\n   }\n },\n\n /**\n  * 请求前台位置权限（增强版）\n  */\n async requestLocationPermission(): Promise<PermissionStatus> {\n   if (!nativeModule) {\n     throw ErrorHandler.nativeModuleUnavailable();\n   }\n   try {\n     const result = await nativeModule.requestLocationPermission();\n     if (!result.granted) {\n       ErrorLogger.warn('前台位置权限未授予', result);\n     }\n     return result;\n   } catch (error: any) {\n     throw ErrorHandler.wrapNativeError(error, '请求前台权限');\n   }\n },\n\n /**\n  * 请求后台位置权限\n  * 注意：必须在前台权限已授予后才能请求\n  */\n async requestBackgroundLocationPermission(): Promise<PermissionStatus> {\n   if (!nativeModule) {\n     throw ErrorHandler.nativeModuleUnavailable();\n   }\n   try {\n     const result = await nativeModule.requestBackgroundLocationPermission();\n     if (!result.granted) {\n       ErrorLogger.warn('后台位置权限未授予', result);\n     }\n     return result;\n   } catch (error: any) {\n     throw ErrorHandler.wrapNativeError(error, '请求后台权限');\n   }\n },\n\n /**\n  * 打开应用设置页面\n  * 引导用户手动授予权限\n  */\n openAppSettings(): void {\n   if (!nativeModule) {\n     throw ErrorHandler.nativeModuleUnavailable();\n   }\n   try {\n     nativeModule.openAppSettings();\n   } catch (error: any) {\n     throw ErrorHandler.wrapNativeError(error, '打开设置');\n   }\n },\n\n /**\n  * 添加定位监听器（便捷方法）\n  * 自动订阅 onLocationUpdate 事件，提供容错处理\n  * @param listener 定位回调函数\n  * @returns 订阅对象，调用 remove() 取消监听\n  * 注意：如果使用 Config Plugin 配置了 API Key，无需调用 initSDK()\n  */\n addLocationListener(listener: LocationListener): { remove: () => void } {\n   if (!nativeModule) {\n     throw ErrorHandler.nativeModuleUnavailable();\n   }\n   // 使用可选链和空值合并，确保即使模块不可用也不会崩溃\n   return nativeModule?.addListener?.('onLocationUpdate', listener) || {\n     remove: () => {},\n   };\n },\n};\n\n/**\n* 获取最近一次 initSDK 的配置\n*/\nexport function getSDKConfig(): SDKConfig | null {\n return _sdkConfig;\n}\n\n/**\n* 获取用于 Web API 的 webKey（若未初始化或未提供则返回 undefined）\n*/\nexport function getWebKey(): string | undefined {\n return _sdkConfig?.webKey;\n}\n\nexport default ExpoGaodeMapModuleWithHelpers as unknown as ExpoGaodeMapModule;\n"]}

package/build/ExpoGaodeMapView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoGaodeMapView.d.ts","sourceRoot":"","sources":["../src/ExpoGaodeMapView.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EAKX,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK1C;;;;;;;;;;;;;;;;;GAiBG;AACH,QAAA,MAAM,gBAAgB,iFAgFpB,CAAC;AAIH,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"ExpoGaodeMapView.d.ts","sourceRoot":"","sources":["../src/ExpoGaodeMapView.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EAKX,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK1C;;;;;;;;;;;;;;;;;GAiBG;AACH,QAAA,MAAM,gBAAgB,iFAwDpB,CAAC;AAIH,eAAe,gBAAgB,CAAC"}