expo-gaode-map 0.1.6 → 1.0.1

package/ios/ExpoGaodeMapView.swift

@@ -1,17 +1,39 @@
 import ExpoModulesCore
 import MAMapKit
 
+/**
+ * 高德地图视图组件
+ * 
+ * 负责:
+ * - 地图视图的创建和管理
+ * - 相机控制和手势交互
+ * - 覆盖物的添加和管理
+ * - 地图事件的派发
+ */
 class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
+    // MARK: - 属性
+    
+    /// 地图类型 (0:标准 1:卫星 2:夜间 3:导航)
     var mapType: Int = 0
+    /// 初始相机位置
     var initialCameraPosition: [String: Any]?
+    /// 是否显示缩放控件
     var showsZoomControls: Bool = true
+    /// 是否显示指南针
     var showsCompass: Bool = true
+    /// 是否显示比例尺
     var showsScale: Bool = true
+    /// 是否启用缩放手势
     var isZoomEnabled: Bool = true
+    /// 是否启用滚动手势
     var isScrollEnabled: Bool = true
+    /// 是否启用旋转手势
     var isRotateEnabled: Bool = true
+    /// 是否启用倾斜手势
     var isTiltEnabled: Bool = true
+    /// 是否显示用户位置
     var showsUserLocation: Bool = false
+    /// 是否跟随用户位置
     var followUserLocation: Bool = false {
         didSet {
             if showsUserLocation {
@@ -19,23 +41,40 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
             }
         }
     }
+    /// 用户位置样式配置
     var userLocationRepresentation: [String: Any]?
+    /// 是否显示交通路况
     var showsTraffic: Bool = false
+    /// 是否显示建筑物
     var showsBuildings: Bool = false
+    /// 是否显示室内地图
     var showsIndoorMap: Bool = false
+    /// 最大缩放级别
     var maxZoomLevel: CGFloat = 20
+    /// 最小缩放级别
     var minZoomLevel: CGFloat = 3
     
+    // MARK: - 事件派发器
+    
     let onMapPress = EventDispatcher()
     let onMapLongPress = EventDispatcher()
     let onLoad = EventDispatcher()
     
+    // MARK: - 私有属性
+    
+    /// 高德地图视图实例
     private var mapView: MAMapView!
+    /// 相机管理器
     private var cameraManager: CameraManager!
+    /// UI 管理器
     private var uiManager: UIManager!
+    /// 覆盖物管理器
     private var overlayManager: OverlayManager!
+    /// 地图是否已加载完成
     private var isMapLoaded = false
     
+    // MARK: - 初始化
+    
     required init(appContext: AppContext? = nil) {
         super.init(appContext: appContext)
         
@@ -60,10 +99,13 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
         mapView.frame = bounds
     }
     
+    /**
+     * 添加子视图时自动连接到地图
+     * 将地图实例传递给覆盖物子视图
+     */
     override func addSubview(_ view: UIView) {
         super.addSubview(view)
         
-        // 自动将地图实例传递给覆盖物子视图
         if let markerView = view as? MarkerView {
             markerView.setMap(mapView)
         } else if let circleView = view as? CircleView {
@@ -81,6 +123,9 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
         }
     }
     
+    /**
+     * 设置默认配置
+     */
     private func setupDefaultConfig() {
         uiManager.setMapType(0)
         uiManager.setShowsScale(showsScale)
@@ -92,6 +137,10 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
         uiManager.setShowsUserLocation(showsUserLocation, followUser: followUserLocation)
     }
     
+    /**
+     * 应用所有属性配置
+     * 在 Props 更新时调用
+     */
     func applyProps() {
         uiManager.setMapType(mapType)
         
@@ -111,6 +160,8 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
         uiManager.setShowsIndoorMap(showsIndoorMap)
     }
     
+    // MARK: - 缩放控制
+    
     func setMaxZoom(_ maxZoom: Double) {
         cameraManager.setMaxZoomLevel(CGFloat(maxZoom))
     }
