Flutter 地图标记增强插件 google_maps_marker_widgets 的使用

Google Maps Marker Widgets

google_maps_marker_widgets 是一个 Flutter 包，用于在 Google 地图上使用任意小部件作为标记。

特性

• 可以使用 任何 小部件作为 [Marker] 显示在 [GoogleMap] 上。
• 更新标记位置时具有平滑动画（无瞬移）。
• 可自定义的 [LocationPuck] 小部件，允许手动控制位置更新和外观。

截图

动画标记小部件	自定义位置指针

开始使用

安装和设置 google_maps_flutter

如果你还没有安装和设置 google_maps_flutter，请先进行安装：

flutter pub add google_maps_flutter

添加权限

iOS

在 Info.plist 文件中添加权限以访问用户的地理位置。

对于仅在使用时访问：

<key>NSLocationWhenInUseUsageDescription</key>
<string>允许此应用在使用时访问您的位置？</string>

对于在后台也监控位置数据的应用：

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>此应用在任何时候跟踪您的位置会表现得更好。</string>

Android

打开 app/src/main/AndroidManifest.xml 并添加以下权限之一：

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

添加 geolocator 和 flutter_compass（可选）

flutter pub add geolocator
flutter pub add flutter_compass

使用方法

google_maps_marker_widgets 有三个主要组件：

1. [MarkerWidget] - 在 [GoogleMap] 中为 [Marker] 提供视觉内容的小部件

final treeMarkerId = MarkerId('treeMarker');
final treeMarkerWidget = MarkerWidget(
  markerId: treeMarkerId,
  child: Icon(Icons.park, color: Colors.green, size: 45),
);

2. [MarkerWidgetsController] - 管理 [MarkerWidget] 及其关联的 [Marker] 在 [GoogleMap] 上

你可以使用 markerWidgetsController 来添加、删除和更新标记。

创建控制器并添加标记

final markerWidgetsController = MarkerWidgetsController();
final treeMarker = Marker(
  markerId: treeMarkerId,
  anchor: Offset(0.5, 0.5),
  position: LatLng(37, -108)
);
markerWidgetsController.addMarkerWidget(
  markerWidget: treeMarkerWidget,
  marker: treeMarker
);

注意 [Marker.anchor] 被设置为 Offset(0.5, 0.5)。这确保了标记在位置上居中。默认情况下，来自 [GoogleMap] 的锚点是 Offset(0.5, 1.0)。

更新标记的位置

final treeMarker = markerWidgetsController.markerForId(treeMarkerId)!;
final newPosition = LatLng(33, -105);
final updatedMarker = treeMarker.copyWith(positionParam: newPosition);
markerWidgetsController.updateMarker(marker: updatedMarker);

当更新标记时，默认情况下会使用动画。你可以通过传递 animated: false 来禁用此行为。

3. [MarkerWidgets] - 用于 [GoogleMap] 的包装小部件

[MarkerWidgets] 是使用 google_maps_marker_widgets 的主要入口点。

将 [MarkerWidgetsController] 传递给 [MarkerWidgets]，并在 [MarkerWidgets.builder] 方法中创建你的 [GoogleMap]，传入提供的标记集合。

MarkerWidgets(
  markerWidgetsController: _markerWidgetsController,
  builder: (context, markers) => GoogleMap(
    initialCameraPosition: CameraPosition(target: LatLng(41.8, -99.65), zoom: 4),
    markers: markers,
  ),
)

完整示例

