expo-gaode-map 1.1.7 → 2.0.0-alpha.1

package/src/ExpoGaodeMapModule.ts

@@ -1,46 +1,235 @@
+/**
+ * 高德地图原生模块
+ * 提供 SDK 初始化、定位、权限管理等功能
+ */
+
 import { NativeModule, requireNativeModule } from 'expo';
 import type { ExpoGaodeMapModuleEvents } from './ExpoGaodeMap.types';
-import type { LatLng, CoordinateType } from './types';
+import type {
+  LatLng,
+  CoordinateType,
+  Coordinates,
+  ReGeocode,
+  LocationMode,
+  LocationAccuracy,
+} from './types';
+
+/**
+ * SDK 配置参数
+ */
+export interface SDKConfig {
+  /** Android 平台的高德地图 API Key */
+  androidKey?: string;
+  /** iOS 平台的高德地图 API Key */
+  iosKey?: string;
+}
+
+/**
+ * 权限状态
+ */
+export interface PermissionStatus {
+  /** 是否已授权 */
+  granted: boolean;
+  /** iOS 权限状态字符串 */
+  status?: 'notDetermined' | 'restricted' | 'denied' | 'authorizedAlways' | 'authorizedWhenInUse' | 'unknown';
+  /** Android 精确位置权限 */
+  fineLocation?: boolean;
+  /** Android 粗略位置权限 */
+  coarseLocation?: boolean;
+}
 
