expo-gaode-map-navigation 1.1.5 → 1.1.6

package/build/map/ExpoGaodeMapOfflineModule.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 高德地图离线地图原生模块
+ */
+import { NativeModule } from 'expo';
+import type { OfflineMapInfo, OfflineMapDownloadConfig, OfflineMapStorageInfo, OfflineMapEvents } from './types/offline.types';
+/**
+ * 离线地图原生模块接口
+ */
+declare class NaviMapOfflineModule extends NativeModule<OfflineMapEvents> {
+    /**
+     * 获取所有可下载的城市列表
+     * @returns Promise<OfflineMapInfo[]> 城市列表
+     */
+    getAvailableCities(): Promise<OfflineMapInfo[]>;
+    /**
+     * 获取所有省份列表
+     * @returns Promise<OfflineMapInfo[]> 省份列表
+     */
+    getAvailableProvinces(): Promise<OfflineMapInfo[]>;
+    /**
+     * 根据省份代码获取城市列表
+     * @param provinceCode 省份代码
+     * @returns Promise<OfflineMapInfo[]> 该省份下的城市列表
+     */
+    getCitiesByProvince(provinceCode: string): Promise<OfflineMapInfo[]>;
+    /**
+     * 获取已下载的地图列表
+     * @returns Promise<OfflineMapInfo[]> 已下载的地图列表
+     */
+    getDownloadedMaps(): Promise<OfflineMapInfo[]>;
+    /**
+     * 开始下载离线地图
+     * @param config 下载配置
+     */
+    startDownload(config: OfflineMapDownloadConfig): Promise<void>;
+    /**
+     * 暂停下载
+     * @param cityCode 城市代码
+     */
+    pauseDownload(cityCode: string): Promise<void>;
+    /**
+     * 恢复下载
+     * @param cityCode 城市代码
+     */
+    resumeDownload(cityCode: string): Promise<void>;
+    /**
+     * 取消下载
+     * @param cityCode 城市代码
+     */
+    cancelDownload(cityCode: string): Promise<void>;
+    /**
+     * 删除离线地图
+     * @param cityCode 城市代码
+     */
+    deleteMap(cityCode: string): Promise<void>;
+    /**
+     * 更新离线地图
+     * @param cityCode 城市代码
+     */
+    updateMap(cityCode: string): Promise<void>;
+    /**
+     * 检查是否有可用更新
+     * @param cityCode 城市代码
+     * @returns Promise<boolean> 是否有更新
+     */
+    checkUpdate(cityCode: string): Promise<boolean>;
+    /**
+     * 检查地图是否已下载
+     * @param cityCode 城市代码
+     * @returns Promise<boolean> 是否已下载
+     */
+    isMapDownloaded(cityCode: string): Promise<boolean>;
+    /**
+     * 获取地图下载状态
+     * @param cityCode 城市代码
+     * @returns Promise<OfflineMapInfo> 地图信息
+     */
+    getMapStatus(cityCode: string): Promise<OfflineMapInfo>;
+    /**
+     * 获取所有下载任务的总进度
+     * @returns Promise<number> 总进度 (0-100)
+     */
+    getTotalProgress(): Promise<number>;
+    /**
+     * 获取当前正在下载的城市列表
+     * @returns Promise<string[]> 城市代码列表
+     */
+    getDownloadingCities(): Promise<string[]>;
+    /**
+     * 获取离线地图占用的存储空间（字节）
+     * @returns Promise<number> 存储空间大小
+     */
+    getStorageSize(): Promise<number>;
+    /**
+     * 获取详细的存储信息
+     * @returns Promise<OfflineMapStorageInfo> 存储信息
+     */
+    getStorageInfo(): Promise<OfflineMapStorageInfo>;
+    /**
+     * 清理所有离线地图
+     */
+    clearAllMaps(): Promise<void>;
+    /**
+     * 设置离线地图存储路径
+     * @param path 存储路径
+     */
+    setStoragePath(path: string): void;
+    /**
+     * 获取离线地图存储路径
+     * @returns Promise<string> 存储路径
+     */
+    getStoragePath(): Promise<string>;
+    /**
+     * 批量下载地图
+     * @param cityCodes 城市代码列表
+     * @param allowCellular 是否允许移动网络
+     */
+    batchDownload(cityCodes: string[], allowCellular?: boolean): Promise<void>;
+    /**
+     * 批量删除地图
+     * @param cityCodes 城市代码列表
+     */
+    batchDelete(cityCodes: string[]): Promise<void>;
+    /**
+     * 批量更新地图
+     * @param cityCodes 城市代码列表
+     */
+    batchUpdate(cityCodes: string[]): Promise<void>;
+    /**
+     * 暂停所有下载任务
+     */
+    pauseAllDownloads(): Promise<void>;
+    /**
+     * 恢复所有下载任务
+     */
+    resumeAllDownloads(): Promise<void>;
+}
+declare const _default: NaviMapOfflineModule;
+export default _default;

