expo-gaode-map-navigation 1.1.5-next.1 → 1.1.5-next.3

package/build/map/types/map-view.types.d.ts

@@ -3,7 +3,8 @@
  * 基于 Expo Modules API
  */
 import type { StyleProp, ViewStyle, NativeSyntheticEvent } from 'react-native';
-import type { CameraPosition, LatLng, LatLngBounds, MapPoi, MapType, Point } from './common.types';
+import type { CameraPosition, LatLng, LatLngBounds, MapPoi, MapType, Point, LatLngPoint } from './common.types';
+import { Coordinates, ReGeocode } from './location.types';
 /**
  * 定位事件数据
  */
@@ -81,6 +82,37 @@ export interface MapViewProps {
         imageWidth?: number;
         /** 定位图标高度(像素) */
         imageHeight?: number;
+        /**
+         * 是否显示定位蓝点 @default true
+         * - iOS: 对应 mapView.showsUserLocation
+         * - Android: 对应 MyLocationStyle.showMyLocation() (5.1.0+)
+         */
+        showMyLocation?: boolean;
+        /** 定位图标锚点 U 坐标 (0.0-1.0) @platform android */
+        anchorU?: number;
+        /** 定位图标锚点 V 坐标 (0.0-1.0) @platform android */
+        anchorV?: number;
+        /**
+         * 定位蓝点展现模式 @platform android
+         * @default 'LOCATION_ROTATE' (连续定位、定位点旋转、移动到中心)
+         *
+         * 🧭 **方向指示说明**：
+         * - Android 通过 locationType 实现方向指示（定位点依照设备方向旋转）
+         * - iOS 通过 showsHeadingIndicator 实现方向指示（显示扇形方向指示器）
+         *
+         * 📱 **Android 方向指示模式**（推荐使用以下两种）：
+         * - 'LOCATION_ROTATE': 定位点依照设备方向旋转，视角跟随移动到中心（默认）⭐
+         * - 'LOCATION_ROTATE_NO_CENTER': 定位点依照设备方向旋转，视角不移动到中心 ⭐
+         *
+         * 🗺️ **其他模式**：
+         * - 'SHOW': 只定位一次
+         * - 'LOCATE': 定位一次，且将视角移动到地图中心点
+         * - 'FOLLOW': 连续定位、跟随移动，但定位点不旋转
+         * - 'MAP_ROTATE': 地图依照设备方向旋转（而非定位点旋转）
+         * - 'FOLLOW_NO_CENTER': 连续定位、不移动到中心，定位点不旋转
+         * - 'MAP_ROTATE_NO_CENTER': 地图依照设备方向旋转，不移动到中心
+         */
+        locationType?: 'SHOW' | 'LOCATE' | 'FOLLOW' | 'MAP_ROTATE' | 'LOCATION_ROTATE' | 'LOCATION_ROTATE_NO_CENTER' | 'FOLLOW_NO_CENTER' | 'MAP_ROTATE_NO_CENTER';
     };
     /**
      * 是否显示室内地图
@@ -151,6 +183,40 @@ export interface MapViewProps {
      * @platform ios
      */
     headingFilter?: number;
+    /**
+     * 是否启用国内外地图自动切换
+     * - true: 当中心点在国外时自动切换到苹果地图（iOS），国内时切换回高德地图
+     * - false: 始终使用高德地图
+     * @platform ios 当前仅支持 iOS 安卓因为需要使用 Google Maps SDK和谷歌服务
+     * @default false
+     */
+    worldMapSwitchEnabled?: boolean;
+    /**
+     * 自定义地图样式
+     *
+     * 支持两种方式：
+     * 1. 在线样式：提供 styleId（从高德开放平台获取）
+     * 2. 本地样式：提供 styleDataPath 和可选的 extraStyleDataPath
+     *
+     * @example
+     * // 使用在线样式
+     * customMapStyle={{ styleId: "your-style-id" }}
+     *
+     * @example
+     * // 使用本地样式文件
+     * customMapStyle={{
+     *   styleDataPath: "path/to/style.data",
+     *   extraStyleDataPath: "path/to/extra.data"
+     * }}
+     */
+    customMapStyle?: {
+        /** 在线样式ID（从高德开放平台获取） */
+        styleId?: string;
+        /** 本地样式文件路径 */
+        styleDataPath?: string;
+        /** 额外样式文件路径（可选） */
+        extraStyleDataPath?: string;
+    };
     /**
      * 样式
      */