+/**
+ * 高德地图原生模块类声明
+ */
 declare class ExpoGaodeMapModule extends NativeModule<ExpoGaodeMapModuleEvents> {
-  // SDK 初始化
-  initSDK(config: { androidKey?: string; iosKey?: string }): void;
+  // ==================== SDK 初始化 ====================
+  
+  /**
+   * 初始化高德地图 SDK
+   * @param config SDK 配置参数，包含 Android 和 iOS 的 API Key
+   */
+  initSDK(config: SDKConfig): void;
+  
+  /**
+   * 获取高德地图 SDK 版本号
+   * @returns SDK 版本字符串
+   */
   getVersion(): string;
   
-  // 定位控制
+  // ==================== 定位控制 ====================
+  
+  /**
+   * 开始连续定位
+   * 启动后会持续接收位置更新，通过 onLocationUpdate 事件回调
+   */
   start(): void;
+  
+  /**
+   * 停止定位
+   * 停止接收位置更新
+   */
   stop(): void;
+  
+  /**
+   * 检查是否正在定位
+   * @returns Promise<boolean> 是否正在定位
+   */
   isStarted(): Promise<boolean>;
-  getCurrentLocation(): Promise<any>;
+  
+  /**
+   * 获取当前位置（单次定位）
+   * @returns Promise<Coordinates | ReGeocode> 位置信息，包含坐标和可选的逆地理编码信息
+   */
+  getCurrentLocation(): Promise<Coordinates | ReGeocode>;
+  
+  /**
+   * 坐标转换
+   * 将其他坐标系的坐标转换为高德地图使用的 GCJ-02 坐标系
+   * @param coordinate 需要转换的坐标
+   * @param type 原坐标系类型
+   * @returns Promise<LatLng> 转换后的 GCJ-02 坐标
+   */
   coordinateConvert(coordinate: LatLng, type: CoordinateType): Promise<LatLng>;
   
-  // 定位配置
+  // ==================== 定位配置 ====================
+  
+  /**
+   * 设置是否返回逆地理编码信息
+   * @param isReGeocode true: 返回地址信息; false: 只返回坐标
+   */
   setLocatingWithReGeocode(isReGeocode: boolean): void;
-  setLocationMode(mode: number): void;
+  
+  /**
+   * 设置定位模式（Android）
+   * @param mode 定位模式：0-低功耗, 1-仅设备, 2-高精度
+   */
+  setLocationMode(mode: LocationMode): void;
+  
+  /**
+   * 设置定位间隔（毫秒）
+   * @param interval 定位间隔时间，单位毫秒，默认 2000ms
+   */
   setInterval(interval: number): void;
+  
+  /**
+   * 设置是否单次定位（Android）
+   * @param isOnceLocation true: 单次定位; false: 连续定位
+   */
   setOnceLocation(isOnceLocation: boolean): void;
+  
+  /**
+   * 设置是否使用设备传感器（Android）
+   * @param sensorEnable true: 使用传感器; false: 不使用
+   */
   setSensorEnable(sensorEnable: boolean): void;
+  
+  /**
+   * 设置是否允许 WiFi 扫描（Android）
+   * @param wifiScan true: 允许; false: 不允许
+   */
   setWifiScan(wifiScan: boolean): void;
+  
+  /**
+   * 设置是否 GPS 优先（Android）
+   * @param gpsFirst true: GPS 优先; false: 网络优先
+   */
   setGpsFirst(gpsFirst: boolean): void;
+  
+  /**
+   * 设置是否等待 WiFi 列表刷新（Android）
+   * @param onceLocationLatest true: 等待; false: 不等待
+   */
   setOnceLocationLatest(onceLocationLatest: boolean): void;
+  
+  /**
+   * 设置逆地理编码语言
+   * @param language 语言代码，如 "zh-CN", "en"
+   */
   setGeoLanguage(language: string): void;
+  
+  /**
+   * 设置是否使用缓存策略（Android）
+   * @param locationCacheEnable true: 使用缓存; false: 不使用
+   */
   setLocationCacheEnable(locationCacheEnable: boolean): void;
+  
+  /**
+   * 设置网络请求超时时间（Android）
+   * @param httpTimeOut 超时时间，单位毫秒
+   */
   setHttpTimeOut(httpTimeOut: number): void;
-  setDesiredAccuracy(accuracy: number): void;
+  
+  /**
+   * 设置期望的定位精度（iOS）
+   * @param accuracy 精度级别：0-最佳, 1-10米, 2-100米, 3-1公里, 4-3公里
+   */
+  setDesiredAccuracy(accuracy: LocationAccuracy): void;
+  
+  /**
+   * 设置定位超时时间（秒）
+   * @param timeout 超时时间，单位秒，默认 10 秒
+   */
   setLocationTimeout(timeout: number): void;
+  
+  /**
+   * 设置逆地理编码超时时间（秒）
+   * @param timeout 超时时间，单位秒，默认 5 秒
+   */
   setReGeocodeTimeout(timeout: number): void;
+  
+  /**
+   * 设置距离过滤器（米）（iOS）
+   * 只有移动超过指定距离才会更新位置
+   * @param distance 距离阈值，单位米
+   */
   setDistanceFilter(distance: number): void;
+  
+  /**
+   * 设置是否自动暂停位置更新（iOS）
+   * @param pauses true: 自动暂停; false: 不暂停
+   */
   setPausesLocationUpdatesAutomatically(pauses: boolean): void;
+  
+  /**
+   * 设置是否允许后台定位（iOS）
+   * @param allows true: 允许; false: 不允许
+   */
   setAllowsBackgroundLocationUpdates(allows: boolean): void;
+  
+  /**
+   * 设置定位协议
+   * @param protocol 协议类型
+   */
   setLocationProtocol(protocol: string): void;
   
-  // 方向更新 (iOS)
+  // ==================== 方向更新 (iOS) ====================
+  
+  /**
+   * 开始更新设备方向（罗盘朝向）
+   * 通过 onHeadingUpdate 事件接收方向更新
+   * @platform ios
+   */
   startUpdatingHeading(): void;
+  
+  /**
+   * 停止更新设备方向
+   * @platform ios
+   */
   stopUpdatingHeading(): void;
   
-  // 权限
-  checkLocationPermission(): Promise<any>;
-  requestLocationPermission(): Promise<any>;
+  // ==================== 权限管理 ====================
+  
+  /**
+   * 检查位置权限状态
+   * @returns Promise<PermissionStatus> 权限状态
+   */
+  checkLocationPermission(): Promise<PermissionStatus>;
+  
+  /**
+   * 请求位置权限
+   * @returns Promise<PermissionStatus> 请求后的权限状态
+   */
+  requestLocationPermission(): Promise<PermissionStatus>;
 }
 
 export default requireNativeModule<ExpoGaodeMapModule>('ExpoGaodeMap');