import 'dart:math';
import 'package:flutter/material.dart';
import 'package:flutter_compass/flutter_compass.dart';
import 'package:geolocator/geolocator.dart';
import 'package:google_maps_flutter/google_maps_flutter.dart';
import 'package:google_maps_marker_widgets/google_maps_marker_widgets.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Google Maps Marker Widgets Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.lightGreen),
        useMaterial3: true,
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final MarkerWidgetsController _markerWidgetsController = MarkerWidgetsController();
  StreamSubscription<Position>? _deviceLocationStream;
  StreamSubscription<CompassEvent>? _compassEventsStream;
  CameraPosition? _cameraPosition;
  GoogleMapController? _mapController;

  [@override](/user/override)
  void initState() {
    _addSampleWidgetMarkers();
    super.initState();
  }

  [@override](/user/override)
  void dispose() {
    _deviceLocationStream?.cancel();
    _compassEventsStream?.cancel();
    super.dispose();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: MarkerWidgets(
        markerWidgetsController: _markerWidgetsController,
        builder: (context, markers) => GoogleMap(
          onMapCreated: _onMapCreated,
          onCameraMove: _onCameraMove,
          initialCameraPosition: CameraPosition(target: LatLng(41.8, -99.65), zoom: 4),
          markers: markers,
          myLocationButtonEnabled: false,
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _moveMarkers,
        child: Icon(Icons.play_arrow_rounded),
      ),
    );
  }

  void _onMapCreated(GoogleMapController mapController) async {
    _mapController = mapController;
    try {
      // 检查权限并开始流式位置数据
      await _startLocationDataStreaming();
      final currentLocation = await Geolocator.getCurrentPosition();
      final newLatLng = LatLng(currentLocation.latitude, currentLocation.longitude);
      final cameraUpdate = CameraUpdate.newLatLng(newLatLng);
      await _mapController?.animateCamera(cameraUpdate);
    } catch (error) {
      // TODO: 处理错误
    }
  }

  void _onCameraMove(CameraPosition cameraPosition) {
    _cameraPosition = cameraPosition;
  }

  void _addSampleWidgetMarkers() {
    // 添加一些示例小部件以演示动画
    // 注意锚点 / Offset 设置为 0.5, 0.5
    // 这会将您的小部件居中在所提供的位置上

    final treeMarkerId = MarkerId('treeMarker');
    _markerWidgetsController.addMarkerWidget(
      markerWidget: MarkerWidget(
        markerId: treeMarkerId,
        child: Icon(Icons.park, color: Colors.green, size: 45),
      ),
      marker: Marker(
        markerId: treeMarkerId,
        anchor: Offset(0.5, 0.5),
        position: LatLng(37, -108),
      ),
    );
    final smileyMarkerId = MarkerId('smileyMarker');
    _markerWidgetsController.addMarkerWidget(
      markerWidget: MarkerWidget(
        markerId: smileyMarkerId,
        child: Text(
          '😀',
          style: TextStyle(fontSize: 40),
        ),
      ),
      marker: Marker(
        markerId: smileyMarkerId,
        position: LatLng(37, -101),
        anchor: Offset(0.5, 0.5),
      ),
    );
    final flightMarkerId = MarkerId('flightMarker');
    _markerWidgetsController.addMarkerWidget(
      markerWidget: MarkerWidget(
        markerId: flightMarkerId,
        child: CircleAvatar(
          backgroundColor: Colors.blue,
          child: Icon(
            Icons.flight,
            color: Colors.white,
          ),
        ),
      ),
      marker: Marker(
        markerId: flightMarkerId,
        anchor: Offset(0.5, 0.5),
        position: LatLng(37, -93.65),
      ),
    );
  }

  // 将标记移动到新随机位置
  void _moveMarkers() {
    final markers = _markerWidgetsController.markers.value;
    for (var marker in markers) {
      if (marker.markerId != MarkerId('device')) {
        final newLat = 41.8 + Random().nextDouble() * 10 * (Random().nextBool() ? -1 : 1);
        final newLng = -99 + Random().nextDouble() * 10 * (Random().nextBool() ? -1 : 1);
        final newMarker = marker.copyWith(positionParam: LatLng(newLat, newLng));
        _markerWidgetsController.updateMarker(newMarker);
      }
    }
  }

  Future<void> _startLocationDataStreaming() async {
    bool serviceEnabled;
    LocationPermission permission;

    // 测试位置服务是否启用
    serviceEnabled = await Geolocator.isLocationServiceEnabled();
    if (!serviceEnabled) {
      // 位置服务未启用，不要继续访问位置并请求用户启用位置服务
      return Future.error('位置服务已禁用。');
    }

    permission = await Geolocator.checkPermission();
    if (permission == LocationPermission.denied) {
      permission = await Geolocator.requestPermission();
      if (permission == LocationPermission.denied) {
        // 权限被拒绝，下次可以再次请求权限（这是 Android 的 shouldShowRequestPermissionRationale 返回 true 的情况。根据 Android 指南，您的应用此时应显示解释性 UI）
        return Future.error('位置权限被拒绝');
      }
    }

    if (permission == LocationPermission.deniedForever) {
      // 权限被永久拒绝，处理这种情况
      return Future.error('位置权限被永久拒绝，我们无法请求权限。');
    }

    // 开始流式当前位置
    _deviceLocationStream = Geolocator.getPositionStream().listen(_onDeviceLocationUpdate);
    _compassEventsStream = FlutterCompass.events?.listen(_onCompassEvent);
  }

  void _onCompassEvent(CompassEvent compassEvent) {
    final currentHeading = compassEvent.heading;
    final marker = _markerWidgetsController.markerForId(MarkerId('device'));
    if (marker != null) {
      double rotationParam = (currentHeading ?? 0) - (_cameraPosition?.bearing ?? 0);
      final newMarker = marker.copyWith(rotationParam: rotationParam);
      _markerWidgetsController.updateMarker(newMarker, animated: false);
    }
  }

  void _onDeviceLocationUpdate(Position position) {
    final newLatLng = LatLng(position.latitude, position.longitude);
    final deviceMaker = _markerWidgetsController.markerForId(MarkerId('device'));
    if (deviceMaker == null) {
      // 添加设备标记到地图
      _markerWidgetsController.addDeviceLocationPuck(
        initialPosition: newLatLng,
        locationPuck: LocationPuck(showHeading: true),
      );
    } else {
      final positionParam = LatLng(position.latitude, position.longitude);
      final newDeviceMarker = deviceMaker.copyWith(positionParam: positionParam);
      _markerWidgetsController.updateMarker(newDeviceMarker);
    }
  }
}