expo-gaode-map-navigation 1.0.1-next.0

package/src/map/ExpoGaodeMapView.tsx

@@ -0,0 +1,120 @@
+import { requireNativeViewManager } from 'expo-modules-core';
+import * as React from 'react';
+
+import type {
+  MapViewProps,
+  MapViewRef,
+  CameraPosition,
+  LatLng,
+  Point,
+
+} from './types';
+
+export type { MapViewRef } from './types';
+
+const NativeView: React.ComponentType<MapViewProps & { ref?: React.Ref<MapViewRef> }> = requireNativeViewManager('NaviMapView');
+
+
+/**
+ * 高德地图视图组件，提供地图操作API和覆盖物管理功能
+ * 
+ * @param props - 组件属性
+ * @param ref - 外部ref引用，用于访问地图API方法
+ * @returns 返回包含地图视图和上下文提供者的React组件
+ * 
+ * @remarks
+ * 该组件内部维护两个ref：
+ * - nativeRef: 指向原生地图视图的引用
+ * - internalRef: 内部使用的API引用，通过MapContext共享
+ * 
+ * 提供的主要API功能包括：
+ * - 相机控制（移动、缩放、获取当前位置）
+ * - 覆盖物管理（添加/删除/更新标记、折线、多边形、圆形等）
+ * 
+ * 所有API方法都会检查地图是否已初始化，未初始化时抛出错误
+ */
+const ExpoGaodeMapView = React.forwardRef<MapViewRef, MapViewProps>((props, ref) => {
+  const nativeRef = React.useRef<MapViewRef>(null);
+  const internalRef = React.useRef<MapViewRef | null>(null);
+  
+
+  const apiRef: MapViewRef = React.useMemo(() => ({
+    /**
+     * 移动地图相机到指定位置
+     * @param position 相机位置参数对象，包含目标经纬度、缩放级别等信息
+     * @param duration 动画持续时间（毫秒），默认300毫秒
+     * @throws 如果地图视图未初始化则抛出错误
+     * @returns Promise<void> 异步操作完成后的Promise
+     */
+    moveCamera: async (position: CameraPosition, duration: number = 300) => {
+      if (!nativeRef.current) throw new Error('MapView not initialized');
+      return nativeRef.current.moveCamera(position, duration);
+    },
+    /**
+     * 将屏幕坐标点转换为地理坐标（经纬度）
+     * @param point 屏幕坐标点 {x: number, y: number}
+     * @returns 返回Promise，解析为对应的地理坐标 {latitude: number, longitude: number}
+     * @throws 如果地图视图未初始化，抛出错误 'MapView not initialized'
+     */
+    getLatLng: async (point: Point) => {
+      if (!nativeRef.current) throw new Error('MapView not initialized');
+      return nativeRef.current.getLatLng(point);
+    },
+    /**
+     * 设置地图中心点坐标
+     * @param center 要设置的中心点坐标(LatLng格式)
+     * @param animated 是否使用动画效果移动地图(默认为false)
+     * @throws 如果地图视图未初始化则抛出错误
+     */
+    setCenter: async (center: LatLng, animated: boolean = false) => {
+      if (!nativeRef.current) throw new Error('MapView not initialized');
+      return nativeRef.current.setCenter(center, animated);
+    },
+    /**
+     * 设置地图的缩放级别
+     * @param zoom 目标缩放级别
+     * @param animated 是否使用动画过渡效果，默认为false
+     * @throws 如果地图视图未初始化，抛出错误
+     */
+    setZoom: async (zoom: number, animated: boolean = false) => {
+      if (!nativeRef.current) throw new Error('MapView not initialized');
+      return nativeRef.current.setZoom(zoom, animated);
+    },
+    /**
+     * 获取当前地图的相机位置（视角中心点、缩放级别、倾斜角度等）
+     * @returns 返回一个Promise，解析为当前相机位置的对象
+     * @throws 如果地图视图未初始化，则抛出错误
+     */
+    getCameraPosition: async () => {
+      if (!nativeRef.current) throw new Error('MapView not initialized');
+      return nativeRef.current.getCameraPosition();
+    }
+
+  }), []);
+
+  /**
+   * 将传入的apiRef赋值给internalRef.current
+   * 用于在组件内部保存对地图API实例的引用
+   */
+  React.useEffect(() => {
+    internalRef.current = apiRef;
+  }, [apiRef]);
+
+  /**
+   * 获取当前地图实例的API引用
+   * @returns 返回地图API的引用对象，可用于调用地图相关方法
+   */
+  React.useImperativeHandle(ref, () => apiRef, [apiRef]);
+
+  return (
+    <NativeView
+        ref={nativeRef}
+          {...props}>
+          {props.children}
+        </NativeView>
+  );
+});
+
+ExpoGaodeMapView.displayName = 'ExpoGaodeMapView';
+
+export default ExpoGaodeMapView;

