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

package/README.md

@@ -1,68 +1,62 @@
 # expo-gaode-map-navigation
 
-高德地图“导航一体化”模块。内置地图渲染能力与导航能力，提供从地图展示到路径规划、实时导航的完整解决方案。
+高德地图“导航一体化”模块。内置地图渲染能力与导航能力，提供从地图展示到路径规划与实时导航的完整解决方案。
 
-## 特性
+## 模块定位与使用约束
 
-- 🗺️ **地图渲染**：内置完整地图能力，支持 Marker、Polyline、Polygon、Circle、Cluster、HeatMap 等覆盖物。
-- 🚗 **多模式路径规划**：支持驾车、步行、骑行、电动车、货车、摩托车等多种出行方式。
-- 🧭 **实时导航 UI**：提供 `NaviView` 组件，内置完整的导航界面、语音播报、转向指引、路况显示等。
-- 🛣️ **独立路径规划**：支持“先算路、再导航”的高级模式，可实现多路线对比与选择。
-- ⚙️ **策略丰富**：支持速度优先、避让拥堵、少收费、不走高速等多种算路策略。
-- � **开箱即用**：封装了 Android/iOS 原生导航 SDK，统一 JS 接口。
+- 独立使用：本模块已封装地图相关能力（MapView/覆盖物等）与导航能力，不需要、也不应同时安装核心地图包。
+- 禁止共存：请勿与 `expo-gaode-map` 同时安装或链接。两者均包含地图 SDK，Android 上会产生 `3dmap` vs `navi-3dmap` 的二进制冲突。
+- 简化依赖：安装本模块即可获得地图 + 导航全量能力，无需额外地图依赖。
+
+## 功能特性
+
+- 🗺️ 地图渲染：内置地图视图与常用覆盖物（标注、折线、多边形、热力图、聚合等）
+- 🧭 路径与导航：驾车、步行、骑行等多种出行策略与实时引导
+- ⚙️ 策略丰富：最快、最短、避拥堵、少收费、少红绿灯等
+- 🚗 复杂路线：支持多途经点、限行考虑、分段规划
+- 🌐 Web API 协作：可与 `expo-gaode-map-web-api` 配合，统一通过基础初始化下发 Web Key 后使用
 
 ## 安装
 
-本模块已包含地图与导航的所有能力，**不需要**、也不应同时安装 `expo-gaode-map`。
+仅安装本模块（不要安装 `expo-gaode-map`）：
 
 ```bash
 # bun
 bun add expo-gaode-map-navigation
 
-# yarn
+# or yarn
 yarn add expo-gaode-map-navigation
 
-# npm
-npm install expo-gaode-map-navigation
 ```
 
-**⚠️ 重要提示：**
-如果项目中已安装 `expo-gaode-map`，请务必先卸载，否则会导致 Android 端二进制冲突（`3dmap` vs `navi-3dmap`）。`expo-gaode-map` 和 `expo-gaode-map-navigation` 由于 SDK 冲突不能同时安装，二选一使用。
+如果项目中已安装过核心地图包，请先移除避免冲突：
 
+```bash
+npm uninstall expo-gaode-map
+# or: yarn remove expo-gaode-map
+# or: bun remove expo-gaode-map
+```
 
-### Config Plugin 配置（推荐）
+## 初始化
 
-在 `app.json` 中配置，自动设置原生 API Key 和权限：
+在应用启动阶段初始化 SDK Key（Android/iOS 原生 Key 与可选的 Web API Key）：
 
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "expo-gaode-map-navigation", 
-        {
-          "androidKey": "your-android-key",
-          "iosKey": "your-ios-key"
-        }
-      ]
-    ]
-  }
-}
-```
-配置后重新构建：
+```ts
+import { ExpoGaodeMapModule } from 'expo-gaode-map-navigation';
 
-```bash
-npx expo prebuild --clean
-npx expo run:android
-npx expo run:ios
+ExpoGaodeMapModule.initSDK({
+  androidKey: 'your-android-key',
+  iosKey: 'your-ios-key',
+  webKey: 'your-web-api-key', // 可选；若使用 Web API 包，建议一并下发
+});
 ```
 