@@ -209,7 +275,7 @@ export interface MapViewMethods {
      * @param center 中心点
      * @param animated 是否启用动画
      */
-    setCenter(center: LatLng, animated?: boolean): void;
+    setCenter(center: LatLngPoint, animated?: boolean): void;
     /**
      * 设置地图缩放级别
      * @param zoom 缩放级别
@@ -221,6 +287,11 @@ export interface MapViewMethods {
      * @returns 相机位置
      */
     getCameraPosition(): Promise<CameraPosition>;
+    /**
+     * 截取地图快照
+     * @returns 快照图片文件路径
+     */
+    takeSnapshot(): Promise<string>;
 }
 /**
  * MapView Ref 公开接口（用户使用）
@@ -228,7 +299,41 @@ export interface MapViewMethods {
 export interface MapViewRef {
     moveCamera(position: CameraPosition, duration?: number): Promise<void>;
     getLatLng(point: Point): Promise<LatLng>;
-    setCenter(center: LatLng, animated?: boolean): Promise<void>;
+    setCenter(center: LatLngPoint, animated?: boolean): Promise<void>;
     setZoom(zoom: number, animated?: boolean): Promise<void>;
     getCameraPosition(): Promise<CameraPosition>;
+    takeSnapshot(): Promise<string>;
 }
+/**
+ * Expo 模块事件类型
+ * 定义了原生模块可以触发的事件
+ */
+export type ExpoGaodeMapModuleEvents = {
+    /**
+     * 定位更新事件
+     * 当位置发生变化时触发
+     * @param location 位置信息，包含坐标和可选的逆地理编码信息
+     */
+    onLocationUpdate: (location: Coordinates | ReGeocode) => void;
+    /**
+     * 方向更新事件（iOS）
+     * 当设备方向发生变化时触发
+     * @param heading 方向信息
+     */
+    onHeadingUpdate: (heading: {
+        /** 磁北方向角度 (0-359.9) */
+        magneticHeading: number;
+        /** 真北方向角度 (0-359.9) */
+        trueHeading: number;
+        /** 方向精度 */
+        headingAccuracy: number;
+        /** X 轴原始数据 */
+        x: number;
+        /** Y 轴原始数据 */
+        y: number;
+        /** Z 轴原始数据 */
+        z: number;
+        /** 时间戳 */
+        timestamp: number;
+    }) => void;
+};

package/build/map/types/native-module.types.d.ts