package/src/map/components/overlays/Circle.tsx

@@ -0,0 +1,20 @@
+
+import * as React from 'react';
+import { requireNativeViewManager } from 'expo-modules-core';
+import type { CircleProps } from '../../types';
+
+const NativeCircleView = requireNativeViewManager<CircleProps>('NaviCircleView');
+
+/**
+ * 高德地图圆形覆盖物组件（声明式）
+ *
+ *
+ * @param props 圆形组件的属性配置
+ * @returns 渲染原生圆形组件
+ */
+function Circle(props: CircleProps) {
+  return <NativeCircleView {...props} />;
+}
+
+// 导出优化后的组件
+export default React.memo(Circle);

package/src/map/components/overlays/Cluster.tsx

@@ -0,0 +1,26 @@
+/*
+ * @Author       : 尚博信_王强 wangqiang03@sunboxsoft.com
+ * @Date         : 2025-12-03 14:27:06
+ * @LastEditors  : 尚博信_王强 wangqiang03@sunboxsoft.com
+ * @LastEditTime : 2025-12-05 16:21:29
+ * @FilePath     : /expo-gaode-map/packages/navigation/src/map/components/overlays/Cluster.tsx
+ * @Description  : 
+ * 
+ * Copyright (c) 2025 by 尚博信_王强, All Rights Reserved. 
+ */
+
+import { requireNativeViewManager } from 'expo-modules-core';
+import * as React from 'react';
+import type { ClusterProps } from '../../types';
+
+const NativeCluster = requireNativeViewManager('NaviClusterView');
+
+/**
+ * 高德地图点聚合组件
+ * 
+ * @param props 点聚合组件的属性配置
+ * @returns 渲染原生点聚合组件
+ */
+export default function Cluster(props: ClusterProps) {
+  return <NativeCluster {...props} />;
+}

package/src/map/components/overlays/HeatMap.tsx

@@ -0,0 +1,27 @@
+/*
+ * @Author       : 尚博信_王强 wangqiang03@sunboxsoft.com
+ * @Date         : 2025-12-03 14:27:06
+ * @LastEditors  : 尚博信_王强 wangqiang03@sunboxsoft.com
+ * @LastEditTime : 2025-12-05 16:21:04
+ * @FilePath     : /expo-gaode-map/packages/navigation/src/map/components/overlays/HeatMap.tsx
+ * @Description  : 
+ * 
+ * Copyright (c) 2025 by 尚博信_王强, All Rights Reserved. 
+ */
+
+import { requireNativeViewManager } from 'expo-modules-core';
+import * as React from 'react';
+import type { HeatMapProps } from '../../types';
+
+const NativeHeatMap = requireNativeViewManager('NaviHeatMapView');
+
+
+/**
+ * 高德地图热力图组件
+ * 
+ * @param props - 热力图配置属性，继承自NativeHeatMap组件的属性
+ * @returns 渲染高德地图原生热力图组件
+ */
+export default function HeatMap(props: HeatMapProps) {
+  return <NativeHeatMap {...props} />;
+}

package/src/map/components/overlays/Marker.tsx