package/src/ExpoGaodeMapView.tsx

@@ -1,41 +1,20 @@
 import { requireNativeViewManager } from 'expo-modules-core';
 import * as React from 'react';
-import { NativeSyntheticEvent } from 'react-native';
-import { EventManager } from './utils/EventManager';
+
 import type {
   MapViewProps,
   MapViewRef,
-  NativeMapViewRef,
   CameraPosition,
   LatLng,
   Point,
-  CircleProps,
-  MarkerProps,
-  PolylineProps,
-  PolygonProps,
+
 } from './types';
 
 export type { MapViewRef } from './types';
 
-const NativeView: React.ComponentType<MapViewProps & { ref?: React.Ref<NativeMapViewRef> }> = requireNativeViewManager('ExpoGaodeMapView');
-
-export const MapContext = React.createContext<React.RefObject<MapViewRef | null> | null>(null);
+const NativeView: React.ComponentType<MapViewProps & { ref?: React.Ref<MapViewRef> }> = requireNativeViewManager('ExpoGaodeMapView');
 
-type MarkerEventCallbacks = {
-  onPress?: (event: NativeSyntheticEvent<{}>) => void;
-  onDragStart?: (event: NativeSyntheticEvent<LatLng>) => void;
-  onDrag?: (event: NativeSyntheticEvent<LatLng>) => void;
-  onDragEnd?: (event: NativeSyntheticEvent<LatLng>) => void;
-};
 