@@ -0,0 +1,363 @@
+/**
+ * 高德地图原生模块类型定义
+ */
+import type { NativeModule } from 'expo';
+import type { LatLng, SDKConfig, PermissionStatus, LatLngPoint } from './common.types';
+import type { CoordinateType, Coordinates, ReGeocode, LocationMode, LocationAccuracy, LocationListener } from './location.types';
+import type { ExpoGaodeMapModuleEvents } from './map-view.types';
+export interface ExpoGaodeMapModule extends NativeModule<ExpoGaodeMapModuleEvents> {
+    /**
+     * 原生事件订阅方法
+     */
+    addListener<K extends keyof ExpoGaodeMapModuleEvents>(eventName: K, listener: ExpoGaodeMapModuleEvents[K]): {
+        remove: () => void;
+    };
+    addListener(eventName: string, listener: (...args: unknown[]) => void): {
+        remove: () => void;
+    };
+    /**
+     * 初始化高德地图 SDK
+     * @param config SDK 配置参数，包含 Android 和 iOS 的 API Key
+     */
+    initSDK(config: SDKConfig): void;
+    /**
+     * 设置是否加载世界向量地图（海外地图）
+     * 必须在地图初始化之前调用
+     * 世界地图为高级服务，需要开通相关权限
+     */
+    setLoadWorldVectorMap(enabled: boolean): void;
+    /**
+     * 获取高德地图 SDK 版本号
+     * @returns SDK 版本字符串
+     */
+    getVersion(): string;
+    /**
+     * 开始连续定位
+     * 启动后会持续接收位置更新，通过 onLocationUpdate 事件回调
+     */
+    start(): void;
+    /**
+     * 停止定位
+     * 停止接收位置更新
+     */
+    stop(): void;
+    /**
+     * 检查是否正在定位
+     * @returns 是否正在定位
+     */
+    isStarted(): Promise<boolean>;
+    /**
+     * 获取当前位置（单次定位）
+     * @returns 位置信息，包含坐标和可选的逆地理编码信息
+     */
+    getCurrentLocation(): Promise<Coordinates | ReGeocode>;
+    /**
+     * 坐标转换
+     * 将其他坐标系的坐标转换为高德地图使用的 GCJ-02 坐标系
+     * @param coordinate 需要转换的坐标
+     * @param type 原坐标系类型
+     */
+    coordinateConvert(coordinate: LatLngPoint, type: CoordinateType): Promise<LatLng>;
+    /**
+     * 设置是否返回逆地理编码信息
+     * @param isReGeocode true: 返回地址信息; false: 只返回坐标
+     */
+    setLocatingWithReGeocode(isReGeocode: boolean): void;
+    /**
+     * 设置定位模式（Android）
+     * @param mode 定位模式：高精度/低功耗/仅设备
+     */
+    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;
+    /**
+     * 设置期望的定位精度（iOS）
+     * @param accuracy 精度级别：最佳/10米/100米/1公里/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;
+    /**
+     * iOS 是否已启用后台定位配置
+     */
+    readonly isBackgroundLocationEnabled: boolean;
+    /**
+     * 设置定位协议
+     * @param protocol 协议类型
+     */
+    setLocationProtocol(protocol: string): void;
+    /**
+     * 开始更新设备方向（罗盘朝向）（iOS）
+     */
+    startUpdatingHeading(): void;
+    /**
+     * 停止更新设备方向（iOS）
+     */
+    stopUpdatingHeading(): void;
+    /**
+     * 检查前台位置权限状态（增强版）
+     * @returns 详细的权限状态信息
+     */
+    checkLocationPermission(): Promise<PermissionStatus>;
+    /**
+     * 请求前台位置权限（增强版）
+     * @returns 请求后的权限状态
+     */
+    requestLocationPermission(): Promise<PermissionStatus>;
+    /**
+     * 请求后台位置权限（Android 10+、iOS）
+     * 注意：必须在前台权限已授予后才能请求
+     * @returns 请求后的权限状态
+     */
+    requestBackgroundLocationPermission(): Promise<PermissionStatus>;
+    /**
+     * 打开应用设置页面
+     * 引导用户手动授予权限（当权限被永久拒绝时使用）
+     */
+    openAppSettings(): void;
+    /**
+     * 检查原生 SDK 是否已配置 API Key
+     * @returns 是否已配置
+     */
+    isNativeSDKConfigured(): boolean;
+    /**
+     * 添加定位监听器（便捷方法）
+     * 封装原生事件订阅，返回带 remove 的订阅对象
+     */
+    addLocationListener(listener: LocationListener): {
+        remove: () => void;
+    };
+    /**
+     * 计算两个坐标点之间的距离
+     * @param coordinate1 第一个坐标点
+     * @param coordinate2 第二个坐标点
+     * @returns 两点之间的距离（单位：米）
+     */
+    distanceBetweenCoordinates(coordinate1: LatLngPoint, coordinate2: LatLngPoint): number;
+    /**
+     * 判断点是否在圆内
+     * @param point 要判断的点
+     * @param center 圆心坐标
+     * @param radius 圆半径（单位：米）
+     * @returns 是否在圆内
+     */
+    isPointInCircle(point: LatLngPoint, center: LatLngPoint, radius: number): boolean;
+    /**
+     * 判断点是否在多边形内
+     * @param point 要判断的点
+     * @param polygon 多边形的顶点坐标数组，支持嵌套数组（多边形空洞）
+     * @returns 是否在多边形内
+     */
+    isPointInPolygon(point: LatLngPoint, polygon: LatLngPoint[] | LatLngPoint[][]): boolean;
+    /**
+     * 计算多边形面积
+     * @param polygon 多边形的顶点坐标数组，支持嵌套数组（多边形空洞，会自动展平计算）
+     * @returns 面积（单位：平方米）
+     */
+    calculatePolygonArea(polygon: LatLngPoint[] | LatLngPoint[][]): number;
+    /**
+     * 计算矩形面积
+     * @param southWest 西南角坐标
+     * @param northEast 东北角坐标
+     * @returns 面积（单位：平方米）
+     */
+    calculateRectangleArea(southWest: LatLngPoint, northEast: LatLngPoint): number;
+    /**
+     * 获取路径上距离目标点最近的点
+     * @param path 路径点集合
+     * @param target 目标点
+     * @returns 最近点信息，包含坐标、索引和距离
+     */
+    getNearestPointOnPath(path: LatLngPoint[], target: LatLngPoint): {
+        latitude: number;
+        longitude: number;
+        index: number;
+        distanceMeters: number;
+    } | null;
+    /**
+     * 计算多边形质心
+     * @param polygon 多边形顶点坐标数组，支持嵌套数组
+     * @returns 质心坐标
+     */
+    calculateCentroid(polygon: LatLngPoint[] | LatLngPoint[][]): LatLng | null;
+    /**
+     * 计算路径边界和中心点
+     * @param points 路径点
+     * @returns 边界和中心点
+     */
+    calculatePathBounds(points: LatLngPoint[]): {
+        north: number;
+        south: number;
+        east: number;
+        west: number;
+        center: LatLngPoint;
+    } | null;
+    /**
+     * GeoHash 编码
+     * @param coordinate 坐标点
+     * @param precision 精度 (1-12)
+     * @returns GeoHash 字符串
+     */
+    encodeGeoHash(coordinate: LatLngPoint, precision: number): string;
+    /**
+     * 轨迹抽稀 (RDP 算法)
+     * @param points 原始轨迹点
+     * @param tolerance 允许误差(米)
+     * @returns 简化后的轨迹点
+     */
+    simplifyPolyline(points: LatLngPoint[], tolerance: number): LatLng[];
+    /**
+     * 计算路径总长度
+     * @param points 路径点
+     * @returns 长度(米)
+     */
+    calculatePathLength(points: LatLngPoint[]): number;
+    /**
+     * 解析高德地图 API 返回的 Polyline 字符串
+     * 格式: "lng,lat;lng,lat;..."
+     * @param polylineStr 高德原始 polyline 字符串，或包含 polyline 属性的对象
+     * @returns 解析后的点集
+     */
+    parsePolyline(polylineStr: string | {
+        polyline: string;
+    }): LatLng[];
+    /**
+     * 获取路径上指定距离的点
+     * @param points 路径点
+     * @param distance 距离起点的米数
+     * @returns 点信息(坐标+角度)
+     */
+    getPointAtDistance(points: LatLngPoint[], distance: number): {
+        latitude: number;
+        longitude: number;
+        angle: number;
+    } | null;
+    /**
+     * 瓦片坐标转换：经纬度 -> 瓦片坐标
+     * @param coordinate 坐标点
+     * @param zoom 缩放级别
+     * @returns 瓦片坐标 (x, y, z)
+     */
+    latLngToTile(coordinate: LatLngPoint, zoom: number): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /**
+     * 瓦片坐标转换：瓦片坐标 -> 经纬度
+     * @param tile 瓦片坐标 (x, y, z)
+     * @returns 经纬度
+     */
+    tileToLatLng(tile: {
+        x: number;
+        y: number;
+        z: number;
+    }): LatLng | null;
+    /**
+     * 像素坐标转换：经纬度 -> 像素坐标
+     * @param coordinate 坐标点
+     * @param zoom 缩放级别
+     * @returns 像素坐标 (x, y)
+     */
+    latLngToPixel(coordinate: LatLngPoint, zoom: number): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * 像素坐标转换：像素坐标 -> 经纬度
+     * @param pixel 像素坐标 (x, y)
+     * @param zoom 缩放级别
+     * @returns 经纬度
+     */
+    pixelToLatLng(pixel: {
+        x: number;
+        y: number;
+    }, zoom: number): LatLng | null;
+    /**
+     * 批量地理围栏检测
+     * @param point 待检测点
+     * @param polygons 多边形集合 (支持嵌套)
+     * @returns 包含该点的多边形索引，若不在任何多边形内返回 -1
+     */
+    findPointInPolygons(point: LatLngPoint, polygons: LatLngPoint[][] | LatLngPoint[][][]): number;
+    /**
+     * 生成热力图网格数据 (C++ 加速)
+     * @param points 点集，包含权重
+     * @param gridSizeMeters 网格大小(米)
+     * @returns 聚合后的网格点
+     */
+    generateHeatmapGrid(points: Array<LatLngPoint & {
+        weight?: number;
+    }>, gridSizeMeters: number): Array<{
+        latitude: number;
+        longitude: number;
+        intensity: number;
+    }>;
+}