@@ -0,0 +1,88 @@
+
+
+import * as React from 'react';
+import { requireNativeViewManager } from 'expo-modules-core';
+import type { MarkerProps } from '../../types';
+
+const NativeMarkerView = requireNativeViewManager('NaviMarkerView');
+
+/**
+ * Marker 组件 - 完全声明式 API
+ *
+ * 支持：
+ * - 自定义图标（icon）
+ * - 自定义内容（children）
+ * - 大头针样式（pinColor）
+ * - 拖拽功能
+ * - 所有事件回调
+ */
+function Marker(props: MarkerProps) {
+  // 根据是否有 children 来决定使用哪个尺寸属性
+  // 有 children：使用 customViewWidth/customViewHeight（默认 200x40）
+  // 无 children：使用 iconWidth/iconHeight（用于自定义图标，默认 40x40）
+  const containerWidth = props.children
+    ? (props.customViewWidth && props.customViewWidth > 0 ? props.customViewWidth : 200)
+    : (props.iconWidth && props.iconWidth > 0 ? props.iconWidth : 40);
+  const containerHeight = props.children
+    ? (props.customViewHeight && props.customViewHeight > 0 ? props.customViewHeight : 40)
+    : (props.iconHeight && props.iconHeight > 0 ? props.iconHeight : 40);
+  
+  // 从 props 中排除 position 属性，避免传递到原生层
+  const { position, ...restProps } = props;
+  
+  return (
+    <NativeMarkerView
+      latitude={position.latitude}
+      longitude={position.longitude}
+      iconWidth={containerWidth}
+      iconHeight={containerHeight}
+      customViewWidth={containerWidth}
+      customViewHeight={containerHeight}
+      {...restProps}
+    >
+      {props.children}
+    </NativeMarkerView>
+  );
+}
+
+/**
+ * 自定义比较函数
+ * 深度比较 position 和其他关键属性
+ */
+function arePropsEqual(prevProps: MarkerProps, nextProps: MarkerProps): boolean {
+  // 比较 position
+  if (
+    prevProps.position.latitude !== nextProps.position.latitude ||
+    prevProps.position.longitude !== nextProps.position.longitude
+  ) {
+    return false;
+  }
+  
+  // 比较基础属性
+  if (
+    prevProps.title !== nextProps.title ||
+    prevProps.snippet !== nextProps.snippet ||
+    prevProps.icon !== nextProps.icon ||
+    prevProps.pinColor !== nextProps.pinColor ||
+    prevProps.draggable !== nextProps.draggable ||
+    prevProps.animatesDrop !== nextProps.animatesDrop ||
+    prevProps.iconWidth !== nextProps.iconWidth ||
+    prevProps.iconHeight !== nextProps.iconHeight ||
+    prevProps.customViewWidth !== nextProps.customViewWidth ||
+    prevProps.customViewHeight !== nextProps.customViewHeight
+  ) {
+    return false;
+  }
+  
+  // 比较 children（简单比较，可根据需要深度比较）
+  if (prevProps.children !== nextProps.children) {
+    return false;
+  }
+  
+  // 其他属性相同，不需要重新渲染
+  return true;
+}
+
+// 导出优化后的组件
+export default React.memo(Marker, arePropsEqual);
+

package/src/map/components/overlays/MultiPoint.tsx

@@ -0,0 +1,27 @@
+/*
+ * @Author       : 尚博信_王强 wangqiang03@sunboxsoft.com
+ * @Date         : 2025-12-03 14:27:06
+ * @LastEditors  : 尚博信_王强 wangqiang03@sunboxsoft.com
+ * @LastEditTime : 2025-12-05 16:21:15
+ * @FilePath     : /expo-gaode-map/packages/navigation/src/map/components/overlays/MultiPoint.tsx
+ * @Description  : 
+ * 
+ * Copyright (c) 2025 by 尚博信_王强, All Rights Reserved. 
+ */
+
+import { requireNativeViewManager } from 'expo-modules-core';
+import * as React from 'react';
+import type { MultiPointProps } from '../../types';
+
+const NativeMultiPoint = requireNativeViewManager('NaviMultiPointView');
+
+
+/**
+ * 高德地图多点标记组件
+ * 
+ * @param props 多点标记的配置属性，继承自MultiPointProps接口
+ * @returns 渲染原生高德地图多点标记组件
+ */
+export default function MultiPoint(props: MultiPointProps) {
+  return <NativeMultiPoint {...props} />;
+}

package/src/map/components/overlays/Polygon.tsx

@@ -0,0 +1,19 @@
+
+import * as React from 'react';
+import type { PolygonProps } from '../../types';
+
+import { requireNativeViewManager } from 'expo-modules-core';
+const NativePolygonView = requireNativeViewManager<PolygonProps>('NaviPolygonView');
+
+/**
+ * 渲染一个高德地图多边形覆盖物组件
+ *
+ * @param props - 多边形属性配置，继承自PolygonProps类型
+ * @returns 高德地图原生多边形视图组件
+ */
+function Polygon(props: PolygonProps) {
+  return <NativePolygonView {...props} />;
+}
+
+// 导出优化后的组件
+export default React.memo(Polygon);

package/src/map/components/overlays/Polyline.tsx

@@ -0,0 +1,19 @@
+
+import * as React from 'react';
+import type { PolylineProps } from '../../types';
+
+import { requireNativeViewManager } from 'expo-modules-core';
+const NativePolylineView = requireNativeViewManager<PolylineProps>('NaviPolylineView');
+
+/**
+ * 渲染高德地图上的折线覆盖物组件
+ *
+ * @param props - 折线属性配置，继承自PolylineProps类型
+ * @returns 高德地图原生折线视图组件
+ */
+function Polyline(props: PolylineProps) {
+  return <NativePolylineView {...props} />;
+}
+
+// 导出优化后的组件
+export default React.memo(Polyline);

package/src/map/components/overlays/index.ts

@@ -0,0 +1,7 @@
+export { default as Marker } from './Marker';
+export { default as Polyline } from './Polyline';
+export { default as Polygon } from './Polygon';
+export { default as Circle } from './Circle';
+export { default as HeatMap } from './HeatMap';
+export { default as MultiPoint } from './MultiPoint';
+export { default as Cluster } from './Cluster';

