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

package/README.md

@@ -1,49 +1,120 @@
 # expo-gaode-map-navigation
 
-高德地图导航功能模块，为 `expo-gaode-map` 提供路径规划和导航引导功能。
+高德地图“导航一体化”模块。内置地图渲染能力与导航能力，提供从地图展示到路径规划与实时导航的完整解决方案。
 
-## 功能特性
-
-- 🗺️ **路径规划**：支持驾车、步行、骑行、公交等多种出行方式
-- 🧭 **导航引导**：提供实时导航引导功能
-- 📍 **多种策略**：支持最快路线、最短路线、避免拥堵等策略
-- 🚗 **途经点支持**：支持设置途经点的路径规划
+## 模块定位与使用约束
 
-## ⚠️ 重要提示
+- 独立使用：本模块已封装地图相关能力（MapView/覆盖物等）与导航能力，不需要、也不应同时安装核心地图包。
+- 禁止共存：请勿与 `expo-gaode-map` 同时安装或链接。两者均包含地图 SDK，Android 上会产生 `3dmap` vs `navi-3dmap` 的二进制冲突。
+- 简化依赖：安装本模块即可获得地图 + 导航全量能力，无需额外地图依赖。
 
-**Android SDK 依赖冲突**：导航模块使用 `navi-3dmap` SDK，与核心包的 `3dmap` SDK 会产生冲突。
+## 功能特性
 
-请务必阅读：[Android SDK 冲突解决方案](./ANDROID_SDK_CONFLICT.md)
+- 🗺️ 地图渲染：内置地图视图与常用覆盖物（标注、折线、多边形、热力图、聚合等）
+- 🧭 路径与导航：驾车、步行、骑行等多种出行策略与实时引导
+- ⚙️ 策略丰富：最快、最短、避拥堵、少收费、少红绿灯等
+- 🚗 复杂路线：支持多途经点、限行考虑、分段规划
+- 🌐 Web API 协作：可与 `expo-gaode-map-web-api` 配合，统一通过基础初始化下发 Web Key 后使用
 
 ## 安装
 
-首先确保已安装主包：
+仅安装本模块（不要安装 `expo-gaode-map`）：
 
 ```bash
-npm install expo-gaode-map
+# npm
+npm install expo-gaode-map-navigation
+
+# or yarn
+yarn add expo-gaode-map-navigation
+
+# or pnpm
+pnpm add expo-gaode-map-navigation
 ```
 
-然后安装导航模块：
+如果项目中已安装过核心地图包，请先移除避免冲突：
 
 ```bash
-npm install expo-gaode-map-navigation
+npm uninstall expo-gaode-map
+# or: yarn remove expo-gaode-map
+# or: pnpm remove expo-gaode-map
 ```
 
-或使用 yarn/pnpm：
+## 初始化
 
-```bash
-yarn add expo-gaode-map-navigation
-pnpm add expo-gaode-map-navigation
+在应用启动阶段初始化 SDK Key（Android/iOS 原生 Key 与可选的 Web API Key）：
+
+```ts
+import { ExpoGaodeMapModule } from 'expo-gaode-map-navigation';
+
+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()）。
+
+## 地图与导航基础用法
+
+地图视图（内置地图能力）：
+
+```tsx
+import React from 'react';
+import { View } from 'react-native';
+import { MapView, Marker } from 'expo-gaode-map-navigation';
+
+export default function BasicMapScreen() {
+  return (
+    <View style={{ flex: 1 }}>
+      <MapView
+        style={{ flex: 1 }}
+        initialCameraPosition={{
+          target: { latitude: 39.909186, longitude: 116.397411 },
+          zoom: 12,
+        }}
+      >
+        <Marker
+          position={{ latitude: 39.909186, longitude: 116.397411 }}
+          title="天安门"
+          snippet="北京·东城区"
+        />
+      </MapView>
+    </View>
+  );
+}
+```
+
+路径规划与导航（示例）：
+
+```ts
+import { calculateRoute, DriveStrategy } from 'expo-gaode-map-navigation';
+
+const result = await calculateRoute({
+  type: 'drive',
+  from: { latitude: 39.9, longitude: 116.4 },
+  to: { latitude: 39.91, longitude: 116.41 },
+  strategy: DriveStrategy.FASTEST,
+});
+
+// 结果包含距离/时长/分步指引等
 ```
 
-**Android 配置**：安装后需要修改核心包的 SDK 依赖，详见 [ANDROID_SDK_CONFLICT.md](./ANDROID_SDK_CONFLICT.md)
+说明：
+- 地图组件与导航能力均来自 `expo-gaode-map-navigation`，无需、也不应从 `expo-gaode-map` 引入任何 API。
 
-## 基础用法
+## 路径规划（原生与 Web API 双方案）
 