package/build/map/ExpoGaodeMapOfflineModule.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * 高德地图离线地图原生模块
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const expo_1 = require("expo");
+// 获取原生模块实例
+exports.default = (0, expo_1.requireNativeModule)('ExpoGaodeMapOffline');

package/build/map/ExpoGaodeMapView.js

@@ -35,7 +35,12 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const expo_modules_core_1 = require("expo-modules-core");
 const React = __importStar(require("react"));
-const NativeView = (0, expo_modules_core_1.requireNativeViewManager)('NaviMapView');
+const GeoUtils_1 = require("./utils/GeoUtils");
+const ErrorHandler_1 = require("./utils/ErrorHandler");
+const MapContext_1 = require("./components/MapContext");
+const MapUI_1 = require("./components/MapUI");
+const react_native_1 = require("react-native");
+const NativeView = (0, expo_modules_core_1.requireNativeViewManager)('ExpoGaodeMapView');
 /**
  * 高德地图视图组件，提供地图操作API和覆盖物管理功能
  *
@@ -57,63 +62,49 @@ const NativeView = (0, expo_modules_core_1.requireNativeViewManager)('NaviMapVie
 const ExpoGaodeMapView = React.forwardRef((props, ref) => {
     const nativeRef = React.useRef(null);
     const internalRef = React.useRef(null);
+    /**
+     * 🔑 性能优化：通用 API 方法包装器
+     * 统一处理初始化检查和错误处理，减少重复代码
+     */
+    const createApiMethod = React.useCallback((methodName) => {
+        return ((...args) => {
+            if (!nativeRef.current) {
+                throw ErrorHandler_1.ErrorHandler.mapViewNotInitialized(methodName);
+            }
+            try {
+                return nativeRef.current[methodName](...args);
+            }
+            catch (error) {
+                throw ErrorHandler_1.ErrorHandler.wrapNativeError(error, methodName);
+            }
+        });
+    }, []);
+    /**
+     * 使用通用包装器创建所有 API 方法
+     * 所有方法共享相同的错误处理逻辑
+     */
     const apiRef = React.useMemo(() => ({
-        /**
-         * 移动地图相机到指定位置
-         * @param position 相机位置参数对象，包含目标经纬度、缩放级别等信息
-         * @param duration 动画持续时间（毫秒），默认300毫秒
-         * @throws 如果地图视图未初始化则抛出错误
-         * @returns Promise<void> 异步操作完成后的Promise
-         */
-        moveCamera: async (position, duration = 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) => {
-            if (!nativeRef.current)
-                throw new Error('MapView not initialized');
-            return nativeRef.current.getLatLng(point);
+        moveCamera: (position, duration) => {
+            if (!nativeRef.current) {
+                throw ErrorHandler_1.ErrorHandler.mapViewNotInitialized('moveCamera');
+            }
+            const normalizedPosition = {
+                ...position,
+                target: position.target ? (0, GeoUtils_1.normalizeLatLng)(position.target) : undefined,
+            };
+            return nativeRef.current.moveCamera(normalizedPosition, duration);
         },
-        /**
-         * 设置地图中心点坐标
-         * @param center 要设置的中心点坐标(LatLng格式)
-         * @param animated 是否使用动画效果移动地图(默认为false)
-         * @throws 如果地图视图未初始化则抛出错误
-         */
-        setCenter: async (center, animated = false) => {
-            if (!nativeRef.current)
-                throw new Error('MapView not initialized');
-            return nativeRef.current.setCenter(center, animated);
+        getLatLng: createApiMethod('getLatLng'),
+        setCenter: (center, animated) => {
+            if (!nativeRef.current) {
+                throw ErrorHandler_1.ErrorHandler.mapViewNotInitialized('setCenter');
+            }
+            return nativeRef.current.setCenter((0, GeoUtils_1.normalizeLatLng)(center), animated);
         },
-        /**
-         * 设置地图的缩放级别
-         * @param zoom 目标缩放级别
-         * @param animated 是否使用动画过渡效果，默认为false
-         * @throws 如果地图视图未初始化，抛出错误
-         */
-        setZoom: async (zoom, animated = 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();
-        }
-    }), []);
+        setZoom: createApiMethod('setZoom'),
+        getCameraPosition: createApiMethod('getCameraPosition'),
+        takeSnapshot: createApiMethod('takeSnapshot'),
+    }), [createApiMethod]);
     /**
      * 将传入的apiRef赋值给internalRef.current
      * 用于在组件内部保存对地图API实例的引用
@@ -126,9 +117,26 @@ const ExpoGaodeMapView = React.forwardRef((props, ref) => {
      * @returns 返回地图API的引用对象，可用于调用地图相关方法
      */
     React.useImperativeHandle(ref, () => apiRef, [apiRef]);
