expo-gaode-map 2.2.8-next.0 → 2.2.8

package/build/types/overlays.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"overlays.types.js","sourceRoot":"","sources":["../../src/types/overlays.types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * 高德地图覆盖物相关类型定义\n * 基于 Expo Modules API\n */\n\nimport type { ImageSourcePropType, ViewStyle, NativeSyntheticEvent } from 'react-native';\nimport type { ColorValue, LatLng, Point } from './common.types';\n\n/**\n * 标记点属性\n */\nexport interface MarkerProps {\n  /**\n   * 坐标\n   */\n  position: LatLng;\n\n  /**\n   * 图标\n   */\n  icon?: string | ImageSourcePropType;\n\n  /**\n   * 图标宽度（像素）\n   * 仅在使用 icon 属性时有效\n   */\n  iconWidth?: number;\n\n  /**\n   * 图标高度（像素）\n   * 仅在使用 icon 属性时有效\n   */\n  iconHeight?: number;\n\n  /**\n   * 标题\n   */\n  title?: string;\n\n  /**\n   * 描述\n   */\n  snippet?: string;\n\n  /**\n   * 透明度 [0, 1]\n   * @platform android\n   * @note iOS 不支持\n   */\n  opacity?: number;\n\n  /**\n   * 是否可拖拽\n   */\n  draggable?: boolean;\n\n  /**\n   * 是否平贴地图\n   * @platform android\n   * @note iOS 不支持\n   */\n  flat?: boolean;\n\n  /**\n   * 层级\n   * @platform android\n   * @note iOS 不支持 (使用 displayPriority)\n   */\n  zIndex?: number;\n\n  /**\n   * 覆盖物锚点比例\n   * @platform android\n   * @note iOS 使用 centerOffset\n   */\n  anchor?: Point;\n\n  /**\n   * 覆盖物偏移位置\n   * @platform ios\n   */\n  centerOffset?: Point;\n\n  /**\n   * 是否显示动画\n   * @platform ios\n   */\n  animatesDrop?: boolean;\n\n  /**\n   * 大头针颜色\n   * Android 支持更多颜色，iOS 只支持 red, green, purple\n   */\n  pinColor?: 'red' | 'orange' | 'yellow' | 'green' | 'cyan' | 'blue' | 'violet' | 'magenta' | 'rose' | 'purple';\n\n  /**\n   * 自定义视图\n   * 当使用 children 时，会将 React Native 组件渲染为图片显示在地图上\n   */\n  children?: React.ReactNode;\n\n  /**\n   * 自定义视图宽度（像素）\n   * 仅在使用 children 属性时有效 \n   * @default 80\n   */\n  customViewWidth?: number;\n\n  /**\n   * 自定义视图高度（像素）\n   * 仅在使用 children 属性时有效\n   * @default 30\n   */\n  customViewHeight?: number;\n\n  /**\n   * 缓存 key 建议使用 提高性能\n   */\n  cacheKey?: string;\n\n  /**\n   * 点击事件\n   */\n  onMarkerPress?: (event: NativeSyntheticEvent<LatLng>) => void;\n\n  /**\n   * 拖拽开始事件\n   */\n  onMarkerDragStart?: (event: NativeSyntheticEvent<LatLng>) => void;\n\n  /**\n   * 拖拽中事件\n   */\n  onMarkerDrag?: (event: NativeSyntheticEvent<LatLng>) => void;\n\n  /**\n   * 拖拽结束事件\n   */\n  onMarkerDragEnd?: (event: NativeSyntheticEvent<LatLng>) => void;\n}\n\n/**\n * 折线属性\n */\nexport interface PolylineProps {\n  /**\n   * 节点坐标数组\n   */\n  points: LatLng[];\n\n  /**\n   * 线宽\n   */\n  strokeWidth?: number;\n\n  /**\n   * 线条颜色\n   */\n  strokeColor?: ColorValue;\n\n  /**\n   * 层级\n   */\n  zIndex?: number;\n\n  /**\n   * 分段颜色\n   */\n  colors?: ColorValue[];\n\n  /**\n   * 是否使用渐变色\n   * @platform android\n   * @note iOS 不支持\n   */\n  gradient?: boolean;\n\n  /**\n   * 是否绘制大地线\n   * @platform android\n   * @note iOS 不支持\n   */\n  geodesic?: boolean;\n\n  /**\n   * 是否绘制虚线\n   * @platform android\n   * @note iOS 不支持\n   */\n  dotted?: boolean;\n\n  /**\n   * 纹理图片\n   * 支持网络图片(http/https)、本地文件(file://)或资源名称\n   */\n  texture?: string;\n\n  /**\n   * 点击事件\n   */\n  onPolylinePress?: (event: NativeSyntheticEvent<{}>) => void;\n}\n\n/**\n * 多边形属性\n */\nexport interface PolygonProps {\n  /**\n   * 节点坐标数组\n   */\n  points: LatLng[];\n\n  /**\n   * 边线宽度\n   */\n  strokeWidth?: number;\n\n  /**\n   * 边线颜色\n   */\n  strokeColor?: ColorValue;\n\n  /**\n   * 填充颜色\n   */\n  fillColor?: ColorValue;\n\n  /**\n   * 层级\n   */\n  zIndex?: number;\n\n  /**\n   * 点击事件\n   */\n  onPolygonPress?: (event: NativeSyntheticEvent<{}>) => void;\n}\n\n/**\n * 圆形属性\n */\nexport interface CircleProps {\n  /**\n   * 圆心坐标\n   */\n  center: LatLng;\n\n  /**\n   * 半径（米）\n   */\n  radius: number;\n\n  /**\n   * 边线宽度\n   */\n  strokeWidth?: number;\n\n  /**\n   * 边线颜色\n   */\n  strokeColor?: ColorValue;\n\n  /**\n   * 填充颜色\n   */\n  fillColor?: ColorValue;\n\n  /**\n   * 层级\n   */\n  zIndex?: number;\n\n  /**\n   * 点击事件\n   */\n  onCirclePress?: (event: NativeSyntheticEvent<{}>) => void;\n\n\n}\n\n/**\n * 热力图属性\n */\nexport interface HeatMapProps {\n  /**\n   * 热力点数据\n   */\n  data: LatLng[];\n\n  /**\n   * 热力半径（米）\n   */\n  radius?: number;\n\n  /**\n   * 透明度 [0, 1]\n   */\n  opacity?: number;\n}\n\n/**\n * 海量点标记项\n */\nexport interface MultiPointItem extends LatLng {\n  /**\n   * 唯一标识\n   */\n  id?: string | number;\n\n  /**\n   * 自定义数据\n   */\n  data?: any;\n}\n\n/**\n * 海量点属性\n */\nexport interface MultiPointProps {\n  /**\n   * 点集合\n   */\n  items: MultiPointItem[];\n\n  /**\n   * 图标\n   */\n  icon?: ImageSourcePropType;\n\n  /**\n   * 点击事件\n   */\n  onPress?: (event: NativeSyntheticEvent<{ index: number; item: MultiPointItem }>) => void;\n}\n\n/**\n * 聚合点参数\n */\nexport interface ClusterParams {\n  /**\n   * 唯一标识\n   */\n  id: number;\n\n  /**\n   * 包含的标记点数量\n   */\n  count: number;\n\n  /**\n   * 聚合点坐标\n   */\n  position: LatLng;\n}\n\n/**\n * 聚合点项\n */\nexport interface ClusterPoint {\n  /**\n   * 坐标\n   */\n  position: LatLng;\n\n  /**\n   * 自定义数据\n   */\n  properties?: any;\n}\n\n/**\n * 聚合图层属性\n */\nexport interface ClusterProps {\n  /**\n   * 聚合半径\n   */\n  radius?: number;\n\n  /**\n   * 聚合点样式\n   */\n  clusterStyle?: ViewStyle;\n\n  /**\n   * 聚合点文本样式\n   */\n  clusterTextStyle?: ViewStyle;\n\n  /**\n   * 坐标点列表\n   */\n  points: ClusterPoint[];\n\n  /**\n   * 渲染标记点\n   */\n  renderMarker: (item: ClusterPoint) => React.ReactNode;\n\n  /**\n   * 渲染聚合点\n   */\n  renderCluster?: (params: ClusterParams) => React.ReactNode;\n\n  /**\n   * 聚合点点击事件\n   */\n  onPress?: (event: NativeSyntheticEvent<ClusterParams>) => void;\n}\n"]}
+{"version":3,"file":"overlays.types.js","sourceRoot":"","sources":["../../src/types/overlays.types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * 高德地图覆盖物相关类型定义\n * 基于 Expo Modules API\n */\n\nimport type { ImageSourcePropType, ViewStyle, NativeSyntheticEvent } from 'react-native';\nimport type { ColorValue, LatLng, Point } from './common.types';\n\n/**\n * 标记点属性\n */\nexport interface MarkerProps {\n  /**\n   * 坐标\n   */\n  position: LatLng;\n\n  /**\n   * 图标\n   */\n  icon?: string | ImageSourcePropType;\n\n  /**\n   * 图标宽度（像素）\n   * 仅在使用 icon 属性时有效\n   */\n  iconWidth?: number;\n\n  /**\n   * 图标高度（像素）\n   * 仅在使用 icon 属性时有效\n   */\n  iconHeight?: number;\n\n  /**\n   * 标题\n   */\n  title?: string;\n\n  /**\n   * 描述\n   */\n  snippet?: string;\n\n  /**\n   * 透明度 [0, 1]\n   * @platform android\n   * @note iOS 不支持\n   */\n  opacity?: number;\n\n  /**\n   * 是否可拖拽\n   */\n  draggable?: boolean;\n\n  /**\n   * 是否平贴地图\n   * @platform android\n   * @note iOS 不支持\n   */\n  flat?: boolean;\n\n  /**\n   * 层级\n   * @platform android\n   * @note iOS 不支持 (使用 displayPriority)\n   */\n  zIndex?: number;\n\n  /**\n   * 覆盖物锚点比例\n   * @platform android\n   * @note iOS 使用 centerOffset\n   */\n  anchor?: Point;\n\n  /**\n   * 覆盖物偏移位置\n   * @platform ios\n   */\n  centerOffset?: Point;\n\n  /**\n   * 是否显示动画\n   * @platform ios\n   */\n  animatesDrop?: boolean;\n\n  /**\n   * 大头针颜色\n   * Android 支持更多颜色，iOS 只支持 red, green, purple\n   */\n  pinColor?: 'red' | 'orange' | 'yellow' | 'green' | 'cyan' | 'blue' | 'violet' | 'magenta' | 'rose' | 'purple';\n\n  /**\n   * 自定义视图\n   * 当使用 children 时，会将 React Native 组件渲染为图片显示在地图上\n   */\n  children?: React.ReactNode;\n\n  /**\n   * 自定义视图宽度（像素）\n   * 仅在使用 children 属性时有效 \n   * @default 80\n   */\n  customViewWidth?: number;\n\n  /**\n   * 自定义视图高度（像素）\n   * 仅在使用 children 属性时有效\n   * @default 30\n   */\n  customViewHeight?: number;\n\n  /**\n   * 缓存 key 建议使用 提高性能\n   */\n  cacheKey?: string;\n\n  /**\n   * 点击事件\n   */\n  onMarkerPress?: (event: NativeSyntheticEvent<LatLng>) => void;\n\n  /**\n   * 拖拽开始事件\n   */\n  onMarkerDragStart?: (event: NativeSyntheticEvent<LatLng>) => void;\n\n  /**\n   * 拖拽中事件\n   */\n  onMarkerDrag?: (event: NativeSyntheticEvent<LatLng>) => void;\n\n  /**\n   * 拖拽结束事件\n   */\n  onMarkerDragEnd?: (event: NativeSyntheticEvent<LatLng>) => void;\n}\n\n/**\n * 折线属性\n */\nexport interface PolylineProps {\n  /**\n   * 节点坐标数组\n   */\n  points: LatLng[];\n\n  /**\n   * 线宽\n   */\n  strokeWidth?: number;\n\n  /**\n   * 线条颜色\n   */\n  strokeColor?: ColorValue;\n\n  /**\n   * 层级\n   */\n  zIndex?: number;\n\n  /**\n   * 分段颜色\n   */\n  colors?: ColorValue[];\n\n  /**\n   * 是否使用渐变色\n   * @platform android\n   * @note iOS 不支持\n   */\n  gradient?: boolean;\n\n  /**\n   * 是否绘制大地线\n   * @platform android\n   * @note iOS 不支持\n   */\n  geodesic?: boolean;\n\n  /**\n   * 是否绘制虚线\n   * @platform android\n   * @note iOS 不支持\n   */\n  dotted?: boolean;\n\n  /**\n   * 纹理图片\n   * 支持网络图片(http/https)、本地文件(file://)或资源名称\n   */\n  texture?: string;\n\n  /**\n   * 点击事件\n   */\n  onPolylinePress?: (event: NativeSyntheticEvent<{}>) => void;\n}\n\n/**\n * 多边形属性\n */\nexport interface PolygonProps {\n  /**\n   * 节点坐标数组\n   */\n  points: LatLng[];\n\n  /**\n   * 边线宽度\n   */\n  strokeWidth?: number;\n\n  /**\n   * 边线颜色\n   */\n  strokeColor?: ColorValue;\n\n  /**\n   * 填充颜色\n   */\n  fillColor?: ColorValue;\n\n  /**\n   * 层级\n   */\n  zIndex?: number;\n\n  /**\n   * 点击事件\n   */\n  onPolygonPress?: (event: NativeSyntheticEvent<{}>) => void;\n}\n\n/**\n * 圆形属性\n */\nexport interface CircleProps {\n  /**\n   * 圆心坐标\n   */\n  center: LatLng;\n\n  /**\n   * 半径（米）\n   */\n  radius: number;\n\n  /**\n   * 边线宽度\n   */\n  strokeWidth?: number;\n\n  /**\n   * 边线颜色\n   */\n  strokeColor?: ColorValue;\n\n  /**\n   * 填充颜色\n   */\n  fillColor?: ColorValue;\n\n  /**\n   * 层级\n   */\n  zIndex?: number;\n\n  /**\n   * 点击事件\n   */\n  onCirclePress?: (event: NativeSyntheticEvent<{}>) => void;\n\n\n}\n\n/**\n * 热力图属性\n */\nexport interface HeatMapProps {\n  /**\n   * 热力点数据\n   */\n  data: LatLng[];\n\n  /**\n   * 热力半径（米）\n   */\n  radius?: number;\n\n  /**\n   * 透明度 [0, 1]\n   */\n  opacity?: number;\n}\n\n/**\n * 海量点标记项\n */\nexport interface MultiPointItem extends LatLng {\n  /**\n   * 唯一标识\n   */\n  id?: string | number;\n\n  /**\n   * 自定义数据\n   */\n  data?: any;\n}\n\n/**\n * 海量点属性\n */\nexport interface MultiPointProps {\n  /**\n   * 点集合\n   */\n  items: MultiPointItem[];\n\n  /**\n   * 图标\n   */\n  icon?: ImageSourcePropType;\n\n  /**\n   * 点击事件\n   */\n  onPress?: (event: NativeSyntheticEvent<{ index: number; item: MultiPointItem }>) => void;\n}\n\n/**\n * 聚合点参数\n */\nexport interface ClusterParams {\n  /**\n   * 唯一标识\n   */\n  id: number;\n\n  /**\n   * 包含的标记点数量\n   */\n  count: number;\n\n  /**\n   * 聚合点坐标\n   */\n  position: LatLng;\n}\n\n/**\n * 聚合点项\n */\nexport interface ClusterPoint {\n  /**\n   * 纬度（原生 Cluster 使用）\n   */\n  latitude?: number;\n  \n  /**\n   * 经度（原生 Cluster 使用）\n   */\n  longitude?: number;\n\n  /**\n   * 坐标（JS ClusterLayer 使用）\n   */\n  position?: LatLng;\n\n  /**\n   * 自定义数据\n   */\n  properties?: any;\n}\n\n/**\n * 聚合图层属性\n */\nexport interface ClusterProps {\n  /**\n   * 聚合半径\n   */\n  radius?: number;\n\n  /**\n   * 最小聚合数量\n   */\n  minClusterSize?: number;\n\n  /**\n   * 聚合点样式\n   */\n  clusterStyle?: ViewStyle;\n\n  /**\n   * 聚合点文本样式\n   */\n  clusterTextStyle?: ViewStyle;\n\n  /**\n   * 坐标点列表\n   */\n  points: ClusterPoint[];\n\n  /**\n   * 渲染标记点（仅 JS 实现的 ClusterLayer 需要）\n   */\n  renderMarker?: (item: ClusterPoint) => React.ReactNode;\n\n  /**\n   * 渲染聚合点（仅 JS 实现的 ClusterLayer 需要）\n   */\n  renderCluster?: (params: ClusterParams) => React.ReactNode;\n\n  /**\n   * 聚合点点击事件\n   */\n  onPress?: (event: NativeSyntheticEvent<ClusterParams>) => void;\n}\n"]}