+说明：
+- 如后续使用 `expo-gaode-map-web-api`，建议同时传入 `webKey`，该包会从本模块运行时读取 `webKey`，实现“无参构造”的简化用法（new GaodeWebAPI()）。
 
-## 快速开始
-
-### 1. 显示地图
+## 地图与导航基础用法
 
-使用内置的 `MapView` 组件显示地图：
+地图视图（内置地图能力）：
 
 ```tsx
 import React from 'react';
@@ -76,12 +70,13 @@ export default function BasicMapScreen() {
         style={{ flex: 1 }}
         initialCameraPosition={{
           target: { latitude: 39.909186, longitude: 116.397411 },
-          zoom: 15,
+          zoom: 12,
         }}
       >
         <Marker
           position={{ latitude: 39.909186, longitude: 116.397411 }}
           title="天安门"
+          snippet="北京·东城区"
         />
       </MapView>
     </View>
@@ -89,204 +84,69 @@ export default function BasicMapScreen() {
 }
 ```
 
-### 2. 嵌入导航视图
+路径规划与导航（示例）：
 
-使用 `NaviView` 组件直接嵌入导航界面：
-
-```tsx
-import React, { useEffect, useRef } from 'react';
-import { View } from 'react-native';
-import { NaviView, type NaviViewRef } from 'expo-gaode-map-navigation';
-
-export default function NavigationScreen() {
-  const naviRef = useRef<NaviViewRef>(null);
-
-  useEffect(() => {
-    // 延迟 1 秒后开始导航
-    const timer = setTimeout(() => {
-      if (naviRef.current) {
-        naviRef.current.startNavigation(
-          { latitude: 39.909186, longitude: 116.397411 }, // 起点
-          { latitude: 39.99, longitude: 116.47 },         // 终点
-          0 // 0: GPS导航, 1: 模拟导航
-        );
-      }
-    }, 1000);
-    return () => clearTimeout(timer);
-  }, []);
-
-  return (
-    <View style={{ flex: 1 }}>
-      <NaviView
-        ref={naviRef}
-        style={{ flex: 1 }}
-        showCamera={true} // 显示摄像头
-        enableVoice={true} // 开启语音
-      />
-    </View>
-  );
-}
-```
-
-## 详细用法
-
-### 路径规划 (API)
-
-使用 `calculateRoute` 方法进行路径计算，不涉及 UI 显示，适合用于获取距离、时间或绘制路线。
-
-#### 驾车路径规划
-
-```typescript
-import { calculateRoute, RouteType, DriveStrategy } from 'expo-gaode-map-navigation';
+```ts
+import { calculateRoute, DriveStrategy } from 'expo-gaode-map-navigation';
 
 const result = await calculateRoute({
-  type: RouteType.DRIVE,
+  type: 'drive',
   from: { latitude: 39.9, longitude: 116.4 },
   to: { latitude: 39.91, longitude: 116.41 },
-  strategy: DriveStrategy.FASTEST, // 速度优先
-  avoidRoad: '京通快速路', // 避让道路名称
+  strategy: DriveStrategy.FASTEST,
 });
 
-console.log(`总距离: ${result.routes[0].distance}米`);
-console.log(`预计耗时: ${result.routes[0].duration}秒`);
+// 结果包含距离/时长/分步指引等
 ```
 
-#### 步行/骑行路径规划
+说明：
+- 地图组件与导航能力均来自 `expo-gaode-map-navigation`，无需、也不应从 `expo-gaode-map` 引入任何 API。
 
-```typescript
-import { calculateRoute, RouteType, RideStrategy } from 'expo-gaode-map-navigation';
+## 路径规划（原生与 Web API 双方案）
 
