Map Launcher 是一个 Flutter 插件,可检测 Android 和 iOS 设备上的可用地图应用,并使用指定的位置或路线启动它们。它使用户能够使用其首选的地图应用程序(如 Google 地图或 Apple 地图)查看标记或获取导航路线。该插件简化了与原生地图功能的集成,无需为每个平台进行自定义实现。它支持静态位置和点之间的动态路线规划。
适合场景
在地图应用中打开特定位置
启动逐向导航
在给定坐标处显示标记
与基于位置的服务集成
启用用户选择地图提供商
主要特点
自动检测已安装的地图应用
同时支持 Android 和 iOS
用于启动地图的简单API
处理路由和标记
跨平台兼容性
适合对象
需要地图集成的应用程序
旅行或配送应用
位置共享功能
导航工具
用户驱动的地图选择
使用建议
需要正确的权限才能访问位置
如果没有安装地图应用,可能无法使用
行为在不同平台之间略有差异
不包括应用内的地图渲染
依赖外部地图应用来实现功能
原始 README
以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。
Map Launcher
Map Launcher is a Flutter plugin to open maps on all platforms: iOS, Android, web, and desktop. Show markers, get directions, or search across 30 supported maps.
Uses universal links (HTTPS URLs), with native app detection on mobile.
Maps are tree-shakeable: only the maps you reference are compiled into your app. No URL schemes, package names, store ids, or icons of unused maps ever ship in your binary. See Binary Size & App Store Compliance.
import'package:map_launcher/map_launcher.dart';
// Show a marker (opens the best available map)awaitMapLauncher.marker(.coords(59.33, 18.07, title: 'Gamla Stan')).show();
// Show directionsawaitMapLauncher.directions(.coords(59.33, 18.07), mode: .walking).show();
// SearchawaitMapLauncher.marker(.search('Fika near Södermalm')).show();
// Specific mapawaitMapLauncher.marker(.coords(59.33, 18.07)).show(map: .google);
// Discover available maps (pass the maps your app supports)final maps = awaitMapLauncher.marker(.coords(59.33, 18.07))
.getSupportedMaps([.apple, .google, .waze]);
await maps.first.show();
Setup
iOS: Add URL schemes to Info.plist
Required for detecting installed native apps. Add only the schemes for the
maps your app uses. Each entry is visible to App Store review, so keep the
list as short as your map list:
<key>LSApplicationQueriesSchemes</key><array><string>comgooglemaps</string><!-- Google Maps --><!-- Add more only if you use them:
<string>waze</string> Waze
<string>iosamap</string> Amap
<string>baidumap</string> Baidu Maps
<string>yandexmaps</string> Yandex Maps
<string>yandexnavi</string> Yandex Navigator
<string>citymapper</string> Citymapper
<string>mapswithme</string> MAPS.ME
<string>osmandmaps</string> OsmAnd
<string>dgis</string> 2GIS
<string>qqmap</string> Tencent (QQ Maps)
<string>here-location</string> HERE WeGo
<string>tomtomgo</string> TomTom Go
<string>copilot</string> CoPilot
<string>com.sygic.aura</string> Sygic Truck
<string>nmap</string> Naver Map
<string>kakaomap</string> Kakao Maps
<string>tmap</string> TMap
<string>szn-mapy</string> Mapy.cz
<string>mappls</string> Mappls
<string>moovit</string> Moovit
<string>neshan</string> Neshan
<string>airnavpro</string> Air Navigation Pro
<string>magicearth</string> Magic Earth
--></array>
Apple Maps needs no entry. Each map's scheme is also available in code as
MapApp.<name>.iosScheme.
If you pass a map to discovery but forget its plist entry, debug builds print
a warning naming the exact scheme to add. Without the entry the map can
never be detected, which is otherwise indistinguishable from "not installed".
Android: No setup needed
The plugin ships a <queries> manifest block so installed map apps are
visible to detection. If you want your merged manifest to list only the maps
you use, remove entries in your app's AndroidManifest.xml:
// By coordinatesawaitMapLauncher.marker(.coords(59.33, 18.07, title: 'Gamla Stan')).show();
// With zoom levelawaitMapLauncher.marker(.coords(59.33, 18.07), zoom: 14).show();
// By search query (Google & Apple Maps)awaitMapLauncher.marker(.search('Vasa Museum Stockholm')).show();
Error Handling
show() throws MapLaunchException if the map cannot be opened:
try {
awaitMapLauncher.marker(.coords(59.33, 18.07)).show(map: .google);
} onMapLaunchExceptioncatch (e) {
print('Failed to open map: $e');
}
// Specific mapawaitMapLauncher.marker(.coords(59.33, 18.07)).show(map: .google);
// If map is omitted, the best available map is used automatically:// • iOS/macOS → Apple Maps// • Other platforms → Google Maps// • Falls back to web if native app unavailable
Discovering Maps
Discovery takes the list of maps your app supports. Only the maps you
reference are compiled into your binary. Declare the list once as a
constant and reuse it:
const myMaps = <MapApp>[.apple, .google, .waze, .citymapper];
// Maps that support a specific marker requestfinal marker = MapLauncher.marker(.coords(59.33, 18.07));
final maps = await marker.getSupportedMaps(myMaps);
for (final map in maps) {
print('${map.name} (installed: ${map.isInstalled})');
}
await maps.first.show(); // launches the marker request with that map// Maps that support a specific directions requestfinal directions = MapLauncher.directions(.coords(59.33, 18.07), mode: .walking);
final navMaps = await directions.getSupportedMaps(myMaps);
// All maps available on this platform (installed + universal link)final allAvailable = awaitMapLauncher.getAvailableMaps(myMaps);
// Every supported map (opts out of tree shaking, see// "Binary Size & App Store Compliance" below)final everything = awaitMapLauncher.getAvailableMaps(MapApp.all);
URL Inspection
final marker = MapLauncher.marker(.coords(59.33, 18.07, title: 'Gamla Stan'));
// Best URL for this platform (scheme on mobile, universal on web)final url = marker.getUrl(map: .google);
// Universal (HTTPS) URL, always works in browserfinal universal = marker.getUniversalUrl(map: .google);
// → https://www.google.com/maps/search/?api=1&query=59.33%2C18.07// Native scheme URL, only works with installed appfinal scheme = marker.getSchemeUrl(map: .google);
// → comgooglemaps://?q=59.33,18.07// Preview scheme URL for a different platformfinal iosScheme = marker.getSchemeUrl(map: .google, platform: .ios);
final androidScheme = marker.getSchemeUrl(map: .google, platform: .android);
Map Info & Store Links
MapApp properties are synchronous:
MapApp.waze.name // "Waze"MapApp.waze.id // "waze", stable and safe to persist in preferencesMapApp.waze.iconBytes // PNG bytes, use with Image.memory()MapApp.waze.appStoreUrl // "https://apps.apple.com/app/id323229106"MapApp.waze.playStoreUrl // "https://play.google.com/store/apps/details?id=com.waze"MapApp.waze.hasUniversalLink // true
Each map is a const object, and only the maps your code references are
compiled into your app: their URL strings, package names, store ids, and
icons. Everything else is removed by Dart's tree shaking in release builds.
This matters beyond binary size: App Store review scans binaries for
references to embargoed services, and there is precedent for apps being
rejected over identifiers they never actually used. With 6.0, if you don't
reference a map, nothing about it exists in your build.
Things to know:
MapApp.all references every map, so using it opts out of tree shaking.
All 30 maps' identifiers will ship in your binary. Prefer an explicit list.
Your LSApplicationQueriesSchemes is part of your app, not the plugin.
Declare only the schemes you use and prune stale ones (see Setup).
The plugin's Android <queries> entries can be removed per map with
tools:node="remove" if you want a minimal manifest (see Setup).
Custom Maps
Subclass MapApp to add a map the plugin doesn't ship. No fork needed:
classAcmeMapsextendsMapApp{
constAcmeMaps();
@overrideStringget id => 'acmeMaps';
@overrideStringget name => 'Acme Maps';
@overrideString? get playStoreId => 'com.acme.maps';
@overrideString? get iosScheme => 'acmemaps://';
@overrideUint8Listget iconBytes => myIconPngBytes;
@overrideString? markerUrl(LocationCoords coords, {int? zoom}) =>
'https://maps.acme.com/?ll=${coords.latlng}';
@overrideString? directionsUrl({
requiredLocationCoords destination,
LocationCoords? origin,
List<LocationCoords>? waypoints,
TravelMode? travelMode,
}) => 'https://maps.acme.com/directions?to=${destination.latlng}';
}
// Works everywhere a built-in map does:awaitMapLauncher.marker(.coords(59.33, 18.07)).show(map: constAcmeMaps());
final maps = await request.getSupportedMaps([.google, constAcmeMaps()]);
Override the scheme-URL methods and capability flags (supportsWaypoints,
supportsMarkerSearch, ...) as needed. See any map in
lib/src/maps/ for a template.
For a custom map to be detected as installed, add its identifiers to your
own app config. The plugin's bundled entries only cover built-in maps:
iOS: add its scheme to LSApplicationQueriesSchemes (debug builds warn
if you forget).
Android: add a <queries> entry to your AndroidManifest.xml:
Note there is no warning for this on Android. The OS gives apps no way to
check their own <queries>, so a missing entry looks exactly like "app
not installed". Launching (show(map: const AcmeMaps())) works either way;
only detection needs these entries.
Migrating from 5.x
Call sites like show(map: .google) compile unchanged. The full guide is in
MIGRATION.md. The short version:
5.x
6.0
MapType.google
MapApp.google
getSupportedMaps()
getSupportedMaps([.apple, .google, .waze])
MapLauncher.getAvailableMaps()
MapLauncher.getAvailableMaps(myMaps)
map.mapType
map.map
map.displayName
map.name
SvgPicture.asset(map.icon)
Image.memory(map.iconBytes)
MapType.values.byName(saved)
myMaps.firstWhere((m) => m.id == saved)
Known Issues
On iOS it's possible to "delete" Apple Maps which actually just removes it from the home screen and does not actually delete it. Because of that Apple Maps will always show up as available on iOS. More info
Contributing
Pull requests are welcome. See CONTRIBUTING.md for setup instructions and guidelines.