expo-gaode-map 2.2.34 → 2.2.35-next.1

package/build/utils/PermissionUtils.js

@@ -1,3 +1,6 @@
+/**
+ * 权限工具类
+ */
 import { Platform } from 'react-native';
 import { PlatformDetector } from './PlatformDetector';
 /**

package/build/utils/PermissionUtils.js.map

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

package/build/utils/RouteUtils.d.ts

@@ -1,8 +1,53 @@
 import type { LatLngBounds, LatLngPoint } from '../types/common.types';
 import type { FitToCoordinatesOptions, FitToCoordinatesTarget, MultiRingPolyline, RouteBounds } from '../types/route-playback.types';
+/**
+ * 估算路径的推荐缩放级别
+ * @param {number} latitudeDelta - 纬度跨度（度）
+ * @param {number} longitudeDelta - 经度跨度（度）
+ * @param {FitToCoordinatesOptions} options - 选项对象，包含最小缩放级别、最大缩放级别
+ * @defaultOptions 默认选项值
+ * @returns {number} - 推荐缩放级别
+ */
 export declare function estimateZoomLevel(latitudeDelta: number, longitudeDelta: number, options?: Pick<FitToCoordinatesOptions, 'minZoom' | 'maxZoom'>): number;
+/**
+ * 根据路径点计算地图展示所需的中心点、外接矩形、经纬度跨度和推荐缩放级别。
+ *
+ * 该函数会先统一坐标格式，再根据所有点的最南/北/东/西位置生成边界。
+ * recommendedZoom 优先使用原生计算结果，失败时退回到经纬度跨度估算。
+ *
+ * @param points 路径点列表，每个点包含经纬度。
+ * @param options 选项对象，包含缓冲因子、视口宽度、视口高度、最小缩放级别、最大缩放级别。
+ * @defaultOptions 默认选项值。
+ * @returns 推荐缩放级别，可能为 null。
+ */
 export declare function getRouteBounds(points: LatLngPoint[], options?: Pick<FitToCoordinatesOptions, 'paddingFactor' | 'paddingPx' | 'viewportWidthPx' | 'viewportHeightPx' | 'minZoom' | 'maxZoom'>): RouteBounds | null;
+/**
+ * 解析高德多环 polyline，并计算整体坐标边界。
+ *
+ * 常用于 AOI、行政区或多边形边界等场景。高德以 `|` 分隔多个环，
+ * 每个环内部再以 `;` 分隔坐标点。
+ *
+ * @param polyline 高德 polyline 字符串。
+ * @returns 解析后的 LatLng 点数组数组。
+ */
 export declare function parseMultiRingPolyline(polyline: string): MultiRingPolyline;
+/**
+ * 将地图相机移动到能够完整展示指定坐标集合的位置。
+ *
+ * 单点场景直接定位到该点；多点场景会先计算路径边界，再移动到边界中心并应用推荐缩放。
+ * 默认会沿用当前相机的 bearing 和 tilt，除非调用方显式关闭 preserveBearing / preserveTilt。
+ *
+ * @param map 高德地图实例。
+ * @param points 路径点列表，每个点包含经纬度。
+ * @param options 选项对象，包含移动时间、缓冲因子、视口宽度、视口高度、最小缩放级别、最大缩放级别。
+ * @defaultOptions 默认选项值。
+ */
 export declare function fitCameraToCoordinates(map: FitToCoordinatesTarget, points: LatLngPoint[], options?: FitToCoordinatesOptions): Promise<void>;
+/**
+ * 将路径点转换为高德地图通用的西南/东北矩形边界。
+ *
+ * @param points 路径点列表，每个点包含经纬度。
+ * @returns 高德地图通用的西南/东北矩形边界。
+ */
 export declare function buildLatLngBounds(points: LatLngPoint[]): LatLngBounds | null;
 //# sourceMappingURL=RouteUtils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"RouteUtils.d.ts","sourceRoot":"","sources":["../../src/utils/RouteUtils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAU,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACZ,MAAM,+BAA+B,CAAC;AAwDvC,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,IAAI,CAAC,uBAAuB,EAAE,SAAS,GAAG,SAAS,CAAM,GACjE,MAAM,CAQR;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,GAAE,IAAI,CACX,uBAAuB,EACvB,eAAe,GAAG,WAAW,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,SAAS,GAAG,SAAS,CAC1F,GACL,WAAW,GAAG,IAAI,CAqCpB;AAyBD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CA0B1E;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,sBAAsB,EAC3B,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,YAAY,GAAG,IAAI,CAgB5E"}