-// 骑行
-const rideResult = await calculateRoute({
-  type: RouteType.RIDE,
-  from: { latitude: 39.9, longitude: 116.4 },
-  to: { latitude: 39.91, longitude: 116.41 },
-  strategy: RideStrategy.FASTEST,
-});
+本模块同时支持“原生导航引擎路径规划”和“Web API 路径规划”，可按业务场景自由选择或组合使用：
 
-// 步行
-const walkResult = await calculateRoute({
-  type: RouteType.WALK,
-  from: { latitude: 39.9, longitude: 116.4 },
-  to: { latitude: 39.91, longitude: 116.41 },
-  multiple: true, // 返回多条路线
-});
-```
-
-#### 货车路径规划
+- 原生方案（推荐用于移动端实时导航）：端侧原生 SDK 能力，更适合实时引导、语音播报、复杂交通路况处理、弱网/离线等。
+- Web API 方案（推荐用于快速查询/对比/多端一致）：通过 `expo-gaode-map-web-api` 发起 HTTP 请求，便于统一计算逻辑、方案对比或与服务端配合。
 
-```typescript
-import { calculateRoute, RouteType, TruckSize } from 'expo-gaode-map-navigation';
+原生方案示例：
+```ts
+import { calculateRoute, DriveStrategy } from 'expo-gaode-map-navigation';
 
-const truckResult = await calculateRoute({
-  type: RouteType.TRUCK,
+const result = await calculateRoute({
+  type: 'drive',
   from: { latitude: 39.9, longitude: 116.4 },
   to: { latitude: 39.91, longitude: 116.41 },
-  size: TruckSize.MEDIUM, // 中型货车
-  height: 3.5, // 高度 3.5m
-  load: 10,    // 载重 10吨
+  strategy: DriveStrategy.FASTEST,
 });
-```
-
-### 独立路径规划 (Advanced)
-
-“独立路径规划”允许你先计算路线，并在地图上展示多条方案，用户选择其中一条后再开始导航。这通常比直接开始导航体验更好。
 
-```typescript
-import {
-  independentDriveRoute,
-  selectIndependentRoute,
-  startNaviWithIndependentPath,
-  DriveStrategy
-} from 'expo-gaode-map-navigation';
+// result 包含距离/时长/分步指引等原生返回
+```
 
-// 1. 发起算路（不会自动开始导航）
-const result = await independentDriveRoute({
-  from: { latitude: 39.9, longitude: 116.4 },
-  to: { latitude: 39.91, longitude: 116.41 },
-  strategy: DriveStrategy.AVOID_CONGESTION,
-});
+Web API 方案示例（需在初始化时提供 webKey）：
+```ts
+import { GaodeWebAPI } from 'expo-gaode-map-web-api';
 
-// 2. 选择某一条路线（例如 index=1 的路线）
-// 这通常配合地图上的点击事件，高亮显示某条路线
-await selectIndependentRoute({
-  routeId: result.routes[1].id
-});
+// 无参构造：从 expo-gaode-map-navigation 初始化中动态解析 webKey
+const api = new GaodeWebAPI();
 
-// 3. 使用当前选中的路线开始导航
-await startNaviWithIndependentPath({
-  emulator: true, // 开启模拟导航
+// 驾车路径规划（Web API）
+const res = await api.route.driving('116.400000,39.900000', '116.410000,39.910000', {
+  show_fields: 'cost,navi',
 });
-```
-
-### 地图组件 (Map)
 
-模块导出了完整的地图组件，与 `expo-gaode-map` API 保持一致。
-
-```tsx
-import { MapView, Circle, Polygon } from 'expo-gaode-map-navigation';
-
-<MapView style={{ flex: 1 }}>
-  {/* 圆形覆盖物 */}
-  <Circle
-    center={{ latitude: 39.9, longitude: 116.4 }}
-    radius={1000}
-    fillColor="rgba(0,0,255, 0.3)"
-    strokeColor="rgba(0,0,255, 0.5)"
-  />
-  
-  {/* 多边形 */}
-  <Polygon
-    points={[
-      { latitude: 39.9, longitude: 116.4 },
-      { latitude: 39.91, longitude: 116.41 },
-      { latitude: 39.92, longitude: 116.42 },
-    ]}
-    strokeWidth={2}
-  />
-</MapView>
+// res.route.paths[0] 中包含距离/时长/导航步骤等
 ```
 
