expo-gaode-map 2.2.5-next.0 → 2.2.5-next.2

package/README.md

@@ -1,35 +1,202 @@
 # expo-gaode-map
 
-一个功能完整的高德地图 React Native 组件库，基于 Expo Modules 开发，提供地图显示、定位、覆盖物等功能。
+一个功能完整的高德地图 React Native 组件库，**基于 Expo Modules 开发**，采用 Monorepo 架构，提供地图显示、定位、搜索、导航、Web API 等完整功能。
 
-# API documentation
+> 💡 本组件使用 [Expo Modules API](https://docs.expo.dev/modules/overview/) 构建，提供了类型安全的原生模块接口和优秀的开发体验。
 
-- [Documentation for the latest stable release](https://docs.expo.dev/versions/latest/sdk/gaode-map/)
-- [Documentation for the main branch](https://docs.expo.dev/versions/unversioned/sdk/gaode-map/)
+## 📖 完整文档
 
-# Installation in managed Expo projects
+**👉 [在线文档网站](https://TomWq.github.io/expo-gaode-map/)** · **👉 [示例仓库](https://github.com/TomWq/expo-gaode-map-example)**
 
-For [managed](https://docs.expo.dev/archive/managed-vs-bare/) Expo projects, please follow the installation instructions in the [API documentation for the latest stable release](#api-documentation). If you follow the link and there is no documentation available then this library is not yet usable within managed projects — it is likely to be included in an upcoming Expo SDK release.
+包含完整的 API 文档、使用指南和示例代码：
+- [快速开始](https://TomWq.github.io/expo-gaode-map/guide/getting-started.html)
+- [初始化指南](https://TomWq.github.io/expo-gaode-map/guide/initialization.html)
+- [搜索功能](https://TomWq.github.io/expo-gaode-map/guide/search.html)
+- [导航功能](https://TomWq.github.io/expo-gaode-map/guide/navigation.html)
+- [Web API](https://TomWq.github.io/expo-gaode-map/guide/web-api.html)
+- [API 参考](https://TomWq.github.io/expo-gaode-map/api/)
+- [使用示例](https://TomWq.github.io/expo-gaode-map/examples/)
 
-# Installation in bare React Native projects
+## ✨ 主要特性
 
-For bare React Native projects, you must ensure that you have [installed and configured the `expo` package](https://docs.expo.dev/bare/installing-expo-modules/) before continuing.
+### 核心功能（expo-gaode-map）
+- ✅ 完整的地图功能（多种地图类型、手势控制、相机操作）
+- ✅ 精准定位（连续定位、单次定位、坐标转换）
+- ✅ 丰富的覆盖物（Circle、Marker、Polyline、Polygon、HeatMap、Cluster 等）
+- ✅ 友好的错误提示系统（详细的解决方案和文档链接）
+- ✅ 完整的 TypeScript 类型定义
+- ✅ 跨平台支持（Android、iOS）
+- ✅ 同时支持 React Native 新旧架构（Paper & Fabric）
+- ✅ 高测试覆盖率（75.7%，207 个单元测试）
+- ✅ 友好的错误提示系统
+- ✅ **高测试覆盖率**（78.82%，164 个单元测试）
+- ✅ **友好的错误提示系统**（v3.0.0+）- 详细的错误信息和解决方案指引
 
-### Add the package to your npm dependencies
+### 可选模块
+- 🔍 **搜索功能**（expo-gaode-map-search）- POI 搜索、周边搜索、关键字搜索、地理编码等
+- 🧭 **导航功能**（expo-gaode-map-navigation）- 驾车、步行、骑行、货车路径规划，实时导航
+- 🌐 **Web API**（expo-gaode-map-web-api）- 纯 JavaScript 实现的路径规划、地理编码、POI 搜索等
 
-```
+## 📦 安装
+
+### 方案一：仅使用地图和定位（核心包）
+
+```bash
 npm install expo-gaode-map
+
+# 可选模块
+npm install expo-gaode-map-search      # 搜索功能
+npm install expo-gaode-map-web-api     # Web API
+```
+
+### 方案二：使用导航功能（导航包，已包含地图功能）
+
+```bash
+npm install expo-gaode-map-navigation  # 包含地图+导航
+
+# 可选模块
+npm install expo-gaode-map-web-api     # Web API
+```
+
+> ⚠️ **重要**：`expo-gaode-map` 和 `expo-gaode-map-navigation` 由于 SDK 冲突不能同时安装，二选一使用。
+
+### Config Plugin 配置（推荐）
+
+在 `app.json` 中配置，自动设置原生 API Key 和权限：
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-gaode-map",  // 或 "expo-gaode-map-navigation"
+        {
+          "androidKey": "your-android-key",
+          "iosKey": "your-ios-key"
+        }
+      ]
+    ]
+  }
+}
+```
+
+配置后重新构建：
+
+```bash
+npx expo prebuild --clean
+npx expo run:android
+npx expo run:ios
+```
+
+## 🚀 快速开始
+
+详细的初始化和使用指南请查看：
+- 📖 [快速开始文档](https://TomWq.github.io/expo-gaode-map/guide/getting-started.html)
+- 💻 [完整示例代码](https://github.com/TomWq/expo-gaode-map-example)
+
+## 📚 功能模块对比
+
+| 功能 | 核心包 | 搜索包 | 导航包 | Web API |
+|-----|-------|-------|-------|---------|
+| 地图显示 | ✅ | ❌ | ✅ | ❌ |
+| 定位 | ✅ | ❌ | ✅ | ❌ |
+| 覆盖物 | ✅ | ❌ | ✅ | ❌ |
+| POI 搜索 | ❌ | ✅ | ❌ | ✅ |
+| 地理编码 | ❌ | ✅ | ❌ | ✅ |
+| 路径规划 | ❌ | ❌ | ✅ | ✅ |
+| 实时导航 | ❌ | ❌ | ✅ | ❌ |
+| 平台 | 原生 | 原生 | 原生 | Web/原生 |
+
+## 🏗️ Monorepo 架构
+
 ```
+expo-gaode-map/
+├── packages/
+│   ├── core/                    # expo-gaode-map（核心包）
+│   │   └── 地图显示、定位、覆盖物
+│   ├── search/                  # expo-gaode-map-search（搜索包）
+│   │   └── POI 搜索、地理编码
+│   ├── navigation/              # expo-gaode-map-navigation（导航包）
+│   │   └── 地图+导航（替代 core）
+│   └── web-api/                 # expo-gaode-map-web-api（Web API）
+│       └── 纯 JS 实现的路径规划等
+└── 注意：core 和 navigation 不能同时安装
+```
+
+## 💡 常见问题
+
+### 1. 核心包和导航包如何选择？
+
+- **只需要地图和定位** → 安装 `expo-gaode-map`
+- **需要导航功能** → 安装 `expo-gaode-map-navigation`（已包含地图功能）
+- **不能同时安装**：两个包由于原生 SDK 冲突，只能选择其一
+
+### 2. 搜索功能和 Web API 有什么区别？
+
+- **搜索包**（`expo-gaode-map-search`）：原生实现，性能更好，需要配置原生环境
+- **Web API**（`expo-gaode-map-web-api`）：纯 JavaScript，无需原生配置，跨平台更好
+
+### 3. 如何配置 API Key？
+
+推荐使用 Config Plugin 自动配置，详见：[初始化指南](https://TomWq.github.io/expo-gaode-map/guide/initialization.html)
+
+### 4. 如何处理错误？ 🆕
+
+`expo-gaode-map` 提供了完善的错误处理系统：
+
+```typescript
+import ExpoGaodeMapModule, { GaodeMapError, ErrorType } from 'expo-gaode-map';
+
+try {
+  await ExpoGaodeMapModule.getCurrentLocation();
+} catch (error) {
+  if (error instanceof GaodeMapError) {
+    console.error(error.message);  // 友好的错误信息
+    console.log(error.solution);   // 详细的解决方案
+    console.log(error.docUrl);     // 相关文档链接
+  }
+}
+```
+
+**完整错误处理指南**：[ERROR_HANDLING_GUIDE.md](./ERROR_HANDLING_GUIDE.md)
+
+支持的错误类型：
+- `SDK_NOT_INITIALIZED` - SDK 未初始化
+- `INVALID_API_KEY` - API Key 配置错误
+- `PERMISSION_DENIED` - 权限未授予
+- `LOCATION_FAILED` - 定位失败
+- `MAP_VIEW_NOT_INITIALIZED` - 地图视图未初始化
+- 更多错误类型...
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可证
+
+MIT
+
+## 📚 文档与资源
 
-### Configure for Android
+- [在线文档](https://TomWq.github.io/expo-gaode-map/)
+- [错误处理指南](./ERROR_HANDLING_GUIDE.md) 🆕
+- [GitHub 仓库](https://github.com/TomWq/expo-gaode-map)
+- [示例项目](https://github.com/TomWq/expo-gaode-map-example)
+- [高德地图开放平台](https://lbs.amap.com/)
+- [Expo Modules API](https://docs.expo.dev/modules/overview/)
 
+## 🙏 致谢
 
+本项目在开发过程中参考了以下优秀项目：
 
+- **[react-native-amap3d](https://github.com/qiuxiang/react-native-amap3d)** - 一个优秀的 React Native 高德地图组件
 
-### Configure for iOS
+感谢这些开源项目的贡献者们！
 
-Run `npx pod-install` after installing the npm package.
+## 📮 反馈与支持
 
-# Contributing
+如果你在使用过程中遇到问题或有任何建议，欢迎：
 
-Contributions are very welcome! Please refer to guidelines described in the [contributing guide]( https://github.com/expo/expo#contributing).
+- 📝 提交 [GitHub Issue](https://github.com/TomWq/expo-gaode-map/issues)
+- 💬 参与 [Discussions](https://github.com/TomWq/expo-gaode-map/discussions)
+- ⭐ 给项目点个 Star 支持一下

package/android/build/.transforms/79e5f1504f216bdae2079192244b6add/results.bin

@@ -0,0 +1 @@
+o/bundleLibRuntimeToDirDebug