-    return (<NativeView ref={nativeRef} {...props}>
-          {props.children}
-        </NativeView>);
+    // 分离 children：区分原生覆盖物和普通 UI 组件
+    const { children, style, ...otherProps } = props;
+    const overlays = [];
+    const uiControls = [];
+    React.Children.forEach(children, (child) => {
+        if (React.isValidElement(child) && (child.type === MapUI_1.MapUI || child.type?.isMapUI)) {
+            uiControls.push(child);
+        }
+        else {
+            overlays.push(child);
+        }
+    });
+    return (<MapContext_1.MapContext.Provider value={apiRef}>
+      <react_native_1.View style={[{ flex: 1, position: 'relative', overflow: 'hidden', }, style]}>
+        <NativeView ref={nativeRef} style={react_native_1.StyleSheet.absoluteFill} {...otherProps}>
+          {overlays}
+        </NativeView>
+        {uiControls}
+      </react_native_1.View>
+    </MapContext_1.MapContext.Provider>);
 });
 ExpoGaodeMapView.displayName = 'ExpoGaodeMapView';
 exports.default = ExpoGaodeMapView;

package/build/map/components/FoldableMapView.d.ts

@@ -0,0 +1,38 @@
+import React from 'react';
+import { DeviceInfo, FoldState } from '../utils/PlatformDetector';
+import { MapViewProps, MapViewRef } from '../types';
+/**
+ * 折叠屏适配配置
+ */
+export interface FoldableConfig {
+    /** 折叠时是否自动调整缩放级别 */
+    autoAdjustZoom?: boolean;
+    /** 展开时的缩放级别增量 */
+    unfoldedZoomDelta?: number;
+    /** 是否在折叠/展开时保持中心点 */
+    keepCenterOnFold?: boolean;
+    /** 折叠状态变化回调 */
+    onFoldStateChange?: (state: FoldState, deviceInfo: DeviceInfo) => void;
+    /** 是否启用调试日志 */
+    debug?: boolean;
+}
+/**
+ * 折叠屏地图视图组件
+ *
+ * 自动适配折叠屏设备的展开/折叠状态变化
+ */
+export interface FoldableMapViewProps extends MapViewProps {
+    /** 折叠屏适配配置 */
+    foldableConfig?: FoldableConfig;
+}
+export declare const FoldableMapView: React.FC<FoldableMapViewProps>;
+/**
+ * 折叠屏适配 Hook
+ *
+ * 用于在现有地图组件中添加折叠屏适配功能
+ */
+export declare function useFoldableMap(mapRef: React.RefObject<MapViewRef>, config?: FoldableConfig): {
+    foldState: FoldState;
+    deviceInfo: DeviceInfo;
+    isFoldable: boolean;
+};

package/build/map/components/FoldableMapView.js