package/build/utils/ErrorHandler.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 高德地图错误处理工具
+ * 提供友好的错误提示和解决方案指引
+ */
+/**
+ * 错误类型枚举
+ */
+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: any): GaodeMapError;
+    /**
+     * 网络错误
+     */
+    static networkError(originalError?: Error): GaodeMapError;
+    /**
+     * 包装原生错误，提供更友好的提示
+     */
+    static wrapNativeError(error: any, 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?: any): void;
+}
+//# sourceMappingURL=ErrorHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorHandler.d.ts","sourceRoot":"","sources":["../../src/utils/ErrorHandler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,oBAAY,SAAS;IACnB,eAAe;IACf,mBAAmB,wBAAwB;IAC3C,mBAAmB;IACnB,eAAe,oBAAoB;IACnC,YAAY;IACZ,iBAAiB,sBAAsB;IACvC,WAAW;IACX,eAAe,oBAAoB;IACnC,cAAc;IACd,yBAAyB,8BAA8B;IACvD,eAAe;IACf,wBAAwB,6BAA6B;IACrD,WAAW;IACX,iBAAiB,sBAAsB;IACvC,WAAW;IACX,aAAa,kBAAkB;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,KAAK,CAAC;gBAEV,OAAO,EAAE,YAAY;CAqBlC;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,UAAU,CAA4C;IAErE;;OAEG;IACH,MAAM,CAAC,iBAAiB,IAAI,aAAa;IAwBzC;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,aAAa;IA+CzE;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,cAAc,EAAE,UAAU,GAAG,aAAa;IAiDlE;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa;IA0BrD;;OAEG;IACH,MAAM,CAAC,uBAAuB,IAAI,aAAa;IA+B/C;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa;IAqC/D;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,aAAa;IAgB1F;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC,EAAE,KAAK,GAAG,aAAa;IAmBzD;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa;CAkDnE;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,SAAS,CAAW;IAEnC;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO;IAIlC;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa;IAU/B;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;CAK3C"}

