expo-gaode-map-navigation 2.0.5 → 2.0.6-next.0

package/README.md

@@ -9,7 +9,7 @@
 - 🧭 **实时导航 UI**：提供 `NaviView` 组件，内置完整的导航界面、语音播报、转向指引、路况显示等。
 - 🛣️ **独立路径规划**：支持“先算路、再导航”的高级模式，可实现多路线对比与选择。
 - ⚙️ **策略丰富**：支持速度优先、避让拥堵、少收费、不走高速等多种算路策略。
-- � **开箱即用**：封装了 Android/iOS 原生导航 SDK，统一 JS 接口。
+- ✅ **开箱即用**：封装了 Android/iOS 原生导航 SDK，统一 JS 接口。
 
 ## 安装
 
@@ -247,6 +247,57 @@ import { MapView, Circle, Polygon } from 'expo-gaode-map-navigation';
 </MapView>
 ```
 
+### 视口控制
+
+导航包的 `MapViewRef` 同样支持：
+
+- `moveCamera(position, duration?)`
+- `getCameraPosition()`
+- `fitToCoordinates(points, options?)`
+
+```tsx
+await mapRef.current?.fitToCoordinates(routePoints, {
+  duration: 500,
+  paddingFactor: 0.2,
+  maxZoom: 18,
+});
+```
+
+注意：
+
+- 这里的用户层 API 形状尽量和 `expo-gaode-map` 保持一致
+- 但底层地图实现仍然绑定导航 SDK，不与 `core` 共用同一套 MapView 实现
+
+### 公交算路 fallback（回退）
+
+`calculateTransitRoute` 会在运行时回退到 `expo-gaode-map-web-api`：
+
+```ts
+import { calculateTransitRoute, RouteType } from 'expo-gaode-map-navigation';
+
+const result = await calculateTransitRoute({
+  type: RouteType.TRANSIT,
+  from: { latitude: 39.9, longitude: 116.4 },
+  to: { latitude: 39.91, longitude: 116.41 },
+  city1: '010',
+  city2: '010',
+});
+```
+
+使用前请确认：
+
+- 已安装 `expo-gaode-map-web-api`
+- 已在 `ExpoGaodeMapModule.initSDK({ webKey })` 中提供 `webKey`
+
+如果缺少依赖或 `webKey`，运行时会抛出明确错误。
+
+### API 边界
+
+- 导航包内置地图能力，但地图实现与 `expo-gaode-map` 独立维护
+- 用户层输入输出会尽量与核心包保持一致，例如 `LatLngPoint`、`fitToCoordinates`
+- 可共享的范围仅限纯 TS 的 route / AOI 数据适配工具、文档和测试思路
+- 原生地图桥接、overlay 宿主逻辑、MapView facade 不会和核心包合并
+
 ## API 参考
 
 ### DriveStrategy (驾车策略)

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

@@ -2,6 +2,7 @@ package expo.modules.gaodemap.map
 
 import android.annotation.SuppressLint
 import android.content.Context
+import android.os.SystemClock
 import android.view.View
 import android.view.ViewGroup
 import com.amap.api.maps.AMap
@@ -32,6 +33,10 @@ import androidx.core.graphics.withTranslation
 @SuppressLint("ViewConstructor")
 class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
 
+    init {
+        orientation = VERTICAL
+    }
+
     /**
      * 拦截 React Native 的 ViewManager 操作
      * 重写 requestLayout 防止在移除视图时触发布局异常
@@ -44,6 +49,63 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
         }
     }
 
+    override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
+        val measuredWidth = View.MeasureSpec.getSize(widthMeasureSpec)
+        val measuredHeight = View.MeasureSpec.getSize(heightMeasureSpec)
+
+        setMeasuredDimension(measuredWidth, measuredHeight)
+
+        for (i in 0 until childCount) {
+            val child = getChildAt(i) ?: continue
+            if (child.visibility == View.GONE) {
+                continue
+            }
+
+            if (child === mapView) {
+                val childWidthSpec = View.MeasureSpec.makeMeasureSpec(measuredWidth, View.MeasureSpec.EXACTLY)
+                val childHeightSpec = View.MeasureSpec.makeMeasureSpec(measuredHeight, View.MeasureSpec.EXACTLY)
+                child.measure(childWidthSpec, childHeightSpec)
+                continue
+            }
+
+            val lp = child.layoutParams
+            val childWidthSpec = when {
+                lp?.width != null && lp.width > 0 ->
+                    View.MeasureSpec.makeMeasureSpec(lp.width, View.MeasureSpec.EXACTLY)
+                else ->
+                    View.MeasureSpec.makeMeasureSpec(measuredWidth, View.MeasureSpec.AT_MOST)
+            }
+            val childHeightSpec = when {
+                lp?.height != null && lp.height > 0 ->
+                    View.MeasureSpec.makeMeasureSpec(lp.height, View.MeasureSpec.EXACTLY)
+                else ->
+                    View.MeasureSpec.makeMeasureSpec(measuredHeight, View.MeasureSpec.AT_MOST)
+            }
+            child.measure(childWidthSpec, childHeightSpec)
+        }
+    }
+
+    override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+        val width = right - left
+        val height = bottom - top
+
+        for (i in 0 until childCount) {
+            val child = getChildAt(i) ?: continue
+            if (child.visibility == View.GONE) {
+                continue
+            }
+
+            if (child === mapView) {
+                child.layout(0, 0, width, height)
+                continue
+            }
+
+            val childWidth = child.measuredWidth
+            val childHeight = child.measuredHeight
+            child.layout(0, 0, childWidth, childHeight)
+        }
+    }
+
     // Props 存储
     /** 地图类型 */
     internal var mapType: Int = 0
@@ -51,6 +113,12 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
     internal var initialCameraPosition: Map<String, Any?>? = null
     /** 是否跟随用户位置 */
     internal var followUserLocation: Boolean = false
+    /** 是否显示底图文字标注 */
+    private var labelsEnabled: Boolean = true
+    /** 是否显示定位按钮 */
+    private var myLocationButtonEnabled: Boolean = false
+    /** 相机移动事件节流间隔 */
+    private var cameraEventThrottleMs: Long = 32L
     /** 自定义地图样式配置（缓存） */
     private var customMapStyleData: Map<String, Any>? = null
 
@@ -59,26 +127,17 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
 
     // 事件派发器
     private val onMapPress by EventDispatcher()
+    private val onPressPoi by EventDispatcher()
     private val onMapLongPress by EventDispatcher()
     private val onLoad by EventDispatcher()
     private val onLocation by EventDispatcher()
     private val onCameraMove by EventDispatcher()
     private val onCameraIdle by EventDispatcher()
 
-    // 事件节流控制
-    /** 相机移动事件节流间隔(毫秒) */
-    private val CAMERA_MOVE_THROTTLE_MS = 100L
-    /** 上次触发相机移动事件的时间戳 */
-    private var lastCameraMoveTime = 0L
     /** 缓存的相机移动事件数据 */
     private var pendingCameraMoveData: Map<String, Any>? = null
-    /** 节流定时器 Runnable */
-    private val throttleRunnable = Runnable {
-        pendingCameraMoveData?.let { data ->
-            onCameraMove(data)
-            pendingCameraMoveData = null
-        }
-    }
+    private var pendingCameraMoveDispatch: Runnable? = null
+    private var lastCameraMoveDispatchAt: Long = 0L
 
     // 高德地图视图
     private lateinit var mapView: MapView
@@ -142,6 +201,9 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
                     uiManager.setCustomMapStyle(styleData)
                 }
 
+                uiManager.setLabelsEnabled(labelsEnabled)
+                uiManager.setMyLocationButtonEnabled(myLocationButtonEnabled)
+
                 onLoad(mapOf("loaded" to true))
             }
         } catch (_: Exception) {
@@ -172,49 +234,8 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
                 // 通知辅助监听器
                 cameraChangeListeners.forEach { it.onCameraChange(cameraPosition) }
 
-                // 相机移动中 - 应用节流优化
                 cameraPosition?.let {
-                    val currentTime = System.currentTimeMillis()
-                    val visibleRegion = aMap.projection.visibleRegion
-                    val eventData = mapOf(
-                        "cameraPosition" to mapOf(
-                            "target" to mapOf(
-                                "latitude" to it.target.latitude,
-                                "longitude" to it.target.longitude
-                            ),
-                            "zoom" to it.zoom,
-                            "tilt" to it.tilt,
-                            "bearing" to it.bearing
-                        ),
-                        "latLngBounds" to mapOf(
-                            "northeast" to mapOf(
-                                "latitude" to visibleRegion.farRight.latitude,
-                                "longitude" to visibleRegion.farRight.longitude
-                            ),
-                            "southwest" to mapOf(
-                                "latitude" to visibleRegion.nearLeft.latitude,
-                                "longitude" to visibleRegion.nearLeft.longitude
-                            )
-                        )
-                    )
-                    
-                    // 节流逻辑：100ms 内只触发一次
-                    if (currentTime - lastCameraMoveTime >= CAMERA_MOVE_THROTTLE_MS) {
-                        // 超过节流时间，立即触发事件
-                        lastCameraMoveTime = currentTime
-                        onCameraMove(eventData)
-                        // 清除待处理的事件和定时器
-                        mainHandler.removeCallbacks(throttleRunnable)
-                        pendingCameraMoveData = null
-                    } else {
-                        // 在节流时间内，缓存事件数据，使用定时器延迟触发
-                        pendingCameraMoveData = eventData
-                        mainHandler.removeCallbacks(throttleRunnable)
-                        mainHandler.postDelayed(
-                            throttleRunnable,
-                            CAMERA_MOVE_THROTTLE_MS - (currentTime - lastCameraMoveTime)
-                        )
-                    }
+                    dispatchCameraMoveEvent(buildCameraEventData(it))
                 }
             }
 
@@ -222,30 +243,10 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
                 // 通知辅助监听器
                 cameraChangeListeners.forEach { it.onCameraChangeFinish(cameraPosition) }
 
-                // 相机移动完成
+                flushPendingCameraMoveEvent()
+
                 cameraPosition?.let {
-                    val visibleRegion = aMap.projection.visibleRegion
-                    onCameraIdle(mapOf(
-                        "cameraPosition" to mapOf(
-                            "target" to mapOf(
-                                "latitude" to it.target.latitude,
-                                "longitude" to it.target.longitude
-                            ),
-                            "zoom" to it.zoom,
-                            "tilt" to it.tilt,
-                            "bearing" to it.bearing
-                        ),
-                        "latLngBounds" to mapOf(
-                            "northeast" to mapOf(
-                                "latitude" to visibleRegion.farRight.latitude,
-                                "longitude" to visibleRegion.farRight.longitude
-                            ),
-                            "southwest" to mapOf(
-                                "latitude" to visibleRegion.nearLeft.latitude,
-                                "longitude" to visibleRegion.nearLeft.longitude
-                            )
-                        )
-                    ))
+                    onCameraIdle(buildCameraEventData(it))
                 }
             }
         })
@@ -312,6 +313,17 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
             ))
         }
 
+        aMap.setOnPOIClickListener { poi ->
+            onPressPoi(mapOf(
+                "id" to poi.poiId,
+                "name" to poi.name,
+                "position" to mapOf(
+                    "latitude" to poi.coordinate.latitude,
+                    "longitude" to poi.coordinate.longitude
+                )
+            ))
+        }
+
         aMap.setOnMapLongClickListener { latLng ->
             onMapLongPress(mapOf(
                 "latitude" to latLng.latitude,
@@ -415,6 +427,24 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
     fun setShowsBuildings(show: Boolean) = uiManager.setShowsBuildings(show)
     /** 设置是否显示室内地图 */
     fun setShowsIndoorMap(show: Boolean) = uiManager.setShowsIndoorMap(show)
+    /** 设置是否显示底图文字标注 */
+    fun setLabelsEnabled(enabled: Boolean) {
+        labelsEnabled = enabled
+        uiManager.setLabelsEnabled(enabled)
+    }
+    /** 设置是否显示定位按钮 */
+    fun setMyLocationButtonEnabled(enabled: Boolean) {
+        myLocationButtonEnabled = enabled
+        uiManager.setMyLocationButtonEnabled(enabled)
+    }
+    /** 设置相机移动事件节流间隔 */
+    fun setCameraEventThrottleMs(throttleMs: Int) {
+        cameraEventThrottleMs = throttleMs.toLong().coerceAtLeast(0L)
+        if (cameraEventThrottleMs == 0L) {
+            pendingCameraMoveDispatch?.let(mainHandler::removeCallbacks)
+            pendingCameraMoveDispatch = null
+        }
+    }
     
     /**
      * 设置自定义地图样式
@@ -591,8 +621,8 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
     @Suppress("unused")
     fun onDestroy() {
                try {
-                   // 清理节流定时器
-                   mainHandler.removeCallbacks(throttleRunnable)
+                   pendingCameraMoveDispatch?.let(mainHandler::removeCallbacks)
+                   pendingCameraMoveDispatch = null
                    pendingCameraMoveData = null
                    
                    // 清理 Handler 回调,防止内存泄露
@@ -600,6 +630,7 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
 
             // 清理所有地图监听器
             aMap.setOnMapClickListener(null)
+            aMap.setOnPOIClickListener(null)
             aMap.setOnMapLongClickListener(null)
             aMap.setOnMapLoadedListener(null)
             aMap.setOnCameraChangeListener(null)
@@ -634,9 +665,10 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
     override fun addView(child: View?, index: Int) {
         if (child is MarkerView) {
             child.setMap(aMap)
-            // MarkerView 也加入实际视图层级，但设置为 0x0 大小并移到屏幕外
-            // 不使用 View.GONE，避免在新架构下出现渲染问题
-            val params = LayoutParams(0, 0)
+            // MarkerView 需要保留可测量尺寸，否则 Android 无法正确处理
+            // Text / View 的 maxWidth 等布局约束，最终会被测成整行宽度。
+            // 这里保留 WRAP_CONTENT，并继续移到屏幕外，避免影响可见布局。
+            val params = LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)
             child.layoutParams = params
             child.translationX = -10000f  // 移到屏幕外
             child.translationY = -10000f
@@ -746,7 +778,71 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
         return false
     }
 
-    override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
-        super.onLayout(changed, left, top, right, bottom)
+    private fun buildCameraEventData(cameraPosition: com.amap.api.maps.model.CameraPosition): Map<String, Any> {
+        val visibleRegion = aMap.projection.visibleRegion
+        return mapOf(
+            "cameraPosition" to mapOf(
+                "target" to mapOf(
+                    "latitude" to cameraPosition.target.latitude,
+                    "longitude" to cameraPosition.target.longitude
+                ),
+                "zoom" to cameraPosition.zoom,
+                "tilt" to cameraPosition.tilt,
+                "bearing" to cameraPosition.bearing
+            ),
+            "latLngBounds" to mapOf(
+                "northeast" to mapOf(
+                    "latitude" to visibleRegion.farRight.latitude,
+                    "longitude" to visibleRegion.farRight.longitude
+                ),
+                "southwest" to mapOf(
+                    "latitude" to visibleRegion.nearLeft.latitude,
+                    "longitude" to visibleRegion.nearLeft.longitude
+                )
+            )
+        )
+    }
+
+    private fun dispatchCameraMoveEvent(eventData: Map<String, Any>) {
+        val throttleMs = cameraEventThrottleMs.coerceAtLeast(0L)
+        if (throttleMs == 0L) {
+            pendingCameraMoveData = null
+            pendingCameraMoveDispatch?.let(mainHandler::removeCallbacks)
+            pendingCameraMoveDispatch = null
+            lastCameraMoveDispatchAt = SystemClock.uptimeMillis()
+            onCameraMove(eventData)
+            return
+        }
+
+        pendingCameraMoveData = eventData
+
+        val now = SystemClock.uptimeMillis()
+        val elapsed = now - lastCameraMoveDispatchAt
+        if (elapsed >= throttleMs) {
+            pendingCameraMoveDispatch?.let(mainHandler::removeCallbacks)
+            pendingCameraMoveDispatch = null
+            flushPendingCameraMoveEvent(now)
+            return
+        }
+
+        if (pendingCameraMoveDispatch != null) {
+            return
+        }
+
+        val delay = (throttleMs - elapsed).coerceAtLeast(0L)
+        val runnable = Runnable {
+            pendingCameraMoveDispatch = null
+            flushPendingCameraMoveEvent()
+        }
+        pendingCameraMoveDispatch = runnable
+        mainHandler.postDelayed(runnable, delay)
     }
+
+    private fun flushPendingCameraMoveEvent(timestamp: Long = SystemClock.uptimeMillis()) {
+        val eventData = pendingCameraMoveData ?: return
+        pendingCameraMoveData = null
+        lastCameraMoveDispatchAt = timestamp
+        onCameraMove(eventData)
+    }
+
 }

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

@@ -11,7 +11,7 @@ class ExpoGaodeMapViewModule : Module() {
     Name("ExpoGaodeMapView")
 
     View(ExpoGaodeMapView::class) {
-      Events("onMapPress", "onMapLongPress", "onLoad", "onLocation", "onCameraMove", "onCameraIdle")
+      Events("onMapPress", "onPressPoi", "onMapLongPress", "onLoad", "onLocation", "onCameraMove", "onCameraIdle")
       
 
       
@@ -54,6 +54,9 @@ class ExpoGaodeMapViewModule : Module() {
       Prop<Boolean>("trafficEnabled") { view, show -> view.setShowsTraffic(show) }
       Prop<Boolean>("buildingsEnabled") { view, show -> view.setShowsBuildings(show) }
       Prop<Boolean>("indoorViewEnabled") { view, show -> view.setShowsIndoorMap(show) }
+      Prop<Boolean>("labelsEnabled") { view, enabled -> view.setLabelsEnabled(enabled) }
+      Prop<Boolean>("myLocationButtonEnabled") { view, enabled -> view.setMyLocationButtonEnabled(enabled) }
+      Prop<Int>("cameraEventThrottleMs") { view, throttleMs -> view.setCameraEventThrottleMs(throttleMs) }
       
       Prop<Map<String, Any>?>("customMapStyle") { view, styleData ->
         styleData?.let { view.setCustomMapStyle(it) }

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

@@ -46,6 +46,13 @@ class UIManager(private val aMap: AMap, private val context: Context) : Location
   fun setShowsScale(show: Boolean) {
     aMap.uiSettings.isScaleControlsEnabled = show
   }
+
+  /**
+   * 设置是否显示定位按钮
+   */
+  fun setMyLocationButtonEnabled(enabled: Boolean) {
+    aMap.uiSettings.isMyLocationButtonEnabled = enabled
+  }
   
   // ==================== 手势控制 ====================
   
@@ -336,6 +343,13 @@ class UIManager(private val aMap: AMap, private val context: Context) : Location
   fun setShowsIndoorMap(show: Boolean) {
     aMap.showIndoorMap(show)
   }
+
+  /**
+   * 设置是否显示底图文字标注
+   */
+  fun setLabelsEnabled(enabled: Boolean) {
+    aMap.showMapText(enabled)
+  }
   
   /**
    * 设置地图类型