package/src/map/index.ts

@@ -0,0 +1,37 @@
+
+// 导出类型定义
+export * from './ExpoGaodeMap.types';
+export * from './types';
+
+// 导出原生模块 - 直接使用，无需封装
+export { default as ExpoGaodeMapModule } from './ExpoGaodeMapModule';
+
+// 从 ExpoGaodeMapModule 重新导出类型，方便使用
+export type { SDKConfig, PermissionStatus } from './ExpoGaodeMapModule';
+
+// 导出地图视图组件
+export { default as MapView } from './ExpoGaodeMapView';
+export type { MapViewRef } from './ExpoGaodeMapView';
+
+// 导出覆盖物组件
+export {
+  Marker,
+  Polyline,
+  Polygon,
+  Circle,
+  HeatMap,
+  MultiPoint,
+  Cluster,
+} from './components/overlays';
+
+// 导出模块检测工具
+export {
+  requireModule,
+  OptionalModules,
+  getInstalledModules,
+  printModuleInfo,
+  createLazyLoader,
+} from './utils/ModuleLoader';
+
+// 默认导出原生模块
+export { default } from './ExpoGaodeMapModule';

package/src/map/types/common.types.ts

@@ -0,0 +1,126 @@
+/**
+ * 高德地图通用类型定义
+ * 基于 Expo Modules API
+ */
+
+/**
+ * 点坐标（屏幕坐标）
+ */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * 地理坐标
+ */
+export interface LatLng {
+  /**
+   * 纬度
+   */
+  latitude: number;
+
+  /**
+   * 经度
+   */
+  longitude: number;
+}
+
+/**
+ * 地图标注点（POI）
+ */
+export interface MapPoi {
+  /**
+   * 标注点 ID
+   */
+  id: string;
+
+  /**
+   * 标注点名称
+   */
+  name: string;
+
+  /**
+   * 标注点坐标
+   */
+  position: LatLng;
+}
+
+/**
+ * 矩形坐标边界
+ */
+export interface LatLngBounds {
+  /**
+   * 西南坐标
+   */
+  southwest: LatLng;
+
+  /**
+   * 东北坐标
+   */
+  northeast: LatLng;
+}
+
+/**
+ * 地图相机位置
+ */
+export interface CameraPosition {
+  /**
+   * 中心坐标
+   */
+  target?: LatLng;
+
+  /**
+   * 缩放级别（3-20）
+   */
+  zoom?: number;
+
+  /**
+   * 朝向、旋转角度（0-360度）
+   */
+  bearing?: number;
+
+  /**
+   * 倾斜角度（0-60度）
+   */
+  tilt?: number;
+}
+
+/**
+ * 地图类型
+ */
+export enum MapType {
+  /**
+   * 标准地图
+   */
+  Standard = 0,
+
+  /**
+   * 卫星地图
+   */
+  Satellite = 1,
+
+  /**
+   * 夜间地图
+   */
+  Night = 2,
+
+  /**
+   * 导航地图
+   */
+  Navi = 3,
+
+  /**
+   * 公交地图
+   * @platform android
+   */
+  Bus = 4,
+}
+
+/**
+ * 颜色值类型
+ * 支持：
+ * - 十六进制字符串: '#AARRGGBB' 或 '#RRGGBB'
+ * - 数字格式: 0xAARRGGBB (用于 Android)
+ */
+export type ColorValue = string | number;

package/src/map/types/index.ts

@@ -0,0 +1,55 @@
+/**
+ * 高德地图 Expo Module 类型定义统一导出
+ * 基于 Expo Modules API 重新设计
+ */
+
+// 通用类型
+export type {
+  Point,
+  LatLng,
+  MapPoi,
+  LatLngBounds,
+  CameraPosition,
+  ColorValue,
+} from './common.types';
+
+export { MapType } from './common.types';
+
+// 地图视图类型
+export type {
+  LocationEvent,
+  CameraEvent,
+  MapViewProps,
+  MapViewMethods,
+  MapViewRef,
+} from './map-view.types';
+
+// 定位类型
+export type {
+  Coordinates,
+  ReGeocode,
+  LocationOptions,
+  LocationListener,
+  GeoLanguage,
+  LocationProtocol,
+} from './location.types';
+
+export {
+  LocationAccuracy,
+  LocationMode,
+  CoordinateType,
+} from './location.types';
+
+// 覆盖物类型
+export type {
+  MarkerProps,
+  PolylineProps,
+  PolygonProps,
+  CircleProps,
+  HeatMapProps,
+  MultiPointItem,
+  MultiPointProps,
+  ClusterParams,
+  ClusterPoint,
+  ClusterProps,
+} from './overlays.types';