expo-gaode-map-navigation 1.1.5 → 1.1.6

package/build/map/types/overlays.types.d.ts

@@ -2,16 +2,17 @@
  * 高德地图覆盖物相关类型定义
  * 基于 Expo Modules API
  */
-import type { ImageSourcePropType, ViewStyle, NativeSyntheticEvent } from 'react-native';
-import type { ColorValue, LatLng, Point } from './common.types';
+import type { ImageSourcePropType, ViewStyle, NativeSyntheticEvent, TextStyle } from 'react-native';
+import type { ColorValue, LatLng, LatLngPoint, Point } from './common.types';
 /**
  * 标记点属性
  */
 export interface MarkerProps {
     /**
      * 坐标
+     * 支持对象 {latitude, longitude} 或数组 [longitude, latitude]
      */
-    position: LatLng;
+    position: LatLngPoint;
     /**
      * 图标
      */
@@ -42,6 +43,7 @@ export interface MarkerProps {
     opacity?: number;
     /**
      * 是否可拖拽
+     * @default false
      */
     draggable?: boolean;
     /**
@@ -94,6 +96,15 @@ export interface MarkerProps {
      * @default 30
      */
     customViewHeight?: number;
+    /**
+     * 缓存 key 建议使用 提高性能
+     */
+    cacheKey?: string;
+    /**
+     * 是否开启生长动画
+     * @default false
+     */
+    growAnimation?: boolean;
     /**
      * 点击事件
      */
@@ -110,6 +121,16 @@ export interface MarkerProps {
      * 拖拽结束事件
      */
     onMarkerDragEnd?: (event: NativeSyntheticEvent<LatLng>) => void;
+    /**
+     * 平滑移动轨迹点数组
+     * 设置后，Marker 会沿着轨迹平滑移动
+     */
+    smoothMovePath?: LatLng[];
+    /**
+     * 平滑移动总时长（秒）
+     * @default 10
+     */
+    smoothMoveDuration?: number;
 }
 /**
  * 折线属性
@@ -117,8 +138,9 @@ export interface MarkerProps {
 export interface PolylineProps {
     /**
      * 节点坐标数组
+     * 支持对象 {latitude, longitude} 或数组 [longitude, latitude]
      */
-    points: LatLng[];
+    points: LatLngPoint[];
     /**
      * 线宽
      */
@@ -147,6 +169,12 @@ export interface PolylineProps {
      * @note iOS 不支持
      */
     geodesic?: boolean;
+    /**
+     * 轨迹抽稀容差（米）
+     * 设置大于 0 的值时启用 RDP 算法简化轨迹点
+     * 建议值为 1.0 - 5.0，值越大简化程度越高
+     */
+    simplificationTolerance?: number;
     /**
      * 是否绘制虚线
      * @platform android
@@ -169,8 +197,11 @@ export interface PolylineProps {
 export interface PolygonProps {
     /**
      * 节点坐标数组
+     * 支持对象 {latitude, longitude} 或数组 [longitude, latitude]
+     * 同时也支持嵌套数组格式 [[p1, p2, ...], [p3, p4, ...]]，用于定义带孔的多边形
+     * 其中第一个数组为外轮廓，后续数组为内孔
      */
-    points: LatLng[];
+    points: LatLngPoint[] | LatLngPoint[][];
     /**
      * 边线宽度
      */
@@ -191,6 +222,19 @@ export interface PolygonProps {
      * 点击事件
      */
     onPolygonPress?: (event: NativeSyntheticEvent<{}>) => void;
+    /**
+     * 轨迹抽稀容差（米）
+     * 设置大于 0 的值时启用 RDP 算法简化多边形边界
+     * 建议值为 1.0 - 5.0，值越大简化程度越高
+     */
+    simplificationTolerance?: number;
+    /**
+     * 简化完成事件
+     */
+    onPolygonSimplified?: (event: NativeSyntheticEvent<{
+        originalCount: number;
+        simplifiedCount: number;
+    }>) => void;
 }
 /**
  * 圆形属性
@@ -198,8 +242,9 @@ export interface PolygonProps {
 export interface CircleProps {
     /**
      * 圆心坐标
+     * 支持对象 {latitude, longitude} 或数组 [longitude, latitude]
      */
-    center: LatLng;
+    center: LatLngPoint;
     /**
      * 半径（米）
      */
@@ -225,14 +270,34 @@ export interface CircleProps {
      */
     onCirclePress?: (event: NativeSyntheticEvent<{}>) => void;
 }
+/**
+ * 热力图渐变配置
+ */
+export interface HeatMapGradient {
+    /**
+     * 颜色数组
+     * 支持 '#RRGGBB', 'rgba()', 'red' 等
+     */
+    colors: ColorValue[];
+    /**
+     * 颜色起始点数组 [0-1]
+     * 必须递增，例如 [0.2, 0.5, 0.9]
+     */
+    startPoints: number[];
+}
 /**
  * 热力图属性
  */
 export interface HeatMapProps {
     /**
      * 热力点数据
+     * 支持对象 {latitude, longitude} 或数组 [longitude, latitude]
+     */
+    data: LatLngPoint[];
+    /**
+     * 是否显示热力图（用于避免频繁卸载/重建导致卡顿）
      */
-    data: LatLng[];
+    visible?: boolean;
     /**
      * 热力半径（米）
      */
@@ -241,6 +306,15 @@ export interface HeatMapProps {
      * 透明度 [0, 1]
      */
     opacity?: number;
+    /**
+     * 热力图渐变配置
+     */
+    gradient?: HeatMapGradient;
+    /**
+     * 是否开启高清热力图（Retina适配）
+     * @platform ios
+     */
+    allowRetinaAdapting?: boolean;
 }
 /**
  * 海量点标记项
@@ -253,7 +327,7 @@ export interface MultiPointItem extends LatLng {
     /**
      * 自定义数据
      */
-    data?: any;
+    data?: unknown;
 }
 /**
  * 海量点属性
@@ -262,15 +336,23 @@ export interface MultiPointProps {
     /**
      * 点集合
      */
-    items: MultiPointItem[];
+    points: MultiPointItem[];
     /**
      * 图标
      */
-    icon?: ImageSourcePropType;
+    icon?: string | ImageSourcePropType;
+    /**
+     * 图标宽度
+     */
+    iconWidth?: number;
+    /**
+     * 图标高度
+     */
+    iconHeight?: number;
     /**
      * 点击事件
      */
-    onPress?: (event: NativeSyntheticEvent<{
+    onMultiPointPress?: (event: NativeSyntheticEvent<{
         index: number;
         item: MultiPointItem;
     }>) => void;
@@ -279,31 +361,51 @@ export interface MultiPointProps {
  * 聚合点参数
  */
 export interface ClusterParams {
-    /**
-     * 唯一标识
-     */
-    id: number;
     /**
      * 包含的标记点数量
      */
     count: number;
     /**
-     * 聚合点坐标
+     * 纬度
+     */
+    latitude: number;
+    /**
+     * 经度
+     */
+    longitude: number;
+    /**
+     * 包含的点数据列表
+     */
+    pois?: ClusterPoint[];
+    /**
+     * 唯一标识 (兼容性保留)
      */
-    position: LatLng;
+    id?: number;
+    /**
+     * 聚合点坐标 (兼容性保留)
+     */
+    position?: LatLng;
 }
 /**
  * 聚合点项
  */
 export interface ClusterPoint {
     /**
-     * 坐标
+     * 纬度（原生 Cluster 使用）
+     */
+    latitude?: number;
+    /**
+     * 经度（原生 Cluster 使用）
+     */
+    longitude?: number;
+    /**
+     * 坐标（JS ClusterLayer 使用）
      */
-    position: LatLng;
+    position?: LatLngPoint;
     /**
      * 自定义数据
      */
-    properties?: any;
+    properties?: Record<string, unknown>;
 }
 /**
  * 聚合图层属性
@@ -313,24 +415,35 @@ export interface ClusterProps {
      * 聚合半径
      */
     radius?: number;
+    /**
+     * 最小聚合数量
+     */
+    minClusterSize?: number;
     /**
      * 聚合点样式
      */
     clusterStyle?: ViewStyle;
+    /**
+     * 分级聚合样式配置
+     * 根据聚合数量动态设置样式
+     */
+    clusterBuckets?: ({
+        minPoints: number;
+    } & ViewStyle)[];
     /**
      * 聚合点文本样式
      */
-    clusterTextStyle?: ViewStyle;
+    clusterTextStyle?: TextStyle;
     /**
      * 坐标点列表
      */
     points: ClusterPoint[];
     /**
-     * 渲染标记点
+     * 暂未实现，请勿使用
      */
-    renderMarker: (item: ClusterPoint) => React.ReactNode;
+    renderMarker?: (item: ClusterPoint) => React.ReactNode;
     /**
-     * 渲染聚合点
+     * 暂未实现，请勿使用
      */
     renderCluster?: (params: ClusterParams) => React.ReactNode;
     /**

package/build/map/utils/ErrorHandler.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 高德地图错误处理工具
+ * 提供友好的错误提示和解决方案指引
+ */
+/**
+ * 错误类型枚举
+ */
+export declare enum ErrorType {
+    /** SDK 未初始化 */
+    SDK_NOT_INITIALIZED = "SDK_NOT_INITIALIZED",
+    /** API Key 配置错误 */
+    INVALID_API_KEY = "INVALID_API_KEY",
+    /** 权限未授予 */
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    /** 定位失败 */
+    LOCATION_FAILED = "LOCATION_FAILED",
+    /** 原生模块不可用 */
+    NATIVE_MODULE_UNAVAILABLE = "NATIVE_MODULE_UNAVAILABLE",
+    /** 地图视图未初始化 */
+    MAP_VIEW_NOT_INITIALIZED = "MAP_VIEW_NOT_INITIALIZED",
+    /** 参数错误 */
+    INVALID_PARAMETER = "INVALID_PARAMETER",
+    /** 网络错误 */
+    NETWORK_ERROR = "NETWORK_ERROR"
+}
+/**
+ * 错误详情接口
+ */
+export interface ErrorDetails {
+    /** 错误类型 */
+    type: ErrorType;
+    /** 错误消息 */
+    message: string;
+    /** 解决方案 */
+    solution: string;
+    /** 文档链接 */
+    docUrl?: string;
+    /** 原始错误 */
+    originalError?: Error;
+}
+/**
+ * 自定义错误类
+ */
+export declare class GaodeMapError extends Error {
+    type: ErrorType;
+    solution: string;
+    docUrl?: string;
+    originalError?: Error;
+    constructor(details: ErrorDetails);
+}
+/**
+ * 错误处理器类
+ */
+export declare class ErrorHandler {
+    private static docBaseUrl;
+    /**
+     * SDK 未初始化错误
+     */
+    static sdkNotInitialized(): GaodeMapError;
+    /**
+     * API Key 配置错误
+     */
+    static invalidApiKey(platform: 'android' | 'ios' | 'both'): GaodeMapError;
+    /**
+     * 权限未授予错误
+     */
+    static permissionDenied(permissionType: 'location'): GaodeMapError;
+    /**
+     * 定位失败错误
+     */
+    static locationFailed(reason?: string): GaodeMapError;
+    /**
+     * 原生模块不可用错误
+     */
+    static nativeModuleUnavailable(): GaodeMapError;
+    /**
+     * 地图视图未初始化错误
+     */
+    static mapViewNotInitialized(methodName: string): GaodeMapError;
+    /**
+     * 参数错误
+     */
+    static invalidParameter(paramName: string, expected: string, received: unknown): GaodeMapError;
+    /**
+     * 网络错误
+     */
+    static networkError(originalError?: Error): GaodeMapError;
+    /**
+     * 包装原生错误，提供更友好的提示
+     */
+    static wrapNativeError(error: unknown, context: string): GaodeMapError;
+}
+/**
+ * 错误日志工具
+ */
+export declare class ErrorLogger {
+    private static isEnabled;
+    /**
+     * 启用/禁用错误日志
+     */
+    static setEnabled(enabled: boolean): void;
+    /**
+     * 记录错误
+     */
+    static log(error: GaodeMapError): void;
+    /**
+     * 记录警告
+     */
+    static warn(message: string, details?: unknown): void;
+}