expo-gaode-map 1.0.6 → 1.0.8

package/README.en.md

@@ -0,0 +1,320 @@
+# expo-gaode-map
+
+English | [简体中文](./README.md)
+
+A full-featured AMap (Gaode Map) React Native component library, **built with Expo Modules**, providing map display, location, overlays, and more:
+- Android: [AMap Android SDK](https://lbs.amap.com/api/android-sdk/summary)
+- iOS: [AMap iOS SDK](https://lbs.amap.com/api/ios-sdk/summary)
+
+> 💡 This component is built with [Expo Modules API](https://docs.expo.dev/modules/overview/), providing type-safe native module interfaces and excellent developer experience.
+
+## ✨ Features
+
+- ✅ Complete map functionality (multiple map types, gesture control, camera operations)
+- ✅ Accurate location (continuous location, single location, coordinate conversion)
+- ✅ Rich overlays (Circle, Marker, Polyline, Polygon)
+- ✅ Complete TypeScript type definitions (zero any types)
+- ✅ Modular architecture design
+- ✅ Support both declarative components and imperative API
+- ✅ Cross-platform support (Android, iOS)
+- ✅ Support custom styles and event listeners
+- ✅ Support both React Native architectures (Paper & Fabric)
+
+## 📦 Installation
+
+```bash
+npm install expo-gaode-map
+# or
+yarn add expo-gaode-map
+# or
+pnpm add expo-gaode-map
+```
+
+### Expo Projects
+
+If you're using an Expo managed project (using `expo prebuild` or development builds), you need to rebuild native code after installation:
+
+```bash
+# Using EAS Build
+eas build --platform android
+
+# Or using local build
+npx expo prebuild
+npx expo run:android
+```
+
+### Pure React Native Projects
+
+For pure React Native projects (created with `react-native init`), ensure `expo` package is installed as a dependency:
+
+```bash
+npm install expo
+# Then rebuild the app
+npx react-native run-android
+```
+
+## 🚀 Quick Start
+
+### 1. Get AMap API Key
+
+Visit [AMap Open Platform](https://lbs.amap.com/) to register and create an application to get API Key.
+
+> ⚠️ **Important: Native Configuration and Permissions**
+>
+> AMap SDK requires configuration in native projects:
+>
+> **Android Required Configuration:**
+> 1. Configure API Key in `AndroidManifest.xml`
+> 2. Add required permissions (network, location, etc.)
+> 3. Configure privacy compliance (required)
+>
+> **iOS Required Configuration:**
+> 1. Configure API Key in `Info.plist`
+> 2. Add location permission descriptions (NSLocationWhenInUseUsageDescription, etc.)
+> 3. Configure privacy compliance (required)
+>
+> **Detailed Configuration Guides:**
+> - **Android**: [AMap Android SDK Configuration Guide](https://lbs.amap.com/api/android-sdk/guide/create-project/android-studio-create-project)
+> - **iOS**: [AMap iOS SDK Configuration Guide](https://lbs.amap.com/api/ios-sdk/guide/create-project/cocoapods)
+>
+> For Expo projects, use `npx expo prebuild` to generate native code before configuration.
+
+### 2. Initialization and Permission Management
+
+**Recommended initialization process**:
+
+```tsx
+import { useEffect, useState } from 'react';
+import {
+  MapView,
+  initSDK,
+  checkLocationPermission,
+  requestLocationPermission,
+  getCurrentLocation,
+} from 'expo-gaode-map';
+
+export default function App() {
+  const [initialPosition, setInitialPosition] = useState(null);
+
+  useEffect(() => {
+    const initialize = async () => {
+      // 1. Initialize SDK
+      initSDK({
+        androidKey: 'your-android-api-key',
+        iosKey: 'your-ios-api-key',
+      });
+      
+      // 2. Check and request permission
+      const status = await checkLocationPermission();
+      if (!status.granted) {
+        await requestLocationPermission();
+      }
+      
+      // 3. Get location and set map
+      try {
+        const location = await getCurrentLocation();
+        setInitialPosition({
+          target: { latitude: location.latitude, longitude: location.longitude },
+          zoom: 15
+        });
+      } catch (error) {
+        // Use default location
+        setInitialPosition({
+          target: { latitude: 39.9, longitude: 116.4 },
+          zoom: 10
+        });
+      }
+    };
+    
+    initialize();
+  }, []);
+
+  if (!initialPosition) return null;
+
+  return (
+    <MapView
+      style={{ flex: 1 }}
+      initialCameraPosition={initialPosition}
+      myLocationEnabled={true}
+    />
+  );
+}
+```
+
+> 📖 **Detailed Initialization Guide**: [INITIALIZATION.en.md](docs/INITIALIZATION.en.md)
+>
+> Includes complete permission handling, error handling, and best practices.
+
+### 3. Basic Map Usage
+
+```tsx
+import { MapView } from 'expo-gaode-map';
+
+export default function MapScreen() {
+  return (
+    <MapView
+      style={{ flex: 1 }}
+      initialCameraPosition={{
+        target: { latitude: 39.9, longitude: 116.4 },
+        zoom: 10,
+      }}
+      myLocationEnabled={true}
+      onLoad={() => console.log('Map loaded')}
+    />
+  );
+}
+```
+
+## 📚 Feature Overview
+
+### 🗺️ Map Display
+- Multiple map types (normal, satellite, night, etc.)
+- Camera control (move, zoom, rotate, tilt)
+- Gesture control and UI control configuration
+- Zoom level limits
+
+### 📍 Location Features
+- Continuous and single location
+- Reverse geocoding (address resolution)
+- Location configuration (accuracy, interval, mode, etc.)
+- Custom location blue dot style
+
+### 🎨 Overlays
+- Circle
+- Marker
+- Polyline
+- Polygon
+- Support both declarative and imperative usage
+
+### 📝 More Examples
+
+For detailed usage examples, see: [EXAMPLES.en.md](docs/EXAMPLES.en.md)
+
+Includes:
+- Basic map application
+- Location tracking application
+- Overlay operation examples
+- Advanced usage and best practices
+
+## 📝 Documentation
+
+- [API Documentation](docs/API.en.md) - Complete API reference
+- [Usage Examples](docs/EXAMPLES.en.md) - Detailed code examples
+- [Initialization Guide](docs/INITIALIZATION.en.md) - SDK initialization and permission management
+- [Architecture Documentation](docs/ARCHITECTURE.en.md) - Project structure and file descriptions
+
+## 🎨 Advanced Usage
+
+### followUserLocation Explained
+
+`followUserLocation` controls whether the map automatically follows user location:
+
+**Browse Mode (default - `false`):**
+```tsx
+<MapView
+  myLocationEnabled={true}
+  followUserLocation={false}  // or omit
+/>
+```
+- ✅ Show location dot
+- ✅ User can freely scroll map
+- ✅ Map won't auto-move
+
+**Navigation Mode (`true`):**
+```tsx
+<MapView
+  myLocationEnabled={true}
+  followUserLocation={true}
+/>
+```
+- ✅ Show location dot
+- ✅ Map auto-follows user movement
+- ⚠️ Suitable for navigation scenarios
+
+### Imperative API Batch Operations
+
+```tsx
+const mapRef = useRef<MapViewRef>(null);
+
+// Add multiple overlays
+const addMultipleOverlays = async () => {
+  await mapRef.current?.addCircle('circle1', {
+    center: { latitude: 39.9, longitude: 116.4 },
+    radius: 1000,
+    fillColor: 0x8800FF00,
+  });
+  
+  await mapRef.current?.addCircle('circle2', {
+    center: { latitude: 40.0, longitude: 116.5 },
+    radius: 500,
+    fillColor: 0x880000FF,
+  });
+  
+  await mapRef.current?.addMarker('marker1', {
+    position: { latitude: 39.95, longitude: 116.45 },
+    title: 'Beijing',
+  });
+};
+
+// Batch clear
+const clearAll = async () => {
+  await mapRef.current?.removeCircle('circle1');
+  await mapRef.current?.removeCircle('circle2');
+  await mapRef.current?.removeMarker('marker1');
+};
+```
+
+### Color Format
+
+Overlay colors support two formats:
+
+1. **String format** (ARGB): `"#AARRGGBB"`
+   ```tsx
+   <Circle fillColor="#8800FF00" />  // 50% transparent green
+   ```
+
+2. **Number format** (imperative API): `0xAARRGGBB`
+   ```tsx
+   await mapRef.current?.addCircle('circle1', {
+     fillColor: 0x8800FF00,  // 50% transparent green
+   });
+   ```
+
+### Performance Optimization
+
+- ✅ Use imperative API for large numbers of overlays
+- ✅ Remove unnecessary overlays promptly
+- ✅ Avoid complex operations in high-frequency events like `onPress`
+- ✅ Don't set location interval too small (recommend >= 1000ms)
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome!
+
+## 📄 License
+
+MIT
+
+## 🔗 Related Links
+
+- [AMap Open Platform](https://lbs.amap.com/)
+- [AMap Android SDK](https://lbs.amap.com/api/android-sdk/summary)
+- [Expo Modules API](https://docs.expo.dev/modules/overview/)
+- [GitHub Repository](https://github.com/TomWq/expo-gaode-map)
+
+## 🙏 Acknowledgments
+
+This project referenced the following excellent projects during development:
+
+- **[react-native-amap3d](https://github.com/qiuxiang/react-native-amap3d)** - An excellent React Native AMap component that provided important references for this project's design and implementation
+
+Thanks to the contributors of these open-source projects for bringing valuable experience and code to the community.
+
+## 📮 Feedback and Support
+
+If you encounter problems or have suggestions:
+
+- 📝 Submit [GitHub Issue](https://github.com/TomWq/expo-gaode-map/issues)
+- 💬 Join [Discussions](https://github.com/TomWq/expo-gaode-map/discussions)
+- ⭐ Star the project to show support
+- 💬 Join QQ Group: 952241387

package/README.md

@@ -1,5 +1,7 @@
 # expo-gaode-map
 
+[English](./README.en.md) | 简体中文
+
 一个功能完整的高德地图 React Native 组件库，**基于 Expo Modules 开发**，提供地图显示、定位、覆盖物等功能：
 - Android: [高德地图 Android SDK](https://lbs.amap.com/api/android-sdk/summary)
 - iOS: [高德地图 iOS SDK](https://lbs.amap.com/api/ios-sdk/summary) 

package/android/src/main/java/expo/modules/gaodemap/ExpoGaodeMapModule.kt

@@ -1,20 +1,17 @@
 package expo.modules.gaodemap
 
-
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 import expo.modules.gaodemap.modules.SDKInitializer
 import expo.modules.gaodemap.modules.LocationManager
-import expo.modules.gaodemap.overlays.*
 
 /**
  * 高德地图 Expo 模块
- * 
+ *
  * 负责:
  * - SDK 初始化和版本管理
  * - 定位功能和配置
  * - 权限管理
- * - 地图视图和覆盖物注册
  */
 class ExpoGaodeMapModule : Module() {
 
@@ -317,302 +314,8 @@ class ExpoGaodeMapModule : Module() {
       handler.postDelayed(checkPermission, 100)
     }
 
-    // ==================== 事件 ====================
-
     Events("onLocationUpdate")
 
-    // ==================== 视图定义 ====================
-
-    View(ExpoGaodeMapView::class) {
-      
-      // 事件
-      Events("onMapPress", "onMapLongPress", "onLoad", "onMarkerPress", "onMarkerDragStart", "onMarkerDrag", "onMarkerDragEnd", "onCirclePress", "onPolygonPress", "onPolylinePress")
-
-      // 地图类型
-      Prop<Int>("mapType") { view, type ->
-        view.mapType = type
-        view.setMapType(type)
-      }
-
-      // 初始相机位置
-      Prop<Map<String, Any?>?>("initialCameraPosition") { view, position ->
-        view.initialCameraPosition = position
-        position?.let { view.setInitialCameraPosition(it) }
-      }
-
-      // 控件显示
-      Prop<Boolean>("zoomControlsEnabled") { view, show -> view.setShowsZoomControls(show) }
-      Prop<Boolean>("compassEnabled") { view, show -> view.setShowsCompass(show) }
-      Prop<Boolean>("scaleControlsEnabled") { view, show -> view.setShowsScale(show) }
-
-      // 手势控制
-      Prop<Boolean>("zoomGesturesEnabled") { view, enabled -> view.setZoomEnabled(enabled) }
-      Prop<Boolean>("scrollGesturesEnabled") { view, enabled -> view.setScrollEnabled(enabled) }
-      Prop<Boolean>("rotateGesturesEnabled") { view, enabled -> view.setRotateEnabled(enabled) }
-      Prop<Boolean>("tiltGesturesEnabled") { view, enabled -> view.setTiltEnabled(enabled) }
-      
-      // 缩放级别限制
-      Prop<Float>("maxZoom") { view, maxZoom -> view.setMaxZoom(maxZoom) }
-      Prop<Float>("minZoom") { view, minZoom -> view.setMinZoom(minZoom) }
-
-      // 地图图层
-      Prop<Boolean>("myLocationEnabled") { view, show -> view.setShowsUserLocation(show) }
-      Prop<Boolean>("followUserLocation") { view, follow -> view.setFollowUserLocation(follow) }
-      Prop<Map<String, Any>?>("userLocationRepresentation") { view, representation ->
-        representation?.let { view.setUserLocationRepresentation(it) }
-      }
-      Prop<Boolean>("trafficEnabled") { view, show -> view.setShowsTraffic(show) }
-      Prop<Boolean>("buildingsEnabled") { view, show -> view.setShowsBuildings(show) }
-      Prop<Boolean>("indoorViewEnabled") { view, show -> view.setShowsIndoorMap(show) }
-
-      // 生命周期方法
-      OnViewDidUpdateProps { view: ExpoGaodeMapView ->
-        if (view.mapType != 0) {
-          view.setMapType(view.mapType)
-        }
-        
-        view.initialCameraPosition?.let { position ->
-          view.setInitialCameraPosition(position)
-        }
-      }
-
-      // 相机控制方法
-      AsyncFunction("moveCamera") { view: ExpoGaodeMapView, position: Map<String, Any>, duration: Int ->
-        view.moveCamera(position, duration)
-      }
-
-      AsyncFunction("getLatLng") { view: ExpoGaodeMapView, point: Map<String, Double> ->
-        view.getLatLng(point)
-      }
-
-      AsyncFunction("setCenter") { view: ExpoGaodeMapView, center: Map<String, Double>, animated: Boolean ->
-        view.setCenter(center, animated)
-      }
-
-      AsyncFunction("setZoom") { view: ExpoGaodeMapView, zoom: Double, animated: Boolean ->
-        view.setZoomLevel(zoom.toFloat(), animated)
-      }
-
-      AsyncFunction("getCameraPosition") { view: ExpoGaodeMapView ->
-        view.getCameraPosition()
-      }
-      
-      // Circle 命令
-      AsyncFunction("addCircle") { view: ExpoGaodeMapView, id: String, props: Map<String, Any> ->
-        view.addCircle(id, props)
-      }
-      
-      AsyncFunction("removeCircle") { view: ExpoGaodeMapView, id: String ->
-        view.removeCircle(id)
-      }
-      
-      AsyncFunction("updateCircle") { view: ExpoGaodeMapView, id: String, props: Map<String, Any> ->
-        view.updateCircle(id, props)
-      }
-      
-      // Marker 命令
-      AsyncFunction("addMarker") { view: ExpoGaodeMapView, id: String, props: Map<String, Any> ->
-        view.addMarker(id, props)
-      }
-      
-      AsyncFunction("removeMarker") { view: ExpoGaodeMapView, id: String ->
-        view.removeMarker(id)
-      }
-      
-      AsyncFunction("updateMarker") { view: ExpoGaodeMapView, id: String, props: Map<String, Any> ->
-        view.updateMarker(id, props)
-      }
-      
-      // Polyline 命令
-      AsyncFunction("addPolyline") { view: ExpoGaodeMapView, id: String, props: Map<String, Any> ->
-        view.addPolyline(id, props)
-      }
-      
-      AsyncFunction("removePolyline") { view: ExpoGaodeMapView, id: String ->
-        view.removePolyline(id)
-      }
-      
-      AsyncFunction("updatePolyline") { view: ExpoGaodeMapView, id: String, props: Map<String, Any> ->
-        view.updatePolyline(id, props)
-      }
-      
-      // Polygon 命令
-      AsyncFunction("addPolygon") { view: ExpoGaodeMapView, id: String, props: Map<String, Any> ->
-        view.addPolygon(id, props)
-      }
-      
-      AsyncFunction("removePolygon") { view: ExpoGaodeMapView, id: String ->
-        view.removePolygon(id)
-      }
-      
-      AsyncFunction("updatePolygon") { view: ExpoGaodeMapView, id: String, props: Map<String, Any> ->
-        view.updatePolygon(id, props)
-      }
-    }
-
-    // ==================== 覆盖物视图注册 ====================
-    
-    // Marker - 标记点
-    View(MarkerView::class) {
-      Events("onPress", "onDragStart", "onDrag", "onDragEnd")
-      
-      Prop<Map<String, Double>>("position") { view: MarkerView, position ->
-        view.setPosition(position)
-      }
-      
-      Prop<String>("title") { view: MarkerView, title ->
-        view.setTitle(title)
-      }
-      
-      Prop<String>("description") { view: MarkerView, description ->
-        view.setDescription(description)
-      }
-      
-      Prop<Boolean>("draggable") { view: MarkerView, draggable ->
-        view.setDraggable(draggable)
-      }
-      
-      Prop<Float>("opacity") { view: MarkerView, opacity ->
-        view.setOpacity(opacity)
-      }
-      
-      Prop<Boolean>("flat") { view: MarkerView, flat ->
-        view.setFlat(flat)
-      }
-      
-      Prop<Float>("zIndex") { view: MarkerView, zIndex ->
-        view.setZIndex(zIndex)
-      }
-      
-      Prop<Map<String, Float>>("anchor") { view: MarkerView, anchor ->
-        view.setAnchor(anchor)
-      }
-    }
-    
-    // Circle - 圆形
-    View(CircleView::class) {
-      Events("onPress")
-      
-      Prop<Map<String, Double>>("center") { view, center ->
-        view.setCenter(center)
-      }
-      
-      Prop<Double>("radius") { view, radius ->
-        view.setRadius(radius)
-      }
-      
-      Prop<Int>("fillColor") { view, color ->
-        view.setFillColor(color)
-      }
-      
-      Prop<Int>("strokeColor") { view, color ->
-        view.setStrokeColor(color)
-      }
-      
-      Prop<Float>("strokeWidth") { view, width ->
-        view.setStrokeWidth(width)
-      }
-
-      Prop<Float>("zIndex") { view, zIndex ->
-        view.setZIndex(zIndex)
-      }
-    }
-    
-    // Polyline - 折线
-    View(PolylineView::class) {
-      Events("onPress")
-      
-      Prop<List<Map<String, Double>>>("points") { view: PolylineView, points ->
-        view.setPoints(points)
-      }
-      
-      Prop<Float>("strokeWidth") { view: PolylineView, width ->
-        view.setStrokeWidth(width)
-      }
-      
-      Prop<Int>("strokeColor") { view: PolylineView, color ->
-        view.setStrokeColor(color)
-      }
-      
-      Prop<String?>("texture") { view: PolylineView, texture ->
-        view.setTexture(texture)
-      }
-      
-      Prop<Boolean>("dotted") { view: PolylineView, dotted ->
-        view.setDotted(dotted)
-      }
-      
-      Prop<Boolean>("geodesic") { view: PolylineView, geodesic ->
-        view.setGeodesic(geodesic)
-      }
-      
-      Prop<Float>("zIndex") { view: PolylineView, zIndex ->
-        view.setZIndex(zIndex)
-      }
-    }
-    
-    // Polygon - 多边形
-    View(PolygonView::class) {
-      Events("onPress")
-      
-      Prop<List<Map<String, Double>>>("points") { view: PolygonView, points ->
-        view.setPoints(points)
-      }
-      
-      Prop<Int>("fillColor") { view: PolygonView, color ->
-        view.setFillColor(color)
-      }
-      
-      Prop<Int>("strokeColor") { view: PolygonView, color ->
-        view.setStrokeColor(color)
-      }
-      
-      Prop<Float>("strokeWidth") { view: PolygonView, width ->
-        view.setStrokeWidth(width)
-      }
-    }
-    
-    // MultiPoint - 海量点
-    View(MultiPointView::class) {
-      Events("onPress")
-      
-      Prop<List<Map<String, Any>>>("points") { view: MultiPointView, points ->
-        view.setPoints(points)
-      }
-    }
-    
-    // HeatMap - 热力图
-    View(HeatMapView::class) {
-      Prop<List<Map<String, Any>>>("data") { view: HeatMapView, data ->
-        view.setData(data)
-      }
-      
-      Prop<Int>("radius") { view: HeatMapView, radius ->
-        view.setRadius(radius)
-      }
-      
-      Prop<Double>("opacity") { view: HeatMapView, opacity ->
-        view.setOpacity(opacity)
-      }
-    }
-    
-    // Cluster - 点聚合
-    View(ClusterView::class) {
-      Events("onPress", "onClusterPress")
-      
-      Prop<List<Map<String, Any>>>("points") { view: ClusterView, points ->
-        view.setPoints(points)
-      }
-      
-      Prop<Int>("radius") { view: ClusterView, radius ->
-        view.setRadius(radius)
-      }
-      
-      Prop<Int>("minClusterSize") { view: ClusterView, size ->
-        view.setMinClusterSize(size)
-      }
-    }
-
     OnDestroy {
       locationManager?.destroy()
       locationManager = null

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

@@ -46,6 +46,7 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
   private val onMapPress by EventDispatcher()
   private val onMapLongPress by EventDispatcher()
   private val onLoad by EventDispatcher()
+  private val onLocation by EventDispatcher()
   private val onMarkerPress by EventDispatcher()
   private val onMarkerDragStart by EventDispatcher()
   private val onMarkerDrag by EventDispatcher()
@@ -80,7 +81,17 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
       
       // 初始化管理器
       cameraManager = CameraManager(aMap)
-      uiManager = UIManager(aMap, context)
+      uiManager = UIManager(aMap, context).apply {
+        // 设置定位变化回调
+        onLocationChanged = { latitude, longitude, accuracy ->
+          this@ExpoGaodeMapView.onLocation(mapOf(
+            "latitude" to latitude,
+            "longitude" to longitude,
+            "accuracy" to accuracy.toDouble(),
+            "timestamp" to System.currentTimeMillis()
+          ))
+        }
+      }
       overlayManager = OverlayManager(aMap, context).apply {
         onMarkerPress = { id, lat, lng ->
           this@ExpoGaodeMapView.onMarkerPress(mapOf(
@@ -479,12 +490,17 @@ class ExpoGaodeMapView(context: Context, appContext: AppContext) : ExpoView(cont
    * 添加子视图时自动连接到地图
    */
   override fun addView(child: View?, index: Int) {
+    if (child is MarkerView) {
+      // 不添加到视图层级,只调用 setMap
+      child.setMap(aMap)
+      return
+    }
+    
     super.addView(child, index)
     
-    // 自动将地图实例传递给覆盖物子视图
+    // 自动将地图实例传递给其他覆盖物子视图
     child?.let {
       when (it) {
-        is MarkerView -> it.setMap(aMap)
         is PolylineView -> it.setMap(aMap)
         is PolygonView -> it.setMap(aMap)
         is CircleView -> it.setMap(aMap)