expo-gaode-map 1.0.5 → 1.0.7

package/docs/EXAMPLES.en.md

@@ -0,0 +1,642 @@
+# Usage Examples
+
+English | [简体中文](./EXAMPLES.md)
+
+Complete usage examples and best practices.
+
+> 📖 **Recommended Reading**: [Initialization Guide](./INITIALIZATION.en.md) - Detailed initialization process and permission handling
+
+## Table of Contents
+
+- [Complete Application Example](#complete-application-example)
+- [Basic Map Application](#basic-map-application)
+- [Location Tracking Application](#location-tracking-application)
+- [Overlay Examples](#overlay-examples)
+- [Advanced Usage](#advanced-usage)
+
+## Complete Application Example
+
+Complete example with permission management, error handling, and loading states:
+
+```tsx
+import { useEffect, useState } from 'react';
+import { View, Text, Alert, Linking, Platform } from 'react-native';
+import {
+  MapView,
+  initSDK,
+  checkLocationPermission,
+  requestLocationPermission,
+  getCurrentLocation,
+  type LatLng,
+} from 'expo-gaode-map';
+
+export default function App() {
+  const [initialPosition, setInitialPosition] = useState<{
+    target: LatLng;
+    zoom: number;
+  } | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const initialize = async () => {
+      try {
+        // 1. Initialize SDK
+        initSDK({
+          androidKey: 'your-android-api-key',
+          iosKey: 'your-ios-api-key',
+        });
+        
+        // 2. Check permission
+        const status = await checkLocationPermission();
+        
+        // 3. Request permission if needed
+        if (!status.granted) {
+          const result = await requestLocationPermission();
+          
+          if (!result.granted) {
+            // Permission denied
+            setInitialPosition({
+              target: { latitude: 39.9, longitude: 116.4 },
+              zoom: 10
+            });
+            
+            // Guide user to settings
+            if (!result.canAskAgain) {
+              Alert.alert(
+                'Location Permission Required',
+                'Please enable location permission in settings',
+                [
+                  { text: 'Cancel' },
+                  { text: 'Settings', onPress: () => {
+                    if (Platform.OS === 'ios') {
+                      Linking.openURL('app-settings:');
+                    } else {
+                      Linking.openSettings();
+                    }
+                  }}
+                ]
+              );
+            }
+            return;
+          }
+        }
+        
+        // 4. Get location
+        const location = await getCurrentLocation();
+        setInitialPosition({
+          target: {
+            latitude: location.latitude,
+            longitude: location.longitude
+          },
+          zoom: 15
+        });
+        
+      } catch (err) {
+        console.error('Initialization failed:', err);
+        setError('Initialization failed');
+        setInitialPosition({
+          target: { latitude: 39.9, longitude: 116.4 },
+          zoom: 10
+        });
+      }
+    };
+
+    initialize();
+  }, []);
+
+  // Loading state
+  if (!initialPosition && !error) {
+    return (
+      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+        <Text>Loading map...</Text>
+      </View>
+    );
+  }
+
+  // Error state
+  if (error) {
+    return (
+      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+        <Text>{error}</Text>
+      </View>
+    );
+  }
+
+  return (
+    <MapView
+      style={{ flex: 1 }}
+      initialCameraPosition={initialPosition!}
+      myLocationEnabled={true}
+      onLoad={() => console.log('Map loaded')}
+    />
+  );
+}
+```
+
+## Basic Map Application
+
+```tsx
+import React, { useRef, useEffect } from 'react';
+import { View, StyleSheet, Button } from 'react-native';
+import { 
+  MapView, 
+  initSDK,
+  Circle,
+  Marker,
+  Polyline,
+  Polygon,
+  type MapViewRef 
+} from 'expo-gaode-map';
+
+export default function App() {
+  const mapRef = useRef<MapViewRef>(null);
+
+  useEffect(() => {
+    const initialize = async () => {
+      initSDK({
+        androidKey: 'your-android-api-key',
+        iosKey: 'your-ios-api-key',
+      });
+      
+      // Check and request permission
+      const status = await checkLocationPermission();
+      if (!status.granted) {
+        await requestLocationPermission();
+      }
+    };
+    
+    initialize();
+  }, []);
+
+  const handleMoveCamera = async () => {
+    await mapRef.current?.moveCamera(
+      {
+        target: { latitude: 40.0, longitude: 116.5 },
+        zoom: 15,
+      },
+      1000
+    );
+  };
+
+  return (
+    <View style={styles.container}>
+      <MapView
+        ref={mapRef}
+        style={styles.map}
+        initialCameraPosition={{
+          target: { latitude: 39.9, longitude: 116.4 },
+          zoom: 10,
+        }}
+        myLocationEnabled={true}
+        followUserLocation={false}
+        trafficEnabled={true}
+        onMapPress={(e) => console.log('Map pressed', e)}
+        onLoad={() => console.log('Map loaded')}
+      >
+        {/* Circle overlay */}
+        <Circle
+          center={{ latitude: 39.9, longitude: 116.4 }}
+          radius={1000}
+          fillColor="#8800FF00"
+          strokeColor="#FFFF0000"
+          strokeWidth={2}
+        />
+
+        {/* Marker */}
+        <Marker
+          position={{ latitude: 39.95, longitude: 116.45 }}
+          title="This is a marker"
+          draggable={true}
+        />
+
+        {/* Polyline */}
+        <Polyline
+          points={[
+            { latitude: 39.9, longitude: 116.4 },
+            { latitude: 39.95, longitude: 116.45 },
+            { latitude: 40.0, longitude: 116.5 },
+          ]}
+          width={5}
+          color="#FF0000FF"
+        />
+
+        {/* Polygon */}
+        <Polygon
+          points={[
+            { latitude: 39.85, longitude: 116.35 },
+            { latitude: 39.85, longitude: 116.45 },
+            { latitude: 39.75, longitude: 116.40 },
+          ]}
+          fillColor="#880000FF"
+          strokeColor="#FFFF0000"
+          strokeWidth={2}
+        />
+      </MapView>
+
+      <View style={styles.controls}>
+        <Button title="Move Camera" onPress={handleMoveCamera} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  map: {
+    flex: 1,
+  },
+  controls: {
+    position: 'absolute',
+    bottom: 20,
+    left: 20,
+    right: 20,
+  },
+});
+```
+
+## Location Tracking Application
+
+```tsx
+import React, { useEffect, useState } from 'react';
+import { View, Text, Button, StyleSheet } from 'react-native';
+import { 
+  MapView,
+  initSDK,
+  configure,
+  start,
+  stop,
+  getCurrentLocation,
+  addLocationListener,
+  type Location,
+} from 'expo-gaode-map';
+
+export default function LocationApp() {
+  const [location, setLocation] = useState<Location | null>(null);
+  const [isTracking, setIsTracking] = useState(false);
+
+  useEffect(() => {
+    const initialize = async () => {
+      // Initialize SDK
+      initSDK({
+        androidKey: 'your-android-api-key',
+        iosKey: 'your-ios-api-key',
+      });
+
+      // Check and request permission
+      const status = await checkLocationPermission();
+      if (!status.granted) {
+        await requestLocationPermission();
+      }
+
+      // Configure location parameters
+      configure({
+        withReGeocode: true,
+        mode: 0,
+        interval: 2000,
+      });
+
+      // Listen to location updates
+      const subscription = addLocationListener((loc) => {
+        console.log('Location update:', loc);
+        setLocation(loc);
+      });
+
+      return () => subscription.remove();
+    };
+
+    initialize();
+  }, []);
+
+  const handleStartTracking = () => {
+    start();
+    setIsTracking(true);
+  };
+
+  const handleStopTracking = () => {
+    stop();
+    setIsTracking(false);
+  };
+
+  const handleGetLocation = async () => {
+    try {
+      const loc = await getCurrentLocation();
+      setLocation(loc);
+    } catch (error) {
+      console.error('Get location failed:', error);
+    }
+  };
+
+  return (
+    <View style={styles.container}>
+      <MapView
+        style={styles.map}
+        myLocationEnabled={true}
+        followUserLocation={isTracking}
+        initialCameraPosition={{
+          target: { 
+            latitude: location?.latitude || 39.9, 
+            longitude: location?.longitude || 116.4 
+          },
+          zoom: 15,
+        }}
+      />
+
+      {location && (
+        <View style={styles.info}>
+          <Text style={styles.infoText}>
+            Latitude: {location.latitude.toFixed(6)}
+          </Text>
+          <Text style={styles.infoText}>
+            Longitude: {location.longitude.toFixed(6)}
+          </Text>
+          <Text style={styles.infoText}>
+            Accuracy: {location.accuracy.toFixed(2)} m
+          </Text>
+          {location.address && (
+            <Text style={styles.infoText}>
+              Address: {location.address}
+            </Text>
+          )}
+        </View>
+      )}
+
+      <View style={styles.controls}>
+        <Button 
+          title="Get Location" 
+          onPress={handleGetLocation} 
+        />
+        <View style={{ height: 10 }} />
+        <Button 
+          title={isTracking ? 'Stop Tracking' : 'Start Tracking'}
+          onPress={isTracking ? handleStopTracking : handleStartTracking}
+          color={isTracking ? '#FF3B30' : '#007AFF'}
+        />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  map: {
+    flex: 1,
+  },
+  info: {
+    position: 'absolute',
+    top: 50,
+    left: 20,
+    right: 20,
+    backgroundColor: 'white',
+    padding: 15,
+    borderRadius: 10,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.25,
+    shadowRadius: 3.84,
+    elevation: 5,
+  },
+  infoText: {
+    fontSize: 14,
+    marginBottom: 5,
+    color: '#333',
+  },
+  controls: {
+    position: 'absolute',
+    bottom: 30,
+    left: 20,
+    right: 20,
+  },
+});
+```
+
+## Overlay Examples
+
+### Circle
+
+**Declarative usage:**
+```tsx
+<MapView style={{ flex: 1 }}>
+  <Circle
+    center={{ latitude: 39.9, longitude: 116.4 }}
+    radius={1000}
+    fillColor="#8800FF00"
+    strokeColor="#FFFF0000"
+    strokeWidth={2}
+    onPress={() => console.log('Circle pressed')}
+  />
+</MapView>
+```
+
+**Imperative usage:**
+```tsx
+const mapRef = useRef<MapViewRef>(null);
+
+await mapRef.current?.addCircle('circle1', {
+  center: { latitude: 39.9, longitude: 116.4 },
+  radius: 1000,
+  fillColor: 0x8800FF00,
+  strokeColor: 0xFFFF0000,
+  strokeWidth: 2,
+});
+
+await mapRef.current?.updateCircle('circle1', {
+  radius: 2000,
+});
+
+await mapRef.current?.removeCircle('circle1');
+```
+
+### Marker
+
+**Declarative usage:**
+```tsx
+<MapView style={{ flex: 1 }}>
+  <Marker
+    position={{ latitude: 39.9, longitude: 116.4 }}
+    title="Title"
+    snippet="Description"
+    draggable={true}
+    onPress={() => console.log('Marker pressed')}
+    onDragEnd={(e) => console.log('Drag ended', e.nativeEvent)}
+  />
+</MapView>
+```
+
+**Imperative usage:**
+```tsx
+await mapRef.current?.addMarker('marker1', {
+  position: { latitude: 39.9, longitude: 116.4 },
+  title: 'Title',
+  snippet: 'Description',
+  draggable: true,
+});
+
+await mapRef.current?.updateMarker('marker1', {
+  position: { latitude: 40.0, longitude: 116.5 },
+});
+
+await mapRef.current?.removeMarker('marker1');
+```
+
+> **⚠️ Limitation**: Markers added via imperative API **do not support event callbacks** (onPress, onDragEnd, etc.). Use declarative `<Marker>` component for event handling.
+
+### Polyline
+
+**Declarative usage - Normal polyline:**
+```tsx
+<MapView style={{ flex: 1 }}>
+  <Polyline
+    points={[
+      { latitude: 39.9, longitude: 116.4 },
+      { latitude: 39.95, longitude: 116.45 },
+      { latitude: 40.0, longitude: 116.5 },
+    ]}
+    width={5}
+    color="#FFFF0000"
+    onPress={() => console.log('Polyline pressed')}
+  />
+</MapView>
+```
+
+**Declarative usage - Textured polyline:**
+```tsx
+import { Image } from 'react-native';
+
+const iconUri = Image.resolveAssetSource(require('./assets/arrow.png')).uri;
+
+<MapView style={{ flex: 1 }}>
+  <Polyline
+    points={[
+      { latitude: 39.9, longitude: 116.4 },
+      { latitude: 39.95, longitude: 116.45 },
+      { latitude: 40.0, longitude: 116.5 },
+    ]}
+    width={20}
+    color="#FFFF0000"
+    texture={iconUri}
+    onPress={() => console.log('Textured polyline pressed')}
+  />
+</MapView>
+```
+
+> **Note**:
+> - Color format uses ARGB (`#AARRGGBB`), e.g., `#FFFF0000` for opaque red
+> - `texture` supports network images (http/https) and local files (file://)
+> - Texture tiles along the polyline direction
+> - Recommend larger `width` values (e.g., 20) for better texture display
+> - **Segment Texture Limitation**: Single Polyline can only have one texture. For different textures on segments, create multiple Polyline components
+
+### Polygon
+
+**Declarative usage:**
+```tsx
+<MapView style={{ flex: 1 }}>
+  <Polygon
+    points={[
+      { latitude: 39.9, longitude: 116.3 },
+      { latitude: 39.9, longitude: 116.4 },
+      { latitude: 39.8, longitude: 116.4 },
+    ]}
+    fillColor="#8800FF00"
+    strokeColor="#FFFF0000"
+    strokeWidth={2}
+    onPress={() => console.log('Polygon pressed')}
+  />
+</MapView>
+```
+
+**Imperative usage:**
+```tsx
+await mapRef.current?.addPolygon('polygon1', {
+  points: [
+    { latitude: 39.9, longitude: 116.3 },
+    { latitude: 39.9, longitude: 116.4 },
+    { latitude: 39.8, longitude: 116.4 },
+  ],
+  fillColor: 0x8800FF00,
+  strokeColor: 0xFFFF0000,
+  strokeWidth: 2,
+});
+```
+
+## Advanced Usage
+
+### Custom Location Blue Dot
+
+```tsx
+import { Image } from 'react-native';
+
+const iconUri = Image.resolveAssetSource(require('./assets/location-icon.png')).uri;
+
+<MapView
+  myLocationEnabled={true}
+  userLocationRepresentation={{
+    showsAccuracyRing: true,
+    fillColor: '#4285F4',
+    strokeColor: '#1967D2',
+    lineWidth: 2,
+    image: iconUri,
+    imageWidth: 40,
+    imageHeight: 40,
+  }}
+/>
+```
+
+### Batch Overlay Operations
+
+```tsx
+const mapRef = useRef<MapViewRef>(null);
+
+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',
+  });
+};
+
+const clearAll = async () => {
+  await mapRef.current?.removeCircle('circle1');
+  await mapRef.current?.removeCircle('circle2');
+  await mapRef.current?.removeMarker('marker1');
+};
+```
+
+### Zoom Level Limits
+
+```tsx
+<MapView
+  maxZoom={18}
+  minZoom={5}
+  initialCameraPosition={{
+    target: { latitude: 39.9, longitude: 116.4 },
+    zoom: 10,
+  }}
+/>
+```
+
+### Heading Updates (iOS)
+
+```tsx
+import { startUpdatingHeading, stopUpdatingHeading } from 'expo-gaode-map';
+
+// Start heading updates
+startUpdatingHeading();
+
+// Stop heading updates
+stopUpdatingHeading();

package/docs/EXAMPLES.md

@@ -1,5 +1,7 @@
 # 使用示例
 
+[English](./EXAMPLES.en.md) | 简体中文
+
 完整的使用示例和最佳实践。
 
 > 📖 **推荐阅读**: [初始化指南](./INITIALIZATION.md) - 详细的初始化流程和权限处理