-## API 参考
-
-### DriveStrategy (驾车策略)
-
-| 值 | 说明 |
-|---|---|
-| `FASTEST` (0) | 速度优先（时间最短） |
-| `FEE_FIRST` (1) | 费用优先（少收费） |
-| `SHORTEST` (2) | 距离优先 |
-| `NO_HIGHWAY` (5) | 不走高速 |
-| `AVOID_CONGESTION` (4) | 躲避拥堵 |
-| ... | 更多策略请参考类型定义 |
-
-### NaviView Props
-
-| 属性 | 类型 | 说明 |
-|---|---|---|
-| `naviType` | number | 导航类型（0: GPS, 1: 模拟） |
-| `showCrossImage` | boolean | 是否显示路口放大图 |
-| `showCamera` | boolean | 是否显示摄像头 |
-| `showTrafficButton` | boolean | 是否显示路况按钮 |
-| `enableVoice` | boolean | 是否开启语音播报 |
-| `onArrive` | function | 到达目的地回调 |
-| `onNaviInfoUpdate` | function | 导航信息更新（剩余距离、时间等） |
-
-## 注意事项
-
-1.  **二进制冲突**：严禁与 `expo-gaode-map` 共存。本模块已包含 `3dmap` SDK。
-2.  **Web API**：如果需要更灵活的 HTTP 算路（如公交跨城规划、Web端展示），推荐配合 `expo-gaode-map-web-api` 使用。
-3.  **权限**：使用导航功能前，请确保应用已获取定位权限（`ACCESS_FINE_LOCATION`）。
-
+选择建议：
+- 实时导航/引导优先原生方案；
+- 方案对比、批量测算、多端统一优先 Web API；也可结合两者，在端上落地选择逻辑。
 
-## 📚 文档与资源
+## Android 注意事项
 