@@ -119,6 +170,8 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
         cameraManager.setMinZoomLevel(CGFloat(minZoom))
     }
     
+    // MARK: - 相机控制
+    
     func moveCamera(position: [String: Any], duration: Int) {
         cameraManager.moveCamera(position: position, duration: duration)
     }
@@ -139,6 +192,8 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
         return cameraManager.getCameraPosition()
     }
     
+    // MARK: - 覆盖物管理
+    
     func addCircle(id: String, props: [String: Any]) {
         overlayManager.addCircle(id: id, props: props)
     }
@@ -187,6 +242,8 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
         overlayManager.updatePolygon(id: id, props: props)
     }
     
+    // MARK: - 图层控制
+    
     func setShowsTraffic(_ show: Bool) {
         showsTraffic = show
         uiManager.setShowsTraffic(show)
@@ -204,7 +261,6 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
     
     func setFollowUserLocation(_ follow: Bool) {
         followUserLocation = follow
-        // 如果定位已开启,立即应用新设置
         uiManager.setShowsUserLocation(showsUserLocation, followUser: follow)
     }
     
@@ -223,13 +279,29 @@ class ExpoGaodeMapView: ExpoView, MAMapViewDelegate {
         }
     }
     
+    /**
+     * 应用用户位置样式
+     */
     private func applyUserLocationStyle() {
         guard let config = userLocationRepresentation else { return }
         uiManager.setUserLocationRepresentation(config)
     }
+    
+    /**
+     * 析构函数 - 清理资源
+     */
+    deinit {
+        mapView?.delegate = nil
+        overlayManager?.clear()
+    }
 }
 
