expo-gaode-map 2.0.0-alpha.6 → 2.0.0

package/docs/INITIALIZATION.en.md

@@ -1,346 +0,0 @@
-# Initialization Guide
-
-English | [简体中文](./INITIALIZATION.md)
-
-This document explains how to properly initialize and configure expo-gaode-map.
-
-## Table of Contents
-
-- [Basic Initialization Process](#basic-initialization-process)
-- [Permission Management](#permission-management)
-- [Complete Example](#complete-example)
-- [Common Issues](#common-issues)
-
-## Basic Initialization Process
-
-### 1. SDK Initialization
-
-Initialize the SDK when the app starts (usually in the App component's useEffect):
-
-```tsx
-import { initSDK } from 'expo-gaode-map';
-
-useEffect(() => {
-  initSDK({
-    androidKey: 'your-android-api-key',
-    iosKey: 'your-ios-api-key',
-  });
-}, []);
-```
-
-### 2. Permission Check and Request
-
-Before using location features, you must check and request permissions:
-
-```tsx
-import { 
-  checkLocationPermission, 
-  requestLocationPermission 
-} from 'expo-gaode-map';
-
-// Check permission status
-const status = await checkLocationPermission();
-console.log('Permission status:', status);
-// { granted: boolean, canAskAgain: boolean }
-
-// Request permission
-if (!status.granted) {
-  const result = await requestLocationPermission();
-  if (result.granted) {
-    console.log('Permission granted');
-  } else {
-    console.log('Permission denied');
-  }
-}
-```
-
-### 3. Get Location
-
-After permission is granted, you can get the current location:
-
-```tsx
-import { getCurrentLocation } from 'expo-gaode-map';
-
-try {
-  const location = await getCurrentLocation();
-  console.log('Current location:', location);
-} catch (error) {
-  console.error('Get location failed:', error);
-}
-```
-
-## Permission Management
-
-### Permission APIs
-
-| API | Description | Return Value |
-|-----|-------------|--------------|
-| `checkLocationPermission()` | Check location permission status | `Promise<PermissionStatus>` |
-| `requestLocationPermission()` | Request location permission | `Promise<PermissionStatus>` |
-
-### PermissionStatus Type
-
-```typescript
-interface PermissionStatus {
-  granted: boolean;      // Whether permission is granted
-  canAskAgain: boolean;  // Whether can request again
-}
-```
-
-### Permission Status Explanation
-
-- **granted: true** - User granted permission, can use location features
-- **granted: false, canAskAgain: true** - User denied permission, but can request again
-- **granted: false, canAskAgain: false** - User permanently denied permission, need to guide user to settings
-
-## Complete Example
-
-### Recommended Initialization Process
-
-```tsx
-import { useEffect, useState } from 'react';
-import { Alert, Platform, Linking } from 'react-native';
-import { 
-  MapView,
-  initSDK,
-  checkLocationPermission,
-  requestLocationPermission,
-  getCurrentLocation,
-  type LatLng,
-} from 'expo-gaode-map';
-
-export default function App() {
-  const [initialPosition, setInitialPosition] = useState<{
-    target: LatLng;
-    zoom: number;
-  } | null>(null);
-
-  useEffect(() => {
-    const initializeApp = async () => {
-      try {
-        // 1. Initialize SDK
-        console.log('Initializing AMap SDK...');
-        initSDK({
-          androidKey: 'your-android-api-key',
-          iosKey: 'your-ios-api-key',
-        });
-        
-        // 2. Check permission
-        const status = await checkLocationPermission();
-        
-        // 3. Request permission if needed
-        if (!status.granted) {
-          const result = await requestLocationPermission();
-          
-          if (!result.granted) {
-            // Permission denied, use default location
-            console.log('Location permission denied, using default location');
-            setInitialPosition({
-              target: { latitude: 39.90923, longitude: 116.397428 },
-              zoom: 10
-            });
-            
-            // Guide user to settings if cannot ask again
-            if (!result.canAskAgain) {
-              Alert.alert(
-                'Location Permission Required',
-                'Please enable location permission in settings',
-                [
-                  { text: 'Cancel', style: 'cancel' },
-                  { text: 'Settings', onPress: () => {
-                    if (Platform.OS === 'ios') {
-                      Linking.openURL('app-settings:');
-                    } else {
-                      Linking.openSettings();
-                    }
-                  }}
-                ]
-              );
-            }
-            return;
-          }
-        }
-        
-        // 4. Get current location
-        const location = await getCurrentLocation();
-        console.log('Current location:', location);
-        
-        // 5. Set map initial position
-        setInitialPosition({
-          target: {
-            latitude: location.latitude,
-            longitude: location.longitude
-          },
-          zoom: 15
-        });
-        
-      } catch (error) {
-        console.error('Initialization failed:', error);
-        // Use default location
-        setInitialPosition({
-          target: { latitude: 39.90923, longitude: 116.397428 },
-          zoom: 10
-        });
-      }
-    };
-
-    initializeApp();
-  }, []);
-
-  // Wait for initialization
-  if (!initialPosition) {
-    return <LoadingScreen />;
-  }
-
-  return (
-    <MapView
-      style={{ flex: 1 }}
-      initialCameraPosition={initialPosition}
-      myLocationEnabled={true}
-      onLoad={() => console.log('Map loaded')}
-    />
-  );
-}
-```
-
-### Key Points
-
-1. **Initialization Order**:
-   ```
-   initSDK → checkPermission → requestPermission → getCurrentLocation → Render Map
-   ```
-
-2. **Permission Handling**:
-   - ✅ Always check permission status first
-   - ✅ Only request permission when needed
-   - ✅ Handle permission denial cases
-   - ✅ Provide default location as fallback
-
-3. **Map Rendering**:
-   - ✅ **Important**: Wait for `initialPosition` to be set before rendering MapView
-   - ✅ Use `initialCameraPosition` to set initial position
-   - ⚠️ **iOS Note**: If map is rendered before getting location, it will show default location (Beijing) first then jump, causing flicker
-   - ✅ Both Android and iOS will directly position to specified location when map is displayed
-
-## Common Issues
-
-### Q: How to handle user denying permission?
-
-**A:** Provide default location and guide user:
-
-```tsx
-if (!result.granted) {
-  // Use default location
-  setInitialPosition({
-    target: { latitude: 39.90923, longitude: 116.397428 },
-    zoom: 10
-  });
-  
-  // Guide to settings if cannot ask again
-  if (!result.canAskAgain) {
-    Alert.alert(
-      'Location Permission Required',
-      'Please enable location permission in settings',
-      [
-        { text: 'Cancel' },
-        { text: 'Settings', onPress: () => Linking.openSettings() }
-      ]
-    );
-  }
-}
-```
-
-### Q: Can I update location after map is loaded?
-
-**A:** Yes, use the `moveCamera` method:
-
-```tsx
-const mapRef = useRef<MapViewRef>(null);
-
-// Update map center
-await mapRef.current?.moveCamera({
-  target: { latitude: 40.0, longitude: 116.5 },
-  zoom: 15,
-}, 1000); // 1 second animation
-```
-
-### Q: How to configure location parameters?
-
-**A:** Use the `configure` function, **must be called after `initSDK`**:
-
-```tsx
-import { initSDK, configure } from 'expo-gaode-map';
-
-// 1. Initialize SDK first
-initSDK({
-  androidKey: 'your-android-api-key',
-  iosKey: 'your-ios-api-key',
-});
-
-// 2. Then configure location parameters
-configure({
-  withReGeocode: true,  // Return address info
-  mode: 0,              // High accuracy mode
-  interval: 2000,       // Update every 2 seconds
-});
-```
-
-> ⚠️ **Important**: `configure` must be called after `initSDK`, otherwise configuration may not take effect.
-
-### Q: Are there differences between Android and iOS initialization?
-
-**A:** The initialization process is the same, but there are differences:
-
-**Android:**
-- Need to configure permissions in `AndroidManifest.xml`
-- Support more location configuration options
-
-**iOS:**
-- Need to configure permission descriptions in `Info.plist`
-- Support background location and heading updates
-
-For detailed configuration, see [AMap Official Documentation](https://lbs.amap.com/).
-
-## Best Practices
-
-1. **Always Handle Permissions**:
-   ```tsx
-   // ✅ Good practice
-   const status = await checkLocationPermission();
-   if (!status.granted) {
-     await requestLocationPermission();
-   }
-   
-   // ❌ Bad practice
-   await getCurrentLocation(); // May fail due to no permission
-   ```
-
-2. **Provide Loading State**:
-   ```tsx
-   if (!initialPosition) {
-     return <LoadingScreen />;
-   }
-   ```
-
-3. **Error Handling**:
-   ```tsx
-   try {
-     const location = await getCurrentLocation();
-   } catch (error) {
-     console.error('Get location failed:', error);
-     // Use default location
-   }
-   ```
-
-4. **Avoid Repeated Initialization**:
-   ```tsx
-   useEffect(() => {
-     initSDK({ ... });
-   }, []); // Empty dependency array, initialize only once
-   ```
-
-## Related Documentation
-
-- [API Documentation](./API.en.md) - Complete API reference
-- [Usage Examples](./EXAMPLES.en.md) - Detailed code examples
-- [README](../README.md) - Quick start guide

package/docs/INITIALIZATION.md

@@ -1,335 +0,0 @@
-# 初始化指南
-
-[English](./INITIALIZATION.en.md) | 简体中文
-
-本文档详细说明如何正确初始化和配置 expo-gaode-map。
-
-## 目录
-
-- [基本初始化流程](#基本初始化流程)
-- [权限管理](#权限管理)
-- [完整示例](#完整示例)
-- [常见问题](#常见问题)
-
-## 基本初始化流程
-
-### 1. SDK 初始化
-
-在应用启动时初始化 SDK（通常在 App 组件的 useEffect 中）:
-
-```tsx
-import { ExpoGaodeMapModule } from 'expo-gaode-map';
-
-useEffect(() => {
-  ExpoGaodeMapModule.initSDK({
-    androidKey: 'your-android-api-key',
-    iosKey: 'your-ios-api-key',
-  });
-}, []);
-```
-
-### 2. 权限检查和请求
-
-在使用定位功能前,必须先检查和请求权限:
-
-```tsx
-import { ExpoGaodeMapModule } from 'expo-gaode-map';
-
-// 检查权限状态
-const status = await ExpoGaodeMapModule.checkLocationPermission();
-console.log('权限状态:', status);
-// { granted: boolean, status: string }
-
-// 请求权限
-if (!status.granted) {
-  const result = await ExpoGaodeMapModule.requestLocationPermission();
-  if (result.granted) {
-    console.log('权限已授予');
-  } else {
-    console.log('权限被拒绝');
-  }
-}
-```
-
-### 3. 获取位置
-
-权限授予后,可以获取当前位置:
-
-```tsx
-import { ExpoGaodeMapModule } from 'expo-gaode-map';
-
-try {
-  const location = await ExpoGaodeMapModule.getCurrentLocation();
-  console.log('当前位置:', location);
-} catch (error) {
-  console.error('获取位置失败:', error);
-}
-```
-
-## 权限管理
-
-### 权限 API
-
-| API | 说明 | 返回值 |
-|-----|------|--------|
-| `ExpoGaodeMapModule.checkLocationPermission()` | 检查定位权限状态 | `Promise<PermissionStatus>` |
-| `ExpoGaodeMapModule.requestLocationPermission()` | 请求定位权限 | `Promise<PermissionStatus>` |
-
-### PermissionStatus 类型
-
-```typescript
-interface PermissionStatus {
-  granted: boolean;  // 是否已授予权限
-  status: string;    // 权限状态字符串
-}
-```
-
-### 权限状态说明
-
-- **granted: true** - 用户已授予权限,可以使用定位功能
-- **granted: false** - 用户未授予权限
-- **status** - 权限状态字符串（notDetermined, denied, authorizedWhenInUse, authorizedAlways 等）
-
-## 完整示例
-
-### 推荐的初始化流程
-
-```tsx
-import { useEffect, useState } from 'react';
-import { Alert, Platform, Linking } from 'react-native';
-import {
-  MapView,
-  ExpoGaodeMapModule,
-  type LatLng,
-} from 'expo-gaode-map';
-
-export default function App() {
-  const [initialPosition, setInitialPosition] = useState<{
-    target: LatLng;
-    zoom: number;
-  } | null>(null);
-
-  useEffect(() => {
-    const initializeApp = async () => {
-      try {
-        // 1. 初始化 SDK
-        console.log('正在初始化高德地图 SDK...');
-        ExpoGaodeMapModule.initSDK({
-          androidKey: 'your-android-api-key',
-          iosKey: 'your-ios-api-key',
-        });
-        
-        // 2. 检查权限
-        const status = await ExpoGaodeMapModule.checkLocationPermission();
-        
-        // 3. 如果没有权限,请求权限
-        if (!status.granted) {
-          const result = await ExpoGaodeMapModule.requestLocationPermission();
-          
-          if (!result.granted) {
-            // 权限被拒绝,使用默认位置
-            console.log('定位权限被拒绝,使用默认位置');
-            setInitialPosition({
-              target: { latitude: 39.90923, longitude: 116.397428 },
-              zoom: 10
-            });
-            
-            // 引导用户到设置
-            Alert.alert(
-              '需要定位权限',
-              '请在设置中开启定位权限以使用完整功能',
-              [
-                { text: '取消', style: 'cancel' },
-                { text: '去设置', onPress: () => {
-                  // 打开应用设置
-                  if (Platform.OS === 'ios') {
-                    Linking.openURL('app-settings:');
-                  } else {
-                    Linking.openSettings();
-                  }
-                }}
-              ]
-            );
-            return;
-          }
-        }
-        
-        // 4. 获取当前位置
-        const location = await ExpoGaodeMapModule.getCurrentLocation();
-        console.log('当前位置:', location);
-        
-        // 5. 设置地图初始位置
-        setInitialPosition({
-          target: {
-            latitude: location.latitude,
-            longitude: location.longitude
-          },
-          zoom: 15
-        });
-        
-      } catch (error) {
-        console.error('初始化失败:', error);
-        // 使用默认位置
-        setInitialPosition({
-          target: { latitude: 39.90923, longitude: 116.397428 },
-          zoom: 10
-        });
-      }
-    };
-
-    initializeApp();
-  }, []);
-
-  // 等待初始化完成
-  if (!initialPosition) {
-    return <LoadingScreen />;
-  }
-
-  return (
-    <MapView
-      style={{ flex: 1 }}
-      initialCameraPosition={initialPosition}
-      myLocationEnabled={true}
-      onLoad={() => console.log('地图加载完成')}
-    />
-  );
-}
-```
-
-### 关键要点
-
-1. **初始化顺序**:
-   ```
-   ExpoGaodeMapModule.initSDK → checkLocationPermission → requestLocationPermission → getCurrentLocation → 渲染地图
-   ```
-
-2. **权限处理**:
-   - ✅ 总是先检查权限状态
-   - ✅ 只在需要时请求权限
-   - ✅ 处理权限被拒绝的情况
-   - ✅ 提供默认位置作为后备方案
-
-3. **地图渲染**:
-   - ✅ **重要**: 等待 `initialPosition` 设置后再渲染 MapView
-   - ✅ 使用 `initialCameraPosition` 设置初始位置
-   - ⚠️ **iOS 注意**: 如果在获取位置前就渲染地图,会先显示默认位置(北京)再跳转,造成闪烁
-   - ✅ Android 和 iOS 都会在地图显示时直接定位到指定位置
-
-## 常见问题
-
-### Q: 如何处理用户拒绝权限的情况?
-
-**A:** 提供默认位置并引导用户:
-
-```tsx
-if (!result.granted) {
-  // 使用默认位置
-  setInitialPosition({
-    target: { latitude: 39.90923, longitude: 116.397428 },
-    zoom: 10
-  });
-  
-  // 引导到设置
-  Alert.alert(
-    '需要定位权限',
-    '请在设置中开启定位权限',
-    [
-      { text: '取消' },
-      { text: '去设置', onPress: () => Linking.openSettings() }
-    ]
-  );
-}
-```
-
-### Q: 可以在地图加载后更新位置吗?
-
-**A:** 可以,使用 `moveCamera` 方法:
-
-```tsx
-const mapRef = useRef<MapViewRef>(null);
-
-// 更新地图中心
-await mapRef.current?.moveCamera({
-  target: { latitude: 40.0, longitude: 116.5 },
-  zoom: 15,
-}, 1000); // 1秒动画
-```
-
-### Q: 如何配置定位参数?
-
-**A:** 使用配置方法,**必须在 `initSDK` 之后调用**:
-
-```tsx
-import { ExpoGaodeMapModule } from 'expo-gaode-map';
-
-// 1. 先初始化 SDK
-ExpoGaodeMapModule.initSDK({
-  androidKey: 'your-android-api-key',
-  iosKey: 'your-ios-api-key',
-});
-
-// 2. 再配置定位参数
-ExpoGaodeMapModule.setLocatingWithReGeocode(true);  // 返回地址信息
-ExpoGaodeMapModule.setLocationMode(0);              // 高精度模式
-ExpoGaodeMapModule.setInterval(2000);               // 2秒更新一次
-```
-
-> ⚠️ **重要**: 配置方法必须在 `initSDK` 之后调用,否则配置可能不生效。
-
-### Q: Android 和 iOS 的初始化有区别吗?
-
-**A:** 初始化流程相同,但有以下差异:
-
-**Android:**
-- 需要在 `AndroidManifest.xml` 中配置权限
-- 支持更多定位配置选项
-
-**iOS:**
-- 需要在 `Info.plist` 中配置权限描述
-- 支持后台定位和方向更新
-
-详细配置请参考 [高德地图官方文档](https://lbs.amap.com/)。
-
-## 最佳实践
-
-1. **总是处理权限**:
-   ```tsx
-   // ✅ 好的做法
-   const status = await ExpoGaodeMapModule.checkLocationPermission();
-   if (!status.granted) {
-     await ExpoGaodeMapModule.requestLocationPermission();
-   }
-   
-   // ❌ 不好的做法
-   await ExpoGaodeMapModule.getCurrentLocation(); // 可能因为没有权限而失败
-   ```
-
-2. **提供加载状态**:
-   ```tsx
-   if (!initialPosition) {
-     return <LoadingScreen />;
-   }
-   ```
-
-3. **错误处理**:
-   ```tsx
-   try {
-     const location = await ExpoGaodeMapModule.getCurrentLocation();
-   } catch (error) {
-     console.error('获取位置失败:', error);
-     // 使用默认位置
-   }
-   ```
-
-4. **避免重复初始化**:
-   ```tsx
-   useEffect(() => {
-     ExpoGaodeMapModule.initSDK({ ... });
-   }, []); // 空依赖数组,只初始化一次
-   ```
-
-## 相关文档
-
-- [API 文档](./API.md) - 完整的 API 参考
-- [使用示例](./EXAMPLES.md) - 详细的代码示例
-- [README](../README.md) - 快速开始指南