expo-gaode-map-web-api 1.0.1-next.0

package/build/utils/client.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 高德地图 Web API HTTP 客户端
+ */
+import { type ErrorInfo } from './errorCodes';
+/**
+ * 高德地图 API 错误类
+ */
+export declare class GaodeAPIError extends Error {
+    /** 错误码 */
+    readonly code: string;
+    /** 官方错误信息 */
+    readonly info: string;
+    /** 友好的错误描述 */
+    readonly description: string;
+    /** 问题排查建议 */
+    readonly suggestion: string;
+    /** 错误类型 */
+    readonly type: ErrorInfo['type'];
+    /** API 响应状态 */
+    readonly status: string;
+    constructor(status: string, info: string, infocode: string);
+    /**
+     * 获取完整的错误信息（用于日志记录）
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        info: string;
+        description: string;
+        suggestion: string;
+        type: "success" | "key_error" | "param_error" | "route_error" | "service_error" | "quota_error";
+        status: string;
+    };
+    /**
+     * 获取用户友好的错误提示
+     */
+    getUserMessage(): string;
+}
+/**
+ * @deprecated 使用 GaodeAPIError 代替
+ */
+export interface APIError {
+    status: string;
+    info: string;
+    infocode: string;
+}
+/**
+ * HTTP 客户端配置
+ */
+export interface ClientConfig {
+    /** 高德地图 Web API Key ,默认可以通过 getWebKey 获取，所以不再是必传*/
+    key?: string;
+    /** 基础 URL，默认：https://restapi.amap.com */
+    baseURL?: string;
+    /** 请求超时时间（毫秒），默认：10000 */
+    timeout?: number;
+}
+/**
+ * 高德地图 Web API HTTP 客户端
+ */
+export declare class GaodeWebAPIClient {
+    private key;
+    private baseURL;
+    private timeout;
+    constructor(config: ClientConfig);
+    /**
+     * 发起 HTTP 请求
+     */
+    request<T>(path: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * 更新 API Key
+     */
+    setKey(key: string): void;
+    /**
+     * 获取当前 API Key
+     */
+    getKey(): string;
+}

package/build/utils/client.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * 高德地图 Web API HTTP 客户端
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GaodeWebAPIClient = exports.GaodeAPIError = void 0;
+const errorCodes_1 = require("./errorCodes");
+function resolveWebKey() {
+    // 1) 尝试从核心地图包读取
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const core = require('expo-gaode-map');
+        const fn = core?.getWebKey;
+        if (typeof fn === 'function') {
+            return fn();
+        }
+    }
+    catch {
+        // ignore
+    }
+    // 2) 若未安装核心包，则尝试从导航包读取（导航内置地图）
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const nav = require('expo-gaode-map-navigation');
+        const fn2 = nav?.getWebKey;
+        if (typeof fn2 === 'function') {
+            return fn2();
+        }
+    }
+    catch {
+        // ignore
+    }
+    return undefined;
+}
+/**
+ * 高德地图 API 错误类
+ */
+class GaodeAPIError extends Error {
+    constructor(status, info, infocode) {
+        const errorInfo = (0, errorCodes_1.getErrorInfo)(infocode);
+        // 使用友好的错误描述作为 message
+        super(`${errorInfo.description} (${infocode})`);
+        this.name = 'GaodeAPIError';
+        this.status = status;
+        this.code = infocode;
+        this.info = info;
+        this.description = errorInfo.description;
+        this.suggestion = errorInfo.suggestion;
+        this.type = errorInfo.type;
+        // 保持正确的 prototype 链
+        Object.setPrototypeOf(this, GaodeAPIError.prototype);
+    }
+    /**
+     * 获取完整的错误信息（用于日志记录）
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            info: this.info,
+            description: this.description,
+            suggestion: this.suggestion,
+            type: this.type,
+            status: this.status,
+        };
+    }
+    /**
+     * 获取用户友好的错误提示
+     */
+    getUserMessage() {
+        return `${this.description}\n\n💡 ${this.suggestion}`;
+    }
+}
+exports.GaodeAPIError = GaodeAPIError;
+/**
+ * 高德地图 Web API HTTP 客户端
+ */
+class GaodeWebAPIClient {
+    constructor(config) {
+        this.key = config.key || resolveWebKey() || '';
+        this.baseURL = config.baseURL || 'https://restapi.amap.com';
+        this.timeout = config.timeout || 10000;
+    }
+    /**
+     * 发起 HTTP 请求
+     */
+    async request(path, params = {}) {
+        // 构建 URL
+        const url = new URL(path, this.baseURL);
+        // 添加 key 参数
+        url.searchParams.append('key', this.key);
+        // 添加其他参数
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined && value !== null) {
+                url.searchParams.append(key, String(value));
+            }
+        });
+        // 创建 AbortController 用于超时控制
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            // 发起请求
+            const response = await fetch(url.toString(), {
+                method: 'GET',
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            // 检查 HTTP 状态
+            if (!response.ok) {
+                throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+            }
+            // 解析 JSON
+            const data = await response.json();
+            // 检查 API 状态
+            if (data.status !== '1' && !(0, errorCodes_1.isSuccess)(data.infocode)) {
+                throw new GaodeAPIError(data.status, data.info || 'Unknown error', data.infocode || '0');
+            }
+            return data;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error) {
+                if (error.name === 'AbortError') {
+                    throw new Error(`Request timeout after ${this.timeout}ms`);
+                }
+                throw error;
+            }
+            throw new Error('Unknown error occurred');
+        }
+    }
+    /**
+     * 更新 API Key
+     */
+    setKey(key) {
+        this.key = key;
+    }
+    /**
+     * 获取当前 API Key
+     */
+    getKey() {
+        return this.key;
+    }
+}
+exports.GaodeWebAPIClient = GaodeWebAPIClient;

