Comment on page
Migrating To v6
This update has renewed two of the oldest surviving sections of 'flutter_map' (state/
MapController
and TileProvider
s), fixed bugs, and added features!This is significant progress in our aim to renew the project and bring it up to date. In the long run, this will bring it inline with up-to-date Flutter good practises and techniques, improve its performance and stability, and reduce the maintenance burden.
There are major breaking changes for all users, as well as some things users should check and possibly change.
Some changes have deprecations and messages, some do not. Please refer to the sections below for information on how to migrate your project, as well as in-code documentation and deprecation messages, if your migration is not listed below. Some changes are omitted if they are deemed unlikely to affect implementations.
There's loads of changes in this release, which will improve performance and reduce costs! Check out these highlights, along with the full changelog:
We've added in-memory caching to the underlying custom
ImageProvider
. This means that they do not need to be re-requested if they are pruned then re-loaded, reducing tile loading times, and reduce tile requests and costs!No action is needed to benefit from this.
If you're developing an app for the web, there's an exciting new performance boost available. By aborting in-flight HTTP requests if tiles are pruned before they are fully-loaded, connections can be freed up, reducing tile loading times, and potentially saving you money!
There are also advantages for other platforms, although they may not be quite as visible.
Manual action is required to benefit from this. See CancellableNetworkTileProvider for more information.
Rotation is now supported on desktop! Simply use the CTRL (or equivalent) keyboard key (customizable in
MapOptions
) and mouse.We've added some warning & recommendation logs in-code, that will trigger under certain circumstances. If they trigger, make sure to listen to them to benefit from performance and efficiency improvements!
Extension methods are now used to add the required functionality to the standard 'dart:math'
Point
object.To migrate, most cases should just need to replace all occurrences of
CustomPoint
with Point
.This import path was getting increasingly useless and exposing increasingly less features compared to the standard import. It also covered the standard import in the auto-generated DartDoc documentation, as it exported it as well.
All features that need to be exposed are now exposed through the primary import, and the dedicated plugin import has been removed.
FlutterMapState
previously represented all of the map's state. However, to improve the maintainability of this library's internals, and to improve performance, it has been removed and replaced with several 'aspects':MapCamera.of
: for more information, see Some of MapController's responsibilities have been moved to MapCameraMapOptions.of
: use to access the ambient configuredMapOptions
- (
MapController.of
): use to access the ambientMapController
, even if one was not explicitly defined by the user
In most cases, migrating will entail replacing
FlutterMapState
with MapCamera
, but another aspect may be required.MapController
now only controls the map's position/viewport/camera. The map's position is now described by MapCamera
.You should not read camera data directly from a
MapController
: these methods have been deprecated.There are multiple possibilities for migration:
- 1.If inside the
FlutterMap
context, prefer usingMapCamera.of(context)
- 2.Otherwise, use
MapController
in the same way, but use the.camera
getter to retrieve theMapCamera
.
The approach to 'mobile' and 'static' layers has been changed. Mobile layers now wrap themselves in a
MobileLayerTransformer
which uses the inherited state, instead of FlutterMap
applying the affects directly to them. Static layers should now ensure they use Align
and/or SizedBox.expand
.This has been done to simplify setup, and allow for placing static layers between mobile layers.
The way custom layers are defined has changed. Mobile/moving layers should now use
MobileLayerTransformer
at the top of their widget tree.Previously, the
retinaMode
property enabled/disabled the simulation of retina mode. To request retina tiles from the server, either the {r}
placeholder or "@2x" string could be included in the urlTemplate
.
This behaviour was unclear, did not conform to the norms of other mapping packages, and meant the {r}
placeholder was actually redundant.Now,
retinaMode
also affects whether the {r}
placeholder is filled in. If true
, and {r}
is present, then that will now be filled in to request retina tiles. If the placeholder is not present, only then will flutter_map simulate retina mode.Additionally, it is now recommended to use the
RetinaMode.isHighDensity
method to check whether retinaMode
should be enabled.This will simplify the developer experience when using multiple overlaid
TileLayer
s, as Colors.transparent
will no longer need to be specified. There is no reason that multiple TileLayer
s would each need to have a different (non-transparent) background colors, as the layers beneath would be invisible and therefore pointless.Therefore,
TileLayer
s now have transparent backgrounds, and the new MapOptions.backgroundColor
property sets the background color of the entire map.To migrate, move any background colour specified on the bottom-most
TileLayer
to MapOptions
.TileProvider.templateFunction
has been deprecated. It is now preferrable to create a custom TileProvider
extension, and override the populateTemplatePlaceholders
method. This has been done to reduce the scope of TileLayer
.These properties on
Marker
have been removed as it is not apparent what any valid use-case could be, and removing them helped simplify the internals significantly.If these are currently used, try changing
alignment
, and if that does not give the desired results, use a Transform
widget yourself.center
, bounds
, zoom
, and rotation
have been replaced with initialCenter
, initialCameraFit
, initialZoom
, and initialRotation
These have been renamed for clarity, as well as to better fit the change into using a documented 'camera' and increasing customizability.
To migrate, rename the properties, and also check the in-code documentation and new objects for information.
This has been done to improve readability and seperation of responsibilities.
It is not recommended to implement
TileProvider
, as there are now two methods of which only one should be implemented (getImage
& getImageWithCancelLoadingSupport
), as well as other members that should not usually be overridden.To migrate, use
extends
instead of implements
.Further panes will refer to implementations that use
extends
as 'extensions' for clarity, not to be confused with extension methods.TileLayer
behaviour has been modified so that the 'User-Agent' header can be set without copying all user-specified headers
. It is now inserted into the Map
, so it must be immutable/non-constant.Note that the
headers
property is also now final
.To migrate, remove the default value for
super.headers
: it is not necessary.The logic previously handled by
getTileUrl
, invertY
, and getSubdomain
has been refactored into generateReplacementMap
, populateTemplatePlaceholders
, and getTileUrl
.To migrate, consider overriding another of those methods, if it is more suitable. This will reduce the amount of code duplicated in your library from flutter_map's implementation.
Extensions implementing
getImage
should consider overriding getImageWithCancelLoadingSupport
instead The framework necessary to support tile providers that can abort in-flight HTTP requests and other processing is now available. For more information about the advantages of cancelling unnecessary tile requests when they are pruned before being fully loaded, see CancellableNetworkTileProvider.
If it is not possible to cancel the loading of a tile, or there is no advantage gained by doing so, you can ignore this.
To migrate, override
supportsCancelLoading
to true
, implement getImageWithCancelLoadingSupport
as appropriate, and remove the implementation of getImage
.Last modified 25d ago