@@ -0,0 +1,209 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FoldableMapView = void 0;
+exports.useFoldableMap = useFoldableMap;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const ExpoGaodeMapView_1 = __importDefault(require("../ExpoGaodeMapView"));
+const PlatformDetector_1 = require("../utils/PlatformDetector");
+const FoldableMapView = ({ foldableConfig, ...mapProps }) => {
+    const mapRef = (0, react_1.useRef)(null);
+    const [currentFoldState, setCurrentFoldState] = (0, react_1.useState)(PlatformDetector_1.FoldState.UNKNOWN);
+    const [deviceInfo, setDeviceInfo] = (0, react_1.useState)(PlatformDetector_1.PlatformDetector.getDeviceInfo());
+    const config = {
+        autoAdjustZoom: true,
+        unfoldedZoomDelta: 1,
+        keepCenterOnFold: true,
+        onFoldStateChange: () => { },
+        debug: false,
+        ...foldableConfig,
+    };
+    (0, react_1.useEffect)(() => {
+        // 仅在 Android 折叠屏设备上启用
+        if (react_native_1.Platform.OS !== 'android' || !deviceInfo.isFoldable) {
+            if (config.debug) {
+                console.log('[FoldableMapView] 非折叠屏设备，跳过适配');
+            }
+            return;
+        }
+        if (config.debug) {
+            console.log('[FoldableMapView] 初始化折叠屏适配');
+            console.log('设备信息:', deviceInfo);
+            console.log('初始折叠状态:', currentFoldState);
+        }
+        // 监听屏幕尺寸变化
+        const removeListener = PlatformDetector_1.PlatformDetector.addDimensionChangeListener(async (newInfo) => {
+            const newFoldState = PlatformDetector_1.PlatformDetector.getFoldState();
+            if (config.debug) {
+                console.log('[FoldableMapView] 屏幕尺寸变化');
+                console.log('新设备信息:', newInfo);
+                console.log('新折叠状态:', newFoldState);
+            }
+            // 折叠状态变化时的处理
+            if (newFoldState !== currentFoldState && currentFoldState !== PlatformDetector_1.FoldState.UNKNOWN) {
+                await handleFoldStateChange(currentFoldState, newFoldState, newInfo);
+            }
+            setCurrentFoldState(newFoldState);
+            setDeviceInfo(newInfo);
+            // 触发回调
+            config.onFoldStateChange(newFoldState, newInfo);
+        });
+        // 设置初始状态
+        const initialState = PlatformDetector_1.PlatformDetector.getFoldState();
+        setCurrentFoldState(initialState);
+        return () => {
+            removeListener();
+        };
+    }, []);
+    /**
+     * 处理折叠状态变化
+     */
+    const handleFoldStateChange = async (oldState, newState, newInfo) => {
+        if (!mapRef.current) {
+            return;
+        }
+        try {
+            // 获取当前地图状态
+            const currentCamera = await mapRef.current.getCameraPosition?.();
+            if (!currentCamera) {
+                if (config.debug) {
+                    console.warn('[FoldableMapView] 无法获取相机位置');
+                }
+                return;
+            }
+            const isUnfolding = newState === PlatformDetector_1.FoldState.UNFOLDED && oldState === PlatformDetector_1.FoldState.FOLDED;
+            const isFolding = newState === PlatformDetector_1.FoldState.FOLDED && oldState === PlatformDetector_1.FoldState.UNFOLDED;
+            if (config.debug) {
+                console.log('[FoldableMapView] 折叠状态变化:', {
+                    oldState,
+                    newState,
+                    isUnfolding,
+                    isFolding,
+                    currentZoom: currentCamera.zoom,
+                });
+            }
+            // 展开时增加缩放级别，折叠时减少
+            if (config.autoAdjustZoom && (isUnfolding || isFolding)) {
+                const currentZoom = currentCamera.zoom ?? 15;
+                const zoomDelta = isUnfolding ? config.unfoldedZoomDelta : -config.unfoldedZoomDelta;
+                const newZoom = Math.max(3, Math.min(20, currentZoom + zoomDelta));
+                if (config.debug) {
+                    console.log('[FoldableMapView] 调整缩放:', {
+                        oldZoom: currentZoom,
+                        newZoom,
+                        delta: zoomDelta,
+                    });
+                }
+                // 保持中心点，只调整缩放
+                await mapRef.current.moveCamera({
+                    target: config.keepCenterOnFold ? currentCamera.target : undefined,
+                    zoom: newZoom,
+                }, 300);
+            }
+        }
+        catch (error) {
+            if (config.debug) {
+                console.error('[FoldableMapView] 处理折叠状态变化失败:');
+            }
+        }
+    };
+    return (<ExpoGaodeMapView_1.default ref={mapRef} {...mapProps}/>);
+};
+exports.FoldableMapView = FoldableMapView;
+/**
+ * 折叠屏适配 Hook
+ *
+ * 用于在现有地图组件中添加折叠屏适配功能
+ */
+function useFoldableMap(mapRef, config) {
+    const [foldState, setFoldState] = (0, react_1.useState)(PlatformDetector_1.FoldState.UNKNOWN);
+    const [deviceInfo, setDeviceInfo] = (0, react_1.useState)(PlatformDetector_1.PlatformDetector.getDeviceInfo());
+    const mergedConfig = {
+        autoAdjustZoom: true,
+        unfoldedZoomDelta: 1,
+        keepCenterOnFold: true,
+        onFoldStateChange: () => { },
+        debug: false,
+        ...config,
+    };
+    (0, react_1.useEffect)(() => {
+        if (react_native_1.Platform.OS !== 'android' || !deviceInfo.isFoldable) {
+            return;
+        }
+        const removeListener = PlatformDetector_1.PlatformDetector.addDimensionChangeListener(async (newInfo) => {
+            const newFoldState = PlatformDetector_1.PlatformDetector.getFoldState();
+            if (newFoldState !== foldState && foldState !== PlatformDetector_1.FoldState.UNKNOWN) {
+                // 处理折叠状态变化
+                if (mapRef.current && mergedConfig.autoAdjustZoom) {
+                    try {
+                        const currentCamera = await mapRef.current.getCameraPosition();
+                        if (currentCamera) {
+                            const currentZoom = currentCamera.zoom ?? 15;
+                            const isUnfolding = newFoldState === PlatformDetector_1.FoldState.UNFOLDED && foldState === PlatformDetector_1.FoldState.FOLDED;
+                            const zoomDelta = isUnfolding ? mergedConfig.unfoldedZoomDelta : -mergedConfig.unfoldedZoomDelta;
+                            const newZoom = Math.max(3, Math.min(20, currentZoom + zoomDelta));
+                            await mapRef.current.moveCamera({
+                                target: mergedConfig.keepCenterOnFold ? currentCamera.target : undefined,
+                                zoom: newZoom,
+                            }, 300);
+                        }
+                    }
+                    catch (error) {
+                        if (mergedConfig.debug) {
+                            console.error('[useFoldableMap] 调整失败:');
+                        }
+                    }
+                }
+            }
+            setFoldState(newFoldState);
+            setDeviceInfo(newInfo);
+            mergedConfig.onFoldStateChange(newFoldState, newInfo);
+        });
+        const initialState = PlatformDetector_1.PlatformDetector.getFoldState();
+        setFoldState(initialState);
+        return () => {
+            removeListener();
+        };
+    }, [foldState, deviceInfo.isFoldable]);
+    return {
+        foldState,
+        deviceInfo,
+        isFoldable: deviceInfo.isFoldable,
+    };
+}