package/build/utils/errorCodes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 高德地图 Web API 错误码定义
+ * 文档: https://lbs.amap.com/api/webservice/guide/tools/info
+ */
+/**
+ * 错误码类型
+ */
+export type InfoCode = '10000' | '10001' | '10002' | '10003' | '10004' | '10005' | '10006' | '10007' | '10008' | '10009' | '10010' | '10011' | '10012' | '10013' | '10014' | '10015' | '10016' | '10017' | '10019' | '10020' | '10021' | '10026' | '10029' | '10041' | '10044' | '10045' | '20000' | '20001' | '20002' | '20003' | '20011' | '20012' | '20800' | '20801' | '20802' | '20803' | '30001' | '30002' | '30003' | '32000' | '32001' | '32002' | '32003' | '32200' | '32201' | '32202' | '32203' | '40000' | '40001' | '40002' | '40003';
+/**
+ * 错误信息接口
+ */
+export interface ErrorInfo {
+    /** 错误码 */
+    code: InfoCode;
+    /** 官方错误信息 */
+    message: string;
+    /** 友好的中文描述 */
+    description: string;
+    /** 问题排查建议 */
+    suggestion: string;
+    /** 错误类型 */
+    type: 'success' | 'key_error' | 'param_error' | 'route_error' | 'service_error' | 'quota_error';
+}
+/**
+ * 高德地图 Web API 错误码映射表
+ */
+export declare const ERROR_CODE_MAP: Record<InfoCode, ErrorInfo>;
+/**
+ * 根据错误码获取错误信息
+ */
+export declare function getErrorInfo(infocode: string): ErrorInfo;
+/**
+ * 判断是否为成功状态
+ */
+export declare function isSuccess(infocode: string): boolean;

package/build/utils/errorCodes.js