-- [在线文档](https://tomwq.github.io/expo-gaode-map/api/navigation.html)
-- [GitHub 仓库](https://github.com/TomWq/expo-gaode-map/packages/navigation)
-- [示例项目(导航)](https://github.com/TomWq/expo-gaode-map-navigation-example)
-- [高德地图开放平台](https://lbs.amap.com/)
-- [Expo Modules API](https://docs.expo.dev/modules/overview/)
+- 本模块内部使用 `navi-3dmap` 体系，已包含地图能力；请勿同时引入核心 `3dmap` 体系以免二进制冲突。
+- 若历史项目从核心包迁移至本模块，务必移除 `expo-gaode-map` 依赖与其 native 配置（Gradle/CocoaPods 链接等）。
 
-## License
+## 许可
 
-MIT License
+MIT

package/build/ExpoGaodeMapNaviView.js

@@ -75,11 +75,12 @@ exports.NaviView = React.forwardRef((props, ref) => {
     // 创建 API 引用
     const apiRef = React.useMemo(() => ({
         startNavigation: async (start, end, type) => {
+            var _a, _b;
             if (!nativeRef.current)
                 throw new Error('NaviView not initialized');
             // 将对象解构为单独的参数传递给原生层
-            const startLat = start?.latitude ?? 0;
-            const startLng = start?.longitude ?? 0;
+            const startLat = (_a = start === null || start === void 0 ? void 0 : start.latitude) !== null && _a !== void 0 ? _a : 0;
+            const startLng = (_b = start === null || start === void 0 ? void 0 : start.longitude) !== null && _b !== void 0 ? _b : 0;
             const endLat = end.latitude;
             const endLng = end.longitude;
             return nativeRef.current.startNavigation(startLat, startLng, endLat, endLng);

package/build/map/ExpoGaodeMapModule.js

@@ -28,8 +28,9 @@ const ExpoGaodeMapModuleWithHelpers = {
      * 初始化 SDK，并缓存配置（包含 webKey）
      */
     initSDK(config) {
-        _sdkConfig = config ?? null;
-        nativeModule?.initSDK?.(config);
+        var _a;
+        _sdkConfig = config !== null && config !== void 0 ? config : null;
+        (_a = nativeModule === null || nativeModule === void 0 ? void 0 : nativeModule.initSDK) === null || _a === void 0 ? void 0 : _a.call(nativeModule, config);
     },
     /**
      * 添加定位监听器（便捷方法）
@@ -39,8 +40,9 @@ const ExpoGaodeMapModuleWithHelpers = {
      * @throws 如果底层模块不可用，返回一个空操作的订阅对象
      */
     addLocationListener(listener) {
+        var _a;
         // 使用可选链和空值合并，确保即使模块不可用也不会崩溃
-        return nativeModule?.addListener?.('onLocationUpdate', listener) || {
+        return ((_a = nativeModule === null || nativeModule === void 0 ? void 0 : nativeModule.addListener) === null || _a === void 0 ? void 0 : _a.call(nativeModule, 'onLocationUpdate', listener)) || {
             remove: () => { },
         };
     },
@@ -55,6 +57,6 @@ function getSDKConfig() {
 * 获取用于 Web API 的 webKey（若未初始化或未提供则返回 undefined）
 */
 function getWebKey() {
-    return _sdkConfig?.webKey;
+    return _sdkConfig === null || _sdkConfig === void 0 ? void 0 : _sdkConfig.webKey;
 }
 exports.default = ExpoGaodeMapModuleWithHelpers;

package/build/map/utils/EventManager.js

@@ -17,7 +17,7 @@ class EventManager {
     }
     trigger(id, eventType, data) {
         const callbacks = this.callbacks.get(id);
-        const callback = callbacks?.[eventType];
+        const callback = callbacks === null || callbacks === void 0 ? void 0 : callbacks[eventType];
         if (typeof callback === 'function') {
             callback(data);
         }

package/ios/map/modules/LocationManager.swift

@@ -1,7 +1,6 @@
 import Foundation
 import AMapLocationKit
 import CoreLocation
-import ExpoModulesCore
 
 /**
  * 定位管理器
@@ -124,13 +123,6 @@ class LocationManager: NSObject, AMapLocationManagerDelegate {
      * @param allows 是否允许后台定位
      */
     func setAllowsBackgroundLocationUpdates(_ allows: Bool) {
-        if allows {
-            let backgroundModes = Bundle.main.object(forInfoDictionaryKey: "UIBackgroundModes") as? [String]
-            if backgroundModes?.contains("location") != true {
-                log.warn("⚠️ [ExpoGaodeMap] iOS 后台定位未正确配置，setAllowsBackgroundLocationUpdates(true) 可能不会生效，请检查 Info.plist 是否包含 UIBackgroundModes: location，或者在 app.json 中配置 enableBackgroundLocation: true，然后重新执行 npx expo prebuild")
-                return
-            }
-        }
         locationManager?.allowsBackgroundLocationUpdates = allows
     }
     
@@ -270,4 +262,4 @@ class LocationManager: NSObject, AMapLocationManagerDelegate {
     func amapLocationManager(_ manager: AMapLocationManager!, didFailWithError error: Error!) {
         // 定位失败 - 静默处理
     }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-gaode-map-navigation",
-  "version": "1.1.5-next.1",
+  "version": "1.1.5",
   "description": "高德地图导航功能模块 - 路径规划、导航引导，独立版本包含完整地图功能",
   "author": "<TomWq> (https://github.com/TomWq)",
   "repository": "https://github.com/TomWq/expo-gaode-map",
@@ -13,7 +13,7 @@
     "lint": "expo-module lint",
     "test": "expo-module test",
     "prepare": "expo-module prepare && bun run build:plugin",
-    "prepublishOnly": "echo 'Skipping proofread check' && exit 0",
+    "prepublishOnly": "expo-module prepublishOnly",
     "expo-module": "expo-module"
   },
   "devDependencies": {