expo-gaode-map-web-api 2.0.6 → 2.0.8

package/README.md

@@ -23,6 +23,7 @@
   - ✅ 公交（含多策略、跨城、地铁图模式、出入口等）
 - 搜索服务
   - ✅ POI 搜索（关键字、周边、类型、详情）
+  - ✅ AOI 边界查询（需开通高阶服务权限）
   - ✅ 输入提示（POI/公交站点/公交线路）
 
 ## 安装
@@ -83,6 +84,18 @@ import { GaodeWebAPI } from 'expo-gaode-map-web-api';
 const api = new GaodeWebAPI({ key: 'your-web-api-key' });
 ```
 
+### Web API Key 解析顺序
+
+`GaodeWebAPI` 会按以下顺序解析 Web API Key：
+
+1. `new GaodeWebAPI({ key })` 中显式传入的 `key`
+2. `expo-gaode-map` 的 `ExpoGaodeMapModule.initSDK({ webKey })`
+3. `expo-gaode-map-navigation` 的 `ExpoGaodeMapModule.initSDK({ webKey })`
+
+如果都没有提供，会直接抛出明确错误。
+
+如果你的业务需要稳定使用 Web API，推荐显式传入 `key`，尤其是在示例工程、测试环境或多入口初始化场景里。
+
 ### 4. 调用服务接口
 ```ts
 // 逆地理编码：坐标 → 地址
@@ -98,10 +111,96 @@ const route = await api.route.driving('116.481028,39.989643', '116.434446,39.908
   show_fields: 'cost,navi,polyline',
 });
 console.log(route.route.paths[0].distance);