-type OverlayEventCallbacks = {
-  onPress?: (event: NativeSyntheticEvent<{}>) => void;
-};
-
-export const MarkerEventContext = React.createContext<EventManager<MarkerEventCallbacks> | null>(null);
-export const CircleEventContext = React.createContext<EventManager<OverlayEventCallbacks> | null>(null);
-export const PolygonEventContext = React.createContext<EventManager<OverlayEventCallbacks> | null>(null);
-export const PolylineEventContext = React.createContext<EventManager<OverlayEventCallbacks> | null>(null);
 
 /**
  * 高德地图视图组件，提供地图操作API和覆盖物管理功能
@@ -56,55 +35,9 @@ export const PolylineEventContext = React.createContext<EventManager<OverlayEven
  * 所有API方法都会检查地图是否已初始化，未初始化时抛出错误
  */
 const ExpoGaodeMapView = React.forwardRef<MapViewRef, MapViewProps>((props, ref) => {
-  const nativeRef = React.useRef<NativeMapViewRef>(null);
+  const nativeRef = React.useRef<MapViewRef>(null);
   const internalRef = React.useRef<MapViewRef | null>(null);
-  const markerEventManager = React.useMemo(() => new EventManager<MarkerEventCallbacks>(), []);
-  const circleEventManager = React.useMemo(() => new EventManager<OverlayEventCallbacks>(), []);
-  const polygonEventManager = React.useMemo(() => new EventManager<OverlayEventCallbacks>(), []);
-  const polylineEventManager = React.useMemo(() => new EventManager<OverlayEventCallbacks>(), []);
-  const handleMarkerPress = (event: any) => {
-    const markerId = event.nativeEvent?.markerId;
-    if (markerId) markerEventManager.trigger(markerId, 'onPress', event);
-    props.onMarkerPress?.(event);
-  };
-  
-  const handleMarkerDragStart = (event: any) => {
-    const markerId = event.nativeEvent?.markerId;
-    if (markerId) markerEventManager.trigger(markerId, 'onDragStart', event);
-    props.onMarkerDragStart?.(event);
-  };
-  
-  const handleMarkerDrag = (event: any) => {
-    const markerId = event.nativeEvent?.markerId;
-    if (markerId) markerEventManager.trigger(markerId, 'onDrag', event);
-    props.onMarkerDrag?.(event);
-  };
-  
-  const handleMarkerDragEnd = (event: any) => {
-    const markerId = event.nativeEvent?.markerId;
-    if (markerId) {
-      markerEventManager.trigger(markerId, 'onDragEnd', event);
-    }
-    props.onMarkerDragEnd?.(event);
-  };
-  
-  const handleCirclePress = (event: any) => {
-    const circleId = event.nativeEvent?.circleId;
-    if (circleId) circleEventManager.trigger(circleId, 'onPress', event);
-    props.onCirclePress?.(event);
-  };
   
-  const handlePolygonPress = (event: any) => {
-    const polygonId = event.nativeEvent?.polygonId;
-    if (polygonId) polygonEventManager.trigger(polygonId, 'onPress', event);
-    props.onPolygonPress?.(event);
-  };
-  
-  const handlePolylinePress = (event: any) => {
-    const polylineId = event.nativeEvent?.polylineId;
-    if (polylineId) polylineEventManager.trigger(polylineId, 'onPress', event);
-    props.onPolylinePress?.(event);
-  };
 
   const apiRef: MapViewRef = React.useMemo(() => ({
     /**
@@ -156,137 +89,8 @@ const ExpoGaodeMapView = React.forwardRef<MapViewRef, MapViewProps>((props, ref)
     getCameraPosition: async () => {
       if (!nativeRef.current) throw new Error('MapView not initialized');
       return nativeRef.current.getCameraPosition();
-    },
-    /**
-     * 在地图上添加圆形覆盖物
-     * @param id - 圆形覆盖物的唯一标识符
-     * @param props - 圆形覆盖物的属性配置
-     * @returns Promise<void> 添加操作的异步结果
-     * @throws 如果地图视图未初始化，抛出错误'MapView not initialized'
-     */
-    addCircle: async (id: string, props: CircleProps) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.addCircle(id, props);
-    },
-    /**
-     * 从地图上移除指定的圆形覆盖物
-     * @param id - 要移除的圆形覆盖物的唯一标识符
-     * @throws 如果地图视图未初始化，抛出错误
-     * @returns Promise<void> 异步操作完成
-     */
-    removeCircle: async (id: string) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.removeCircle(id);
-    },
-    /**
-     * 更新地图上的圆形覆盖物
-     * @param id 要更新的圆形覆盖物的唯一标识符
-     * @param props 要更新的圆形属性（部分属性）
-     * @throws 如果地图视图未初始化，抛出错误
-     * @returns Promise<void> 表示更新操作完成
-     */
-    updateCircle: async (id: string, props: Partial<CircleProps>) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.updateCircle(id, props);
-    },
-    /**
-     * 添加一个标记点到地图上
-     * @param id 标记点的唯一标识符
-     * @param props 标记点的配置属性
-     * @returns Promise<void> 添加操作完成后的Promise
-     * @throws 如果地图视图未初始化则抛出错误
-     */
-    addMarker: async (id: string, props: MarkerProps) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.addMarker(id, props);
-    },
-    /**
-     * 从地图上移除指定ID的标记点
-     * @param id 要移除的标记点ID
-     * @throws 如果地图视图未初始化则抛出错误
-     * @returns Promise<void> 异步操作完成
-     */
-    removeMarker: async (id: string) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.removeMarker(id);
-    },
-    /**
-     * 更新地图上指定ID的标记点属性
-     * @param id - 要更新的标记点唯一标识符
-     * @param props - 需要更新的标记点属性对象（部分属性）
-     * @throws 如果地图视图未初始化则抛出错误
-     * @returns Promise对象，表示异步更新操作
-     */
-    updateMarker: async (id: string, props: Partial<MarkerProps>) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.updateMarker(id, props);
-    },
-    /**
-     * 添加折线覆盖物到地图
-     * @param id - 折线的唯一标识符
-     * @param props - 折线的配置属性
-     * @returns Promise<void> 添加操作的异步结果
-     * @throws 如果地图视图未初始化则抛出错误
-     */
-    addPolyline: async (id: string, props: PolylineProps) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.addPolyline(id, props);
-    },
-    /**
-     * 移除地图上的指定折线
-     * @param id - 要移除的折线的唯一标识符
-     * @throws 如果地图视图未初始化，抛出错误
-     * @returns Promise<void>
-     */
-    removePolyline: async (id: string) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.removePolyline(id);
-    },
-    /**
-     * 更新地图上的折线覆盖物
-     * 
-     * @param id 要更新的折线覆盖物的唯一标识符
-     * @param props 要更新的折线属性，包含部分PolylineProps属性
-     * @returns Promise<void> 异步操作结果
-     * @throws 如果地图视图未初始化，抛出错误
-     */
-    updatePolyline: async (id: string, props: Partial<PolylineProps>) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.updatePolyline(id, props);
-    },
-    /**
-     * 向地图添加多边形覆盖物
-     * @param id - 多边形的唯一标识符
-     * @param props - 多边形的配置属性
-     * @returns Promise<void> 添加操作的异步结果
-     * @throws 如果地图视图未初始化则抛出错误
-     */
-    addPolygon: async (id: string, props: PolygonProps) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.addPolygon(id, props);
-    },
-    /**
-     * 移除地图上的多边形覆盖物
-     * @param id - 要移除的多边形覆盖物的唯一标识符
-     * @throws 如果地图视图未初始化，抛出错误 'MapView not initialized'
-     * @returns Promise<void> 异步操作完成
-     */
-    removePolygon: async (id: string) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.removePolygon(id);
-    },
-    /**
-     * 更新多边形覆盖物的属性
-     * 
-     * @param id - 要更新的多边形覆盖物的唯一标识符
-     * @param props - 要更新的多边形属性对象，包含需要更新的部分属性
-     * @throws {Error} 当地图视图未初始化时抛出错误
-     * @returns Promise<void> 异步操作完成后的Promise
-     */
-    updatePolygon: async (id: string, props: Partial<PolygonProps>) => {
-      if (!nativeRef.current) throw new Error('MapView not initialized');
-      return nativeRef.current.updatePolygon(id, props);
-    },
+    }
+
   }), []);
 
   /**
@@ -304,29 +108,11 @@ const ExpoGaodeMapView = React.forwardRef<MapViewRef, MapViewProps>((props, ref)
   React.useImperativeHandle(ref, () => apiRef, [apiRef]);
 
   return (
-    <MapContext.Provider value={internalRef}>
-      <MarkerEventContext.Provider value={markerEventManager}>
-        <CircleEventContext.Provider value={circleEventManager}>
-          <PolygonEventContext.Provider value={polygonEventManager}>
-            <PolylineEventContext.Provider value={polylineEventManager}>
-              <NativeView
-                ref={nativeRef}
-                {...props}
-                onMarkerPress={handleMarkerPress}
-                onMarkerDragStart={handleMarkerDragStart}
-                onMarkerDrag={handleMarkerDrag}
-                onMarkerDragEnd={handleMarkerDragEnd}
-                onCirclePress={handleCirclePress}
-                onPolygonPress={handlePolygonPress}
-                onPolylinePress={handlePolylinePress}
-              >
-                {props.children}
-              </NativeView>
-            </PolylineEventContext.Provider>
-          </PolygonEventContext.Provider>
-        </CircleEventContext.Provider>
-      </MarkerEventContext.Provider>
-    </MapContext.Provider>
+    <NativeView
+        ref={nativeRef}
+          {...props}>
+          {props.children}
+        </NativeView>
   );
 });
 

package/src/components/overlays/Circle.tsx

@@ -1,111 +1,19 @@
-/*
- * @Author       : 尚博信_王强 wangqiang03@sunboxsoft.com
- * @Date         : 2025-11-13 15:02:04
- * @LastEditors  : 尚博信_王强 wangqiang03@sunboxsoft.com
- * @LastEditTime : 2025-11-21 10:36:10
- * @FilePath     : /expo-gaode-map/src/components/overlays/Circle.tsx
- * @Description  :
- *
- * Copyright (c) 2025 by 尚博信_王强, All Rights Reserved.
- */
 import * as React from 'react';
 import { requireNativeViewManager } from 'expo-modules-core';
 import type { CircleProps } from '../../types';
