Flutter Mapbox GL

请注意，本项目由社区驱动，并非官方 Mapbox 产品。

我们欢迎 反馈 和贡献。

这个 Flutter 插件允许在 Flutter widget 中显示嵌入式的、可交互的、可定制的矢量地图。对于 Android 和 iOS 集成，我们使用了 mapbox-gl-native。对于 Web，我们依赖于 mapbox-gl-js。本项目仅支持这些库暴露的 API 的一个子集。

screenshot.png

如何使用

本项目在 pub.dev 上提供，请遵循 说明 将该包添加到您的 Flutter 应用程序中。

私有 Mapbox 访问令牌

本项目需要 Mapbox 访问令牌才能下载底层的 Android/iOS SDK。秘密访问令牌必须具有 *下载：读取* 范围，用于
Android 和/或
iOS.

如果未配置此项，则在构建过程中会出现类似以下的错误：
构建过程

Android

* What went wrong:
A problem occurred evaluating project ':mapbox_gl'.
> SDK Registry token is null. See README.md for more information.

iOS

[!] Error installing Mapbox-iOS-SDK
curl: (22) The requested URL returned error: 401 Unauthorized

公开 Mapbox 访问令牌

除了私有访问令牌外，您还需要一个公开访问令牌
以检索样式和底层资源。这可以通过运行应用程序并添加一个额外的定义语句来实现。

flutter run -d {device_id} --dart-define=ACCESS_TOKEN=ADD_YOUR_TOKEN_HERE`

支持的 API

功能 Android iOS Web
风格 ✅ ✅ ✅
相机 ✅ ✅ ✅
手势 ✅ ✅ ✅
用户位置 ✅ ✅ ✅
样式 DSL ❌ ❌ ❌
栅格图层 ❌ ❌ ❌
符号图层 ✅ ✅ ✅
圆形图层 ✅ ✅ ✅
线图层 ✅ ✅ ✅
填充图层 ✅ ✅ ✅
矢量源 ❌ ❌ ❌
栅格源 ❌ ❌ ❌
GeoJson 源 ✅ ✅ ✅
图像源 ✅ ✅ ✅
表达式 ✅ ✅ ✅
符号标注 ✅ ✅ ✅
圆形标注 ✅ ✅ ✅
线标注 ✅ ✅ ✅
填充标注 ✅ ✅ ✅

地图样式

可以通过在 MapOptions 中设置 styleString 来提供地图样式。支持以下格式：

  1. 传递地图样式的 URL。可以是内置的地图样式之一，也可以是 MapboxStyles，或者是一个自定义地图样式，通过以 ‘http(s)://’ 或 ‘mapbox://’ 开头的 URL 进行远程服务。
  2. 将样式作为本地资源传递。在 assets 中创建一个 JSON 文件，并在 pubspec.yml 中添加引用。将样式字符串设置为该资源的相对路径，以便将其加载到地图中。
  3. 将样式作为本地文件传递。在应用程序目录（例如 ApplicationDocumentsDirectory）中创建一个 JSON 文件。将样式字符串设置为该 JSON 文件的绝对路径。
  4. 传递原始 JSON 格式的地图样式。这仅在 Android 上受支持。

离线侧载

通过侧载所需的地图图块并将其包含在 assets 文件夹中，可以支持离线地图。

  • 请遵循 此处 提供的指南来创建您的图块包。

  • 将第一步生成的 tiles.db 文件放置在您的 assets 目录中，并在 pubspec.yml 文件中为其添加引用。

   assets:
     - assets/cache.db
  • 在应用程序启动时调用 installOfflineMapTiles 以将您的图块复制到 Mapbox 可以访问的位置。**注意：** 此方法应在加载 Map Widget **之前** 调用，以防止在将文件复制到位时发生冲突。

    try {
      await installOfflineMapTiles(join("assets", "cache.db"));
    } catch (err) {
      print(err);
    }

下载离线区域

离线区域是地图的已定义区域，可在网络连接有限或无网络连接的情况下使用。地图图块、样式和精度将使用适当的 SDK 方法从 Mapbox 下载，并存储在应用程序的缓存中。

    final Function(DownloadRegionStatus event) onEvent = (DownloadRegionStatus status) {
      if (status.runtimeType == Success) {
        // ...
      } else if (status.runtimeType == InProgress) {
        int progress = (status as InProgress).progress.round();
        // ...
      } else if (status.runtimeType == Error) {
        // ...
      }
    };

    final OfflineRegion offlineRegion = OfflineRegion(
      bounds: LatLngBounds(
        northeast: LatLng(52.5050648, 13.3915634),
        southwest: LatLng(52.4943073, 13.4055383),
      ),
      id: 1,
      minZoom: 6,
      maxZoom: 18,
      mapStyleUrl: 'mapbox://styles/mapbox/streets-v11',
    );

    downloadOfflineRegionStream(offlineRegion, onEvent);

位置功能

Android

在应用程序清单 android/app/src/main/AndroidManifest.xml 中添加 ACCESS_COARSE_LOCATION 或 ACCESS_FINE_LOCATION 权限，以在 **Android** 应用程序中启用位置功能。

<manifest ...
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

从 Android API 级别 23 开始，您还需要在运行时请求它。此插件不会为您处理此问题。示例应用程序使用 flutter 的 ‘location’ 插件 来实现此目的。

iOS

要在 **iOS** 应用程序中启用位置功能

如果您访问用户的位置，您还应该将以下键添加到 ios/Runner/Info.plist 中，以解释为什么您需要访问他们的位置数据：

xml ...
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>[Your explanation here]</string>

推荐 关于“在地图上显示您的位置并帮助改进地图”的说明。

贡献

我们欢迎为本项目做出贡献！如果您有兴趣帮助构建此 Mapbox-Flutter 集成，请阅读 贡献指南 以了解如何开始。

GitHub

查看 Github