flutter_map_tile_caching

flutter_map 库的一个插件，可提供一种缓存图块和下载地图区域以供离线使用的简便方法。

安装

要安装此插件，请使用正常的安装方法

   > flutter pub add flutter_map_tile_caching

如果您急需此包的最新版本（尚未发布到 pub.dev），请在您的 pubspec.yaml 中使用此代码片段替换（请注意，不推荐此方法）

    flutter_map_tile_caching:
        git:
            url: https://github.com/JaffaKetchup/flutter_map_tile_caching

安装包后，在项目中将它导入到必要的文件中

import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';

Android

由于后台下载功能，Android 需要额外的步骤，不幸的是，即使您不打算使用该功能。这是因为用于执行后台下载的依赖项的工作方式。
有关这些步骤，请访问：background_fetch 的 Android 安装说明。

iOS

由于后台下载功能，iOS 需要额外的步骤，尽管此功能在 iOS 上目前不幸被阻止。这是因为用于执行后台下载的依赖项的工作方式。
有关这些步骤，请访问：background_fetch 的 iOS 安装说明。
您不需要遵循 BackgroundFetch.scheduleTask 的说明，但如果遇到构建错误，请执行这些说明 - 最后一步中要求的自定义任务标识符正是 'backgroundTileDownload'。
请注意，此库尚未在 iOS 设备上进行测试，因此可能会出现问题。如果出现问题，请提交一个 Issue，我将尽力调试和解决它们。

示例

要查看示例项目，请创建一个新项目，并将现有 'main.dart' 文件替换为该项目示例文件夹中的 'main.dart' 文件。然后将此库添加到 'pubspec.yaml' 文件中。最后，遵循上面的平台特定安装说明，以使您的应用能够成功构建。

或者，如果您只想快速了解其工作原理，可以通过安装“example”目录中的 APK 文件在 Android 设备上运行示例应用程序。但请注意，此文件可能比当前版本旧。

功能

此库提供 3 项主要功能和 4 个主要 API

  • 自动图块缓存 (TileProvider API & Caches API)
  • 区域下载 (TileProvider API, Regions API, Downloading API & Caches API)
    • 简易形状选择器 (Regions API)

所有这些功能协同工作，为您提供在 Flutter 应用中实现完全离线地图所需的一切。

API 详情

您可以在 Dart 自动生成文档 (dartdoc) 中查看每个类、方法、扩展和枚举。其中包含了所有可用功能及其使用说明。您还可以查看示例了解这些功能如何协同工作。但是，为了让新用户更轻松地使用此项目，主要/最有用/最常见的部分如下，您可以使用搜索功能在文档中查找它们。

StorageCachingTileProvider()

将其用作 FlutterMap() 的图块提供程序，以便在用户平移（即浏览）图块时自动缓存图块。在整个脚本中使用相同的“实例”以避免重复冲突。
下面阅读有关缓存行为的更多信息。

downloadRegion() 及其后台对应函数

使用此功能在用户访问某地之前下载大片地图区域（例如，在野外徒步旅行之前）。
目前，区域可以是矩形区域或圆形区域。未来计划添加更多类型。
下面阅读有关缓存行为的更多信息。

简易形状选择器

将其用作地图上的一个“图层”，让用户能够轻松选择一个区域进行下载。在整个脚本中使用相同的“实例”以避免重复冲突。
目前，区域可以是矩形区域或圆形区域。未来计划添加更多类型。
未来将继续改进此功能，以提供更好的功能。

从 v2 迁移到 v3

不幸的是，由于变化太大，迁移的最佳方式是使用新功能重写您项目中的相应部分。
我已努力使 v3 易于理解和使用，即使有所有新功能，所以我希望您不会觉得这太难。不幸的是，下一个主要版本可能也需要进行大规模迁移，因为此库将“完全成熟”。

离线/缓存行为

因为这是一个离线优先的包，所以它的行为可能与您的预期略有不同。下面详细介绍了与缓存交互的两个区域

浏览时

在此库中，“浏览”是指平移、缩放和旋转地图。

当浏览到一个新图块，并且用户在线时，图块将从服务器获取并缓存，并记录其到期日期（由图块提供程序上的 cachedValidDuration 决定）。
如果此图块再次被浏览，并且用户在线，即使用户在线，图块仍将从缓存中获取，除非图块已过期，在这种情况下，它将被重新获取并再次缓存。这被称为“缓存优先”缓存。
如果此图块再次被浏览，但用户不在线，即使图块已过期，图块也将从缓存中获取。但是，仍然会发出网络请求，但会静默失败。
如果用户不在线，并且图块尚未缓存，则请求将以控制台错误的形式失败，但应用程序将正常继续运行。

下载区域时

在使用 downloadRegion() 函数（或其后台对应函数（见下文））时，区域中的每个图块都将始终被缓存，即使图块以前已缓存但尚未过期。
然后，每个下载的图块将像已被浏览过一样进行处理（见上文）。

后台区域下载

而不是在前台（主线程）下载，Android 上有一个选项可以在后台开始下载。

这具有几个主要优点，包括更好的核心应用程序性能，能够在用户与应用程序的其他组件交互时继续下载，以及（潜在）即使在用户使用其他应用程序或设备锁定时也能继续下载。

后台下载功能存在 bug，在 Android 以外的平台上并不总是按预期工作，因此该功能已在除 Android 以外的所有平台上禁用。这未来可能会改变，但没有保证。

要获得完整的后台功能，包括不被系统限制以及确保在应用程序“最小化”时仍能运行，请在开始后台任务之前通过调用 requestIgnoreBatteryOptimizations() 来请求“忽略电池优化”权限。这将向用户显示一个系统中断提示，允许或拒绝该权限。如果拒绝了权限，后台任务仍将运行，但仅限于用户在应用程序内时；在应用程序外，下载不保证正在运行。

限制、已知 bug 和测试

  • 此包不支持 Web 平台（由于使用了 dart:io 和 sqflite 包）。未来可能会修复此问题。

  • 自定义图块大小（256x256 除外）或自定义 CRS（Epsg3857() 除外）的支持可能存在 bug，但已尝试通过 flutter_map 的内置功能使此库与之兼容。v4.0.0 版本将继续进行兼容性测试。

  • 不幸的是，使用 TileStorageCachingManager.changeMaxTileAmount() 不会更改图块提供程序/下载器中的断言。在 v4.0.0 之前，一次可下载的图块最大数量为 20000。这个问题将在 v4.0.0 中得到修复，因为该版本还将包含其他重构。

  • 圆形区域函数在圆的半径越大时精度越低。为防止出现干扰性错误，计算值已钳制到有效的最小值和最大值，但这会导致副作用。为防止这些副作用，仅使用小于欧洲国家平均尺寸的圆，并在使用靠近极端值（赤道、经度 180 或 -180，以及纬度 -90 或 90）的圆时要谨慎。如果选择大区域或在使用上述极端值附近时，请改用矩形区域。未来可能会修复此问题。

此包仅在 Android 设备上进行了测试（一个真实的 Android 8，一个 Android 8 模拟器，以及一个 Android 11 模拟器）。但是，由于功能众多，且每种功能都有许多不同的变体，因此发现许多 bug 几乎是不可能的。因此，如果您发现 bug，请在 GitHub 上提交一个 Issue，我将尽最大努力快速修复。

GitHub

https://github.com/JaffaKetchup/flutter_map_tile_caching