package/build/utils/ErrorHandler.js

@@ -0,0 +1,398 @@
+/**
+ * 高德地图错误处理工具
+ * 提供友好的错误提示和解决方案指引
+ */
+/**
+ * 错误类型枚举
+ */
+export var ErrorType;
+(function (ErrorType) {
+    /** SDK 未初始化 */
+    ErrorType["SDK_NOT_INITIALIZED"] = "SDK_NOT_INITIALIZED";
+    /** API Key 配置错误 */
+    ErrorType["INVALID_API_KEY"] = "INVALID_API_KEY";
+    /** 权限未授予 */
+    ErrorType["PERMISSION_DENIED"] = "PERMISSION_DENIED";
+    /** 定位失败 */
+    ErrorType["LOCATION_FAILED"] = "LOCATION_FAILED";
+    /** 原生模块不可用 */
+    ErrorType["NATIVE_MODULE_UNAVAILABLE"] = "NATIVE_MODULE_UNAVAILABLE";
+    /** 地图视图未初始化 */
+    ErrorType["MAP_VIEW_NOT_INITIALIZED"] = "MAP_VIEW_NOT_INITIALIZED";
+    /** 参数错误 */
+    ErrorType["INVALID_PARAMETER"] = "INVALID_PARAMETER";
+    /** 网络错误 */
+    ErrorType["NETWORK_ERROR"] = "NETWORK_ERROR";
+})(ErrorType || (ErrorType = {}));
+/**
+ * 自定义错误类
+ */
+export class GaodeMapError extends Error {
+    type;
+    solution;
+    docUrl;
+    originalError;
+    constructor(details) {
+        const fullMessage = `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🗺️  高德地图错误 [${details.type}]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❌ 错误信息：
+   ${details.message}
+
+💡 解决方案：
+   ${details.solution}
+
+${details.docUrl ? `📖 详细文档：\n   ${details.docUrl}\n` : ''}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+        super(fullMessage);
+        this.name = 'GaodeMapError';
+        this.type = details.type;
+        this.solution = details.solution;
+        this.docUrl = details.docUrl;
+        this.originalError = details.originalError;
+    }
+}
+/**
+ * 错误处理器类
+ */
+export class ErrorHandler {
+    static docBaseUrl = 'https://TomWq.github.io/expo-gaode-map';
+    /**
+     * SDK 未初始化错误
+     */
+    static sdkNotInitialized() {
+        return new GaodeMapError({
+            type: ErrorType.SDK_NOT_INITIALIZED,
+            message: '高德地图 SDK 尚未初始化',
+            solution: `请在使用地图功能前先调用 initSDK()：
+
+import ExpoGaodeMapModule from 'expo-gaode-map';
+
+useEffect(() => {
+  // 在组件挂载时初始化
+  ExpoGaodeMapModule.initSDK({
+    androidKey: 'your-android-key',
+    iosKey: 'your-ios-key',
+  });
+}, []);
+
+⚠️  常见原因：
+1. 忘记调用 initSDK() 就使用了定位或地图功能
+2. initSDK() 调用时机过晚（应在 useEffect 中尽早调用）
+3. 使用 Config Plugin 但未重新构建原生代码`,
+            docUrl: `${this.docBaseUrl}/guide/initialization.html`,
+        });
+    }
+    /**
+     * API Key 配置错误
+     */
+    static invalidApiKey(platform) {
+        const platformText = {
+            android: 'Android',
+            ios: 'iOS',
+            both: 'Android 和 iOS',
+        }[platform];
+        return new GaodeMapError({
+            type: ErrorType.INVALID_API_KEY,
+            message: `${platformText} API Key 配置错误或未配置`,
+            solution: `请检查以下步骤：
+
+1️⃣  获取 API Key：
+   • 访问高德开放平台：https://lbs.amap.com/
+   • 注册并创建应用
+   • 获取对应平台的 API Key
+
+2️⃣  配置 API Key（推荐使用 Config Plugin）：
+
+在 app.json 中配置：
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-gaode-map",
+        {
+          "androidKey": "your-android-key",
+          "iosKey": "your-ios-key"
+        }
+      ]
+    ]
+  }
+}
+
+然后重新构建：
+npx expo prebuild --clean
+npx expo run:${platform === 'ios' ? 'ios' : 'android'}
+
+3️⃣  或在代码中配置：
+ExpoGaodeMapModule.initSDK({
+  androidKey: 'your-android-key',
+  iosKey: 'your-ios-key',
+});`,
+            docUrl: `${this.docBaseUrl}/guide/initialization.html`,
+        });
+    }
+    /**
+     * 权限未授予错误
+     */
+    static permissionDenied(permissionType) {
+        return new GaodeMapError({
+            type: ErrorType.PERMISSION_DENIED,
+            message: '定位权限未授予，无法使用定位功能',
+            solution: `请按以下步骤授予权限：
+
+1️⃣  请求权限：
+import ExpoGaodeMapModule from 'expo-gaode-map';
+
+const checkPermission = async () => {
+  // 检查权限状态
+  const status = await ExpoGaodeMapModule.checkLocationPermission();
+  
+  if (!status.granted) {
+    // 请求权限
+    const result = await ExpoGaodeMapModule.requestLocationPermission();
+    
+    if (!result.granted) {
+      // 用户拒绝授权，引导用户去设置
+      Alert.alert(
+        '需要定位权限',
+        '请在设置中开启定位权限以使用地图功能',
+        [
+          { text: '取消', style: 'cancel' },
+          { text: '去设置', onPress: () => Linking.openSettings() }
+        ]
+      );
+    }
+  }
+};
+
+2️⃣  iOS 配置（在 app.json 中）：
+{
+  "expo": {
+    "ios": {
+      "infoPlist": {
+        "NSLocationWhenInUseUsageDescription": "需要获取您的位置信息以显示地图",
+        "NSLocationAlwaysAndWhenInUseUsageDescription": "需要获取您的位置信息"
+      }
+    }
+  }
+}
+
+3️⃣  Android 配置（Config Plugin 会自动添加）：
+使用 expo-gaode-map 的 Config Plugin 会自动添加必要的权限声明`,
+            docUrl: `${this.docBaseUrl}/guide/getting-started.html#权限配置`,
+        });
+    }
+    /**
+     * 定位失败错误
+     */
+    static locationFailed(reason) {
+        return new GaodeMapError({
+            type: ErrorType.LOCATION_FAILED,
+            message: `定位失败${reason ? `：${reason}` : ''}`,
+            solution: `请检查以下问题：
+
+1️⃣  设备 GPS 是否开启
+2️⃣  网络连接是否正常
+3️⃣  定位权限是否已授予
+4️⃣  是否在室内或信号较弱的地方
+
+💡 解决方法：
+// 配置定位参数
+ExpoGaodeMapModule.setLocationTimeout(30); // 增加超时时间
+ExpoGaodeMapModule.setInterval(2000); // 设置定位间隔
+
+// Android 特有配置
+ExpoGaodeMapModule.setLocationMode(2); // 高精度模式
+ExpoGaodeMapModule.setGpsFirst(true);  // GPS 优先
+
+// iOS 特有配置
+ExpoGaodeMapModule.setDesiredAccuracy(0); // 最佳精度`,
+            docUrl: `${this.docBaseUrl}/api/location.html`,
+        });
+    }
+    /**
+     * 原生模块不可用错误
+     */
+    static nativeModuleUnavailable() {
+        return new GaodeMapError({
+            type: ErrorType.NATIVE_MODULE_UNAVAILABLE,
+            message: 'expo-gaode-map 原生模块不可用',
+            solution: `请检查以下步骤：
+
+1️⃣  确认已正确安装：
+npm install expo-gaode-map
+# 或
+pnpm install expo-gaode-map
+
+2️⃣  重新构建原生代码：
+npx expo prebuild --clean
+npx expo run:android
+npx expo run:ios
+
+3️⃣  检查 Expo 版本兼容性：
+• expo-gaode-map 需要 Expo SDK 49+
+• 不支持 Expo Go，必须使用 Development Build
+
+4️⃣  检查是否与其他包冲突：
+• 不能同时安装 expo-gaode-map 和 expo-gaode-map-navigation
+• 两个包选择其一使用
+
+5️⃣  清理缓存后重试：
+cd android && ./gradlew clean && cd ..
+cd ios && pod deintegrate && pod install && cd ..`,
+            docUrl: `${this.docBaseUrl}/guide/getting-started.html`,
+        });
+    }
+    /**
+     * 地图视图未初始化错误
+     */
+    static mapViewNotInitialized(methodName) {
+        return new GaodeMapError({
+            type: ErrorType.MAP_VIEW_NOT_INITIALIZED,
+            message: `无法调用 ${methodName}：地图视图尚未初始化`,
+            solution: `请确保：
+
+1️⃣  MapView 已经渲染完成
+2️⃣  使用 ref 获取地图实例后再调用方法
+
+正确用法：
+import { MapView, MapViewRef } from 'expo-gaode-map';
+
+const App = () => {
+  const mapRef = useRef<MapViewRef>(null);
+  
+  // ❌ 错误：在渲染前调用
+  // mapRef.current?.moveCamera(...);
+  
+  // ✅ 正确：等待地图加载完成
+  const handleMapReady = () => {
+    mapRef.current?.moveCamera({
+      target: { latitude: 39.9, longitude: 116.4 },
+      zoom: 15,
+    });
+  };
+  
+  return (
+    <MapView
+      ref={mapRef}
+      onMapReady={handleMapReady}
+    />
+  );
+};`,
+            docUrl: `${this.docBaseUrl}/api/mapview.html`,
+        });
+    }
+    /**
+     * 参数错误
+     */
+    static invalidParameter(paramName, expected, received) {
+        return new GaodeMapError({
+            type: ErrorType.INVALID_PARAMETER,
+            message: `参数 "${paramName}" 类型错误`,
+            solution: `期望类型：${expected}
+实际接收：${typeof received} (${JSON.stringify(received)})
+
+请检查传入的参数是否符合要求。
+
+💡 提示：
+• 使用 TypeScript 可以在编译时发现类型错误
+• 参考 API 文档了解正确的参数类型`,
+            docUrl: `${this.docBaseUrl}/api/`,
+        });
+    }
+    /**
+     * 网络错误
+     */
+    static networkError(originalError) {
+        return new GaodeMapError({
+            type: ErrorType.NETWORK_ERROR,
+            message: '网络请求失败',
+            solution: `请检查：
+
+1️⃣  网络连接是否正常
+2️⃣  API Key 是否有效
+3️⃣  是否超出配额限制
+
+💡 如果问题持续，请：
+• 检查高德开放平台控制台
+• 查看 API 调用量和配额
+• 确认 Key 的服务是否已开通`,
+            docUrl: `${this.docBaseUrl}/guide/troubleshooting.html`,
+            originalError,
+        });
+    }
+    /**
+     * 包装原生错误，提供更友好的提示
+     */
+    static wrapNativeError(error, context) {
+        const errorMessage = error?.message || String(error);
+        // SDK 未初始化相关错误
+        if (errorMessage.includes('not initialized') ||
+            errorMessage.includes('未初始化') ||
+            errorMessage.includes('SDK未设置')) {
+            return this.sdkNotInitialized();
+        }
+        // API Key 相关错误
+        if (errorMessage.includes('key') ||
+            errorMessage.includes('invalid') ||
+            errorMessage.includes('鉴权失败')) {
+            return this.invalidApiKey('both');
+        }
+        // 权限相关错误
+        if (errorMessage.includes('permission') ||
+            errorMessage.includes('权限')) {
+            return this.permissionDenied('location');
+        }
+        // 定位相关错误
+        if (errorMessage.includes('location') ||
+            errorMessage.includes('定位')) {
+            return this.locationFailed(errorMessage);
+        }
+        // 通用错误
+        return new GaodeMapError({
+            type: ErrorType.INVALID_PARAMETER,
+            message: `${context} 失败`,
+            solution: `原始错误信息：${errorMessage}
+
+如果问题持续，请：
+1. 查看完整的错误堆栈
+2. 检查 API 调用参数
+3. 提交 Issue：https://github.com/TomWq/expo-gaode-map/issues`,
+            originalError: error instanceof Error ? error : undefined,
+        });
+    }
+}
+/**
+ * 错误日志工具
+ */
+export class ErrorLogger {
+    static isEnabled = __DEV__;
+    /**
+     * 启用/禁用错误日志
+     */
+    static setEnabled(enabled) {
+        this.isEnabled = enabled;
+    }
+    /**
+     * 记录错误
+     */
+    static log(error) {
+        if (!this.isEnabled)
+            return;
+        console.error(error.message);
+        if (error.originalError) {
+            console.error('原始错误：', error.originalError);
+        }
+    }
+    /**
+     * 记录警告
+     */
+    static warn(message, details) {
+        if (!this.isEnabled)
+            return;
+        console.warn(`⚠️  expo-gaode-map: ${message}`, details || '');
+    }
+}
+//# sourceMappingURL=ErrorHandler.js.map

