mapbox/mapbox-maps-flutter
Interactive, thoroughly customizable maps for Flutter powered by Mapbox Maps SDK
github へ移動してダウンロードMapbox Maps SDK Flutter Plugin
The Mapbox Maps SDK Flutter Plugin is an officially developed solution from Mapbox that enables use of our latest Maps SDK product (v11.2.0). The plugin allows developers to embed highly customized maps using a Flutter widget on Android and iOS.
Web and desktop are not supported.
Contributions welcome!
Supported API
Feature | Android | iOS |
---|---|---|
Style | :white_check_mark: | :white_check_mark: |
Camera position | :white_check_mark: | :white_check_mark: |
Camera animations | :white_check_mark: | :white_check_mark: |
Events | :white_check_mark: | :white_check_mark: |
Gestures | :white_check_mark: | :white_check_mark: |
User Location | :white_check_mark: | :white_check_mark: |
Circle Layer | :white_check_mark: | :white_check_mark: |
Fill Layer | :white_check_mark: | :white_check_mark: |
Fill extrusion Layer | :white_check_mark: | :white_check_mark: |
Line Layer | :white_check_mark: | :white_check_mark: |
Circle Layer | :white_check_mark: | :white_check_mark: |
Raster Layer | :white_check_mark: | :white_check_mark: |
Symbol Layer | :white_check_mark: | :white_check_mark: |
Hillshade Layer | :white_check_mark: | :white_check_mark: |
Heatmap Layer | :white_check_mark: | :white_check_mark: |
Sky Layer | :white_check_mark: | :white_check_mark: |
GeoJson Source | :white_check_mark: | :white_check_mark: |
Image Source | :white_check_mark: | :white_check_mark: |
Vector Source | :white_check_mark: | :white_check_mark: |
Raster Source | :white_check_mark: | :white_check_mark: |
Rasterdem Source | :white_check_mark: | :white_check_mark: |
Circle Annotations | :white_check_mark: | :white_check_mark: |
Point Annotations | :white_check_mark: | :white_check_mark: |
Line Annotations | :white_check_mark: | :white_check_mark: |
Fill Annotations | :white_check_mark: | :white_check_mark: |
Offline | :x: | :x: |
Viewport | :x: | :x: |
Style DSL | :x: | :x: |
Expression DSL | :x: | :x: |
View Annotations | :x: | :x: |
Requirements
The Maps Flutter Plugin is compatible with applications:
- Deployed on iOS 12 or higher
- Built using the Android SDK 21 or higher
- Built using the Dart SDK 3.0.0 or higher
Installation
Configure credentials
To run the Maps Flutter Plugin you will need to configure the Mapbox Access Tokens.
Read more about access tokens and public/secret scopes at the platform Android or iOS docs.
Secret token
To access platform SDKs you will need to create a secret access token with the Downloads:Read
scope and then:
- to download the Android SDK add the token configuration to
~/.gradle/gradle.properties
:
SDK_REGISTRY_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN
- to download the iOS SDK add the token configuration to
~/.netrc
:
machine api.mapbox.com
login mapbox
password YOUR_SECRET_MAPBOX_ACCESS_TOKEN
Public token
You can set the access token for Mapbox Maps Flutter Plugin(as well as for evey Mapbox SDK) via MapboxOptions
:
MapboxOptions.setAccessToken(ACCESS_TOKEN);
It’s a good practice to retrieve access tokens from some external source.
You can pass access token via the command line arguments when either building :
flutter build <platform> --dart-define PUBLIC_ACCESS_TOKEN=...
or running the application :
flutter run --dart-define PUBLIC_ACCESS_TOKEN=...
You can also persist token in launch.json :
"configurations": [
{
...
"args": [
"--dart-define", "PUBLIC_ACCESS_TOKEN=..."
],
}
]
Then to retrieve the token from the environment in the application :
String ACCESS_TOKEN = String.fromEnvironment("ACCESS_TOKEN");
Add the dependency
To use the Maps Flutter Plugin add the git dependency to the pubspec.yaml:
dependencies:
mapbox_maps_flutter: ^1.0.0
Configure permissions
You will need to grant location permission in order to use the location component of the Maps Flutter Plugin.
You can use an existing library to request location permission, e.g. with permission_handler await Permission.locationWhenInUse.request();
will trigger permission request.
You also need to declare the permission for both platforms :
Android
Add the following permissions to the manifest:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
iOS
Add the following to the Runner/Info.plist
to explain why you need access to the location data:
<key>NSLocationWhenInUseUsageDescription</key>
<string>[Your explanation here]</string>
Add a map
Import mapbox_maps_flutter
library and add a simple map:
import 'package:flutter/material.dart';
import 'package:mapbox_maps_flutter/mapbox_maps_flutter.dart';
void main() {
runApp(MaterialApp(home: MapWidget()));
}
MapWidget widget
The MapWidget
widget provides options to customize the map - you can set MapOptions
, CameraOptions
, styleURL
etc.
It also allows or add listeners for various events - related to style loading, map rendering, map loading.
MapboxMap controller
The MapboxMap
controller instance is provided with MapWidget.onMapCreated
callback.
MapboxMap
exposes an entry point to the most of the APIs Maps Flutter Plugin provides. It allows to control the map, camera, styles, observe map events,
query rendered features, etc.
It’s organized similarly to the Android and iOS counterparts.
To interact with the map after it’s created store the MapboxMap object somewhere :
class FullMap extends StatefulWidget {
const FullMap();
@override
State createState() => FullMapState();
}
class FullMapState extends State<FullMap> {
MapboxMap? mapboxMap;
_onMapCreated(MapboxMap mapboxMap) {
this.mapboxMap = mapboxMap;
}
@override
Widget build(BuildContext context) {
return new Scaffold(
body: MapWidget(
key: ValueKey("mapWidget"),
onMapCreated: _onMapCreated,
));
}
}
User location
To observe the user’s location and show the location indicator on the map use LocationComponentSettingsInterface
accessible via MapboxMap.location
.
You need to grant location permission prior to using location component (as explained before).
Location puck
To customize the appearance of the location puck call MapboxMap.location.updateSettings
method.
To use the 3D puck with model downloaded from Uri instead of the default 2D puck :
mapboxMap.location.updateSettings(LocationComponentSettings(
locationPuck: LocationPuck(
locationPuck3D: LocationPuck3D(
modelUri:
"https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Duck/glTF-Embedded/Duck.gltf",))));
You can find more examples of customization in the sample app.
Markers and annotations
You have several options to add annotations on the map.
- Use the AnnotationManager APIs to create circle/point/polygon/polyline annotations.
To create 5 point annotations using custom icon:
mapboxMap.annotations.createPointAnnotationManager().then((pointAnnotationManager) async {
final ByteData bytes =
await rootBundle.load('assets/symbols/custom-icon.png');
final Uint8List list = bytes.buffer.asUint8List();
var options = <PointAnnotationOptions>[];
for (var i = 0; i < 5; i++) {
options.add(PointAnnotationOptions(
geometry: createRandomPoint().toJson(), image: list));
}
pointAnnotationManager?.createMulti(options);
});
You can find more examples of the AnnotationManagers usage in the sample app : point annotations, circle annotations, polygon annotations, polyline annotations.
- Use style layers. This will require writing more code but is more flexible and provides better performance for the large amount of annotations (e.g. hundreds and thousands of them). More about adding style layers in the Map styles section.
Map styles
The Mapbox Maps Flutter Plugin allows full customization of the look of the map used in your application.
Set a style
You can specify the initial style uri at MapWidget.styleUri
, or load it at runtime using MapboxMap.loadStyleURI
/ MapboxMap.loadStyleJson
:
mapboxMap.loadStyleURI(Styles.LIGHT);
Work with layers
You can familiarize with the concept of sources, layers and their supported types in the platform documentation.
To add, remove or change a source or a layer use the MapboxMap.style
object.
To add a GeoJsonSource
and a LineLayer
using the source :
var data = await rootBundle.loadString('assets/polyline.geojson');
await mapboxMap.style.addSource(GeoJsonSource(id: "line", data: data));
await mapboxMap.style.addLayer(LineLayer(
id: "line_layer",
sourceId: "line",
lineJoin: LineJoin.ROUND,
lineCap: LineCap.ROUND,
lineOpacity: 0.7,
lineColor: Colors.red.value,
lineWidth: 8.0));
Using expressions
You can change the appearance of a layer based on properties in the layer’s data source or zoom level.
Refer to the documentation for the description of supported expressions.
To apply an expression to interpolate gradient color to a line layer:
mapboxMap.style.setStyleLayerProperty("layer", "line-gradient",
'["interpolate",["linear"],["line-progress"],0.0,["rgb",6,1,255],0.5,["rgb",0,255,42],0.7,["rgb",255,252,0],1.0,["rgb",255,30,0]]');
Camera and animations
Platform docs : Android, iOS.
The camera is the user’s viewpoint above the map. The Maps Flutter Plugin provides you with options to set and adjust the camera position, listen for camera changes, get the camera position, and restrict the camera position to set bounds.
Camera position
You can set the starting camera position using MapWidget.cameraOptions
:
MapWidget(
key: ValueKey("mapWidget"),
cameraOptions: CameraOptions(
center: Point(coordinates: Position(-80.1263, 25.7845)).toJson(),
zoom: 12.0),
));
or update it at runtime using MapboxMap.setCamera
:
MapboxMap.setCamera(CameraOptions(
center: Point(coordinates: Position(-80.1263, 25.7845)).toJson(),
zoom: 12.0));
You can find more examples of interaction with the camera in the sample app.
Camera animations
Camera animations are the means by which camera settings are changed from old values to new values over a period of time. You can animate the camera using flyTo
or easeTo
and move to a new center location, update the bearing, pitch, zoom, padding, and anchor.
To start a flyTo
animation to the specific camera options :
mapboxMap?.flyTo(
CameraOptions(
anchor: ScreenCoordinate(x: 0, y: 0),
zoom: 17,
bearing: 180,
pitch: 30),
MapAnimationOptions(duration: 2000, startDelay: 0));
You can find more examples of animations in the sample app.
User interaction
Users interacting with the map in your application can explore the map by performing standard gestures.
You can retrieve or update the GestureSettings
using MapboxMap.gestures
.
You can observe gesture events using MapWidget.onTapListener
, MapWidget.onLongTapListener
, MapWidget.onScrollListener
.
![](/images/banner-woo.jpg)
関連する mapbox/mapbox-maps-flutter 優れたプロジェクトの推薦ダウンロード
AppFlowy
47859
AppFlowy is an open-source alternative to Notion. You are in charge of your data and customizations. Built with Flutter and Rust.
localsend
33797
An open-source cross-platform alternative to AirDrop
spotube
23772
🎧 Open source Spotify client that doesn't require Premium nor uses Electron! Available for both desktop & mobile!
revanced-manager
15035
💊 Application to use ReVanced on Android
gsy_github_app_flutter
14559
Flutter 超完整的开源项目,功能丰富,适合学习和日常使用。GSYGithubApp系列的优势:我们目前已经拥有Flutter、Weex、ReactNative、kotlin 四个版本。 功能齐全,项目框架内技术涉及面广,完成度高,持续维护,配套文章,适合全面学习,对比参考。跨平台的开源Github客户端App,更好的体验,更丰富的功能,旨在更好的日常管理和维护个人Github,提供更好更方便的驾车体验Σ( ̄。 ̄ノ)ノ。同款Weex版本 : https://github.com/CarGuo/GSYGithubAppWeex 、同款React Native版本 : https://github.com/CarGuo/GSYGithubApp 、原生 kotlin 版本 https://github.com/CarGuo/GSYGithubAppKotlin
dio
12249
A powerful HTTP client for Dart and Flutter, which supports global settings, Interceptors, FormData, aborting and canceling a request, files uploading and downloading, requests timeout, custom adapters, etc.
gopeed
11832
A modern download manager that supports all platforms. Built with Golang and Flutter.
bloc
11441
A predictable state management library that helps implement the BLoC design pattern
getx
9899
Open screens/snackbars/dialogs/bottomSheets without context, manage states and inject dependencies easily with Get.
flame
8846
A Flutter based game engine.
flutter_deer
7595
🦌 Flutter 练习项目(包括集成测试、可访问性测试)。内含完整UI设计图,更贴近真实项目的练习。Flutter practice project (including integration testing and accessibility testing). Contains complete UI design drawings for a more realistic practice project.
fish-redux
7343
An assembled flutter application framework.
fl_chart
6451
FL Chart is a highly customizable Flutter chart library that supports Line Chart, Bar Chart, Pie Chart, Scatter Chart, and Radar Chart.
pixez-flutter
6360
一个支持免代理直连及查看动图的第三方Pixiv flutter客户端
Flutter-Responsive-Admin-Panel-or-Dashboard
6355
Responsive Admin Panel or Dashboard using Flutter
aidea
6021
AIdea 是一款支持 GPT 以及国产大语言模型通义千问、文心一言等,支持 Stable Diffusion 文生图、图生图、 SDXL1.0、超分辨率、图片上色的全能型 APP。
riverpod
5828
A reactive caching and data-binding framework. Riverpod makes working with asynchronous code a breeze.
pikapika
5463
美观易用且无广告的漫画和游戏客户端,同时支持MacOS,Windows,Android,iOS。
provider
5029
InheritedWidgets, but simple
getwidget
4416
Most popular and easy to use open source UI library with 1000+ Widgets to build flutter app.