Начало работы с MapKit для Flutter

В этом руководстве объясняется как установить и настроить библиотеку MapKit и создать карту с меткой для определенной локации.

Шаг 1. Получите API-ключ для работы с MapKit

Перед тем, как использовать MapKit SDK в своем приложении, вам нужно получить API-ключ.

1. Перейдите в Кабинет Разработчика.

2. Авторизуйтесь, используя учетную запись Яндекса, или зарегистрируйте новый аккаунт.

3. Нажмите Подключить API и выберите MapKit – мобильный SDK.

4. Введите информацию о себе и своем проекте, выберите тарифный план и нажмите Продолжить.

5. После того, как ваш API-ключ будет успешно создан, он будет доступен на вкладке Интерфейсы API → MapKit – мобильный SDK.

Шаг 2. Добавьте библиотеку MapKit в проект

Библиотека MapKit SDK доступна в репозитории pub.dev.

1. Создайте новый проект или откройте существующий, например, в Visual Studio Code или Android Studio.

2. Откройте файл pubspec.yaml приложения (модуля). В секции dependencies добавьте зависимость:

   dependencies:
     # Облегченная библиотека, содержит только карту, слой пробок,
     # LocationManager, UserLocationLayer
     # и возможность скачивать офлайн-карты (только в платной версии).
     {{company_url_part}}_maps_mapkit_lite:
       version: ^4.8.1
   
     # Полная библиотека в дополнение к lite версии предоставляет автомобильную маршрутизацию,
     # веломаршрутизацию, пешеходную маршрутизацию и маршрутизацию на общественном транспорте,
     # поиск, suggest, геокодирование и отображение панорам.
     # {{company_url_part}}_maps_mapkit:
     #   version: ^4.8.1
   

3. Выполните pub get, чтобы синхронизировать проект и применить изменения.

   Если синхронизация завершилась успешно, при компиляции библиотека будет добавлена в проект автоматически.

4. Добавьте платформенные зависимости в ./android/app/build.gradle:

   implementation "com.google.android.gms:play-services-location:21.1.0"
   
   // Зависимость Work Manager . Вам нужно добавить ее, если Вы хотите использовать офлайн карты
   // implementation "androidx.work:work-runtime:2.9.0"
   

Шаг 3. Добавьте API-ключ для MapKit

Для MapKit SDK необходимо, чтобы вы инициализировали библиотеку и установили API-ключ с помощью функции initMapkit.

Рекомендуем сделать это в вашей main() функции:

import 'package:{{company_url_part}}_maps_mapkit_lite/init.dart' as init;

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await init.initMapkit(
    apiKey: 'YOUR_API_KEY'
  ); 
}

Если вы не хотите, чтобы ваш API-ключ хранился файле, который будет включен в систему контроля версий, вы можете сделать это одним из способов:

1. Определите флаг времени компиляции:

   flutter run --dart-define MAPKIT_API_KEY=your_api_key
   

   И используйте его так:

   import 'package:{{company_url_part}}_maps_mapkit_lite/init.dart' as init;
   
   void main() async {
     WidgetsFlutterBinding.ensureInitialized();
   
     final mapkitApiKey = String.fromEnvironment('MAPKIT_API_KEY');
   
     await init.initMapkit(
       apiKey: mapkitApiKey
     ); 
   }
   

2. Используйте пакет ENVied или создайте отдельный .dart файл, в котором будет находиться глобальная переменная, содержащая API-ключ.

Шаг 4. Добавьте карту

1. Добавьте YandexMap в дерево виджетов:

   void main() async {
     WidgetsFlutterBinding.ensureInitialized();
       
     await init.initMapkit(
       apiKey: 'YOUR_API_KEY'
     );
               
     runApp(const MyApp());
   }
     
   class MyApp extends StatefulWidget {
     const MyApp({super.key});
     
     @override
     State<MyApp> createState() => _MyAppState();
   }
     
   class _MyAppState extends State<MyApp> {
     
     MapWindow? _mapWindow;
     
     @override
     Widget build(BuildContext context) {
       return MaterialApp(
         home: Scaffold(
           body: YandexMap(onMapCreated: (mapWindow) => _mapWindow = mapWindow)
         )
       );
     }
   }
   

2. Когда карта становится видимой или невидимой для пользователя, отправляйте события onStart и onStop в Mapkit при помощи методов mapkit.onStart() и mapkit.onStop() соответственно.
   Иначе Mapkit не сможет отображать карту и прекратит ее обработку, когда приложение с картой станет невидимым для пользователя.

Создайте и запустите приложение. Пример приложения с кликабельной картой:

Чтобы изменить положение или масштаб карты, используйте метод Map.moveWithAnimation:

map.move(
  CameraPosition(
    Point(latitude: 55.751225, longitude: 37.62954),
    zoom: 17.0,
    azimuth: 150.0,
    tilt: 30.0
  )
);

Map.moveWithAnimation принимает на вход аргумент CameraPosition, который полностью задает положение, масштаб, наклон и азимут карты.

Карты по умолчанию поддерживают несколько действий: перемещение, поворот, изменение масштаба и наклон.

Без дополнительной настройки карта будет отображаться с минимально возможным масштабом для экрана пользователя.

Пример карты после изменения положения камеры:

Шаг 5. Обратите внимание при дальнейшей работе

MapKit хранит слабые ссылки на передаваемые ему Listener-объекты. Необходимо самим хранить ссылку на них в памяти:

final class MapCameraListenerImpl implements MapCameraListener {
  // ......
}

final class SomeMapScopedClass {

  final MapWindow _mapWindow;
  final MapCameraListener _cameraListener = MapCameraListenerImpl();

  SomeMapScopedClass(this._mapWindow);

  void addListener() {
    _mapWindow.map.addCameraListener(_cameraListener);
  }
}

Шаг 6. Отображение метки на карте

Изменим приложение таким образом, чтобы вы могли показывать на карте кликабельную метку.

1. Добавьте в проект ресурс png для изображения метки.

   Например, есть изображение, и оно доступно по идентификатору assets/ic_pin.png.

   

2. Добавьте метку для коллекции Map.mapObjects в определенное место.

   Используйте ImageProvider.fromImageProvider, чтобы создать экземпляр ImageProvider для изображения метки.

   final imageProvider = ImageProvider.fromImageProvider(const AssetImage("assets/ic_pin.png"));
   final placemark = mapWindow.map.mapObjects.addPlacemark()
     ..geometry = const Point(latitude: 55.751225, longitude: 37.62954)
     ..setIcon(imageProvider);
   

3. Чтобы подписаться на нажатия на созданную метку, используйте метод MapObject.addTapListener.

   final class MapObjectTapListenerImpl implements MapObjectTapListener {
   
     @override
     bool onMapObjectTap(MapObject mapObject, Point point) {
       showSnackBar("Tapped the placemark: Point(latitude: ${point.latitude}, longitude: ${point.longitude})");
       return true;
     }
   }
   
   final listener = MapObjectTapListenerImpl();
   placemark.addTapListener(listener);
   

Соберите и запустите приложение. На карте есть метка с вашим изображением. Коснитесь метки, и появится всплывающее сообщение:

Исходный код

Полные примеры кода из руководства вы можете найти в приложении map_objects в нашем репозитории на GitHub.