mapbox-flutter-patterns

Mapbox Flutter Integration Patterns 是 Mapbox 官方提供的集成模式技能，用于在 iOS 和 Android 上以 Dart 集成 Mapbox Maps SDK for Flutter（mapbox_maps_flutter）。

一、用途 适用于以下场景：在 Flutter 应用中安装和配置 mapbox_maps_flutter；以正确方式设置 Mapbox 访问令牌；使用相机/样式选项初始化 MapWidget；添加标注（点、圆、线、多边形）并处理点击；显示用户位置指示；从应用资源加载 GeoJSON；排查添加 Mapbox 后出现的 iOS 构建失败。

二、前置要求 Flutter SDK 3.22.3 / Dart 3.4.4 及以上；iOS 部署目标 14.0 或更高；Android minSdk 21 或更高；一个免费的 Mapbox 账户。Web 和桌面端不受支持，该 Flutter SDK 仅面向 iOS 与 Android。

三、安装与配置

1. 添加依赖：在 pubspec.yaml 中声明 mapbox_maps_flutter: ^2.0.0，然后执行 flutter pub get。
2. 将 iOS 部署目标提升到 14.0（必需）：这是添加 Mapbox 后 iOS 构建失败最常见的原因。在 Xcode 中打开 ios/Runner.xcworkspace，选择 Runner target → General → Minimum Deployments → iOS 设为 14.0；若存在 ios/Podfile，同时更新 platform :ios, '14.0'。无需担心 CocoaPods 与 Swift Package Manager 的选择，mapbox_maps_flutter 两者都支持。
3. iOS 定位权限：在 ios/Runner/Info.plist 添加 NSLocationWhenInUseUsageDescription。
4. Android 权限：在 android/app/src/main/AndroidManifest.xml 添加 ACCESS_FINE_LOCATION 与 ACCESS_COARSE_LOCATION。
5. 配置访问令牌：推荐通过构建/运行时的 --dart-define 传入令牌，并在创建任何 MapWidget 之前于 MapboxOptions 上设置。示例：flutter run --dart-define=ACCESS_TOKEN=pk.your_token_here，代码中通过 const accessToken = String.fromEnvironment('ACCESS_TOKEN');，在 main() 中调用 MapboxOptions.setAccessToken(accessToken) 后再 runApp。切勿在源码中硬编码令牌；CI 中可传 --dart-define=ACCESS_TOKEN=$MAPBOX_ACCESS_TOKEN。

四、主要能力与用法

1. 地图初始化：使用 MapWidget 并传入 key、cameraOptions（center 为 Point(coordinates: Position(经度, 纬度)) 与 zoom）以及 styleUri（如 MapboxStyles.STANDARD）；通过 onMapCreated 获取 MapboxMap 控制器。
2. 添加标注：使用 mapboxMap.annotations 创建点、圆、折线、多边形的管理器。管理器应长期持有，创建一次后复用于更新。点标注支持自定义图片，需从 rootBundle 加载图片字节并在 pubspec.yaml 中注册资源；可通过 createMulti 批量创建。
3. 点击处理：使用 manager.tapEvents，这是当前 API，addOnPointAnnotationClickListener 已废弃。tapEvents 返回 Cancelable，需保存并在不再需要时调用 .cancel()。每个管理器的 longPressEvents 和 dragEvents 以及其它标注类型（如 CircleAnnotationManager.tapEvents）都遵循同样返回 Cancelable 的模式。
4. 从 GeoJSON 加载标注：读取资源文件、jsonDecode 后遍历 features，将坐标转换为 PointAnnotationOptions 并用 createMulti 创建。对于数千个要素，应使用样式图层（GeoJsonSource + SymbolLayer）而非标注。
5. 显示用户位置：需先授予权限（可使用 permission_handler 等），再通过 mapboxMap.location.updateSettings 配置 LocationComponentSettings（enabled、puckBearingEnabled、locationPuck 使用 DefaultLocationPuck2D）。
6. 相机控制：setCamera 可即时跳转；flyTo 配合 MapAnimationOptions(duration) 可实现动画飞行动画，支持 center、zoom、bearing、pitch。

五、故障排查

1. iOS 构建报“platform is lower than deployment target”：Flutter 默认 iOS 部署目标低于 Mapbox 最低要求（iOS 14），需在 Xcode 中将 Runner target 的 Minimum Deployments → iOS 设为 14.0；若项目有 ios/Podfile，也需设置 platform :ios, '14.0' 并重新执行 pod install。
2. 未调用 setAccessToken：若在创建 MapWidget 前忘记调用 MapboxOptions.setAccessToken，地图会加载为空白网格。务必在 main() 中于 runApp 之前调用。
3. 标注点击处理不触发：确认使用 manager.tapEvents(onTap: ...)，addOnPointAnnotationClickListener 已废弃；同时确认在创建标注管理器前已通过 onMapCreated 捕获 MapboxMap 控制器。
4. 权限变更后热重载：iOS/Android 不会在热重载时重新读取 manifest 或 Info.plist，编辑权限后需完全重启应用。

六、参考文件与资源 references/annotations.md 提供圆、折线、多边形模式以及 GeoJSON source/layer 配方；references/platform-setup.md 提供更深入的 iOS/Android 设置、令牌策略与发布签名说明。另有 Flutter Maps 指南、pub.dev 上的 API 参考、标注与用户位置指南以及示例应用可供查阅。