+
+// AOI 边界查询（需开通权限）
+const aoi = await api.poi.getAOIBoundary('your-aoi-id');
+console.log(Array.isArray(aoi.aois) ? aoi.aois[0]?.polyline : aoi.aois?.polyline);
 ```
 
 ## 详细用法
 
+### AOI 边界查询
+
+```typescript
+const result = await api.poi.getAOIBoundary('your-aoi-id');
+
+const aoi = Array.isArray(result.aois) ? result.aois[0] : result.aois;
+console.log(aoi?.name);
+console.log(aoi?.polyline);
+```
+
+注意：
+
+- `AOI 边界查询` 是高德 Web 服务里的高阶能力，正式使用前通常需要额外开通权限。
+- 返回的 `polyline` 通常是 `lng,lat;lng,lat;...`，多环场景下可能为 `ring1|ring2`。
+
+## 路线 / AOI 数据适配工具
+
+为了让 Web API 的返回值能直接喂给 `expo-gaode-map` / `expo-gaode-map-navigation` 的用户层地图 API，本包额外提供了几个纯数据适配工具。
+
+### extractRoutePoints(routeResult)
+
+将驾车 / 步行 / 骑行 / 电动车结果中的 `steps.polyline` 摊平成一条连续点集：
+
+```ts
+import { extractRoutePoints } from 'expo-gaode-map-web-api';
+
+const result = await api.route.driving(origin, destination, {
+  show_fields: 'polyline,cost',
+});
+
+const points = extractRoutePoints(result);
+```
+
+### normalizeDrivingRoute(routeResult)
+
+将驾车结果归一化为：
+
+```ts
+interface NormalizedDrivingRoute {
+  distance: number;
+  duration: number;
+  taxiCost?: number;
+  points: RoutePoint[];
+}
+```
+
+### extractAOIBoundary(aoiResult)
+
+将 AOI 查询结果统一转成：
+
+```ts
+interface ExtractedAOIBoundary {
+  id?: string;
+  name?: string;
+  rings: RoutePoint[][];
+}
+```
+
+### extractTransitRoutePoints(transitResult)
+
+将公交换乘结果提取为“每条换乘方案对应一条完整点集”：
+
+```ts
+const lines = extractTransitRoutePoints(transitResult);
+```
+
+### 配合地图组件使用
+
+```tsx
+const routeResult = await api.route.driving(origin, destination, {
+  show_fields: 'polyline,cost',
+});
+
+const points = extractRoutePoints(routeResult);
+
+await mapRef.current?.fitToCoordinates(points, { duration: 500 });
+
+<RouteOverlay points={points} />
+```
+
+这些适配结果可以同时用于 `core` 和 `navigation` 两套地图实现；共享的是数据结构，不是底层地图实现。
+
 ### 逆地理编码
 
 #### 基础用法
@@ -539,6 +638,7 @@ interface ClientConfig {
   - `search()` - 关键字搜索
   - `searchAround()` - 周边搜索
   - `getDetail()` - 详情
+  - `getAOIBoundary()` - AOI 边界查询
 - inputTips - 输入提示
   - `getTips()` - 基础提示
   - `getPOITips()` - POI 类型提示
@@ -688,4 +788,3 @@ try {
 ## License
 
 MIT License
-

package/build/index.d.ts

@@ -44,11 +44,13 @@ import { InputTipsService } from './services/InputTipsService';
 export * from './types/geocode.types';
 export * from './types/route.types';
 export * from './types/inputtips.types';
-export type { POISearchParams, POIAroundParams, POIPolygonParams, POIDetailParams, POIInfo, POISearchResponse, } from './types/poi.types';
+export type { AOIBoundaryInfo, AOIBoundaryParams, AOIBoundaryResponse, POISearchParams, POIAroundParams, POIPolygonParams, POIDetailParams, POIInfo, POISearchResponse, } from './types/poi.types';
 export type { ClientConfig, APIError } from './utils/client';
 export { GaodeAPIError } from './utils/client';
 export { getErrorInfo, isSuccess, ERROR_CODE_MAP } from './utils/errorCodes';
 export type { InfoCode, ErrorInfo } from './utils/errorCodes';
+export { extractAOIBoundary, extractRoutePoints, extractTransitRoutePoints, normalizeDrivingRoute, } from './utils/normalizers';
+export type { ExtractedAOIBoundary, NormalizedDrivingRoute, RoutePoint, } from './utils/normalizers';
 /**
  * 高德地图 Web API 主类
  */

package/build/index.js

@@ -52,7 +52,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GaodeWebAPI = exports.ERROR_CODE_MAP = exports.isSuccess = exports.getErrorInfo = exports.GaodeAPIError = void 0;
+exports.GaodeWebAPI = exports.normalizeDrivingRoute = exports.extractTransitRoutePoints = exports.extractRoutePoints = exports.extractAOIBoundary = exports.ERROR_CODE_MAP = exports.isSuccess = exports.getErrorInfo = exports.GaodeAPIError = void 0;
 /**
  * 在加载 Web API 模块前，强制校验“基础地图提供者”是否已安装。
  * 支持以下任一包：
@@ -132,6 +132,11 @@ var errorCodes_1 = require("./utils/errorCodes");
 Object.defineProperty(exports, "getErrorInfo", { enumerable: true, get: function () { return errorCodes_1.getErrorInfo; } });
 Object.defineProperty(exports, "isSuccess", { enumerable: true, get: function () { return errorCodes_1.isSuccess; } });
 Object.defineProperty(exports, "ERROR_CODE_MAP", { enumerable: true, get: function () { return errorCodes_1.ERROR_CODE_MAP; } });
+var normalizers_1 = require("./utils/normalizers");
+Object.defineProperty(exports, "extractAOIBoundary", { enumerable: true, get: function () { return normalizers_1.extractAOIBoundary; } });
+Object.defineProperty(exports, "extractRoutePoints", { enumerable: true, get: function () { return normalizers_1.extractRoutePoints; } });
+Object.defineProperty(exports, "extractTransitRoutePoints", { enumerable: true, get: function () { return normalizers_1.extractTransitRoutePoints; } });
+Object.defineProperty(exports, "normalizeDrivingRoute", { enumerable: true, get: function () { return normalizers_1.normalizeDrivingRoute; } });
 /**
  * 高德地图 Web API 主类
  */

package/build/services/POIService.d.ts

@@ -2,7 +2,7 @@
  * 高德地图 Web API - POI 搜索服务
  */
 import { GaodeWebAPIClient } from '../utils/client';
-import type { POISearchParams, POIAroundParams, POIPolygonParams, POISearchResponse } from '../types/poi.types';
+import type { AOIBoundaryParams, AOIBoundaryResponse, POISearchParams, POIAroundParams, POIPolygonParams, POISearchResponse } from '../types/poi.types';
 /**
  * POI 搜索服务
  */
@@ -134,4 +134,23 @@ export declare class POIService {
     batchGetDetail(ids: string[], show_fields?: string, version?: 'v3' | 'v5', options?: {
         signal?: AbortSignal;
     }): Promise<POISearchResponse>;
+    /**
+     * AOI 边界查询
+     * 根据 AOI ID 获取其边界 polyline。
+     *
+     * 注意：该接口属于高阶服务，通常需要先在高德开放平台开通权限。
+     *
+     * @param id AOI ID
+     * @param options 可选参数
+     * @returns AOI 边界查询结果
+     *
+     * @example
+     * ```typescript
+     * const result = await api.poi.getAOIBoundary('aoi-id');
+     *
+     * const aoi = Array.isArray(result.aois) ? result.aois[0] : result.aois;
+     * console.log(aoi?.polyline);
+     * ```
+     */
+    getAOIBoundary(id: string, options?: Omit<AOIBoundaryParams, 'id'>): Promise<AOIBoundaryResponse>;
 }

package/build/services/POIService.js

@@ -182,5 +182,34 @@ class POIService {
         const path = `/${version}/place/detail`;
         return this.client.request(path, { params, signal: options?.signal });
     }
+    /**
+     * AOI 边界查询
+     * 根据 AOI ID 获取其边界 polyline。
+     *
+     * 注意：该接口属于高阶服务，通常需要先在高德开放平台开通权限。
+     *
+     * @param id AOI ID
+     * @param options 可选参数
+     * @returns AOI 边界查询结果
+     *
+     * @example
+     * ```typescript
+     * const result = await api.poi.getAOIBoundary('aoi-id');
+     *
+     * const aoi = Array.isArray(result.aois) ? result.aois[0] : result.aois;
+     * console.log(aoi?.polyline);
+     * ```
+     */
+    async getAOIBoundary(id, options) {
+        const { signal, ...rest } = options || {};
+        const params = {
+            id,
+            ...rest,
+        };
+        return this.client.request('/v5/aoi/polyline', {
+            params,
+            signal,
+        });
+    }
 }
 exports.POIService = POIService;

package/build/types/poi.types.d.ts

@@ -353,3 +353,82 @@ export interface POIDetailParams {
      */
     signal?: AbortSignal;
 }
+/**
+ * AOI 边界查询参数
+ *
+ * 注意：该接口属于高阶服务，通常需要单独开通权限后才能正常使用。
+ */
+export interface AOIBoundaryParams {
+    /**
+     * AOI 唯一标识
+     */
+    id: string;
+    /**
+     * 数字签名
+     */
+    sig?: string;
+    /**
+     * JSONP 回调函数名
+     */
+    callback?: string;
+    /**
+     * 透传扩展参数
+     */
+    parameters?: string;
+    /**
+     * AbortSignal 用于取消请求
+     */
+    signal?: AbortSignal;
+}
+/**
+ * AOI 边界信息
+ */
+export interface AOIBoundaryInfo {
+    /** AOI 名称 */
+    name?: string;
+    /** AOI 唯一标识 */
+    id?: string;
+    /** AOI 中心点坐标，格式：经度,纬度 */
+    location?: string;
+    /**
+     * AOI 边界串
+     * 通常格式为：
+     * - 单环：lng,lat;lng,lat;...
+     * - 多环：ring1|ring2
+     */
+    polyline?: string;
+    /** AOI 所属分类 */
+    type?: string;
+    /** AOI 分类编码 */
+    typecode?: string;
+    /** AOI 所属省份 */
+    pname?: string;
+    /** AOI 所属城市 */
+    cityname?: string;
+    /** AOI 所属区域 */
+    adname?: string;
+    /** AOI 详细地址 */
+    address?: string;
+    /** AOI 所属省份编码 */
+    pcode?: string;
+    /** AOI 所属城市编码 */
+    citycode?: string;
+    /** AOI 所属区域编码 */
+    adcode?: string;
+}
+/**
+ * AOI 边界查询响应
+ *
+ * 官方文档字段名为 `aois`，但多数场景只返回单个 AOI 对象；
+ * 这里兼容单对象和数组两种结构，避免调用方被接口细节卡住。
+ */
+export interface AOIBoundaryResponse {
+    /** 返回状态 */
+    status: string;
+    /** 返回的状态信息 */
+    info: string;
+    /** 状态码 */
+    infocode: string;
+    /** AOI 边界结果 */
+    aois?: AOIBoundaryInfo | AOIBoundaryInfo[];
+}

package/build/utils/client.d.ts

@@ -72,7 +72,7 @@ export interface ClientConfig {
  */
 export interface RequestOptions {
     /** 请求参数 */
-    params?: Record<string, any>;
+    params?: object;
     /** AbortSignal 用于取消请求 */
     signal?: AbortSignal;
     /** 是否使用缓存（仅当全局启用缓存时有效），默认：true */

package/build/utils/normalizers.d.ts

@@ -0,0 +1,23 @@
+import type { BicyclingRouteResponse, DrivingRouteResponse, ElectricBikeRouteResponse, TransitRouteResponse, WalkingRouteResponse } from '../types/route.types';
+import type { AOIBoundaryResponse } from '../types/poi.types';
+export interface RoutePoint {
+    latitude: number;
+    longitude: number;
+}
+export interface NormalizedDrivingRoute {
+    distance: number;
+    duration: number;
+    taxiCost?: number;
+    points: RoutePoint[];
+}
+export interface ExtractedAOIBoundary {
+    id?: string;
+    name?: string;
+    rings: RoutePoint[][];
+}
+type SupportedRouteResponse = DrivingRouteResponse | WalkingRouteResponse | BicyclingRouteResponse | ElectricBikeRouteResponse;
+export declare function extractRoutePoints(routeResult: SupportedRouteResponse): RoutePoint[];
+export declare function normalizeDrivingRoute(routeResult: DrivingRouteResponse): NormalizedDrivingRoute;
+export declare function extractAOIBoundary(aoiResult: AOIBoundaryResponse): ExtractedAOIBoundary;
+export declare function extractTransitRoutePoints(transitResult: TransitRouteResponse): RoutePoint[][];
+export {};

package/build/utils/normalizers.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRoutePoints = extractRoutePoints;
+exports.normalizeDrivingRoute = normalizeDrivingRoute;
+exports.extractAOIBoundary = extractAOIBoundary;
+exports.extractTransitRoutePoints = extractTransitRoutePoints;
+function parsePolyline(polyline) {
+    if (!polyline?.trim()) {
+        return [];
+    }
+    return polyline
+        .split(';')
+        .map((segment) => segment.trim())
+        .filter(Boolean)
+        .map((segment) => {
+        const [longitude, latitude] = segment.split(',').map((value) => Number(value.trim()));
+        if (!Number.isFinite(longitude) || !Number.isFinite(latitude)) {
+            return null;
+        }
+        return {
+            latitude,
+            longitude,
+        };
+    })
+        .filter((point) => point !== null);
+}
+function dedupeAdjacentPoints(points) {
+    return points.filter((point, index) => {
+        if (index === 0) {
+            return true;
+        }
+        const previous = points[index - 1];
+        return (previous.latitude !== point.latitude ||
+            previous.longitude !== point.longitude);
+    });
+}
+function extractStepPoints(steps = []) {
+    return dedupeAdjacentPoints(steps.flatMap((step) => parsePolyline(step.polyline)));
+}
+function extractRoutePoints(routeResult) {
+    // 将 Web API 的 steps.polyline 摊平成地图组件可直接消费的点集。
+    const firstPath = routeResult.route?.paths?.[0];
+    if (!firstPath) {
+        return [];
+    }
+    return extractStepPoints(firstPath.steps);
+}
+function normalizeDrivingRoute(routeResult) {
+    // 为常见“路径预览 / 地图绘制”场景提供一个更扁平的数据结构，
+    // 业务层不必再自己处理字符串数字和嵌套字段。
+    const firstPath = routeResult.route?.paths?.[0];
+    return {
+        distance: Number(firstPath?.distance ?? 0),
+        duration: Number(firstPath?.cost?.duration ?? firstPath?.duration ?? 0),
+        taxiCost: routeResult.route?.taxi_cost ? Number(routeResult.route.taxi_cost) : undefined,
+        points: extractRoutePoints(routeResult),
+    };
+}
+function extractAOIBoundary(aoiResult) {
+    // AOI 边界返回值可能是单对象，也可能是数组；
+    // 这里统一归一成 { id, name, rings } 结构。
+    const aoi = Array.isArray(aoiResult.aois) ? aoiResult.aois[0] : aoiResult.aois;
+    const polyline = aoi?.polyline ?? '';
+    const rings = polyline
+        .split('|')
+        .map((ring) => parsePolyline(ring))
+        .filter((ring) => ring.length > 0);
+    return {
+        id: aoi?.id,
+        name: aoi?.name,
+        rings,
+    };
+}
+function extractTransitRoutePoints(transitResult) {
+    // 公交换乘路线会混合步行段、公交段、铁路段，
+    // 这里统一抽成“每条换乘方案 -> 一条完整点集”。
+    return (transitResult.route?.transits ?? []).map((transit) => dedupeAdjacentPoints(transit.segments.flatMap((segment) => [
+        ...(segment.walking ? extractStepPoints(segment.walking.steps) : []),
+        ...(segment.bus?.buslines?.flatMap((line) => parsePolyline(line.polyline)) ?? []),
+        ...(segment.railway?.buslines?.flatMap((line) => parsePolyline(line.polyline)) ?? []),
+    ])));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "expo-gaode-map-web-api",
-  "version": "2.0.6",
-  "description": "高德地图 Web API 服务 - 搜索、路径规划、地理编码（纯 JavaScript 实现），配合 expo-gaode-map或者 expo-gaode-map-navigation 使用",
+  "version": "2.0.8",
+  "description": "AMap (Gaode Map) Web API toolkit for Expo/React Native: search, geocoding, and route planning in pure JavaScript.",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [
@@ -19,11 +19,18 @@
   "keywords": [
     "react-native",
     "expo",
+    "expo-gaode-map-web-api",
+    "expo-amap",
+    "react-native-amap",
+    "react-native-gaode-map",
     "amap",
     "gaode",
+    "gaode-map",
     "web-api",
     "search",
     "geocode",
+    "geocoding",
+    "route-planning",
     "route",
     "高德地图"
   ],