+// MARK: - MAMapViewDelegate
+
 extension ExpoGaodeMapView {
+    /**
+     * 地图加载完成回调
+     */
     public func mapViewDidFinishLoadingMap(_ mapView: MAMapView) {
         guard !isMapLoaded else { return }
         isMapLoaded = true
@@ -239,16 +311,25 @@ extension ExpoGaodeMapView {
         onLoad(["loaded": true])
     }
     
+    /**
+     * 地图单击事件
+     */
     public func mapView(_ mapView: MAMapView, didSingleTappedAt coordinate: CLLocationCoordinate2D) {
         onMapPress(["latitude": coordinate.latitude, "longitude": coordinate.longitude])
     }
     
+    /**
+     * 地图长按事件
+     */
     public func mapView(_ mapView: MAMapView, didLongPressedAt coordinate: CLLocationCoordinate2D) {
         onMapLongPress(["latitude": coordinate.latitude, "longitude": coordinate.longitude])
     }
     
+    /**
+     * 创建标注视图
+     * 定位蓝点返回 nil 使用系统默认样式
+     */
     public func mapView(_ mapView: MAMapView, viewFor annotation: MAAnnotation) -> MAAnnotationView? {
-        // 定位蓝点返回 nil,使用系统默认样式
         if annotation.isKind(of: MAUserLocation.self) {
             return nil
         }
@@ -265,8 +346,11 @@ extension ExpoGaodeMapView {
         return nil
     }
     
+    /**
+     * 创建覆盖物渲染器
+     * 优先使用子视图的渲染器,否则使用 OverlayManager 的渲染器
+     */
     public func mapView(_ mapView: MAMapView, rendererFor overlay: MAOverlay) -> MAOverlayRenderer {
-        // 首先检查是否是通过子视图添加的覆盖物
         for subview in subviews {
             if let circleView = subview as? CircleView, circleView.circle === overlay {
                 return circleView.getRenderer()
@@ -277,8 +361,6 @@ extension ExpoGaodeMapView {
             }
         }
         
-        // 否则使用 OverlayManager 的渲染器
         return overlayManager.getRenderer(for: overlay) ?? MAOverlayRenderer(overlay: overlay)
     }
 }
-

package/ios/managers/CameraManager.swift

@@ -1,21 +1,47 @@
 import ExpoModulesCore
 import MAMapKit
 
+/**
+ * 相机管理器
+ * 
+ * 负责:
+ * - 相机位置和视角控制
+ * - 缩放级别管理
+ * - 坐标转换
+ */
 class CameraManager {
+    /// 弱引用地图视图,避免循环引用
     private weak var mapView: MAMapView?
     
     init(mapView: MAMapView) {
         self.mapView = mapView
     }
     
+    // MARK: - 缩放级别控制
+    
+    /**
+     * 设置最大缩放级别
+     * @param maxZoom 最大缩放级别 (3-20)
+     */
     func setMaxZoomLevel(_ maxZoom: CGFloat) {
         mapView?.maxZoomLevel = maxZoom
     }
     
+    /**
+     * 设置最小缩放级别
+     * @param minZoom 最小缩放级别 (3-20)
+     */
     func setMinZoomLevel(_ minZoom: CGFloat) {
         mapView?.minZoomLevel = minZoom
     }
     
+    // MARK: - 相机位置控制
+    
+    /**
+     * 设置初始相机位置
+     * 不带动画,用于地图初始化
+     * @param position 包含 target、zoom、bearing、tilt 的字典
+     */
     func setInitialCameraPosition(_ position: [String: Any]) {
         guard let mapView = mapView else { return }
         let status = MAMapStatus()
@@ -41,10 +67,18 @@ class CameraManager {
         mapView.setMapStatus(status, animated: false, duration: 0)
     }
     
+    /**
+     * 移动相机到指定位置
+     * 支持动画效果
+     * @param position 目标位置信息
+     * @param duration 动画时长(毫秒)
+     */
     func moveCamera(position: [String: Any], duration: Int) {
         guard let mapView = mapView else { return }
+        
         let status = MAMapStatus()
         
+        // 设置中心点,如果未提供则保持当前值
         if let target = position["target"] as? [String: Double],
            let latitude = target["latitude"],
            let longitude = target["longitude"] {
@@ -53,18 +87,21 @@ class CameraManager {
             status.centerCoordinate = mapView.centerCoordinate
         }
         
+        // 设置缩放级别
         if let zoom = position["zoom"] as? Double {
             status.zoomLevel = CGFloat(zoom)
         } else {
             status.zoomLevel = mapView.zoomLevel
         }
         
+        // 设置旋转角度
         if let bearing = position["bearing"] as? Double {
             status.rotationDegree = CGFloat(bearing)
         } else {
             status.rotationDegree = mapView.rotationDegree
         }
         
+        // 设置倾斜角度
         if let tilt = position["tilt"] as? Double {
             status.cameraDegree = CGFloat(tilt)
         } else {
@@ -74,6 +111,11 @@ class CameraManager {
         mapView.setMapStatus(status, animated: duration > 0, duration: TimeInterval(duration) / 1000.0)
     }
     
+    /**
+     * 设置地图中心点
+     * @param center 中心点坐标
+     * @param animated 是否使用动画
+     */
     func setCenter(center: [String: Double], animated: Bool) {
         guard let mapView = mapView,
               let latitude = center["latitude"],
@@ -81,10 +123,21 @@ class CameraManager {
         mapView.setCenter(CLLocationCoordinate2D(latitude: latitude, longitude: longitude), animated: animated)
     }
     
+    /**
+     * 设置缩放级别
+     * @param zoom 缩放级别 (3-20)
+     * @param animated 是否使用动画
+     */
     func setZoomLevel(zoom: CGFloat, animated: Bool) {
         mapView?.setZoomLevel(zoom, animated: animated)
     }
     
+    // MARK: - 相机信息获取
+    
+    /**
+     * 获取当前相机位置信息
+     * @return 包含 target、zoom、bearing、tilt 的字典
+     */
     func getCameraPosition() -> [String: Any] {
         guard let mapView = mapView else { return [:] }
         let center = mapView.centerCoordinate
@@ -96,6 +149,11 @@ class CameraManager {
         ]
     }
     
+    /**
+     * 将屏幕坐标转换为地理坐标
+     * @param point 屏幕坐标点 {x, y}
+     * @return 地理坐标 {latitude, longitude}
+     */
     func getLatLng(point: [String: Double]) -> [String: Double] {
         guard let mapView = mapView,
               let x = point["x"],

package/ios/managers/OverlayManager.swift

@@ -1,17 +1,39 @@
 import MAMapKit
 
+/**
+ * 覆盖物管理器
+ * 
+ * 负责:
+ * - 管理地图覆盖物(圆形、折线、多边形)
+ * - 管理标记点(Marker)
+ * - 处理覆盖物样式和渲染
+ * - 支持纹理贴图
+ */
 class OverlayManager {
+    /// 地图视图弱引用
     private weak var mapView: MAMapView?
+    /// 覆盖物字典 (id -> overlay)
     private var overlays: [String: MAOverlay] = [:]
+    /// 覆盖物样式字典 (id -> style)
     private var overlayStyles: [String: [String: Any]] = [:]
+    /// 标记点字典 (id -> annotation)
     private var annotations: [String: MAPointAnnotation] = [:]
     
+    /**
+     * 初始化覆盖物管理器
+     * @param mapView 地图视图实例
+     */
     init(mapView: MAMapView) {
         self.mapView = mapView
     }
     
-    // MARK: - Circle
+    // MARK: - Circle 圆形
     
+    /**
+     * 添加圆形覆盖物
+     * @param id 圆形唯一标识
+     * @param props 圆形属性(center, radius, fillColor, strokeColor, strokeWidth)
+     */
     func addCircle(id: String, props: [String: Any]) {
         guard let mapView = mapView,
               let center = props["center"] as? [String: Double],
@@ -25,6 +47,10 @@ class OverlayManager {
         overlays[id] = circle
     }
     
+    /**
+     * 移除圆形覆盖物
+     * @param id 圆形唯一标识
+     */
     func removeCircle(id: String) {
         guard let mapView = mapView, let circle = overlays[id] else { return }
         mapView.remove(circle)
@@ -32,13 +58,23 @@ class OverlayManager {
         overlayStyles.removeValue(forKey: id)
     }
     
+    /**
+     * 更新圆形覆盖物
+     * @param id 圆形唯一标识
+     * @param props 新的圆形属性
+     */
     func updateCircle(id: String, props: [String: Any]) {
         removeCircle(id: id)
         addCircle(id: id, props: props)
     }
     
-    // MARK: - Marker
+    // MARK: - Marker 标记点
     
+    /**
+     * 添加标记点
+     * @param id 标记点唯一标识
+     * @param props 标记点属性(position, title, description)
+     */
     func addMarker(id: String, props: [String: Any]) {
         guard let mapView = mapView,
               let position = props["position"] as? [String: Double],
@@ -53,25 +89,36 @@ class OverlayManager {
         annotations[id] = annotation
     }
     
+    /**
+     * 移除标记点
+     * @param id 标记点唯一标识
+     */
     func removeMarker(id: String) {
         guard let mapView = mapView, let annotation = annotations[id] else { return }
         mapView.removeAnnotation(annotation)
         annotations.removeValue(forKey: id)
     }
     
+    /**
+     * 更新标记点
+     * @param id 标记点唯一标识
+     * @param props 新的标记点属性
+     */
     func updateMarker(id: String, props: [String: Any]) {
         removeMarker(id: id)
         addMarker(id: id, props: props)
     }
     
-    // MARK: - Polyline
+    // MARK: - Polyline 折线
     
+    /**
+     * 添加折线覆盖物
+     * @param id 折线唯一标识
+     * @param props 折线属性(points, strokeWidth, strokeColor, texture)
+     */
     func addPolyline(id: String, props: [String: Any]) {
-        print("📏 OverlayManager.addPolyline - id: \(id), props: \(props)")
-        
         guard let mapView = mapView,
               let points = props["points"] as? [[String: Double]] else {
-            print("❌ OverlayManager.addPolyline - mapView 或 points 为空")
             return
         }
         
@@ -81,7 +128,6 @@ class OverlayManager {
             coordinates.append(CLLocationCoordinate2D(latitude: lat, longitude: lng))
         }
         guard coordinates.count >= 2 else {
-            print("❌ OverlayManager.addPolyline - 坐标点数量不足: \(coordinates.count)")
             return
         }
         
@@ -90,12 +136,13 @@ class OverlayManager {
         // 先保存样式和 overlay，再添加到地图
         overlayStyles[id] = props
         overlays[id] = polyline
-        
-        print("✅ OverlayManager.addPolyline - 准备添加到地图，id: \(id)")
         mapView.add(polyline)
-        print("✅ OverlayManager.addPolyline - 已添加到地图")
     }
     
+    /**
+     * 移除折线覆盖物
+     * @param id 折线唯一标识
+     */
     func removePolyline(id: String) {
         guard let mapView = mapView, let polyline = overlays[id] else { return }
         mapView.remove(polyline)
@@ -103,13 +150,23 @@ class OverlayManager {
         overlayStyles.removeValue(forKey: id)
     }
     
+    /**
+     * 更新折线覆盖物
+     * @param id 折线唯一标识
+     * @param props 新的折线属性
+     */
     func updatePolyline(id: String, props: [String: Any]) {
         removePolyline(id: id)
         addPolyline(id: id, props: props)
     }
     
-    // MARK: - Polygon
+    // MARK: - Polygon 多边形
     
+    /**
+     * 添加多边形覆盖物
+     * @param id 多边形唯一标识
+     * @param props 多边形属性(points, fillColor, strokeColor, strokeWidth)
+     */
     func addPolygon(id: String, props: [String: Any]) {
         guard let mapView = mapView,
               let points = props["points"] as? [[String: Double]] else { return }
@@ -125,6 +182,10 @@ class OverlayManager {
         overlays[id] = polygon
     }
     
+    /**
+     * 移除多边形覆盖物
+     * @param id 多边形唯一标识
+     */
     func removePolygon(id: String) {
         guard let mapView = mapView, let polygon = overlays[id] else { return }
         mapView.remove(polygon)
@@ -132,30 +193,41 @@ class OverlayManager {
         overlayStyles.removeValue(forKey: id)
     }
     
+    /**
+     * 更新多边形覆盖物
+     * @param id 多边形唯一标识
+     * @param props 新的多边形属性
+     */
     func updatePolygon(id: String, props: [String: Any]) {
         removePolygon(id: id)
         addPolygon(id: id, props: props)
     }
     
-    // MARK: - Renderer
+    // MARK: - Renderer 渲染器
     
+    /**
+     * 获取覆盖物渲染器
+     * @param overlay 覆盖物对象
+     * @return 对应的渲染器
+     */
     func getRenderer(for overlay: MAOverlay) -> MAOverlayRenderer? {
         let id = overlays.first(where: { $0.value === overlay })?.key
         let style = id != nil ? overlayStyles[id!] : nil
         
-        print("🎨 OverlayManager.getRenderer - overlay类型: \(type(of: overlay)), id: \(id ?? "nil"), style: \(style ?? [:])")
-        
         if let circle = overlay as? MACircle {
             guard let renderer = MACircleRenderer(circle: circle) else {
                 return nil
             }
             
+            // 设置填充颜色
             if let fillColor = style?["fillColor"] {
                 renderer.fillColor = ColorParser.parseColor(fillColor)
             }
+            // 设置边框颜色
             if let strokeColor = style?["strokeColor"] {
                 renderer.strokeColor = ColorParser.parseColor(strokeColor)
             }
+            // 设置边框宽度
             if let strokeWidth = style?["strokeWidth"] as? Double {
                 renderer.lineWidth = CGFloat(strokeWidth)
             }
@@ -182,17 +254,12 @@ class OverlayManager {
                 loadPolylineTexture(url: textureUrl, renderer: renderer)
             } else {
                 if let color = style?["color"] {
-                    print("🎨 color 原始值: \(color), 类型: \(type(of: color))")
                     let parsedColor = ColorParser.parseColor(color)
-                    print("🎨 解析后的颜色: \(String(describing: parsedColor))")
                     renderer.strokeColor = parsedColor ?? .red
                 } else if let strokeColor = style?["strokeColor"] {
-                    print("🎨 strokeColor 原始值: \(strokeColor), 类型: \(type(of: strokeColor))")
                     let parsedColor = ColorParser.parseColor(strokeColor)
-                    print("🎨 解析后的颜色: \(String(describing: parsedColor))")
                     renderer.strokeColor = parsedColor ?? .red
                 } else {
-                    print("⚠️ 没有找到 color 或 strokeColor，使用默认红色")
                     renderer.strokeColor = .red
                 }
             }
@@ -203,12 +270,15 @@ class OverlayManager {
                 return nil
             }
             
+            // 设置填充颜色
             if let fillColor = style?["fillColor"] {
                 renderer.fillColor = ColorParser.parseColor(fillColor)
             }
+            // 设置边框颜色
             if let strokeColor = style?["strokeColor"] {
                 renderer.strokeColor = ColorParser.parseColor(strokeColor)
             }
+            // 设置边框宽度
             if let strokeWidth = style?["strokeWidth"] as? Double {
                 renderer.lineWidth = CGFloat(strokeWidth)
             }
@@ -219,48 +289,54 @@ class OverlayManager {
         return nil
     }
     
+    /**
+     * 加载折线纹理图片
+     * @param url 图片 URL (支持 http/https/file/本地资源)
+     * @param renderer 折线渲染器
+     */
     private func loadPolylineTexture(url: String, renderer: MAPolylineRenderer) {
         if url.hasPrefix("http://") || url.hasPrefix("https://") {
+            // 网络图片
             guard let imageUrl = URL(string: url) else {
-                print("❌ OverlayManager: 无效的 URL: \(url)")
                 return
             }
             URLSession.shared.dataTask(with: imageUrl) { [weak self] data, _, error in
                 if let error = error {
-                    print("❌ OverlayManager: 下载图片失败: \(error)")
                     return
                 }
                 guard let data = data, let image = UIImage(data: data) else {
-                    print("❌ OverlayManager: 无法创建图片")
                     return
                 }
-                print("✅ OverlayManager: 图片下载成功，大小: \(image.size)")
                 DispatchQueue.main.async {
                     self?.applyPolylineTexture(image: image, to: renderer)
                 }
             }.resume()
         } else if url.hasPrefix("file://") {
+            // 本地文件
             let path = String(url.dropFirst(7))
             if let image = UIImage(contentsOfFile: path) {
-                print("✅ OverlayManager: 本地图片加载成功")
                 applyPolylineTexture(image: image, to: renderer)
-            } else {
-                print("❌ OverlayManager: 本地图片加载失败: \(path)")
             }
         } else {
+            // 资源文件
             if let image = UIImage(named: url) {
-                print("✅ OverlayManager: 资源图片加载成功")
                 applyPolylineTexture(image: image, to: renderer)
-            } else {
-                print("❌ OverlayManager: 资源图片加载失败: \(url)")
             }
         }
     }
     
+    /**
+     * 应用纹理到折线渲染器
+     * @param image 纹理图片
+     * @param renderer 折线渲染器
+     */
     private func applyPolylineTexture(image: UIImage, to renderer: MAPolylineRenderer) {
         renderer.strokeImage = image
     }
     
+    /**
+     * 清除所有覆盖物和标记点
+     */
     func clear() {
         guard let mapView = mapView else { return }
         for overlay in overlays.values {