package/build/map/types/native-module.types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * 高德地图原生模块类型定义
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,132 @@
+/**
+ * 高德地图离线地图类型定义
+ */
+/**
+ * 离线地图下载状态
+ */
+export type OfflineMapStatus = 'not_downloaded' | 'downloading' | 'downloaded' | 'paused' | 'failed' | 'updating' | 'unzipping';
+/**
+ * 离线地图信息
+ */
+export interface OfflineMapInfo {
+    /** 城市代码 */
+    cityCode: string;
+    /** 城市名称 */
+    cityName: string;
+    /** 地图大小（字节） */
+    size: number;
+    /** 下载状态 */
+    status: OfflineMapStatus;
+    /** 下载进度 (0-100) */
+    progress: number;
+    /** 版本号 */
+    version: string;
+    /** 是否有更新 */
+    hasUpdate?: boolean;
+    /** 省份名称 */
+    provinceName?: string;
+    /** 省份代码 */
+    provinceCode?: string;
+    /** 已下载大小（字节） */
+    downloadedSize?: number;
+}
+/**
+ * 离线地图下载配置
+ */
+export interface OfflineMapDownloadConfig {
+    /** 城市代码 */
+    cityCode: string;
+    /** 是否允许移动网络下载 @default false */
+    allowCellular?: boolean;
+}
+/**
+ * 离线地图下载进度事件
+ */
+export interface OfflineMapDownloadEvent {
+    /** 城市代码 */
+    cityCode: string;
+    /** 城市名称 */
+    cityName: string;
+    /** 下载进度 (0-100) */
+    progress: number;
+    /** 已下载大小（字节） */
+    downloadedSize: number;
+    /** 总大小（字节） */
+    totalSize: number;
+    /** 下载状态 */
+    status: OfflineMapStatus;
+    /** 当前状态描述 */
+    statusMessage?: string;
+}
+/**
+ * 离线地图完成事件
+ */
+export interface OfflineMapCompleteEvent {
+    /** 城市代码 */
+    cityCode: string;
+    /** 城市名称 */
+    cityName: string;
+    /** 是否成功 */
+    success: boolean;
+}
+/**
+ * 离线地图暂停事件
+ */
+export interface OfflineMapPausedEvent {
+    /** 城市代码 */
+    cityCode: string;
+    /** 城市名称 */
+    cityName: string;
+}
+/**
+ * 离线地图取消事件
+ */
+export interface OfflineMapCancelledEvent {
+    /** 城市代码 */
+    cityCode: string;
+    /** 城市名称 */
+    cityName: string;
+}
+/**
+ * 离线地图错误事件
+ */
+export interface OfflineMapErrorEvent {
+    /** 城市代码 */
+    cityCode: string;
+    /** 城市名称 */
+    cityName: string;
+    /** 错误信息 */
+    error: string;
+    /** 错误代码 */
+    errorCode?: number;
+}
+/**
+ * 离线地图存储信息
+ */
+export interface OfflineMapStorageInfo {
+    /** 总存储空间（字节） */
+    totalSpace: number;
+    /** 已使用空间（字节） */
+    usedSpace: number;
+    /** 可用空间（字节） */
+    availableSpace: number;
+    /** 离线地图占用空间（字节） */
+    offlineMapSize: number;
+}
+/**
+ * 离线地图事件类型
+ */
+export type OfflineMapEvents = {
+    /** 下载进度更新 */
+    onDownloadProgress: (event: OfflineMapDownloadEvent) => void;
+    /** 下载完成 */
+    onDownloadComplete: (event: OfflineMapCompleteEvent) => void;
+    /** 下载错误 */
+    onDownloadError: (event: OfflineMapErrorEvent) => void;
+    /** 解压进度更新 */
+    onUnzipProgress: (event: OfflineMapDownloadEvent) => void;
+    /** 下载暂停 */
+    onDownloadPaused: (event: OfflineMapPausedEvent) => void;
+    /** 下载取消 */
+    onDownloadCancelled: (event: OfflineMapCancelledEvent) => void;
+};

package/build/map/types/offline.types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * 高德地图离线地图类型定义
+ */
+Object.defineProperty(exports, "__esModule", { value: true });