-```typescript
+本模块同时支持“原生导航引擎路径规划”和“Web API 路径规划”，可按业务场景自由选择或组合使用：
+
+- 原生方案（推荐用于移动端实时导航）：端侧原生 SDK 能力，更适合实时引导、语音播报、复杂交通路况处理、弱网/离线等。
+- Web API 方案（推荐用于快速查询/对比/多端一致）：通过 `expo-gaode-map-web-api` 发起 HTTP 请求，便于统一计算逻辑、方案对比或与服务端配合。
+
+原生方案示例：
+```ts
 import { calculateRoute, DriveStrategy } from 'expo-gaode-map-navigation';
 
-// 驾车路径规划
 const result = await calculateRoute({
   type: 'drive',
   from: { latitude: 39.9, longitude: 116.4 },
@@ -51,15 +122,33 @@ const result = await calculateRoute({
   strategy: DriveStrategy.FASTEST,
 });
 
-console.log('距离:', result.distance, '米');
-console.log('时间:', result.duration, '秒');
-console.log('路径点:', result.steps.length, '步');
+// result 包含距离/时长/分步指引等原生返回
 ```
 
-## API 文档
+Web API 方案示例（需在初始化时提供 webKey）：
+```ts
+import { GaodeWebAPI } from 'expo-gaode-map-web-api';
+
+// 无参构造：从 expo-gaode-map-navigation 初始化中动态解析 webKey
+const api = new GaodeWebAPI();
+
+// 驾车路径规划（Web API）
+const res = await api.route.driving('116.400000,39.900000', '116.410000,39.910000', {
+  show_fields: 'cost,navi',
+});
+
+// res.route.paths[0] 中包含距离/时长/导航步骤等
+```
+
+选择建议：
+- 实时导航/引导优先原生方案；
+- 方案对比、批量测算、多端统一优先 Web API；也可结合两者，在端上落地选择逻辑。
+
+## Android 注意事项
 
-详细的 API 文档请参考主项目文档。
+- 本模块内部使用 `navi-3dmap` 体系，已包含地图能力；请勿同时引入核心 `3dmap` 体系以免二进制冲突。
+- 若历史项目从核心包迁移至本模块，务必移除 `expo-gaode-map` 依赖与其 native 配置（Gradle/CocoaPods 链接等）。
 
-## 许可证
+## 许可
 
 MIT

package/android/src/main/java/expo/modules/gaodemap/map/ExpoGaodeMapModule.kt

@@ -32,6 +32,13 @@ class ExpoGaodeMapModule : Module() {
   override fun definition() = ModuleDefinition {
     Name("NaviMap")
 
+    // 在模块加载时尝试从本地缓存恢复隐私同意状态，避免每次启动都必须 JS 调用
+    try {
+      SDKInitializer.restorePrivacyState(appContext.reactContext!!)
+    } catch (e: Exception) {
+      android.util.Log.w("ExpoGaodeMap", "恢复隐私状态时出现问题: ${e.message}")
+    }
+ 
     // ==================== 隐私合规管理 ====================
     
     /**

package/android/src/main/java/expo/modules/gaodemap/map/modules/SDKInitializer.kt

@@ -1,12 +1,13 @@
 package expo.modules.gaodemap.map.modules
 
 import android.content.Context
+import android.content.SharedPreferences
 import com.amap.api.location.AMapLocationClient
 import com.amap.api.maps.MapsInitializer
 
 /**
  * SDK 初始化管理器
- * 
+ *
  * 负责:
  * - 初始化高德地图 SDK
  * - 初始化高德定位 SDK
@@ -15,8 +16,14 @@ import com.amap.api.maps.MapsInitializer
  */
 object SDKInitializer {
     
-    /** 隐私协议是否已同意 */
+    /** 隐私协议是否已同意（进程内缓存） */
     private var privacyAgreed = false
+
+    private const val PREFS_NAME = "expo_gaode_map_prefs"
+    private const val KEY_PRIVACY_AGREED = "privacy_agreed"
+
+    private fun prefs(context: Context): SharedPreferences =
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
     
     /**
      * 更新隐私合规状态
@@ -42,8 +49,36 @@ object SDKInitializer {
             AMapLocationClient.updatePrivacyAgree(context, false)
             android.util.Log.w("ExpoGaodeMap", "⚠️ 用户未同意隐私协议，SDK 功能将受限")
         }
+
+        // 持久化状态，供下次启动自动恢复
+        try {
+            prefs(context).edit().putBoolean(KEY_PRIVACY_AGREED, hasAgreed).apply()
+        } catch (e: Exception) {
+            android.util.Log.w("ExpoGaodeMap", "持久化隐私状态失败: ${e.message}")
+        }
     }
     
+    /**
+     * 从本地存储恢复隐私合规状态（在应用启动或模块加载时调用）
+     * 若无记录则保持默认 false，不抛出异常。
+     */
+    fun restorePrivacyState(context: Context) {
+        try {
+            val saved = prefs(context).getBoolean(KEY_PRIVACY_AGREED, false)
+            privacyAgreed = saved
+
+            // 同步到 SDK
+            MapsInitializer.updatePrivacyShow(context, true, true)
+            AMapLocationClient.updatePrivacyShow(context, true, true)
+            MapsInitializer.updatePrivacyAgree(context, saved)
+            AMapLocationClient.updatePrivacyAgree(context, saved)
+
+            android.util.Log.d("ExpoGaodeMap", "🔁 已从缓存恢复隐私状态: $saved")
+        } catch (e: Exception) {
+            android.util.Log.w("ExpoGaodeMap", "恢复隐私状态失败: ${e.message}")
+        }
+    }
+
     /**
      * 检查隐私协议是否已同意
      *
@@ -79,7 +114,7 @@ object SDKInitializer {
 
     /**
      * 获取 SDK 版本号
-     * 
+     *
      * @return SDK 版本字符串
      */
     fun getVersion(): String {

package/ios/map/ExpoGaodeMapModule.swift

@@ -18,16 +18,27 @@ public class NaviMapModule: Module {
     private var permissionManager: PermissionManager?
     /// 隐私协议是否已同意（模块级别跟踪）
     private static var privacyAgreed: Bool = false
+    /// 隐私同意持久化 Key
+    private static let privacyDefaultsKey = "expo_gaode_map_privacy_agreed"
     
     public func definition() -> ModuleDefinition {
         Name("NaviMap")
         
-        // 模块初始化时不设置隐私合规
-        // 需要在用户同意隐私协议后手动调用 updatePrivacyCompliance 方法
+        // 模块初始化：尝试从本地缓存恢复隐私同意状态
         OnCreate {
-            // 仅更新隐私信息显示状态，不表示用户已同意
+            // 先确保隐私信息展示状态
             MAMapView.updatePrivacyShow(AMapPrivacyShowStatus.didShow, privacyInfo: AMapPrivacyInfoStatus.didContain)
-            print("ℹ️ ExpoGaodeMap: 隐私信息已更新，但需要用户同意隐私协议才能使用 SDK")
+
+            // 从 UserDefaults 恢复上次的同意状态（默认 false）
+            let saved = UserDefaults.standard.bool(forKey: NaviMapModule.privacyDefaultsKey)
+            NaviMapModule.privacyAgreed = saved
+            if saved {
+                // 同步到 SDK
+                MAMapView.updatePrivacyAgree(AMapPrivacyAgreeStatus.didAgree)
+                print("🔁 ExpoGaodeMap: 已从缓存恢复隐私同意状态: true")
+            } else {
+                print("ℹ️ ExpoGaodeMap: 未发现已同意记录，等待用户同意后再使用 SDK")
+            }
         }
         
         // ==================== 隐私合规管理 ====================
@@ -37,10 +48,15 @@ public class NaviMapModule: Module {
          * 必须在用户同意隐私协议后调用
          */
         Function("updatePrivacyCompliance") { (hasAgreed: Bool) in
+            // 更新内存状态
             NaviMapModule.privacyAgreed = hasAgreed
+            // 持久化到本地，供下次启动自动恢复
+            UserDefaults.standard.set(hasAgreed, forKey: NaviMapModule.privacyDefaultsKey)
+
             if hasAgreed {
+                // 同步到 SDK
                 MAMapView.updatePrivacyAgree(AMapPrivacyAgreeStatus.didAgree)
-                print("✅ ExpoGaodeMap: 用户已同意隐私协议，可以使用 SDK")
+                print("✅ ExpoGaodeMap: 用户已同意隐私协议，可以使用 SDK（状态已持久化）")
                 
                 // 在用户同意后，如果尚未设置 API Key，则尝试从 Info.plist 读取并设置
                 if AMapServices.shared().apiKey == nil || AMapServices.shared().apiKey?.isEmpty == true {
@@ -54,7 +70,7 @@ public class NaviMapModule: Module {
                 }
             } else {
                 MAMapView.updatePrivacyAgree(AMapPrivacyAgreeStatus.notAgree)
-                print("⚠️ ExpoGaodeMap: 用户未同意隐私协议，SDK 功能将受限")
+                print("⚠️ ExpoGaodeMap: 用户未同意隐私协议，SDK 功能将受限（状态已持久化）")
             }
         }
         

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-gaode-map-navigation",
-  "version": "1.0.1-next.0",
+  "version": "1.0.1-next.1",
   "description": "高德地图导航功能模块 - 路径规划、导航引导，基于expo-gaode-map",
   "main": "src/index.ts",
   "types": "src/index.d.ts",
@@ -22,7 +22,7 @@
   "license": "MIT",
   "homepage": "https://github.com/TomWq/expo-gaode-map#readme",
   "dependencies": {
-    "expo-gaode-map": "^2.2.4-next.0"
+    "expo-gaode-map": "^2.1.1-next.0"
   },
   "devDependencies": {
     "@types/react": "~19.1.0",

package/package.json.backup

@@ -1,6 +1,6 @@
 {
   "name": "expo-gaode-map-navigation",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0",
   "description": "高德地图导航功能模块 - 路径规划、导航引导，基于expo-gaode-map",
   "main": "src/index.ts",
   "types": "src/index.d.ts",