@@ -0,0 +1,396 @@
+"use strict";
+/**
+ * 高德地图 Web API 错误码定义
+ * 文档: https://lbs.amap.com/api/webservice/guide/tools/info
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_CODE_MAP = void 0;
+exports.getErrorInfo = getErrorInfo;
+exports.isSuccess = isSuccess;
+/**
+ * 高德地图 Web API 错误码映射表
+ */
+exports.ERROR_CODE_MAP = {
+    // 成功
+    '10000': {
+        code: '10000',
+        message: 'OK',
+        description: '请求正常',
+        suggestion: '请求成功',
+        type: 'success',
+    },
+    // Key相关错误
+    '10001': {
+        code: '10001',
+        message: 'INVALID_USER_KEY',
+        description: 'Key不正确或过期',
+        suggestion: '请检查您的 API Key 是否正确，或前往控制台查看 Key 是否已过期',
+        type: 'key_error',
+    },
+    '10002': {
+        code: '10002',
+        message: 'SERVICE_NOT_AVAILABLE',
+        description: '没有权限使用相应的服务或请求接口路径拼写错误',
+        suggestion: '1. 检查 Key 是否有权限使用该服务\n2. 检查请求接口路径是否正确',
+        type: 'key_error',
+    },
+    '10003': {
+        code: '10003',
+        message: 'DAILY_QUERY_OVER_LIMIT',
+        description: '访问已超出日访问量',
+        suggestion: '日访问量已超限，系统已自动封停，第二天 0:00 会自动解封',
+        type: 'key_error',
+    },
+    '10004': {
+        code: '10004',
+        message: 'ACCESS_TOO_FREQUENT',
+        description: '单位时间内访问过于频繁',
+        suggestion: '单位时间内（1分钟）访问量超限，请降低请求频率，下一分钟自动解封',
+        type: 'key_error',
+    },
+    '10005': {
+        code: '10005',
+        message: 'INVALID_USER_IP',
+        description: 'IP白名单出错，发送请求的服务器IP不在白名单内',
+        suggestion: '请在控制台检查并设置正确的 IP 白名单',
+        type: 'key_error',
+    },
+    '10006': {
+        code: '10006',
+        message: 'INVALID_USER_DOMAIN',
+        description: '绑定域名无效',
+        suggestion: '请在控制台重新设置绑定域名',
+        type: 'key_error',
+    },
+    '10007': {
+        code: '10007',
+        message: 'INVALID_USER_SIGNATURE',
+        description: '数字签名未通过验证',
+        suggestion: '请检查数字签名生成算法是否正确',
+        type: 'key_error',
+    },
+    '10008': {
+        code: '10008',
+        message: 'INVALID_USER_SCODE',
+        description: 'MD5安全码未通过验证',
+        suggestion: '请检查 Key 绑定的 SHA1 和 package 是否与 SDK 包一致',
+        type: 'key_error',
+    },
+    '10009': {
+        code: '10009',
+        message: 'USERKEY_PLAT_NOMATCH',
+        description: '请求Key与绑定平台不符',
+        suggestion: '请使用对应平台的 Key（如：Web 服务 Key、JS API Key 等）',
+        type: 'key_error',
+    },
+    '10010': {
+        code: '10010',
+        message: 'IP_QUERY_OVER_LIMIT',
+        description: 'IP访问超限',
+        suggestion: '单个 IP 访问次数超限已被封停，请提交工单联系客服',
+        type: 'key_error',
+    },
+    '10011': {
+        code: '10011',
+        message: 'NOT_SUPPORT_HTTPS',
+        description: '服务不支持HTTPS请求',
+        suggestion: '该服务暂不支持 HTTPS，请使用 HTTP 或提交工单申请支持',
+        type: 'key_error',
+    },
+    '10012': {
+        code: '10012',
+        message: 'INSUFFICIENT_PRIVILEGES',
+        description: '权限不足，服务请求被拒绝',
+        suggestion: '您的 Key 没有权限访问该服务，请在控制台开通相应服务',
+        type: 'key_error',
+    },
+    '10013': {
+        code: '10013',
+        message: 'USER_KEY_RECYCLED',
+        description: 'Key被删除',
+        suggestion: 'Key 已被删除无法使用，请使用有效的 Key',
+        type: 'key_error',
+    },
+    '10014': {
+        code: '10014',
+        message: 'QPS_HAS_EXCEEDED_THE_LIMIT',
+        description: '云图服务QPS超限',
+        suggestion: 'QPS 超出限制，请降低请求频率或在控制台提工单',
+        type: 'key_error',
+    },
+    '10015': {
+        code: '10015',
+        message: 'GATEWAY_TIMEOUT',
+        description: '受单机QPS限流限制',
+        suggestion: '建议降低请求的 QPS 或提工单联系客服',
+        type: 'key_error',
+    },
+    '10016': {
+        code: '10016',
+        message: 'SERVER_IS_BUSY',
+        description: '服务器负载过高',
+        suggestion: '服务器繁忙，请稍后重试',
+        type: 'key_error',
+    },
+    '10017': {
+        code: '10017',
+        message: 'RESOURCE_UNAVAILABLE',
+        description: '所请求的资源不可用',
+        suggestion: '请求的资源暂时不可用，请稍后重试',
+        type: 'key_error',
+    },
+    '10019': {
+        code: '10019',
+        message: 'CQPS_HAS_EXCEEDED_THE_LIMIT',
+        description: '使用的某个服务总QPS超限',
+        suggestion: 'QPS 超出限制，请降低请求频率',
+        type: 'key_error',
+    },
+    '10020': {
+        code: '10020',
+        message: 'CKQPS_HAS_EXCEEDED_THE_LIMIT',
+        description: '某个Key使用某个服务接口QPS超出限制',
+        suggestion: 'QPS 超出限制，请降低该 Key 的请求频率',
+        type: 'key_error',
+    },
+    '10021': {
+        code: '10021',
+        message: 'CUQPS_HAS_EXCEEDED_THE_LIMIT',
+        description: '账号使用某个服务接口QPS超出限制',
+        suggestion: 'QPS 超出限制，请降低账号的请求频率',
+        type: 'key_error',
+    },
+    '10026': {
+        code: '10026',
+        message: 'INVALID_REQUEST',
+        description: '账号处于被封禁状态',
+        suggestion: '账号因违规被封禁，如有异议请登录控制台提交申诉工单',
+        type: 'key_error',
+    },
+    '10029': {
+        code: '10029',
+        message: 'ABROAD_DAILY_QUERY_OVER_LIMIT',
+        description: '某个Key的海外服务日调用量超出限制',
+        suggestion: '海外服务日调用量已超限，请等待次日解封',
+        type: 'key_error',
+    },
+    '10041': {
+        code: '10041',
+        message: 'NO_EFFECTIVE_INTERFACE',
+        description: '请求的接口权限过期',
+        suggestion: '接口权限已过期，请提交工单联系客服',
+        type: 'key_error',
+    },
+    '10044': {
+        code: '10044',
+        message: 'USER_DAILY_QUERY_OVER_LIMIT',
+        description: '账号维度日调用量超出限制',
+        suggestion: '账号日调用量已超限，请等待次日解封',
+        type: 'key_error',
+    },
+    '10045': {
+        code: '10045',
+        message: 'USER_ABROAD_DAILY_QUERY_OVER_LIMIT',
+        description: '账号维度海外服务日调用量超出限制',
+        suggestion: '账号海外服务日调用量已超限，请等待次日解封',
+        type: 'key_error',
+    },
+    // 请求参数错误
+    '20000': {
+        code: '20000',
+        message: 'INVALID_PARAMS',
+        description: '请求参数非法',
+        suggestion: '请检查请求参数的值是否符合规范要求',
+        type: 'param_error',
+    },
+    '20001': {
+        code: '20001',
+        message: 'MISSING_REQUIRED_PARAMS',
+        description: '缺少必填参数',
+        suggestion: '请检查并补充接口要求的必填参数',
+        type: 'param_error',
+    },
+    '20002': {
+        code: '20002',
+        message: 'ILLEGAL_REQUEST',
+        description: '请求协议非法',
+        suggestion: '请检查请求方法是否正确（GET/POST）',
+        type: 'param_error',
+    },
+    '20003': {
+        code: '20003',
+        message: 'UNKNOWN_ERROR',
+        description: '其他未知错误',
+        suggestion: '发生未知错误，请提交工单联系客服',
+        type: 'param_error',
+    },
+    '20011': {
+        code: '20011',
+        message: 'INSUFFICIENT_ABROAD_PRIVILEGES',
+        description: '查询坐标在海外，但没有海外地图权限',
+        suggestion: '请在控制台开通海外地图服务权限',
+        type: 'param_error',
+    },
+    '20012': {
+        code: '20012',
+        message: 'ILLEGAL_CONTENT',
+        description: '查询信息存在非法内容',
+        suggestion: '请检查查询内容是否合法',
+        type: 'param_error',
+    },
+    // 路径规划错误
+    '20800': {
+        code: '20800',
+        message: 'OUT_OF_SERVICE',
+        description: '规划点不在中国陆地范围内',
+        suggestion: '起点、终点或途经点不在中国大陆范围内，请检查坐标',
+        type: 'route_error',
+    },
+    '20801': {
+        code: '20801',
+        message: 'NO_ROADS_NEARBY',
+        description: '规划点附近搜不到路',
+        suggestion: '起点、终点或途经点附近没有道路，请调整坐标位置',
+        type: 'route_error',
+    },
+    '20802': {
+        code: '20802',
+        message: 'ROUTE_FAIL',
+        description: '路线计算失败',
+        suggestion: '路线计算失败，通常是由于道路连通关系导致，请尝试调整起终点',
+        type: 'route_error',
+    },
+    '20803': {
+        code: '20803',
+        message: 'OVER_DIRECTION_RANGE',
+        description: '起点终点距离过长',
+        suggestion: '起点和终点距离过长，请缩短距离或添加途经点',
+        type: 'route_error',
+    },
+    // 服务响应错误
+    '30001': {
+        code: '30001',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '30002': {
+        code: '30002',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '30003': {
+        code: '30003',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '32000': {
+        code: '32000',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '32001': {
+        code: '32001',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '32002': {
+        code: '32002',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '32003': {
+        code: '32003',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '32200': {
+        code: '32200',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '32201': {
+        code: '32201',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '32202': {
+        code: '32202',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    '32203': {
+        code: '32203',
+        message: 'ENGINE_RESPONSE_DATA_ERROR',
+        description: '服务响应失败',
+        suggestion: '请检查传入参数是否正确，如无法解决请提交工单',
+        type: 'service_error',
+    },
+    // 配额相关错误
+    '40000': {
+        code: '40000',
+        message: 'QUOTA_PLAN_RUN_OUT',
+        description: '余额耗尽',
+        suggestion: '服务余额已耗尽，请前往控制台充值',
+        type: 'quota_error',
+    },
+    '40001': {
+        code: '40001',
+        message: 'GEOFENCE_MAX_COUNT_REACHED',
+        description: '围栏个数达到上限',
+        suggestion: 'Key 可创建的地理围栏数量已达上限',
+        type: 'quota_error',
+    },
+    '40002': {
+        code: '40002',
+        message: 'SERVICE_EXPIRED',
+        description: '购买服务到期',
+        suggestion: '服务已到期，请前往控制台续费',
+        type: 'quota_error',
+    },
+    '40003': {
+        code: '40003',
+        message: 'ABROAD_QUOTA_PLAN_RUN_OUT',
+        description: '海外服务余额耗尽',
+        suggestion: '海外服务余额已耗尽，请前往控制台充值',
+        type: 'quota_error',
+    },
+};
+/**
+ * 根据错误码获取错误信息
+ */
+function getErrorInfo(infocode) {
+    const code = infocode;
+    return exports.ERROR_CODE_MAP[code] || {
+        code: code,
+        message: 'UNKNOWN_ERROR',
+        description: '未知错误',
+        suggestion: `未知错误码: ${infocode}，请联系技术支持`,
+        type: 'service_error',
+    };
+}
+/**
+ * 判断是否为成功状态
+ */
+function isSuccess(infocode) {
+    return infocode === '10000';
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "expo-gaode-map-web-api",
+  "version": "1.0.1-next.0",
+  "description": "高德地图 Web API 服务 - 搜索、路径规划、地理编码（纯 JavaScript 实现），配合 expo-gaode-map 使用",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "keywords": [
+    "react-native",
+    "expo",
+    "amap",
+    "gaode",
+    "web-api",
+    "search",
+    "geocode",
+    "route",
+    "高德地图"
+  ],
+  "repository": "https://github.com/TomWq/expo-gaode-map",
+  "bugs": {
+    "url": "https://github.com/TomWq/expo-gaode-map/issues"
+  },
+  "author": "尚博信_王强 <wangqiang03@sunboxsoft.com> (https://github.com/TomWq)",
+  "license": "MIT",
+  "homepage": "https://github.com/TomWq/expo-gaode-map#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/react": "~19.1.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "react-native": "*"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf build",
+    "postinstall": "node -e \"try{require.resolve('expo-gaode-map');process.exit(0)}catch(e1){try{require.resolve('expo-gaode-map-navigation');process.exit(0)}catch(e2){console.error('[expo-gaode-map-web-api] 需要安装基础地图组件：expo-gaode-map 或 expo-gaode-map-navigation 中的任意一个。\\n请执行：pnpm add expo-gaode-map 或 pnpm add expo-gaode-map-navigation');process.exit(1)}}\""
+  }
+}