package/build/utils/ErrorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorHandler.js","sourceRoot":"","sources":["../../src/utils/ErrorHandler.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 高德地图错误处理工具\n * 提供友好的错误提示和解决方案指引\n */\n\n/**\n * 错误类型枚举\n */\nexport enum ErrorType {\n  /** SDK 未初始化 */\n  SDK_NOT_INITIALIZED = 'SDK_NOT_INITIALIZED',\n  /** API Key 配置错误 */\n  INVALID_API_KEY = 'INVALID_API_KEY',\n  /** 权限未授予 */\n  PERMISSION_DENIED = 'PERMISSION_DENIED',\n  /** 定位失败 */\n  LOCATION_FAILED = 'LOCATION_FAILED',\n  /** 原生模块不可用 */\n  NATIVE_MODULE_UNAVAILABLE = 'NATIVE_MODULE_UNAVAILABLE',\n  /** 地图视图未初始化 */\n  MAP_VIEW_NOT_INITIALIZED = 'MAP_VIEW_NOT_INITIALIZED',\n  /** 参数错误 */\n  INVALID_PARAMETER = 'INVALID_PARAMETER',\n  /** 网络错误 */\n  NETWORK_ERROR = 'NETWORK_ERROR',\n}\n\n/**\n * 错误详情接口\n */\nexport interface ErrorDetails {\n  /** 错误类型 */\n  type: ErrorType;\n  /** 错误消息 */\n  message: string;\n  /** 解决方案 */\n  solution: string;\n  /** 文档链接 */\n  docUrl?: string;\n  /** 原始错误 */\n  originalError?: Error;\n}\n\n/**\n * 自定义错误类\n */\nexport class GaodeMapError extends Error {\n  type: ErrorType;\n  solution: string;\n  docUrl?: string;\n  originalError?: Error;\n\n  constructor(details: ErrorDetails) {\n    const fullMessage = `\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n🗺️  高德地图错误 [${details.type}]\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n❌ 错误信息：\n   ${details.message}\n\n💡 解决方案：\n   ${details.solution}\n\n${details.docUrl ? `📖 详细文档：\\n   ${details.docUrl}\\n` : ''}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;\n    super(fullMessage);\n    this.name = 'GaodeMapError';\n    this.type = details.type;\n    this.solution = details.solution;\n    this.docUrl = details.docUrl;\n    this.originalError = details.originalError;\n  }\n}\n\n/**\n * 错误处理器类\n */\nexport class ErrorHandler {\n  private static docBaseUrl = 'https://TomWq.github.io/expo-gaode-map';\n\n  /**\n   * SDK 未初始化错误\n   */\n  static sdkNotInitialized(): GaodeMapError {\n    return new GaodeMapError({\n      type: ErrorType.SDK_NOT_INITIALIZED,\n      message: '高德地图 SDK 尚未初始化',\n      solution: `请在使用地图功能前先调用 initSDK()：\n\nimport ExpoGaodeMapModule from 'expo-gaode-map';\n\nuseEffect(() => {\n  // 在组件挂载时初始化\n  ExpoGaodeMapModule.initSDK({\n    androidKey: 'your-android-key',\n    iosKey: 'your-ios-key',\n  });\n}, []);\n\n⚠️  常见原因：\n1. 忘记调用 initSDK() 就使用了定位或地图功能\n2. initSDK() 调用时机过晚（应在 useEffect 中尽早调用）\n3. 使用 Config Plugin 但未重新构建原生代码`,\n      docUrl: `${this.docBaseUrl}/guide/initialization.html`,\n    });\n  }\n\n  /**\n   * API Key 配置错误\n   */\n  static invalidApiKey(platform: 'android' | 'ios' | 'both'): GaodeMapError {\n    const platformText = {\n      android: 'Android',\n      ios: 'iOS',\n      both: 'Android 和 iOS',\n    }[platform];\n\n    return new GaodeMapError({\n      type: ErrorType.INVALID_API_KEY,\n      message: `${platformText} API Key 配置错误或未配置`,\n      solution: `请检查以下步骤：\n\n1️⃣  获取 API Key：\n   • 访问高德开放平台：https://lbs.amap.com/\n   • 注册并创建应用\n   • 获取对应平台的 API Key\n\n2️⃣  配置 API Key（推荐使用 Config Plugin）：\n\n在 app.json 中配置：\n{\n  \"expo\": {\n    \"plugins\": [\n      [\n        \"expo-gaode-map\",\n        {\n          \"androidKey\": \"your-android-key\",\n          \"iosKey\": \"your-ios-key\"\n        }\n      ]\n    ]\n  }\n}\n\n然后重新构建：\nnpx expo prebuild --clean\nnpx expo run:${platform === 'ios' ? 'ios' : 'android'}\n\n3️⃣  或在代码中配置：\nExpoGaodeMapModule.initSDK({\n  androidKey: 'your-android-key',\n  iosKey: 'your-ios-key',\n});`,\n      docUrl: `${this.docBaseUrl}/guide/initialization.html`,\n    });\n  }\n\n  /**\n   * 权限未授予错误\n   */\n  static permissionDenied(permissionType: 'location'): GaodeMapError {\n    return new GaodeMapError({\n      type: ErrorType.PERMISSION_DENIED,\n      message: '定位权限未授予，无法使用定位功能',\n      solution: `请按以下步骤授予权限：\n\n1️⃣  请求权限：\nimport ExpoGaodeMapModule from 'expo-gaode-map';\n\nconst checkPermission = async () => {\n  // 检查权限状态\n  const status = await ExpoGaodeMapModule.checkLocationPermission();\n  \n  if (!status.granted) {\n    // 请求权限\n    const result = await ExpoGaodeMapModule.requestLocationPermission();\n    \n    if (!result.granted) {\n      // 用户拒绝授权，引导用户去设置\n      Alert.alert(\n        '需要定位权限',\n        '请在设置中开启定位权限以使用地图功能',\n        [\n          { text: '取消', style: 'cancel' },\n          { text: '去设置', onPress: () => Linking.openSettings() }\n        ]\n      );\n    }\n  }\n};\n\n2️⃣  iOS 配置（在 app.json 中）：\n{\n  \"expo\": {\n    \"ios\": {\n      \"infoPlist\": {\n        \"NSLocationWhenInUseUsageDescription\": \"需要获取您的位置信息以显示地图\",\n        \"NSLocationAlwaysAndWhenInUseUsageDescription\": \"需要获取您的位置信息\"\n      }\n    }\n  }\n}\n\n3️⃣  Android 配置（Config Plugin 会自动添加）：\n使用 expo-gaode-map 的 Config Plugin 会自动添加必要的权限声明`,\n      docUrl: `${this.docBaseUrl}/guide/getting-started.html#权限配置`,\n    });\n  }\n\n  /**\n   * 定位失败错误\n   */\n  static locationFailed(reason?: string): GaodeMapError {\n    return new GaodeMapError({\n      type: ErrorType.LOCATION_FAILED,\n      message: `定位失败${reason ? `：${reason}` : ''}`,\n      solution: `请检查以下问题：\n\n1️⃣  设备 GPS 是否开启\n2️⃣  网络连接是否正常\n3️⃣  定位权限是否已授予\n4️⃣  是否在室内或信号较弱的地方\n\n💡 解决方法：\n// 配置定位参数\nExpoGaodeMapModule.setLocationTimeout(30); // 增加超时时间\nExpoGaodeMapModule.setInterval(2000); // 设置定位间隔\n\n// Android 特有配置\nExpoGaodeMapModule.setLocationMode(2); // 高精度模式\nExpoGaodeMapModule.setGpsFirst(true);  // GPS 优先\n\n// iOS 特有配置\nExpoGaodeMapModule.setDesiredAccuracy(0); // 最佳精度`,\n      docUrl: `${this.docBaseUrl}/api/location.html`,\n    });\n  }\n\n  /**\n   * 原生模块不可用错误\n   */\n  static nativeModuleUnavailable(): GaodeMapError {\n    return new GaodeMapError({\n      type: ErrorType.NATIVE_MODULE_UNAVAILABLE,\n      message: 'expo-gaode-map 原生模块不可用',\n      solution: `请检查以下步骤：\n\n1️⃣  确认已正确安装：\nnpm install expo-gaode-map\n# 或\npnpm install expo-gaode-map\n\n2️⃣  重新构建原生代码：\nnpx expo prebuild --clean\nnpx expo run:android\nnpx expo run:ios\n\n3️⃣  检查 Expo 版本兼容性：\n• expo-gaode-map 需要 Expo SDK 49+\n• 不支持 Expo Go，必须使用 Development Build\n\n4️⃣  检查是否与其他包冲突：\n• 不能同时安装 expo-gaode-map 和 expo-gaode-map-navigation\n• 两个包选择其一使用\n\n5️⃣  清理缓存后重试：\ncd android && ./gradlew clean && cd ..\ncd ios && pod deintegrate && pod install && cd ..`,\n      docUrl: `${this.docBaseUrl}/guide/getting-started.html`,\n    });\n  }\n\n  /**\n   * 地图视图未初始化错误\n   */\n  static mapViewNotInitialized(methodName: string): GaodeMapError {\n    return new GaodeMapError({\n      type: ErrorType.MAP_VIEW_NOT_INITIALIZED,\n      message: `无法调用 ${methodName}：地图视图尚未初始化`,\n      solution: `请确保：\n\n1️⃣  MapView 已经渲染完成\n2️⃣  使用 ref 获取地图实例后再调用方法\n\n正确用法：\nimport { MapView, MapViewRef } from 'expo-gaode-map';\n\nconst App = () => {\n  const mapRef = useRef<MapViewRef>(null);\n  \n  // ❌ 错误：在渲染前调用\n  // mapRef.current?.moveCamera(...);\n  \n  // ✅ 正确：等待地图加载完成\n  const handleMapReady = () => {\n    mapRef.current?.moveCamera({\n      target: { latitude: 39.9, longitude: 116.4 },\n      zoom: 15,\n    });\n  };\n  \n  return (\n    <MapView\n      ref={mapRef}\n      onMapReady={handleMapReady}\n    />\n  );\n};`,\n      docUrl: `${this.docBaseUrl}/api/mapview.html`,\n    });\n  }\n\n  /**\n   * 参数错误\n   */\n  static invalidParameter(paramName: string, expected: string, received: any): GaodeMapError {\n    return new GaodeMapError({\n      type: ErrorType.INVALID_PARAMETER,\n      message: `参数 \"${paramName}\" 类型错误`,\n      solution: `期望类型：${expected}\n实际接收：${typeof received} (${JSON.stringify(received)})\n\n请检查传入的参数是否符合要求。\n\n💡 提示：\n• 使用 TypeScript 可以在编译时发现类型错误\n• 参考 API 文档了解正确的参数类型`,\n      docUrl: `${this.docBaseUrl}/api/`,\n    });\n  }\n\n  /**\n   * 网络错误\n   */\n  static networkError(originalError?: Error): GaodeMapError {\n    return new GaodeMapError({\n      type: ErrorType.NETWORK_ERROR,\n      message: '网络请求失败',\n      solution: `请检查：\n\n1️⃣  网络连接是否正常\n2️⃣  API Key 是否有效\n3️⃣  是否超出配额限制\n\n💡 如果问题持续，请：\n• 检查高德开放平台控制台\n• 查看 API 调用量和配额\n• 确认 Key 的服务是否已开通`,\n      docUrl: `${this.docBaseUrl}/guide/troubleshooting.html`,\n      originalError,\n    });\n  }\n\n  /**\n   * 包装原生错误，提供更友好的提示\n   */\n  static wrapNativeError(error: any, context: string): GaodeMapError {\n    const errorMessage = error?.message || String(error);\n    \n    // SDK 未初始化相关错误\n    if (\n      errorMessage.includes('not initialized') ||\n      errorMessage.includes('未初始化') ||\n      errorMessage.includes('SDK未设置')\n    ) {\n      return this.sdkNotInitialized();\n    }\n    \n    // API Key 相关错误\n    if (\n      errorMessage.includes('key') ||\n      errorMessage.includes('invalid') ||\n      errorMessage.includes('鉴权失败')\n    ) {\n      return this.invalidApiKey('both');\n    }\n    \n    // 权限相关错误\n    if (\n      errorMessage.includes('permission') ||\n      errorMessage.includes('权限')\n    ) {\n      return this.permissionDenied('location');\n    }\n    \n    // 定位相关错误\n    if (\n      errorMessage.includes('location') ||\n      errorMessage.includes('定位')\n    ) {\n      return this.locationFailed(errorMessage);\n    }\n    \n    // 通用错误\n    return new GaodeMapError({\n      type: ErrorType.INVALID_PARAMETER,\n      message: `${context} 失败`,\n      solution: `原始错误信息：${errorMessage}\n\n如果问题持续，请：\n1. 查看完整的错误堆栈\n2. 检查 API 调用参数\n3. 提交 Issue：https://github.com/TomWq/expo-gaode-map/issues`,\n      originalError: error instanceof Error ? error : undefined,\n    });\n  }\n}\n\n/**\n * 错误日志工具\n */\nexport class ErrorLogger {\n  private static isEnabled = __DEV__;\n\n  /**\n   * 启用/禁用错误日志\n   */\n  static setEnabled(enabled: boolean) {\n    this.isEnabled = enabled;\n  }\n\n  /**\n   * 记录错误\n   */\n  static log(error: GaodeMapError) {\n    if (!this.isEnabled) return;\n\n    console.error(error.message);\n    \n    if (error.originalError) {\n      console.error('原始错误：', error.originalError);\n    }\n  }\n\n  /**\n   * 记录警告\n   */\n  static warn(message: string, details?: any) {\n    if (!this.isEnabled) return;\n    \n    console.warn(`⚠️  expo-gaode-map: ${message}`, details || '');\n  }\n}"]}

package/build/utils/PermissionUtils.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 位置权限类型
+ */
+export declare enum LocationPermissionType {
+    /** 仅前台（使用时） */
+    FOREGROUND = "foreground",
+    /** 后台位置 */
+    BACKGROUND = "background",
+    /** 前台+后台 */
+    FOREGROUND_AND_BACKGROUND = "foreground_and_background"
+}
+/**
+ * 权限工具类
+ *
+ * 🔔 **重要说明**：
+ *
+ * 本工具类**不执行实际的权限请求**，仅提供：
+ * - 平台检测（Android 14+、iOS 17+）
+ * - 权限说明文案（适配新系统特性）
+ * - 最佳实践建议
+ * - 诊断信息
+ *
+ * **实际权限请求请使用**：
+ * ```typescript
+ * import ExpoGaodeMapModule from 'expo-gaode-map';
+ *
+ * // 检查权限
+ * const status = await ExpoGaodeMapModule.checkLocationPermission();
+ *
+ * // 请求权限
+ * const result = await ExpoGaodeMapModule.requestLocationPermission();
+ * ```
+ *
+ * 本工具类主要用于在请求权限**之前**向用户展示说明文案。
+ */
+export declare class PermissionUtils {
+    /**
+     * 检查当前平台的系统版本
+     */
+    static getSystemInfo(): {
+        platform: 'android' | 'ios';
+        version: number;
+        isAndroid14Plus: boolean;
+        isiOS17Plus: boolean;
+    };
+    /**
+     * 获取权限说明文案
+     */
+    static getPermissionRationale(type: LocationPermissionType): string;
+    /**
+     * Android 权限说明文案
+     */
+    private static getAndroidRationale;
+    /**
+     * iOS 权限说明文案
+     */
+    private static getiOSRationale;
+    /**
+     * 获取精确位置权限说明（iOS 14+）
+     */
+    static getAccuracyRationale(): string;
+    /**
+     * 获取权限请求的最佳实践建议
+     */
+    static getBestPractices(): {
+        android14: string[];
+        ios17: string[];
+        general: string[];
+    };
+    /**
+     * 验证 Info.plist 配置（仅 iOS）
+     */
+    static validateiOSConfiguration(): {
+        valid: boolean;
+        missingKeys: string[];
+        recommendations: string[];
+    };
+    /**
+     * 检查是否支持后台位置权限
+     */
+    static supportsBackgroundLocation(): boolean;
+    /**
+     * 打印权限诊断信息
+     */
+    static printDiagnostics(): void;
+}
+/**
+ * 向后兼容的别名
+ * @deprecated 请使用 PermissionUtils
+ */
+export declare const PermissionManager: typeof PermissionUtils;
+//# sourceMappingURL=PermissionUtils.d.ts.map