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

package/README.md

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

package/android/src/main/java/expo/modules/gaodemap/navigation/ExpoGaodeMapNaviView.kt

@@ -58,6 +58,7 @@ class ExpoGaodeMapNaviView(context: Context, appContext: AppContext) : ExpoView(
     internal var isAfterRouteAutoGray: Boolean = false
     internal var isVectorLineShow: Boolean = true
     internal var isNaviTravelView : Boolean = false
+    internal var isCompassEnabled: Boolean = true
     private val naviView: AMapNaviView = AMapNaviView(context)
     private var aMapNavi: AMapNavi? = null
     private var startCoordinate: NaviLatLng? = null
@@ -329,7 +330,7 @@ class ExpoGaodeMapNaviView(context: Context, appContext: AppContext) : ExpoView(
             // 设置为 true 将显示导航信息面板（包括距离、时间等）
             options.isLayoutVisible = showUIElements
             options.isSettingMenuEnabled = true // 显示设置菜单按钮
-            options.isCompassEnabled = true // 显示指南针
+            options.isCompassEnabled = isCompassEnabled // 显示指南针
             options.isTrafficBarEnabled = androidTrafficBarEnabled // 显示路况条
             options.isRouteListButtonShow = isRouteListButtonShow // 显示路线全览按钮
 
@@ -843,7 +844,15 @@ class ExpoGaodeMapNaviView(context: Context, appContext: AppContext) : ExpoView(
         options.isRealCrossDisplayShow = enabled
         naviView.viewOptions = options
     }
-    
+
+    fun applyShowCompassEnabled(enabled: Boolean){
+        isCompassEnabled = enabled
+        val options = naviView.viewOptions
+        options.isCompassEnabled = enabled
+        naviView.viewOptions = options
+    }
+
+
     fun applyNaviMode(mode: Int) {
         // 0: 车头朝上 1: 正北朝上
         naviView.naviMode = mode
@@ -884,7 +893,8 @@ class ExpoGaodeMapNaviView(context: Context, appContext: AppContext) : ExpoView(
             Log.e("ExpoGaodeMapNaviView", "Failed to set car overlay visibility", e)
         }
     }
-    
+
+
     /**
      * 设置是否显示交通信号灯
      * @param visible true-显示 false-隐藏

package/android/src/main/java/expo/modules/gaodemap/navigation/ExpoGaodeMapNaviViewModule.kt

@@ -75,6 +75,10 @@ class ExpoGaodeMapNaviViewModule : Module() {
       Prop<Boolean>("showTrafficLights") { view, visible ->
         view.applyTrafficLightsVisible(visible)
       }
+
+      Prop<Boolean>("showCompassEnabled") {view, enabled ->
+          view.applyShowCompassEnabled(enabled)
+      }
       
       Prop<Map<String, Boolean>?>("routeMarkerVisible") { view, config ->
         config?.let {

package/build/ExpoGaodeMapNaviView.js

@@ -75,12 +75,11 @@ 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 = (_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 startLat = start?.latitude ?? 0;
+            const startLng = start?.longitude ?? 0;
             const endLat = end.latitude;
             const endLng = end.longitude;
             return nativeRef.current.startNavigation(startLat, startLng, endLat, endLng);

package/build/map/ExpoGaodeMapModule.js

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

package/build/types/naviview.types.d.ts

@@ -203,6 +203,11 @@ export interface NaviViewProps extends ViewProps {
      * @default false
      */
     isNaviTravelView?: boolean;
+    /**
+     * 是否显示指南针
+     * @default true
+     */
+    showCompassEnabled?: boolean;
     /**
      * 是否显示红绿灯图标
      * @default true

package/ios/map/modules/LocationManager.swift

@@ -1,6 +1,7 @@
 import Foundation
 import AMapLocationKit
 import CoreLocation
+import ExpoModulesCore
 
 /**
  * 定位管理器
@@ -123,6 +124,13 @@ 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
     }
     
@@ -262,4 +270,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.0",
+  "version": "1.1.5-next.1",
   "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": "expo-module prepublishOnly",
+    "prepublishOnly": "echo 'Skipping proofread check' && exit 0",
     "expo-module": "expo-module"
   },
   "devDependencies": {