package/build/map/components/MapContext.d.ts

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import type { MapViewRef } from '../types';
+/**
+ * 地图上下文
+ * 用于在子组件中访问地图实例的方法
+ */
+export declare const MapContext: React.Context<MapViewRef | null>;
+/**
+ * Hook: 获取地图实例引用
+ * 只能在 MapView 的子组件中使用
+ */
+export declare function useMap(): MapViewRef;

package/build/map/components/MapContext.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapContext = void 0;
+exports.useMap = useMap;
+const React = __importStar(require("react"));
+/**
+ * 地图上下文
+ * 用于在子组件中访问地图实例的方法
+ */
+exports.MapContext = React.createContext(null);
+/**
+ * Hook: 获取地图实例引用
+ * 只能在 MapView 的子组件中使用
+ */
+function useMap() {
+    const context = React.useContext(exports.MapContext);
+    if (!context) {
+        throw new Error('useMap must be used within a MapView component');
+    }
+    return context;
+}

package/build/map/components/MapUI.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+/**
+ * MapUI 组件
+ * 用于包裹不需要作为地图原生子组件（如 Marker）的普通 React 组件。
+ * 被此组件包裹的内容将渲染在地图视图的上方（兄弟节点），而不是内部。
+ * 这解决了在地图内部放置普通 View 导致的触摸事件冲突问题。
+ *
+ * 示例:
+ * <MapView>
+ *   <Marker ... />
+ *   <MapUI>
+ *     <View style={{ position: 'absolute', ... }}>
+ *       <Text>悬浮层</Text>
+ *     </View>
+ *   </MapUI>
+ * </MapView>
+ */
+export declare const MapUI: React.FC<React.PropsWithChildren<{}>>;

package/build/map/components/MapUI.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapUI = void 0;
+const react_1 = __importDefault(require("react"));
+/**
+ * MapUI 组件
+ * 用于包裹不需要作为地图原生子组件（如 Marker）的普通 React 组件。
+ * 被此组件包裹的内容将渲染在地图视图的上方（兄弟节点），而不是内部。
+ * 这解决了在地图内部放置普通 View 导致的触摸事件冲突问题。
+ *
+ * 示例:
+ * <MapView>
+ *   <Marker ... />
+ *   <MapUI>
+ *     <View style={{ position: 'absolute', ... }}>
+ *       <Text>悬浮层</Text>
+ *     </View>
+ *   </MapUI>
+ * </MapView>
+ */
+const MapUI = ({ children }) => {
+    return <>{children}</>;
+};
+exports.MapUI = MapUI;
+// 静态标志，用于识别
+exports.MapUI.isMapUI = true;