-import { MapContext, CircleEventContext } from '../../ExpoGaodeMapView';
 
-const NativeCircleView = requireNativeViewManager('CircleView');
+const NativeCircleView = requireNativeViewManager<CircleProps>('CircleView');
 
-export default function Circle(props: CircleProps) {
-  // 如果有 children，使用声明式 API
-  if (props.children) {
-    return <CircleDeclarative {...props} />;
-  }
-  // 否则使用命令式 API
-  return <CircleImperative {...props} />;
-}
-
-function CircleDeclarative(props: CircleProps) {
-  const eventManager = React.useContext(CircleEventContext);
-  const circleIdRef = React.useRef(`circle_${Date.now()}_${Math.random()}`);
-  
-  React.useEffect(() => {
-    if (eventManager) {
-      eventManager.register(circleIdRef.current, {
-        onPress: props.onPress,
-      });
-    }
-    return () => {
-      if (eventManager) {
-        eventManager.unregister(circleIdRef.current);
-      }
-    };
-  }, [props.onPress]);
-  
-  return (
-    <NativeCircleView
-      {...props}
-    >
-      {props.children}
-    </NativeCircleView>
-  );
+/**
+ * 高德地图圆形覆盖物组件（声明式）
+ *
+ *
+ * @param props 圆形组件的属性配置
+ * @returns 渲染原生圆形组件
+ */
+function Circle(props: CircleProps) {
+  return <NativeCircleView {...props} />;
 }
 
-function CircleImperative(props: CircleProps) {
-  const mapRef = React.useContext(MapContext);
-  const eventManager = React.useContext(CircleEventContext);
-  const circleIdRef = React.useRef<string | null>(null);
-  const propsRef = React.useRef(props);
-  
-  React.useEffect(() => {
-    propsRef.current = props;
-  }, [props]);
-  
-  React.useEffect(() => {
-    const checkAndAdd = () => {
-      if (!mapRef?.current) {
-        setTimeout(checkAndAdd, 50);
-        return;
-      }
-      
-      const circleId = `circle_${Date.now()}_${Math.random()}`;
-      circleIdRef.current = circleId;
-      
-      if (eventManager && props.onPress) {
-        eventManager.register(circleId, {
-          onPress: props.onPress,
-        });
-      }
-      
-      mapRef.current.addCircle(circleId, propsRef.current);
-    };
-    
-    checkAndAdd();
-    
-    return () => {
-      if (circleIdRef.current) {
-        if (eventManager) {
-          eventManager.unregister(circleIdRef.current);
-        }
-        if (mapRef?.current) {
-          mapRef.current.removeCircle(circleIdRef.current);
-        }
-      }
-    };
-  }, []);
-
-  React.useEffect(() => {
-    if (circleIdRef.current && eventManager) {
-      eventManager.register(circleIdRef.current, {
-        onPress: props.onPress,
-      });
-    }
-  }, [props.onPress]);
-
-  React.useEffect(() => {
-    if (circleIdRef.current && mapRef?.current) {
-      mapRef.current.updateCircle(circleIdRef.current, props);
-    }
-  }, [props.center, props.radius, props.fillColor, props.strokeColor, props.strokeWidth]);
-  
-  return null;
-}
+// 导出优化后的组件
+export default React.memo(Circle);

package/src/components/overlays/Cluster.tsx

@@ -5,7 +5,6 @@ import type { ClusterProps } from '../../types';
 
 const NativeCluster = requireNativeViewManager('ClusterView');
 
-
 /**
  * 高德地图点聚合组件
  *