本文档以插件源码中的公开 API 为准，覆盖 地图展示、地图状态控制、交互回调、覆盖物、聚合、热力图、离线地图、粒子效果、室内图、个性化地图 等能力。 若你需要 路线规划、POI 搜索、地理编码、天气服务 等能力，本插件中并未实现（这些通常在搜索/路线规划类插件中提供）。
- 1. 快速开始
- 2. 地图组件与创建流程
- 3. MapOptions（地图初始化配置）
- 4. 地图控制与状态操作（BMFMapController）
- 5. 事件与回调
- 6. 覆盖物与图层
- 7. 点聚合（Cluster）
- 8. 定位与定位展示
- 9. 室内图
- 10. 热力图
- 11. 个性化地图
- 12. 粒子效果图层
- 13. 离线地图
- 14. 坐标与屏幕点转换
- 15. 版本与版权信息
- 16. 本插件不包含的能力说明
Android 10 以下设备使用 TextureMapView，Android 10 及以上使用 SurfaceMapView。
在 runApp 前调用：
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await BMFAndroidVersion.initAndroidVersion();
runApp(const MyApp());
}class MapPage extends StatefulWidget {
const MapPage({super.key});
@override
State<MapPage> createState() => _MapPageState();
}
class _MapPageState extends State<MapPage> {
late BMFMapController _controller;
@override
Widget build(BuildContext context) {
return Scaffold(
body: BMFMapWidget(
mapOptions: BMFMapOptions(
center: BMFCoordinate(39.915, 116.404),
zoomLevel: 15,
mapType: BMFMapType.Standard,
compassEnabled: true,
),
onBMFMapCreated: (controller) {
_controller = controller;
},
),
);
}
}- BMFMapWidget：主地图控件，通过
onBMFMapCreated获取BMFMapController进行后续操作。 - BMFMapController：所有地图操作接口的入口，按功能分为多个 extension（地图状态、覆盖物、热力图、定位、回调等）。
- BMFAndroidVersion：用于在 Android 10 以下设备选择 TextureMapView 渲染。
BMFMapOptions 用于创建地图时的默认配置，常用字段包括：
- 基础展示：
mapType、languageType、fontSizeLevel、backgroundColor。 - 地图状态：
center、zoomLevel、rotation、overlooking。 - 手势控制：
gesturesEnabled、zoomEnabled、scrollEnabled、rotateEnabled、overlookEnabled。 - 图层控制：
trafficEnabled、baiduHeatMapEnabled、showMapPoi、buildingsEnabled。 - UI 控件：
compassEnabled、showMapScaleBar、mapScaleBarPosition、showZoomControl、mapZoomControlPosition、logoPosition。 - 室内图：
baseIndoorMapEnabled、showIndoorMapPoi。 - 地图范围：
limitMapBounds、visibleMapBounds、mapPadding。
你也可以在地图创建后通过
updateMapOptions动态更新这些属性。
getMapStatus()/getMapType()/getMapLanguageType()/getZoomLevel()/getRotation()/getOverlooking()getVisibleMapBounds()/getMapScaleBarPosition()/getLogoPosition()getTrafficEnabled()/getBaiduHeatMapEnabled()/getBuildingsEnabled()/getShowMapPoi()
updateMapOptions(BMFMapOptions change)setNewMapStatus(mapStatus: ...)setCenterCoordinate(...)/setNewLatLngZoom(...)zoomIn()/zoomOut()/setZoomTo(...)/setZoomBy(...)setScrollBy(...)/setZoomPointBy(...)setVisibleMapBounds(...)/setVisibleMapRectWithPadding(...)/fitVisibleMapRectWithPadding(...)setMapCenterToScreenPt(...)mapRefresh()
takeSnapshot()/takeSnapshotWithRect(...)setCustomTrafficColor(...)setCompassImage(...)
- 地图加载完成：
setMapDidLoadCallback - 渲染完成/绘制帧：
setMapDidFinishedRenderCallback/setMapOnDrawMapFrameCallback - 地图区域变化：
setMapRegionWillChangeCallback/setMapRegionDidChangeCallback - 地图状态变化：
setMapStatusDidChangedCallback - 定位模式变化：
setUserTrackingModeChangedCallback
- 点击 POI：
setMapOnClickedMapPoiCallback - 点击空白：
setMapOnClickedMapBlankCallback - 双击：
setMapOnDoubleClickCallback - 长按：
setMapOnLongClickCallback - 3D Touch：
setMapOnForceTouchCallback
- 覆盖物点击：
setMapOnClickedOverlayCallback - 海量点点击：
setMapOnClickedMultiPointOverlaItemCallback - Marker：
setMapClickedMarkerCallback/setMaptDidSelectMarkerCallback/setMapDidDeselectMarkerCallback - Marker 拖拽：
setMapDragMarkerCallback - InfoWindow 点击：
setMapDidClickedInfoWindowCallback - 聚合点击：
setMapClusterClickCallback/setMapClusterItemClickCallback
覆盖物都通过 BMFMapController 的 OverlayExtension 或 MarkerExtension 添加：
- Marker：
addMarker/addMarkers/removeMarker/selectMarker/deselectMarker - Polyline：
addPolyline - Polygon：
addPolygon - Circle：
addCircle/addGradientCircle - ArcLine：
addArcline - GeodesicLine：
addGeodesicLine - Ground（图片覆盖物）：
addGround - Text / TextMarker / IconMarker：
addText/addTextMarker/addIconMarker - MultiPoint（海量点）：
addMultiPointOverlay - TraceOverlay（动态轨迹）：
addTraceOverlay - 3D 模型 & 3D 棱柱：
add3dModelOverlay/addPrismOverlay - Tile（瓦片图层）：
addTile/removeTile
addOverlays(List<BMFOverlay> overlays)clearOverlays()removeOverlay(overlayId)
switchOverlayLayerAndPOILayer(...)：Overlay 与 POI 层级互换switchLayerOrder(...)：任意图层顺序交换setPoiTagEnableAndPoiTagType(...)：按类型隐藏/显示底图 POI 标签
Android/iOS 聚合支持基于 BMFClusterInfo：
- 设置聚合点：
setClusterCoordinates(List<BMFClusterInfo>) - 更新聚合：
updateClusters(...) - 清理聚合：
cleanCluster() - 设置聚合最大距离：
setClusterMaxDistanceInDP(...) - 获取某 zoom 的聚合结果：
getClusterOnZoomLevel(...) - 控制显示/刷新：
setClusterVisible(...)
iOS 可在
setMapRegionDidChangeCallback内调用refreshClusters自定义样式。
- 显示/隐藏定位图层：
showUserLocation(bool show) - 设置定位模式：
setUserTrackingMode(...) - 更新定位数据：
updateLocationData(BMFUserLocation userLocation) - 自定义定位样式：
updateLocationViewWithParam(...)
定位数据对象为 BMFUserLocation，支持设置经纬度、精度、方向等字段。
- 显示/隐藏室内图：
showBaseIndoorMap(bool show) - 显示/隐藏室内图 POI：
showBaseIndoorMapPoi(bool showPoi) - 切换楼层：
switchBaseIndoorMapFloor(floorId, indoorId) - 获取当前室内图信息：
getFocusedBaseIndoorMapInfo()
回调：setMapInOrOutBaseIndoorMapCallback
- 添加热力图：
addHeatMap(BMFHeatMap heatMap) - 更新热力图：
updateHeatMap(...) - 删除热力图：
removeHeatMap() - 显示/隐藏：
showHeatMap(bool show) - 帧动画控制：
startHeatMapFrameAnimation()/stopHeatMapFrameAnimation()/setHeatMapFrameAnimatioIndex(...)
回调：setHeatMapFrameAnimationIndexCallback
- 开关：
setCustomMapStyleEnable(bool enable) - 本地样式：
setCustomMapStyle(String path, int mode) - 在线样式：
setCustomMapStyleWithOptionPath(...)
在线样式需要在百度地图控制台创建样式 ID。
- 显示粒子效果：
showParticleEffect(BMFParticleEffectType effect) - 关闭粒子效果：
closeParticleEffect(BMFParticleEffectType effect) - 自定义粒子效果：
customParticleEffectWithOption(effect, option)
使用 OfflineController：
- 初始化：
init() - 下载/更新/暂停：
startOfflineMap(cityId)/updateOfflineMap(cityId)/pauseOfflineMap(cityId) - 删除：
removeOfflineMap(cityId) - 城市列表：
getHotCityList()/getOfflineCityList()/searchCity(cityName) - 下载状态：
getAllUpdateInfo()/getUpdateInfo(cityId) - 回调：
onGetOfflineMapStateBack(...)
- 屏幕点 -> 经纬度：
convertPointToCoordinate(...) - 经纬度 -> 屏幕点：
convertCoordinateToScreenPoint(...) - 三维坐标 -> 屏幕点：
convertScreenPointFromMapPoint3(...)
- 获取 SDK 版本：
BMFMapVersion.nativeMapVersion - 版权信息：
getNativeMapCopyright() - 测绘资质/审图号：
getNativeMapQualification()/getNativeMapApprovalNumber()
本仓库仅封装 地图展示与图层绘制能力，并不包含：
- POI 检索、地点输入提示、公交/驾车/骑行/步行路线规划
- 天气服务、推荐上车点、地理编码
- 分享短串等
如果你需要这些功能，请查看 Baidu Map Search/Route 相关 Flutter 插件（例如 flutter_baidu_mapapi_search / flutter_baidu_mapapi_utils 等）。
如需更深入的字段说明，请参考对应模型类：
BMFMapOptions：地图初始化配置BMFMapStatus：地图状态BMFMarker/BMFPolyline/BMFPolygon/BMFCircle/BMFHeatMap等覆盖物模型
这些模型均在 lib/src/models/ 与 lib/src/models/overlays/ 目录中。