expo-gaode-map-navigation 2.0.12 → 2.0.13

package/README.md

@@ -5,6 +5,7 @@
 ## 特性
 
 - 🗺️ **地图渲染**：内置完整地图能力，支持 Marker、Polyline、Polygon、Circle、Cluster、HeatMap 等覆盖物。
+- 🔍 **原生搜索**：内置 POI 搜索、周边搜索、沿途搜索、输入提示、逆地理编码等搜索能力。
 - 🚗 **多模式路径规划**：支持驾车、步行、骑行、电动车、货车、摩托车等多种出行方式。
 - 🧭 **实时导航 UI**：提供 `NaviView` 官方嵌入视图，并暴露完整事件与原生参数，方便你自行定制导航界面。
 - 🛣️ **独立路径规划**：支持“先算路、再导航”的高级模式，可实现多路线对比与选择。
@@ -13,7 +14,7 @@
 
 ## 安装
 
-本模块已包含地图与导航的所有能力，**不需要**、也不应同时安装 `expo-gaode-map`。
+本模块已包含地图、搜索与导航能力，**不需要**、也不应同时安装 `expo-gaode-map` 或 `expo-gaode-map-search`。
 
 ```bash
 # bun
@@ -29,6 +30,10 @@ npm install expo-gaode-map-navigation
 **⚠️ 重要提示：**
 如果项目中已安装 `expo-gaode-map`，请务必先卸载，否则会导致 Android 端二进制冲突（`3dmap` vs `navi-3dmap`）。`expo-gaode-map` 和 `expo-gaode-map-navigation` 由于 SDK 冲突不能同时安装，二选一使用。
 
+`expo-gaode-map-search` 的独立集成只维护到 `2.2.33`。从下个版本开始，搜索能力随 `expo-gaode-map` / `expo-gaode-map-navigation` 一起维护；在导航包中请直接从 `expo-gaode-map-navigation` 导入搜索 API。
+
+高德官方 Android SDK 在 `10.0.700` 之后将远程依赖由“地图 + 定位”调整为“地图 + 定位 + 搜索”，依赖地址从 `com.amap.api:3dmap:latest.integration` 调整为 `com.amap.api:3dmap-location-search:latest.integration`。继续单独维护 search 模块会带来重复合包和依赖冲突成本，因此搜索能力改为随 core / navigation 一起维护。
+
 > ⚠️ **版本兼容性说明**：
 > - 如果你的项目使用 **Expo SDK 54 及以上**，请安装 默认的 版本。
 > - 如果你的项目使用 **Expo SDK 53 及以下**（如 50, 51, 52, 53），请使用 **V1** 版本（Tag: `v1`）。
@@ -643,7 +648,7 @@ const result = await calculateTransitRoute({
 
 - [在线文档](https://tomwq.github.io/expo-gaode-map/api/navigation.html)
 - [GitHub 仓库](https://github.com/TomWq/expo-gaode-map/packages/navigation)
-- [示例项目(导航)](https://github.com/TomWq/expo-gaode-map-navigation-example)
+- [导航示例工程](../../example-navigation)
 - [高德地图开放平台](https://lbs.amap.com/)
 - [Expo Modules API](https://docs.expo.dev/modules/overview/)
 

package/android/build.gradle

@@ -1,7 +1,7 @@
 apply plugin: 'com.android.library'
 
 group = 'expo.modules.gaodemap.navigation'
-version = '2.0.0'
+version = '2.0.13'
 
 def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
 apply from: expoModulesCorePlugin
@@ -34,7 +34,7 @@ android {
   namespace "expo.modules.gaodemap.navigation"
   defaultConfig {
     versionCode 1
-    versionName "2.0.0"
+    versionName "2.0.13"
   }
   lintOptions {
     abortOnError false
@@ -60,10 +60,14 @@ dependencies {
             implementation files(sdkFile)
         } else {
             println "ExpoGaodeMapNavigation: Custom SDK path configured but file not found, falling back to Maven dependency."
-            implementation 'com.amap.api:navi-3dmap:latest.integration'
+            implementation 'com.amap.api:navi-3dmap-location-search:10.1.600_3dmap10.1.600_loc6.5.1_sea9.7.4'
+
         }
     } else {
-        implementation 'com.amap.api:navi-3dmap:latest.integration'
+        // 10.1.600 is the last Android 3D map SDK line that supports offline
+        // map downloads without the separate 11.x offline-download permission.
+        implementation 'com.amap.api:navi-3dmap-location-search:10.1.600_3dmap10.1.600_loc6.5.1_sea9.7.4'
+
     }
 
     // Live Update APIs on NotificationCompat.Builder

package/android/src/main/AndroidManifest.xml

@@ -21,4 +21,12 @@
     <!-- 蓝牙权限 - 用于室内定位 (可选) -->
     <uses-permission android:name="android.permission.BLUETOOTH" />
     <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+
+    <application>
+        <!-- 高德 3D 地图 SDK 官方离线地图 UI 组件 -->
+        <activity
+            android:name="com.amap.api.maps.offlinemap.OfflineMapActivity"
+            android:screenOrientation="portrait"
+            android:exported="false" />
+    </application>
 </manifest>

package/android/src/main/java/expo/modules/gaodemap/map/ExpoGaodeMapOfflineModule.kt

@@ -1,14 +1,19 @@
 package expo.modules.gaodemap.map
 
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
 import android.os.Bundle
 import android.os.StatFs
 import android.os.Environment
 import android.util.Log
+import com.amap.api.maps.offlinemap.OfflineMapActivity
 import com.amap.api.maps.offlinemap.OfflineMapCity
 import com.amap.api.maps.offlinemap.OfflineMapManager
 import com.amap.api.maps.offlinemap.OfflineMapProvince
 import com.amap.api.maps.offlinemap.OfflineMapStatus
 import expo.modules.gaodemap.map.modules.SDKInitializer
+import expo.modules.kotlin.exception.CodedException
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 
@@ -92,12 +97,18 @@ class ExpoGaodeMapOfflineModule : Module() {
       offlineMapManager = null
       downloadingCities.clear()
     }
+
+    AsyncFunction("openOfflineMapUI") {
+      openOfflineMapUI()
+    }
     
     // ==================== 地图列表管理 ====================
     
     AsyncFunction("getAvailableCities") {
-      val cities = getOfflineMapManager()?.offlineMapCityList ?: emptyList()
-      cities.map { city -> convertCityToMap(city) }
+      val manager = getOfflineMapManager()
+      val cities = manager?.offlineMapCityList ?: emptyList()
+      val downloadedCityKeys = getDownloadedCityKeys(manager)
+      cities.map { city -> convertCityToMap(city, downloadedCityKeys) }
     }
     
     AsyncFunction("getAvailableProvinces") {
@@ -106,15 +117,19 @@ class ExpoGaodeMapOfflineModule : Module() {
     }
     
     AsyncFunction("getCitiesByProvince") { provinceCode: String ->
-      val province = getOfflineMapManager()?.offlineMapProvinceList?.find {
-        it.provinceCode == provinceCode 
+      val manager = getOfflineMapManager()
+      val province = manager?.offlineMapProvinceList?.find {
+        it.provinceCode == provinceCode
       }
-      province?.cityList?.map { city -> convertCityToMap(city) } ?: emptyList()
+      val downloadedCityKeys = getDownloadedCityKeys(manager)
+      province?.cityList?.map { city -> convertCityToMap(city, downloadedCityKeys) } ?: emptyList()
     }
     
     AsyncFunction("getDownloadedMaps") {
-      val cities = getOfflineMapManager()?.downloadOfflineMapCityList ?: emptyList()
-      cities.map { city -> convertCityToMap(city) }
+      val manager = getOfflineMapManager()
+      val cities = manager?.downloadOfflineMapCityList ?: emptyList()
+      val downloadedCityKeys = getDownloadedCityKeys(manager)
+      cities.map { city -> convertCityToMap(city, downloadedCityKeys) }
     }
     
     // ==================== 下载管理 ====================
@@ -208,14 +223,17 @@ class ExpoGaodeMapOfflineModule : Module() {
     // ==================== 状态查询 ====================
     
     AsyncFunction("isMapDownloaded") { cityCode: String ->
-      val city = getOfflineMapManager()?.getItemByCityCode(cityCode)
-      city?.state == OfflineMapStatus.SUCCESS || 
-      city?.state == OfflineMapStatus.CHECKUPDATES
+      val manager = getOfflineMapManager()
+      val city = manager?.getItemByCityCode(cityCode)
+      city?.state == OfflineMapStatus.SUCCESS ||
+        city?.let { isDownloadedCity(it, getDownloadedCityKeys(manager)) } == true
     }
     
     AsyncFunction("getMapStatus") { cityCode: String ->
-      val city = getOfflineMapManager()?.getItemByCityCode(cityCode)
-      city?.let { convertCityToMap(it) } ?: Bundle()
+      val manager = getOfflineMapManager()
+      val city = manager?.getItemByCityCode(cityCode)
+      val downloadedCityKeys = getDownloadedCityKeys(manager)
+      city?.let { convertCityToMap(it, downloadedCityKeys) } ?: Bundle()
     }
     
     AsyncFunction("getTotalProgress") {
@@ -463,13 +481,37 @@ class ExpoGaodeMapOfflineModule : Module() {
   /**
    * 转换城市对象为 Map
    */
-  private fun convertCityToMap(city: OfflineMapCity): Bundle {
+  private fun getDownloadedCityKeys(manager: OfflineMapManager?): Set<String> {
+    return manager?.downloadOfflineMapCityList
+      ?.flatMap { getCityIdentityKeys(it) }
+      ?.toSet()
+      ?: emptySet()
+  }
+
+  private fun getCityIdentityKeys(city: OfflineMapCity): List<String> {
+    return listOfNotNull(
+      city.code?.trim()?.takeIf { it.isNotEmpty() }?.let { "code:$it" },
+      city.adcode?.trim()?.takeIf { it.isNotEmpty() }?.let { "adcode:$it" },
+      city.city?.trim()?.takeIf { it.isNotEmpty() }?.let { "name:$it" }
+    )
+  }
+
+  private fun isDownloadedCity(city: OfflineMapCity, downloadedCityKeys: Set<String>): Boolean {
+    return getCityIdentityKeys(city).any { downloadedCityKeys.contains(it) }
+  }
+
+  private fun convertCityToMap(
+    city: OfflineMapCity,
+    downloadedCityKeys: Set<String> = emptySet()
+  ): Bundle {
     val isPaused = synchronized(lock) { pausedCities.contains(city.code) }
     val isDownloading = synchronized(lock) { downloadingCities.contains(city.code) }
+    val isDownloaded = isDownloadedCity(city, downloadedCityKeys)
     
     val status = when {
       isPaused -> "paused"
       isDownloading -> "downloading"
+      isDownloaded -> "downloaded"
       else -> getStatusString(city.state)
     }
     
@@ -501,8 +543,9 @@ class ExpoGaodeMapOfflineModule : Module() {
   }
   
   /**
-   * 获取状态字符串
-   * 注意：只有 SUCCESS 状态才表示真正下载完成
+   * 获取状态字符串。
+   * CHECKUPDATES / NEW_VERSION 在 10.1.600 冷启动时可能出现在普通城市列表,
+   * 不能单独作为已下载依据；已下载状态以 downloadOfflineMapCityList 为准。
    */
   private fun getStatusString(state: Int): String {
     return when (state) {
@@ -558,4 +601,29 @@ class ExpoGaodeMapOfflineModule : Module() {
       null
     }
   }
+
+  private fun getActivityLaunchContext(): Context {
+    return appContext.currentActivity
+      ?: appContext.reactContext
+      ?: throw CodedException("NO_CONTEXT", "React context not available", null)
+  }
+
+  private fun openOfflineMapUI() {
+    val context = getActivityLaunchContext()
+    SDKInitializer.restorePersistedState(context.applicationContext)
+
+    if (!SDKInitializer.isPrivacyReady()) {
+      throw CodedException(
+        "PRIVACY_NOT_AGREED",
+        "隐私协议未完成确认，请先调用 setPrivacyConfig",
+        null
+      )
+    }
+
+    val intent = Intent(context, OfflineMapActivity::class.java)
+    if (context !is Activity) {
+      intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+    }
+    context.startActivity(intent)
+  }
 }

package/android/src/main/java/expo/modules/gaodemap/map/ExpoGaodeMapView.kt

@@ -150,6 +150,7 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
     // 缓存初始相机位置，等待地图加载完成后设置
     private var pendingCameraPosition: Map<String, Any?>? = null
     private var isMapLoaded = false
+    private var hasAppliedInitialCameraPosition = false
 
     init {
         try {
@@ -192,7 +193,7 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
 
                 val positionToApply = initialCameraPosition ?: pendingCameraPosition
                 positionToApply?.let { position ->
-                    applyInitialCameraPosition(position)
+                    applyInitialCameraPositionIfNeeded(position)
                     pendingCameraPosition = null
                 }
 
@@ -351,10 +352,14 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
     fun setInitialCameraPosition(position: Map<String, Any?>) {
         initialCameraPosition = position
 
+        if (hasAppliedInitialCameraPosition) {
+            return
+        }
+
         // 如果地图已加载,立即应用;否则缓存等待地图加载完成
         if (isMapLoaded) {
             mainHandler.post {
-                applyInitialCameraPosition(position)
+                applyInitialCameraPositionIfNeeded(position)
             }
         } else {
             pendingCameraPosition = position
@@ -365,8 +370,12 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
      * 实际应用相机位置
      * @param position 相机位置配置
      */
-    private fun applyInitialCameraPosition(position: Map<String, Any?>) {
+    private fun applyInitialCameraPositionIfNeeded(position: Map<String, Any?>) {
+        if (hasAppliedInitialCameraPosition) {
+            return
+        }
         cameraManager.setInitialCameraPosition(position)
+        hasAppliedInitialCameraPosition = true
     }
 
     // ==================== UI 控件和手势 ====================
@@ -643,6 +652,7 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
 
             // 销毁地图实例
             mapView.onDestroy()
+            hasAppliedInitialCameraPosition = false
         } catch (e: Exception) {
             // 静默处理异常,确保销毁流程不会中断
             android.util.Log.e("ExpoGaodeMapView", "Error destroying map", e)

package/android/src/main/java/expo/modules/gaodemap/map/managers/UIManager.kt

@@ -87,36 +87,46 @@ class UIManager(private val aMap: AMap, private val context: Context) : Location
   // ==================== 图层显示 ====================
   
   private var currentLocationStyle: MyLocationStyle? = null
+  private var currentFollowUserLocation: Boolean = false
+  private var explicitLocationType: Int? = null
+
+  private fun parseLocationType(locationType: String): Int? {
+    return when (locationType) {
+      "SHOW" -> MyLocationStyle.LOCATION_TYPE_SHOW
+      "LOCATE" -> MyLocationStyle.LOCATION_TYPE_LOCATE
+      "FOLLOW" -> MyLocationStyle.LOCATION_TYPE_FOLLOW
+      "MAP_ROTATE" -> MyLocationStyle.LOCATION_TYPE_MAP_ROTATE
+      "LOCATION_ROTATE" -> MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE
+      "LOCATION_ROTATE_NO_CENTER" -> MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE_NO_CENTER
+      "FOLLOW_NO_CENTER" -> MyLocationStyle.LOCATION_TYPE_FOLLOW_NO_CENTER
+      "MAP_ROTATE_NO_CENTER" -> MyLocationStyle.LOCATION_TYPE_MAP_ROTATE_NO_CENTER
+      else -> null
+    }
+  }
+
+  private fun resolveLocationType(followUserLocation: Boolean): Int {
+    explicitLocationType?.let { return it }
+    return if (followUserLocation) {
+      MyLocationStyle.LOCATION_TYPE_FOLLOW
+    } else {
+      MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE_NO_CENTER
+    }
+  }
   
   /**
    * 设置是否显示用户位置
    */
   fun setShowsUserLocation(show: Boolean, followUserLocation: Boolean = false) {
+    currentFollowUserLocation = followUserLocation
     if (show) {
-      // 创建默认的定位样式
       if (currentLocationStyle == null) {
-        currentLocationStyle = MyLocationStyle().apply {
-          // 根据是否跟随设置定位类型
-          val locationType = if (followUserLocation) {
-            MyLocationStyle.LOCATION_TYPE_FOLLOW  // 连续定位并跟随
-          } else {
-            MyLocationStyle.LOCATION_TYPE_SHOW  // 只显示定位点，不跟随
-          }
-          myLocationType(locationType)
-          interval(2000)  // 2秒定位一次
-          showMyLocation(true)
-        }
-      } else {
-        // 更新定位类型
-        val locationType = if (followUserLocation) {
-          MyLocationStyle.LOCATION_TYPE_FOLLOW
-        } else {
-          MyLocationStyle.LOCATION_TYPE_SHOW
-        }
-        currentLocationStyle?.apply {
-          myLocationType(locationType)
-          interval(2000)
-        }
+        currentLocationStyle = MyLocationStyle()
+      }
+
+      currentLocationStyle?.apply {
+        myLocationType(resolveLocationType(followUserLocation))
+        interval(2000)  // 2秒定位一次
+        showMyLocation(true)
       }
       
       // 监听定位变化（用于通知 React Native）
@@ -171,9 +181,10 @@ class UIManager(private val aMap: AMap, private val context: Context) : Location
    */
   @SuppressLint("DiscouragedApi")
   fun setUserLocationRepresentation(config: Map<String, Any>) {
+    explicitLocationType = (config["locationType"] as? String)?.let(::parseLocationType)
+
     if (currentLocationStyle == null) {
       currentLocationStyle = MyLocationStyle().apply {
-        myLocationType(MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE)
         interval(2000)
         showMyLocation(true)
       }
@@ -182,21 +193,7 @@ class UIManager(private val aMap: AMap, private val context: Context) : Location
     val style = currentLocationStyle!!
     
     // 定位蓝点展现模式 (locationType) - Android 支持8种模式
-    val locationType = config["locationType"] as? String
-    if (locationType != null) {
-      val locationTypeValue = when (locationType) {
-        "SHOW" -> MyLocationStyle.LOCATION_TYPE_SHOW
-        "LOCATE" -> MyLocationStyle.LOCATION_TYPE_LOCATE
-        "FOLLOW" -> MyLocationStyle.LOCATION_TYPE_FOLLOW
-        "MAP_ROTATE" -> MyLocationStyle.LOCATION_TYPE_MAP_ROTATE
-        "LOCATION_ROTATE" -> MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE
-        "LOCATION_ROTATE_NO_CENTER" -> MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE_NO_CENTER
-        "FOLLOW_NO_CENTER" -> MyLocationStyle.LOCATION_TYPE_FOLLOW_NO_CENTER
-        "MAP_ROTATE_NO_CENTER" -> MyLocationStyle.LOCATION_TYPE_MAP_ROTATE_NO_CENTER
-        else -> MyLocationStyle.LOCATION_TYPE_LOCATION_ROTATE // 默认值
-      }
-      style.myLocationType(locationTypeValue)
-    }
+    style.myLocationType(resolveLocationType(currentFollowUserLocation))
     
     // 是否显示定位蓝点 (showMyLocation) - Android 5.1.0+ 支持
     // 注意：这个属性在 iOS 中没有对应项，是 Android 特有的

package/android/src/main/java/expo/modules/gaodemap/map/overlays/ClusterView.kt

@@ -141,8 +141,11 @@ class ClusterView(context: Context, appContext: AppContext) : ExpoView(context,
    * 设置最小聚合数量
    */
   fun setMinClusterSize(size: Int) {
-    Log.d("ClusterView", "setMinClusterSize: $size")
-    minClusterSize = size
+    val nextSize = size.coerceAtLeast(1)
+    if (minClusterSize != nextSize) {
+      minClusterSize = nextSize
+      styleChanged = true
+    }
     updateClusters()
   }
   

package/android/src/main/java/expo/modules/gaodemap/map/overlays/HeatMapView.kt

@@ -1,21 +1,27 @@
 package expo.modules.gaodemap.map.overlays
 
 import android.content.Context
+import android.graphics.Color
 import android.os.Looper
 import android.util.Log
 import com.amap.api.maps.AMap
+import com.amap.api.maps.CameraUpdateFactory
+import com.amap.api.maps.model.Gradient
+import com.amap.api.maps.model.HeatmapTileProvider
 import com.amap.api.maps.model.LatLng
 import com.amap.api.maps.model.TileOverlay
 import com.amap.api.maps.model.TileOverlayOptions
-import com.amap.api.maps.model.HeatmapTileProvider
-import com.amap.api.maps.CameraUpdateFactory
+import com.amap.api.maps.model.WeightedLatLng
 import expo.modules.kotlin.AppContext
 import expo.modules.kotlin.views.ExpoView
+import expo.modules.gaodemap.map.utils.LatLngParser
 import java.util.concurrent.ExecutorService
 import java.util.concurrent.Executors
-import expo.modules.gaodemap.map.utils.LatLngParser
 
 class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
+  private companion object {
+    const val TAG = "HeatMapView"
+  }
   
   private val executor: ExecutorService = Executors.newSingleThreadExecutor()
   private val applyUpdateRunnable = Runnable { applyUpdateOnMain() }
@@ -25,9 +31,10 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
 
   private var heatmapOverlay: TileOverlay? = null
   private var aMap: AMap? = null
-  private var dataList: MutableList<LatLng> = mutableListOf()
+  private var dataList: MutableList<WeightedLatLng> = mutableListOf()
   private var radius: Int = 50
   private var opacity: Double = 0.6
+  private var gradient: Gradient? = null
   
   /**
    * 设置地图实例
@@ -36,6 +43,7 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
   fun setMap(map: AMap) {
     aMap = map
     needsRebuild = true
+    Log.d(TAG, "setMap: map attached")
     scheduleUpdate()
   }
   
@@ -46,7 +54,8 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
    */
   fun setData(data: List<Any>?) {
     dataList.clear()
-    dataList.addAll(LatLngParser.parseLatLngList(data))
+    dataList.addAll(parseWeightedLatLngList(data))
+    Log.d(TAG, "setData: raw=${data?.size ?: 0}, parsed=${dataList.size}, ${formatPointStats(dataList)}")
     needsRebuild = true
     scheduleUpdate()
   }
@@ -56,6 +65,7 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
    */
   fun setRadius(radiusValue: Int) {
     radius = radiusValue
+    Log.d(TAG, "setRadius: $radiusValue")
     needsRebuild = true
     scheduleUpdate()
   }
@@ -65,10 +75,20 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
    */
   fun setOpacity(opacityValue: Double) {
     opacity = opacityValue
-    applyOverlayOpacity()
+    Log.d(TAG, "setOpacity: $opacityValue")
+    needsRebuild = true
+    scheduleUpdate()
+  }
+
+  fun setGradient(gradientValue: Map<String, Any>?) {
+    gradient = parseGradient(gradientValue)
+    Log.d(TAG, "setGradient: hasGradient=${gradient != null}, raw=${gradientValue != null}")
+    needsRebuild = true
+    scheduleUpdate()
   }
 
   fun setVisible(visibleValue: Boolean) {
+    Log.d(TAG, "setVisible: $visibleValue, points=${dataList.size}, hasOverlay=${heatmapOverlay != null}, needsRebuild=$needsRebuild")
     if (!visibleValue) {
       visible = false
       updateToken += 1
@@ -95,6 +115,7 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
   private fun scheduleUpdate() {
     updateToken += 1
     removeCallbacks(applyUpdateRunnable)
+    Log.d(TAG, "scheduleUpdate: token=$updateToken, mapAttached=${aMap != null}, visible=$visible, points=${dataList.size}")
     postDelayed(applyUpdateRunnable, 32)
   }
 
@@ -142,8 +163,11 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
     val map = aMap ?: return
     val token = updateToken
     val pointsSnapshot = ArrayList(dataList)
+    val latLngSnapshot = pointsSnapshot.map { it.latLng }
     val radiusValue = radius.coerceIn(10, 200)
     val opacityValue = opacity.coerceIn(0.0, 1.0)
+    val gradientValue = gradient
+    Log.d(TAG, "applyUpdate: token=$token, visible=$visible, points=${pointsSnapshot.size}, radius=$radiusValue, opacity=$opacityValue, gradient=${gradientValue != null}, ${formatPointStats(pointsSnapshot)}")
 
     if (!visible) {
       applyOverlayVisibility()
@@ -151,6 +175,7 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
     }
 
     if (pointsSnapshot.isEmpty()) {
+      Log.w(TAG, "applyUpdate: no valid heatmap points, removing overlay")
       heatmapOverlay?.remove()
       heatmapOverlay = null
       return
@@ -164,19 +189,25 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
 
     executor.execute {
       try {
-        val provider = HeatmapTileProvider.Builder()
-          .data(pointsSnapshot)
+        val builder = HeatmapTileProvider.Builder()
+          .data(latLngSnapshot)
           .radius(radiusValue)
-          .build()
+
+        gradientValue?.let { builder.gradient(it) }
+
+        val provider = builder.build()
 
         post {
           if (token != updateToken) {
+            Log.d(TAG, "addOverlay skipped: stale token=$token, current=$updateToken")
             return@post
           }
           if (aMap !== map) {
+            Log.d(TAG, "addOverlay skipped: map instance changed")
             return@post
           }
           if (!visible) {
+            Log.d(TAG, "addOverlay skipped: hidden")
             return@post
           }
 
@@ -200,9 +231,10 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
           applyOverlayVisibility()
           applyOverlayOpacity()
           forceRefresh()
+          Log.i(TAG, "addOverlay success: id=${runCatching { heatmapOverlay?.id }.getOrNull()}, points=${pointsSnapshot.size}, radius=$radiusValue, opacity=$opacityValue")
         }
       } catch (t: Throwable) {
-        Log.e("HeatMapView", "Failed to build heatmap", t)
+        Log.e(TAG, "Failed to build heatmap", t)
       }
     }
   }
@@ -217,11 +249,91 @@ class HeatMapView(context: Context, appContext: AppContext) : ExpoView(context,
   fun removeHeatMap() {
     updateToken += 1
     removeCallbacks(applyUpdateRunnable)
+    Log.d(TAG, "removeHeatMap")
     heatmapOverlay?.remove()
     heatmapOverlay = null
     dataList.clear()
     needsRebuild = true
   }
+
+  private fun parseWeightedLatLngList(data: Any?): List<WeightedLatLng> {
+    if (data == null || data !is List<*>) return emptyList()
+
+    val result = mutableListOf<WeightedLatLng>()
+    for (item in data) {
+      val point = parseWeightedLatLng(item)
+      if (point != null) {
+        result.add(point)
+      } else if (item is List<*>) {
+        result.addAll(parseWeightedLatLngList(item))
+      }
+    }
+    return result
+  }
+
+  private fun parseWeightedLatLng(data: Any?): WeightedLatLng? {
+    val latLng = LatLngParser.parseLatLng(data) ?: return null
+    val intensity = when (data) {
+      is Map<*, *> -> listOf(data["intensity"], data["weight"], data["count"], data["value"])
+        .firstOrNull { it is Number }
+      is List<*> -> data.getOrNull(2)
+      else -> null
+    }
+    val weight = ((intensity as? Number)?.toDouble() ?: 1.0).takeIf { it.isFinite() && it > 0.0 } ?: 1.0
+    return WeightedLatLng(latLng, weight)
+  }
+
+  private fun parseGradient(gradientValue: Map<String, Any>?): Gradient? {
+    if (gradientValue == null) return null
+    val rawColors = gradientValue["colors"] as? List<*> ?: return null
+    val rawStartPoints = gradientValue["startPoints"] as? List<*> ?: return null
+    if (rawColors.size < 2 || rawColors.size != rawStartPoints.size) {
+      Log.w(TAG, "parseGradient ignored: colors=${rawColors.size}, startPoints=${rawStartPoints.size}")
+      return null
+    }
+
+    val colors = IntArray(rawColors.size)
+    val startPoints = FloatArray(rawStartPoints.size)
+    for (index in rawColors.indices) {
+      val color = parseColor(rawColors[index]) ?: run {
+        Log.w(TAG, "parseGradient ignored: invalid color at index=$index, value=${rawColors[index]}")
+        return null
+      }
+      val startPoint = (rawStartPoints[index] as? Number)?.toFloat() ?: run {
+        Log.w(TAG, "parseGradient ignored: invalid startPoint at index=$index, value=${rawStartPoints[index]}")
+        return null
+      }
+      colors[index] = color
+      startPoints[index] = startPoint.coerceIn(0f, 1f)
+    }
+    return Gradient(colors, startPoints)
+  }
+
+  private fun parseColor(value: Any?): Int? {
+    return when (value) {
+      is Number -> value.toInt()
+      is String -> runCatching { Color.parseColor(value) }.getOrNull()
+      else -> null
+    }
+  }
+
+  private fun formatPointStats(points: List<WeightedLatLng>): String {
+    if (points.isEmpty()) return "bounds=empty"
+    var minLat = Double.POSITIVE_INFINITY
+    var maxLat = Double.NEGATIVE_INFINITY
+    var minLng = Double.POSITIVE_INFINITY
+    var maxLng = Double.NEGATIVE_INFINITY
+    var totalIntensity = 0.0
+    points.forEach { point ->
+      val latLng: LatLng = point.latLng
+      minLat = minOf(minLat, latLng.latitude)
+      maxLat = maxOf(maxLat, latLng.latitude)
+      minLng = minOf(minLng, latLng.longitude)
+      maxLng = maxOf(maxLng, latLng.longitude)
+      totalIntensity += point.intensity
+    }
+    return "bounds=[$minLat,$minLng]-[$maxLat,$maxLng], totalIntensity=$totalIntensity"
+  }
   
   override fun onDetachedFromWindow() {
     super.onDetachedFromWindow()