+{"version":3,"file":"RouteUtils.d.ts","sourceRoot":"","sources":["../../src/utils/RouteUtils.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAU,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACZ,MAAM,+BAA+B,CAAC;AA+EvC;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,IAAI,CAAC,uBAAuB,EAAE,SAAS,GAAG,SAAS,CAAM,GACjE,MAAM,CAQR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,GAAE,IAAI,CACX,uBAAuB,EACvB,eAAe,GAAG,WAAW,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,SAAS,GAAG,SAAS,CAC1F,GACL,WAAW,GAAG,IAAI,CAqCpB;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CA0B1E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,sBAAsB,EAC3B,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,YAAY,GAAG,IAAI,CAgB5E"}

package/build/utils/RouteUtils.js

@@ -1,12 +1,31 @@
+/**
+ * 路线与区域展示相关的工具函数。
+ *
+ * 本文件主要负责路径坐标的边界计算、推荐缩放级别估算、
+ * 高德 polyline / 多环边界字符串解析，以及将地图相机移动到合适的展示范围。
+ * 这些逻辑用于在 JS 层统一处理路线回放、区域遮罩和路径自适应视野等场景。
+ */
 import ExpoGaodeMapModule from '../ExpoGaodeMapModule';
 import { normalizeLatLng, normalizeLatLngList } from './GeoUtils';
-const MIN_ZOOM = 3;
-const MAX_ZOOM = 20;
-const DEFAULT_SINGLE_POINT_ZOOM = 16;
-const DEFAULT_PADDING_FACTOR = 1.2;
-const DEFAULT_VIEWPORT_WIDTH_PX = 390;
-const DEFAULT_VIEWPORT_HEIGHT_PX = 844;
-const DEFAULT_PADDING_PX = 48;
+const MIN_ZOOM = 3; // 最小缩放级别
+const MAX_ZOOM = 20; // 最大缩放级别
+const DEFAULT_SINGLE_POINT_ZOOM = 16; // 默认单点缩放级别
+const DEFAULT_PADDING_FACTOR = 1.2; // 默认缓冲因子
+const DEFAULT_VIEWPORT_WIDTH_PX = 390; // 默认视口宽度（像素）
+const DEFAULT_VIEWPORT_HEIGHT_PX = 844; // 默认视口高度（像素）
+const DEFAULT_PADDING_PX = 48; // 默认缓冲值（像素）
+/**
+ * 将缩放缓冲因子换算成地图四周需要预留的像素 padding。
+ *
+ * paddingFactor 表示“视野比实际路径范围放大多少倍”：
+ * - 1 表示不额外留白；
+ * - 1.2 表示路径只占视口中间约 83%，四周留出约 8.3% 的空白。
+ *
+ * @param paddingFactor 缓冲因子，必须大于 1 才会产生 padding。
+ * @param viewportWidthPx 视口宽度，单位像素。
+ * @param viewportHeightPx 视口高度，单位像素。
+ * @returns 以较短边计算得到的单边 padding，单位像素。
+ */
 function paddingFactorToPaddingPx(paddingFactor, viewportWidthPx, viewportHeightPx) {
     if (!Number.isFinite(paddingFactor) || paddingFactor <= 1) {
         return 0;
@@ -14,6 +33,17 @@ function paddingFactorToPaddingPx(paddingFactor, viewportWidthPx, viewportHeight
     const paddingRatio = (1 - 1 / paddingFactor) / 2;
     return Math.max(0, Math.min(viewportWidthPx, viewportHeightPx) * paddingRatio);
 }
+/**
+ * 优先调用原生模块计算适配一组坐标的推荐缩放级别。
+ *
+ * 原生侧通常能结合地图 SDK 的投影与缩放规则给出更接近真实显示效果的 zoom。
+ * 如果原生模块不可用或计算失败，返回 null，由上层使用纯 TS 估算逻辑兜底。
+ *
+ * @param points 路径点列表，每个点包含经纬度。
+ * @param options 选项对象，包含缓冲因子、视口宽度、视口高度、最小缩放级别、最大缩放级别。
+ * @defaultOptions 默认选项值。
+ * @returns 推荐缩放级别，可能为 null。
+ */
 function calculateFitZoom(points, options) {
     if (points.length === 0) {
         return null;
@@ -35,6 +65,14 @@ function calculateFitZoom(points, options) {
         return null;
     }
 }
+/**
+ * 估算路径的推荐缩放级别
+ * @param {number} latitudeDelta - 纬度跨度（度）
+ * @param {number} longitudeDelta - 经度跨度（度）
+ * @param {FitToCoordinatesOptions} options - 选项对象，包含最小缩放级别、最大缩放级别
+ * @defaultOptions 默认选项值
+ * @returns {number} - 推荐缩放级别
+ */
 export function estimateZoomLevel(latitudeDelta, longitudeDelta, options = {}) {
     // 使用经纬度跨度估算一个“足够看全路径”的缩放级别。
     // 这是高层 TS 兜底逻辑，不依赖具体原生 SDK 的 fitBounds 能力。
@@ -44,6 +82,17 @@ export function estimateZoomLevel(latitudeDelta, longitudeDelta, options = {}) {
     const maxZoom = options.maxZoom ?? MAX_ZOOM;
     return Math.max(minZoom, Math.min(maxZoom, Number(rawZoom.toFixed(2))));
 }
+/**
+ * 根据路径点计算地图展示所需的中心点、外接矩形、经纬度跨度和推荐缩放级别。
+ *
+ * 该函数会先统一坐标格式，再根据所有点的最南/北/东/西位置生成边界。
+ * recommendedZoom 优先使用原生计算结果，失败时退回到经纬度跨度估算。
+ *
+ * @param points 路径点列表，每个点包含经纬度。
+ * @param options 选项对象，包含缓冲因子、视口宽度、视口高度、最小缩放级别、最大缩放级别。
+ * @defaultOptions 默认选项值。
+ * @returns 推荐缩放级别，可能为 null。
+ */
 export function getRouteBounds(points, options = {}) {
     // 统一将路径点转换为对象坐标，再计算中心点、边界和推荐缩放。
     const normalized = normalizeLatLngList(points);
@@ -79,6 +128,15 @@ export function getRouteBounds(points, options = {}) {
         recommendedZoom: nativeZoom ?? fallbackZoom,
     };
 }
+/**
+ * 解析单个高德 polyline 环。
+ *
+ * 高德返回的 polyline 字符串通常为 `longitude,latitude;longitude,latitude`。
+ * 这里会忽略空片段和非法坐标，避免单个异常点导致整个边界解析失败。
+ *
+ * @param polyline 高德 polyline 字符串。
+ * @returns 解析后的 LatLng 点数组。
+ */
 function parsePolylineRing(polyline) {
     if (!polyline.trim()) {
         return [];
@@ -99,6 +157,15 @@ function parsePolylineRing(polyline) {
     })
         .filter((point) => point !== null);
 }
+/**
+ * 解析高德多环 polyline，并计算整体坐标边界。
+ *
+ * 常用于 AOI、行政区或多边形边界等场景。高德以 `|` 分隔多个环，
+ * 每个环内部再以 `;` 分隔坐标点。
+ *
+ * @param polyline 高德 polyline 字符串。
+ * @returns 解析后的 LatLng 点数组数组。
+ */
 export function parseMultiRingPolyline(polyline) {
     // 高德 AOI / 多边形边界常见格式为 ring1|ring2，
     // 这里按“外环/内环”统一拆成二维坐标数组。
@@ -124,6 +191,17 @@ export function parseMultiRingPolyline(polyline) {
         bounds,
     };
 }
+/**
+ * 将地图相机移动到能够完整展示指定坐标集合的位置。
+ *
+ * 单点场景直接定位到该点；多点场景会先计算路径边界，再移动到边界中心并应用推荐缩放。
+ * 默认会沿用当前相机的 bearing 和 tilt，除非调用方显式关闭 preserveBearing / preserveTilt。
+ *
+ * @param map 高德地图实例。
+ * @param points 路径点列表，每个点包含经纬度。
+ * @param options 选项对象，包含移动时间、缓冲因子、视口宽度、视口高度、最小缩放级别、最大缩放级别。
+ * @defaultOptions 默认选项值。
+ */
 export async function fitCameraToCoordinates(map, points, options = {}) {
     // 高层相机适配：
     // 1. 单点时直接移动到该点；
@@ -155,6 +233,12 @@ export async function fitCameraToCoordinates(map, points, options = {}) {
         tilt: options.preserveTilt === false ? options.tilt : currentCamera.tilt ?? options.tilt,
     }, options.duration ?? 0);
 }
+/**
+ * 将路径点转换为高德地图通用的西南/东北矩形边界。
+ *
+ * @param points 路径点列表，每个点包含经纬度。
+ * @returns 高德地图通用的西南/东北矩形边界。
+ */
 export function buildLatLngBounds(points) {
     const routeBounds = getRouteBounds(points);
     if (!routeBounds) {

package/build/utils/RouteUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouteUtils.js","sourceRoot":"","sources":["../../src/utils/RouteUtils.ts"],"names":[],"mappings":"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","sourcesContent":["import ExpoGaodeMapModule from '../ExpoGaodeMapModule';\nimport type { LatLng, LatLngBounds, LatLngPoint } from '../types/common.types';\nimport type {\n  FitToCoordinatesOptions,\n  FitToCoordinatesTarget,\n  MultiRingPolyline,\n  RouteBounds,\n} from '../types/route-playback.types';\nimport { normalizeLatLng, normalizeLatLngList } from './GeoUtils';\n\nconst MIN_ZOOM = 3;\nconst MAX_ZOOM = 20;\nconst DEFAULT_SINGLE_POINT_ZOOM = 16;\nconst DEFAULT_PADDING_FACTOR = 1.2;\nconst DEFAULT_VIEWPORT_WIDTH_PX = 390;\nconst DEFAULT_VIEWPORT_HEIGHT_PX = 844;\nconst DEFAULT_PADDING_PX = 48;\n\nfunction paddingFactorToPaddingPx(\n  paddingFactor: number,\n  viewportWidthPx: number,\n  viewportHeightPx: number\n): number {\n  if (!Number.isFinite(paddingFactor) || paddingFactor <= 1) {\n    return 0;\n  }\n  const paddingRatio = (1 - 1 / paddingFactor) / 2;\n  return Math.max(0, Math.min(viewportWidthPx, viewportHeightPx) * paddingRatio);\n}\n\nfunction calculateFitZoom(\n  points: LatLng[],\n  options: Pick<\n    FitToCoordinatesOptions,\n    'paddingFactor' | 'paddingPx' | 'viewportWidthPx' | 'viewportHeightPx' | 'minZoom' | 'maxZoom'\n  >\n): number | null {\n  if (points.length === 0) {\n    return null;\n  }\n\n  const viewportWidthPx = options.viewportWidthPx ?? DEFAULT_VIEWPORT_WIDTH_PX;\n  const viewportHeightPx = options.viewportHeightPx ?? DEFAULT_VIEWPORT_HEIGHT_PX;\n  const paddingFromFactor = paddingFactorToPaddingPx(\n    options.paddingFactor ?? DEFAULT_PADDING_FACTOR,\n    viewportWidthPx,\n    viewportHeightPx\n  );\n  const paddingPx = options.paddingPx ?? (paddingFromFactor > 0 ? paddingFromFactor : DEFAULT_PADDING_PX);\n\n  try {\n    return ExpoGaodeMapModule.calculateFitZoom(points, {\n      viewportWidthPx,\n      viewportHeightPx,\n      paddingPx,\n      minZoom: options.minZoom,\n      maxZoom: options.maxZoom,\n    });\n  } catch {\n    return null;\n  }\n}\n\nexport function estimateZoomLevel(\n  latitudeDelta: number,\n  longitudeDelta: number,\n  options: Pick<FitToCoordinatesOptions, 'minZoom' | 'maxZoom'> = {}\n): number {\n  // 使用经纬度跨度估算一个“足够看全路径”的缩放级别。\n  // 这是高层 TS 兜底逻辑，不依赖具体原生 SDK 的 fitBounds 能力。\n  const span = Math.max(latitudeDelta, longitudeDelta, 0.0001);\n  const rawZoom = Math.log2(360 / span);\n  const minZoom = options.minZoom ?? MIN_ZOOM;\n  const maxZoom = options.maxZoom ?? MAX_ZOOM;\n  return Math.max(minZoom, Math.min(maxZoom, Number(rawZoom.toFixed(2))));\n}\n\nexport function getRouteBounds(\n  points: LatLngPoint[],\n  options: Pick<\n    FitToCoordinatesOptions,\n    'paddingFactor' | 'paddingPx' | 'viewportWidthPx' | 'viewportHeightPx' | 'minZoom' | 'maxZoom'\n  > = {}\n): RouteBounds | null {\n  // 统一将路径点转换为对象坐标，再计算中心点、边界和推荐缩放。\n  const normalized = normalizeLatLngList(points) as LatLng[];\n  if (normalized.length === 0) {\n    return null;\n  }\n\n  const latitudes = normalized.map((point) => point.latitude);\n  const longitudes = normalized.map((point) => point.longitude);\n\n  const north = Math.max(...latitudes);\n  const south = Math.min(...latitudes);\n  const east = Math.max(...longitudes);\n  const west = Math.min(...longitudes);\n  const paddingFactor = options.paddingFactor ?? DEFAULT_PADDING_FACTOR;\n  const latitudeDelta = Math.max((north - south) * paddingFactor, 0.0001);\n  const longitudeDelta = Math.max((east - west) * paddingFactor, 0.0001);\n  const nativeZoom = calculateFitZoom(normalized, options);\n  const fallbackZoom = estimateZoomLevel(latitudeDelta, longitudeDelta, options);\n\n  return {\n    center: {\n      latitude: (north + south) / 2,\n      longitude: (east + west) / 2,\n    },\n    bounds: {\n      north,\n      south,\n      east,\n      west,\n    },\n    span: {\n      latitudeDelta,\n      longitudeDelta,\n    },\n    recommendedZoom: nativeZoom ?? fallbackZoom,\n  };\n}\n\nfunction parsePolylineRing(polyline: string): LatLng[] {\n  if (!polyline.trim()) {\n    return [];\n  }\n\n  return polyline\n    .split(';')\n    .map((segment) => segment.trim())\n    .filter(Boolean)\n    .map((segment) => {\n      const [longitude, latitude] = segment.split(',').map((value) => Number(value.trim()));\n      if (!Number.isFinite(longitude) || !Number.isFinite(latitude)) {\n        return null;\n      }\n\n      return {\n        latitude,\n        longitude,\n      };\n    })\n    .filter((point): point is LatLng => point !== null);\n}\n\nexport function parseMultiRingPolyline(polyline: string): MultiRingPolyline {\n  // 高德 AOI / 多边形边界常见格式为 ring1|ring2，\n  // 这里按“外环/内环”统一拆成二维坐标数组。\n  const rings = polyline\n    .split('|')\n    .map((ring) => parsePolylineRing(ring))\n    .filter((ring) => ring.length > 0);\n\n  const flattened = rings.flat();\n  const bounds = flattened.length\n    ? {\n        southwest: {\n          latitude: Math.min(...flattened.map((point) => point.latitude)),\n          longitude: Math.min(...flattened.map((point) => point.longitude)),\n        },\n        northeast: {\n          latitude: Math.max(...flattened.map((point) => point.latitude)),\n          longitude: Math.max(...flattened.map((point) => point.longitude)),\n        },\n      }\n    : null;\n\n  return {\n    rings,\n    bounds,\n  };\n}\n\nexport async function fitCameraToCoordinates(\n  map: FitToCoordinatesTarget,\n  points: LatLngPoint[],\n  options: FitToCoordinatesOptions = {}\n): Promise<void> {\n  // 高层相机适配：\n  // 1. 单点时直接移动到该点；\n  // 2. 多点时计算中心点与推荐缩放；\n  // 3. 尽量保留当前朝向和俯仰，避免突兀跳变。\n  const normalized = normalizeLatLngList(points) as LatLng[];\n  if (normalized.length === 0) {\n    return;\n  }\n\n  const currentCamera: Awaited<ReturnType<FitToCoordinatesTarget['getCameraPosition']>> =\n    await map.getCameraPosition().catch(() => ({}));\n\n  if (normalized.length === 1) {\n    const single = normalizeLatLng(normalized[0]);\n    await map.moveCamera(\n      {\n        target: single,\n        zoom: options.singlePointZoom ?? currentCamera.zoom ?? DEFAULT_SINGLE_POINT_ZOOM,\n        bearing: options.preserveBearing === false ? options.bearing : currentCamera.bearing ?? options.bearing,\n        tilt: options.preserveTilt === false ? options.tilt : currentCamera.tilt ?? options.tilt,\n      },\n      options.duration ?? 0\n    );\n    return;\n  }\n\n  const routeBounds = getRouteBounds(normalized, options);\n  if (!routeBounds) {\n    return;\n  }\n\n  await map.moveCamera(\n    {\n      target: routeBounds.center,\n      zoom: routeBounds.recommendedZoom,\n      bearing: options.preserveBearing === false ? options.bearing : currentCamera.bearing ?? options.bearing,\n      tilt: options.preserveTilt === false ? options.tilt : currentCamera.tilt ?? options.tilt,\n    },\n    options.duration ?? 0\n  );\n}\n\nexport function buildLatLngBounds(points: LatLngPoint[]): LatLngBounds | null {\n  const routeBounds = getRouteBounds(points);\n  if (!routeBounds) {\n    return null;\n  }\n\n  return {\n    southwest: {\n      latitude: routeBounds.bounds.south,\n      longitude: routeBounds.bounds.west,\n    },\n    northeast: {\n      latitude: routeBounds.bounds.north,\n      longitude: routeBounds.bounds.east,\n    },\n  };\n}\n"]}
+{"version":3,"file":"RouteUtils.js","sourceRoot":"","sources":["../../src/utils/RouteUtils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 路线与区域展示相关的工具函数。\n *\n * 本文件主要负责路径坐标的边界计算、推荐缩放级别估算、\n * 高德 polyline / 多环边界字符串解析，以及将地图相机移动到合适的展示范围。\n * 这些逻辑用于在 JS 层统一处理路线回放、区域遮罩和路径自适应视野等场景。\n */\nimport ExpoGaodeMapModule from '../ExpoGaodeMapModule';\nimport type { LatLng, LatLngBounds, LatLngPoint } from '../types/common.types';\nimport type {\n  FitToCoordinatesOptions,\n  FitToCoordinatesTarget,\n  MultiRingPolyline,\n  RouteBounds,\n} from '../types/route-playback.types';\nimport { normalizeLatLng, normalizeLatLngList } from './GeoUtils';\n\nconst MIN_ZOOM = 3; // 最小缩放级别\nconst MAX_ZOOM = 20; // 最大缩放级别\nconst DEFAULT_SINGLE_POINT_ZOOM = 16; // 默认单点缩放级别\nconst DEFAULT_PADDING_FACTOR = 1.2; // 默认缓冲因子\nconst DEFAULT_VIEWPORT_WIDTH_PX = 390; // 默认视口宽度（像素）\nconst DEFAULT_VIEWPORT_HEIGHT_PX = 844; // 默认视口高度（像素）\nconst DEFAULT_PADDING_PX = 48; // 默认缓冲值（像素）\n\n/**\n * 将缩放缓冲因子换算成地图四周需要预留的像素 padding。\n *\n * paddingFactor 表示“视野比实际路径范围放大多少倍”：\n * - 1 表示不额外留白；\n * - 1.2 表示路径只占视口中间约 83%，四周留出约 8.3% 的空白。\n *\n * @param paddingFactor 缓冲因子，必须大于 1 才会产生 padding。\n * @param viewportWidthPx 视口宽度，单位像素。\n * @param viewportHeightPx 视口高度，单位像素。\n * @returns 以较短边计算得到的单边 padding，单位像素。\n */\nfunction paddingFactorToPaddingPx(\n  paddingFactor: number,\n  viewportWidthPx: number,\n  viewportHeightPx: number\n): number {\n  if (!Number.isFinite(paddingFactor) || paddingFactor <= 1) {\n    return 0;\n  }\n  const paddingRatio = (1 - 1 / paddingFactor) / 2;\n  return Math.max(0, Math.min(viewportWidthPx, viewportHeightPx) * paddingRatio);\n}\n\n/**\n * 优先调用原生模块计算适配一组坐标的推荐缩放级别。\n *\n * 原生侧通常能结合地图 SDK 的投影与缩放规则给出更接近真实显示效果的 zoom。\n * 如果原生模块不可用或计算失败，返回 null，由上层使用纯 TS 估算逻辑兜底。\n *\n * @param points 路径点列表，每个点包含经纬度。\n * @param options 选项对象，包含缓冲因子、视口宽度、视口高度、最小缩放级别、最大缩放级别。\n * @defaultOptions 默认选项值。\n * @returns 推荐缩放级别，可能为 null。\n */\nfunction calculateFitZoom(\n  points: LatLng[],\n  options: Pick<\n    FitToCoordinatesOptions,\n    'paddingFactor' | 'paddingPx' | 'viewportWidthPx' | 'viewportHeightPx' | 'minZoom' | 'maxZoom'\n  >\n): number | null {\n  if (points.length === 0) {\n    return null;\n  }\n\n  const viewportWidthPx = options.viewportWidthPx ?? DEFAULT_VIEWPORT_WIDTH_PX;\n  const viewportHeightPx = options.viewportHeightPx ?? DEFAULT_VIEWPORT_HEIGHT_PX;\n  const paddingFromFactor = paddingFactorToPaddingPx(\n    options.paddingFactor ?? DEFAULT_PADDING_FACTOR,\n    viewportWidthPx,\n    viewportHeightPx\n  );\n  const paddingPx = options.paddingPx ?? (paddingFromFactor > 0 ? paddingFromFactor : DEFAULT_PADDING_PX);\n\n  try {\n    return ExpoGaodeMapModule.calculateFitZoom(points, {\n      viewportWidthPx,\n      viewportHeightPx,\n      paddingPx,\n      minZoom: options.minZoom,\n      maxZoom: options.maxZoom,\n    });\n  } catch {\n    return null;\n  }\n}\n\n/**\n * 估算路径的推荐缩放级别\n * @param {number} latitudeDelta - 纬度跨度（度）\n * @param {number} longitudeDelta - 经度跨度（度）\n * @param {FitToCoordinatesOptions} options - 选项对象，包含最小缩放级别、最大缩放级别\n * @defaultOptions 默认选项值\n * @returns {number} - 推荐缩放级别\n */\nexport function estimateZoomLevel(\n  latitudeDelta: number,\n  longitudeDelta: number,\n  options: Pick<FitToCoordinatesOptions, 'minZoom' | 'maxZoom'> = {}\n): number {\n  // 使用经纬度跨度估算一个“足够看全路径”的缩放级别。\n  // 这是高层 TS 兜底逻辑，不依赖具体原生 SDK 的 fitBounds 能力。\n  const span = Math.max(latitudeDelta, longitudeDelta, 0.0001);\n  const rawZoom = Math.log2(360 / span);\n  const minZoom = options.minZoom ?? MIN_ZOOM;\n  const maxZoom = options.maxZoom ?? MAX_ZOOM;\n  return Math.max(minZoom, Math.min(maxZoom, Number(rawZoom.toFixed(2))));\n}\n\n/**\n * 根据路径点计算地图展示所需的中心点、外接矩形、经纬度跨度和推荐缩放级别。\n *\n * 该函数会先统一坐标格式，再根据所有点的最南/北/东/西位置生成边界。\n * recommendedZoom 优先使用原生计算结果，失败时退回到经纬度跨度估算。\n * \n * @param points 路径点列表，每个点包含经纬度。\n * @param options 选项对象，包含缓冲因子、视口宽度、视口高度、最小缩放级别、最大缩放级别。\n * @defaultOptions 默认选项值。\n * @returns 推荐缩放级别，可能为 null。\n */\nexport function getRouteBounds(\n  points: LatLngPoint[],\n  options: Pick<\n    FitToCoordinatesOptions,\n    'paddingFactor' | 'paddingPx' | 'viewportWidthPx' | 'viewportHeightPx' | 'minZoom' | 'maxZoom'\n  > = {}\n): RouteBounds | null {\n  // 统一将路径点转换为对象坐标，再计算中心点、边界和推荐缩放。\n  const normalized = normalizeLatLngList(points) as LatLng[];\n  if (normalized.length === 0) {\n    return null;\n  }\n\n  const latitudes = normalized.map((point) => point.latitude);\n  const longitudes = normalized.map((point) => point.longitude);\n\n  const north = Math.max(...latitudes);\n  const south = Math.min(...latitudes);\n  const east = Math.max(...longitudes);\n  const west = Math.min(...longitudes);\n  const paddingFactor = options.paddingFactor ?? DEFAULT_PADDING_FACTOR;\n  const latitudeDelta = Math.max((north - south) * paddingFactor, 0.0001);\n  const longitudeDelta = Math.max((east - west) * paddingFactor, 0.0001);\n  const nativeZoom = calculateFitZoom(normalized, options);\n  const fallbackZoom = estimateZoomLevel(latitudeDelta, longitudeDelta, options);\n\n  return {\n    center: {\n      latitude: (north + south) / 2,\n      longitude: (east + west) / 2,\n    },\n    bounds: {\n      north,\n      south,\n      east,\n      west,\n    },\n    span: {\n      latitudeDelta,\n      longitudeDelta,\n    },\n    recommendedZoom: nativeZoom ?? fallbackZoom,\n  };\n}\n\n/**\n * 解析单个高德 polyline 环。\n *\n * 高德返回的 polyline 字符串通常为 `longitude,latitude;longitude,latitude`。\n * 这里会忽略空片段和非法坐标，避免单个异常点导致整个边界解析失败。\n * \n * @param polyline 高德 polyline 字符串。\n * @returns 解析后的 LatLng 点数组。\n */\nfunction parsePolylineRing(polyline: string): LatLng[] {\n  if (!polyline.trim()) {\n    return [];\n  }\n\n  return polyline\n    .split(';')\n    .map((segment) => segment.trim())\n    .filter(Boolean)\n    .map((segment) => {\n      const [longitude, latitude] = segment.split(',').map((value) => Number(value.trim()));\n      if (!Number.isFinite(longitude) || !Number.isFinite(latitude)) {\n        return null;\n      }\n\n      return {\n        latitude,\n        longitude,\n      };\n    })\n    .filter((point): point is LatLng => point !== null);\n}\n\n/**\n * 解析高德多环 polyline，并计算整体坐标边界。\n *\n * 常用于 AOI、行政区或多边形边界等场景。高德以 `|` 分隔多个环，\n * 每个环内部再以 `;` 分隔坐标点。\n * \n * @param polyline 高德 polyline 字符串。\n * @returns 解析后的 LatLng 点数组数组。\n */\nexport function parseMultiRingPolyline(polyline: string): MultiRingPolyline {\n  // 高德 AOI / 多边形边界常见格式为 ring1|ring2，\n  // 这里按“外环/内环”统一拆成二维坐标数组。\n  const rings = polyline\n    .split('|')\n    .map((ring) => parsePolylineRing(ring))\n    .filter((ring) => ring.length > 0);\n\n  const flattened = rings.flat();\n  const bounds = flattened.length\n    ? {\n        southwest: {\n          latitude: Math.min(...flattened.map((point) => point.latitude)),\n          longitude: Math.min(...flattened.map((point) => point.longitude)),\n        },\n        northeast: {\n          latitude: Math.max(...flattened.map((point) => point.latitude)),\n          longitude: Math.max(...flattened.map((point) => point.longitude)),\n        },\n      }\n    : null;\n\n  return {\n    rings,\n    bounds,\n  };\n}\n\n/**\n * 将地图相机移动到能够完整展示指定坐标集合的位置。\n *\n * 单点场景直接定位到该点；多点场景会先计算路径边界，再移动到边界中心并应用推荐缩放。\n * 默认会沿用当前相机的 bearing 和 tilt，除非调用方显式关闭 preserveBearing / preserveTilt。\n * \n * @param map 高德地图实例。\n * @param points 路径点列表，每个点包含经纬度。\n * @param options 选项对象，包含移动时间、缓冲因子、视口宽度、视口高度、最小缩放级别、最大缩放级别。\n * @defaultOptions 默认选项值。\n */\nexport async function fitCameraToCoordinates(\n  map: FitToCoordinatesTarget,\n  points: LatLngPoint[],\n  options: FitToCoordinatesOptions = {}\n): Promise<void> {\n  // 高层相机适配：\n  // 1. 单点时直接移动到该点；\n  // 2. 多点时计算中心点与推荐缩放；\n  // 3. 尽量保留当前朝向和俯仰，避免突兀跳变。\n  const normalized = normalizeLatLngList(points) as LatLng[];\n  if (normalized.length === 0) {\n    return;\n  }\n\n  const currentCamera: Awaited<ReturnType<FitToCoordinatesTarget['getCameraPosition']>> =\n    await map.getCameraPosition().catch(() => ({}));\n\n  if (normalized.length === 1) {\n    const single = normalizeLatLng(normalized[0]);\n    await map.moveCamera(\n      {\n        target: single,\n        zoom: options.singlePointZoom ?? currentCamera.zoom ?? DEFAULT_SINGLE_POINT_ZOOM,\n        bearing: options.preserveBearing === false ? options.bearing : currentCamera.bearing ?? options.bearing,\n        tilt: options.preserveTilt === false ? options.tilt : currentCamera.tilt ?? options.tilt,\n      },\n      options.duration ?? 0\n    );\n    return;\n  }\n\n  const routeBounds = getRouteBounds(normalized, options);\n  if (!routeBounds) {\n    return;\n  }\n\n  await map.moveCamera(\n    {\n      target: routeBounds.center,\n      zoom: routeBounds.recommendedZoom,\n      bearing: options.preserveBearing === false ? options.bearing : currentCamera.bearing ?? options.bearing,\n      tilt: options.preserveTilt === false ? options.tilt : currentCamera.tilt ?? options.tilt,\n    },\n    options.duration ?? 0\n  );\n}\n\n/**\n * 将路径点转换为高德地图通用的西南/东北矩形边界。\n * \n * @param points 路径点列表，每个点包含经纬度。\n * @returns 高德地图通用的西南/东北矩形边界。\n */\nexport function buildLatLngBounds(points: LatLngPoint[]): LatLngBounds | null {\n  const routeBounds = getRouteBounds(points);\n  if (!routeBounds) {\n    return null;\n  }\n\n  return {\n    southwest: {\n      latitude: routeBounds.bounds.south,\n      longitude: routeBounds.bounds.west,\n    },\n    northeast: {\n      latitude: routeBounds.bounds.north,\n      longitude: routeBounds.bounds.east,\n    },\n  };\n}\n"]}

package/build/utils/lazyNativeViewManager.d.ts

@@ -1,3 +1,6 @@
+/**
+ * 懒加载原生视图管理器
+ */
 import type { ComponentType } from 'react';
 export declare function createLazyNativeViewManager<Props extends object = Record<string, unknown>>(name: string): () => ComponentType<Props>;
 //# sourceMappingURL=lazyNativeViewManager.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"lazyNativeViewManager.d.ts","sourceRoot":"","sources":["../../src/utils/lazyNativeViewManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAG3C,wBAAgB,2BAA2B,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxF,IAAI,EAAE,MAAM,GACX,MAAM,aAAa,CAAC,KAAK,CAAC,CAS5B"}
+{"version":3,"file":"lazyNativeViewManager.d.ts","sourceRoot":"","sources":["../../src/utils/lazyNativeViewManager.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAG3C,wBAAgB,2BAA2B,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxF,IAAI,EAAE,MAAM,GACX,MAAM,aAAa,CAAC,KAAK,CAAC,CAS5B"}

package/build/utils/lazyNativeViewManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"lazyNativeViewManager.js","sourceRoot":"","sources":["../../src/utils/lazyNativeViewManager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,UAAU,2BAA2B,CACzC,IAAY;IAEZ,IAAI,MAAM,GAAgC,IAAI,CAAC;IAE/C,OAAO,GAAG,EAAE;QACV,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,wBAAwB,CAAQ,IAAI,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,MAAO,CAAC;IACjB,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import type { ComponentType } from 'react';\nimport { requireNativeViewManager } from 'expo-modules-core';\n\nexport function createLazyNativeViewManager<Props extends object = Record<string, unknown>>(\n  name: string\n): () => ComponentType<Props> {\n  let cached: ComponentType<Props> | null = null;\n\n  return () => {\n    if (!cached) {\n      cached = requireNativeViewManager<Props>(name);\n    }\n    return cached!;\n  };\n}\n"]}
+{"version":3,"file":"lazyNativeViewManager.js","sourceRoot":"","sources":["../../src/utils/lazyNativeViewManager.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,UAAU,2BAA2B,CACzC,IAAY;IAEZ,IAAI,MAAM,GAAgC,IAAI,CAAC;IAE/C,OAAO,GAAG,EAAE;QACV,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,wBAAwB,CAAQ,IAAI,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,MAAO,CAAC;IACjB,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * 懒加载原生视图管理器\n */\nimport type { ComponentType } from 'react';\nimport { requireNativeViewManager } from 'expo-modules-core';\n\nexport function createLazyNativeViewManager<Props extends object = Record<string, unknown>>(\n  name: string\n): () => ComponentType<Props> {\n  let cached: ComponentType<Props> | null = null;\n\n  return () => {\n    if (!cached) {\n      cached = requireNativeViewManager<Props>(name);\n    }\n    return cached!;\n  };\n}\n"]}

package/ios/modules/LocationManager.swift

@@ -101,10 +101,8 @@ class LocationManager: NSObject, AMapLocationManagerDelegate {
         ensureLocationManager()?.allowsBackgroundLocationUpdates = allows
     }
 
-    private func setReGeocodeLanguage(_ rawValue: AMapRegionLanguageType.RawValue) {
-        if let language = AMapRegionLanguageType(rawValue: rawValue) {
-            ensureLocationManager()?.reGeocodeLanguage = language
-        }
+    private func setReGeocodeLanguage(_ rawValue: Int) {
+        ensureLocationManager()?.setValue(rawValue, forKey: "reGeocodeLanguage")
     }
 
     func setGeoLanguage(_ language: String) {

package/ios/overlays/MarkerView.swift

@@ -736,36 +736,42 @@ class MarkerView: ExpoView {
         pendingUpdateTask?.cancel(); pendingUpdateTask = nil
         pendingSubviewRefreshTask?.cancel(); pendingSubviewRefreshTask = nil
 
-        guard let mapView = mapView else { 
-            isRemoving = false
-            return 
-        }
-        
-        // 确保在主线程执行移除操作
-        let cleanup = { [weak self, weak mapView] in
-            guard let self = self, let mapView = mapView else { return }
-            
-            // 1. 停止任何正在进行的平滑移动
-            if self.animatedAnnotation != nil {
-                self.stopSmoothMove()
-            }
-            
-            // 2. 移除普通标记点
-            if let annotation = self.annotation {
-                mapView.removeAnnotation(annotation)
-                self.annotation = nil
+        if Thread.isMainThread {
+            cleanupAnnotationFromMap()
+        } else {
+            DispatchQueue.main.sync {
+                cleanupAnnotationFromMap()
             }
+        }
+    }
+
+    private func cleanupAnnotationFromMap() {
+        defer { isRemoving = false }
+
+        guard let mapView = mapView else { return }
 
-            self.annotationView = nil
-            self.animatedAnnotationView = nil
-            self.isRemoving = false
+        if let animAnnotation = animatedAnnotation {
+            if let animations = animAnnotation.allMoveAnimations() {
+                for animation in animations {
+                    animation.cancel()
+                }
+            }
+            mapView.removeAnnotation(animAnnotation)
+            animatedAnnotation = nil
         }
 
-        if Thread.isMainThread {
-            cleanup()
-        } else {
-            DispatchQueue.main.async(execute: cleanup)
+        if let annotation = annotation {
+            mapView.removeAnnotation(annotation)
+            self.annotation = nil
         }
+
+        annotationView?.annotation = nil
+        animatedAnnotationView?.annotation = nil
+        annotationView = nil
+        animatedAnnotationView = nil
+        isAnimating = false
+        lastSetMapView = nil
+        self.mapView = nil
     }
 
     override func willRemoveSubview(_ subview: UIView) {
@@ -791,10 +797,12 @@ class MarkerView: ExpoView {
     }
 
     private func scheduleSubviewRefresh(allowFallbackToDefault: Bool) {
+        guard superview != nil else { return }
+
         pendingSubviewRefreshTask?.cancel()
 
         let task = DispatchWorkItem { [weak self] in
-            guard let self = self, !self.isRemoving else { return }
+            guard let self = self, !self.isRemoving, self.superview != nil else { return }
             self.refreshAnnotationForSubviewChanges(allowFallbackToDefault: allowFallbackToDefault)
         }
 
@@ -1273,11 +1281,17 @@ class MarkerView: ExpoView {
         pendingAddTask?.cancel()
         pendingUpdateTask?.cancel()
         pendingSubviewRefreshTask?.cancel()
+
+        if Thread.isMainThread {
+            cleanupAnnotationFromMap()
+        }
         
         // 清理引用，防止内存泄漏
         mapView = nil
         annotation = nil
         annotationView = nil
+        animatedAnnotation = nil
+        animatedAnnotationView = nil
         lastSetMapView = nil
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-gaode-map",
-  "version": "2.2.34",
+  "version": "2.2.35-next.1",
   "description": "A full-featured React Native AMap (Gaode Map) library for Expo, including map display, location, overlays, offline maps, and geometry utilities.",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -19,7 +19,7 @@
     "build:plugin": "tsc --project plugin/tsconfig.json",
     "clean": "expo-module clean && rm -rf plugin/build",
     "lint": "expo-module lint",
-    "test": "expo-module test",
+    "test": "npx jest --no-watchman --config jest.config.js --runInBand",
     "prepare": "expo-module prepare && yarn build:plugin",
     "postinstall": "node scripts/check-expo-modules.js",
     "prepublishOnly": "echo 'Skipping proofread check' && exit 0",
@@ -35,12 +35,17 @@
     "expo-gaode-map",
     "ExpoGaodeMap",
     "expo-amap",
+    "expo-map",
     "react-native-amap",
+    "react-native-amap3d",
     "react-native-gaode-map",
     "rn-amap",
     "rn-gaode-map",
     "gaode-map",
+    "gaode",
     "amap",
+    "amap3d",
+    "china-map",
     "高德地图",
     "地图",
     "mapview",