Разработка

Офлайн-режим карт и навигации в Qorvia MapKit

Qorvia Team 2026-03-09 58 просмотров
Офлайн-режим карт и навигации в Qorvia MapKit

Сегодня расскажем немного о том как работает офлайн режим в нашем Flutter SDK

Многие навигационные приложения сталкиваются с одной и той же проблемой: интернет не всегда доступен.

  1. туннели
  2. сельская местность
  3. нестабильный мобильный интернет
  4. корпоративные устройства с ограниченной сетью

Чтобы приложение продолжало работать в таких условиях, Qorvia Maps SDK включает полноценную систему офлайн-режима.

Она позволяет:

  1. отображать карту без интернета
  2. использовать уже найденные адреса
  3. следовать маршруту
  4. работать с ранее полученными результатами поиска

Офлайн-система SDK состоит из трёх основных компонентов.

1. Кэширование API-ответов

SDK автоматически сохраняет результаты:

  1. геокодирования
  2. reverse геокодирования
  3. построения маршрутов
  4. Smart Search

Это позволяет использовать их повторно, даже если сеть недоступна.

2. Офлайн-карты

SDK поддерживает загрузку карт целыми регионами.

После загрузки:

  1. карта продолжает отображаться без интернета
  2. тайлы автоматически берутся из локального хранилища
  3. пользователю не требуется никаких дополнительных действий

3. Мониторинг сети

SDK автоматически отслеживает состояние сети и переключает поведение API:

  1. при наличии интернета используется сервер
  2. при отсутствии — используется кэш и офлайн-данные

Это происходит полностью автоматически.

Архитектура

Офлайн-подсистема SDK разделена на несколько независимых компонентов.

┌─────────────────────────────────────────────────────────────┐
│ Flutter App │
├─────────────────────────────────────────────────────────────┤
│ Offline UI │
│ ├── OfflineRegionsList │
│ ├── OfflineRegionPicker │
│ └── OfflineModeIndicator │
├─────────────────────────────────────────────────────────────┤
│ OfflineAwareClient │
│ (API клиент с поддержкой офлайн режима) │
├──────────────────────────┬──────────────────────────────────┤
│ │ │
▼ ▼ ▼
ConnectivityService CacheRepository OfflineTileManager
(мониторинг сети) (кэш API) (оффлайн карты)
│ │ │
▼ ▼ ▼
NetworkStatus CacheDatabase(SQLite) MapLibre GL Native
(скачивание тайлов)

Каждый компонент отвечает за отдельную часть системы:

  1. ConnectivityService — определяет состояние сети
  2. CacheRepository — хранит API-ответы
  3. OfflineTileManager — управляет офлайн-картами

Компоненты офлайн-системы

1. Кэширование API-ответов

SDK автоматически кэширует результаты API-запросов.

ОперацияTTLМаксимум записей
Геокодирование24 часа100
Reverse геокодинг6 часов200
Маршруты1 час50
Smart Search12 часов100




Такая стратегия позволяет:

  1. уменьшить нагрузку на API
  2. ускорить повторные запросы
  3. обеспечить работу офлайн

Конфигурация

Офлайн-режим настраивается при инициализации SDK.


await QorviaMapsSDK.init(
apiKey: 'your_api_key',
offlineConfig: OfflineConfig(
enabled: true,
geocodeTtl: Duration(hours: 24),
routeTtl: Duration(hours: 1),
reverseTtl: Duration(hours: 6),
smartSearchTtl: Duration(hours: 12),
cleanupOnStartup: true,
),
);

Алгоритм работы

Онлайн-режим

API запрос
↓
ответ сохраняется в кэш
↓
результат возвращается пользователю

Офлайн-режим

проверка кэша
↓
если данные найдены → вернуть
↓
если нет → OfflineException

Пример


final client = QorviaMapsSDK.instance.offlineClient;

final result = await client.geocode(
query: 'Москва, Красная площадь',
language: 'ru',
);

Результат автоматически сохранится в кэш.

2. Управление офлайн-картами

Офлайн-карты позволяют отображать карту без подключения к интернету.

SDK использует нативный механизм MapLibre (downloadOfflineRegion), который:

  1. скачивает тайлы напрямую с tile-сервера
  2. сохраняет их в mbgl-offline.db
  3. автоматически использует их при отсутствии сети

Архитектура загрузки тайлов

Flutter App
│
▼
OfflineTileManager
│
▼
MapLibre GL Native
│
▼
mbgl-offline.db

Поток скачивания

1 пользователь выбирает регион
│
▼
2 downloadRegionNative()
│
▼
3 запись в SDK базе (status=downloading)
│
▼
4 MapLibre downloadOfflineRegion()
│
▼
5 загрузка тайлов
│
▼
6 status = completed

API Reference

OfflineTileManager

Основной класс управления офлайн-картами.

downloadRegionNative

Скачивает регион карты.


Future<maplibre.OfflineRegion> downloadRegionNative({
required String styleUrl,
required OfflineBounds bounds,
required int minZoom,
required int maxZoom,
String? regionName,
void Function(double progress)? onProgress,
})

Пример использования


final tileManager = QorviaMapsSDK.offlineManager;
final styleUrl = await QorviaMapsSDK.instance.getTileUrl();

await tileManager.downloadRegionNative(
styleUrl: styleUrl,
bounds: OfflineBounds.fromCoordinates(
swLat: 55.5,
swLon: 37.3,
neLat: 55.9,
neLon: 37.9,
),
minZoom: 10,
maxZoom: 16,
regionName: "Москва",
);

getAllRegions


Future<List<OfflineRegion>> getAllRegions()

Возвращает список скачанных регионов.

deleteRegion


Future<void> deleteRegion(String regionId)

Удаляет регион и связанные данные.

resetNativeDatabase

Используется при повреждении базы MapLibre.


Future<bool> resetNativeDatabase()

OfflineRegion


class OfflineRegion {
final String id;
final String name;
final OfflineBounds bounds;
final double minZoom;
final double maxZoom;
final OfflineRegionStatus status;
final int sizeBytes;
}

OfflineRegionStatus


enum OfflineRegionStatus {
pending,
downloading,
paused,
completed,
failed
}

3. Мониторинг сети

SDK автоматически отслеживает состояние сети.


final connectivity = ConnectivityService.instance;

connectivity.statusStream.listen((status) {
if (status == NetworkStatus.offline) {
print("offline mode");
}
});

Поддерживаемые типы подключения:

  1. WiFi
  2. Mobile data
  3. Ethernet
  4. VPN
  5. Bluetooth

Хранение данных

SDK использует две базы данных.

app_directory/

mbgl-offline.db
└ MapLibre offline tiles

qorvia_cache.db
└ API cache

Таблицы кэша

ТаблицаНазначение
GeocodeCacheTableгеокодирование
ReverseCacheTablereverse
RouteCacheTableмаршруты
SmartSearchCacheTableпоиск
OfflineRegionTableрегионы

Примеры интеграции

Инициализация SDK


await QorviaMapsSDK.init(
apiKey: 'API_KEY',
offlineConfig: OfflineConfig(
enabled: true,
maxCacheSize: 500 * 1024 * 1024,
),
);

Минимальный экран офлайн карт


class OfflineMapsScreen extends StatefulWidget {
@override
State createState() => _OfflineMapsScreenState();
}

class _OfflineMapsScreenState extends State<OfflineMapsScreen> {

final manager = QorviaMapsSDK.offlineManager;

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text("Offline maps")),
body: ElevatedButton(
onPressed: () async {

final style = await QorviaMapsSDK.instance.getTileUrl();

await manager.downloadRegionNative(
styleUrl: style,
bounds: OfflineBounds.fromCoordinates(
swLat: 55.5,
swLon: 37.3,
neLat: 55.9,
neLon: 37.9,
),
minZoom: 10,
maxZoom: 16,
regionName: "Москва",
);
},
child: Text("Download region"),
),
);
}
}

Офлайн-навигация

Чтобы навигация работала офлайн, необходимо заранее:

  1. скачать тайлы региона
  2. построить маршрут
  3. закэшировать точки поиска

final route = await client.route(from: a, to: b);

await tileManager.downloadRegion(region.id).last;

Navigator.push(
context,
MaterialPageRoute(
builder: (_) => NavigationScreen(route: route),
),
);

Ограничения офлайн режима

ФункцияОнлайнОфлайн
Карта✓✓
Навигация✓✓
Voice guidance✓✓
Перестроение маршрута✓✗
Поиск новых адресов✓✗

MapLibreNativeHelper

SDK включает встроенный helper для управления базой MapLibre.

Он используется для обхода известной ошибки:

no such table: regions

Проверка базы


final exists = await MapLibreNativeHelper.checkDatabaseExists();

Удаление повреждённой базы


await MapLibreNativeHelper.deleteOfflineDatabase();

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

Рекомендации

Оптимизация загрузки карт

  1. используйте уровни зума 12-16
  2. скачивайте только необходимые регионы
  3. удаляйте устаревшие карты

TTL кэша

Тип данныхРекомендуемый TTL
Маршруты1–2 часа
Геокодинг24–48 часов
Поиск6–12 часов

Заключение

Офлайн-система Qorvia Maps SDK позволяет приложениям работать даже при отсутствии сети.

Она включает:

  1. автоматическое кэширование API
  2. загрузку офлайн-карт
  3. мониторинг сети
  4. поддержку офлайн-навигации
  5. готовые UI-компоненты

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


Теги: #Flutter #Offline Maps #Qorvia MapKit #qorvia_maps_sdk
Q
Qorvia Team
Автор статьи
Поделиться: VK
Недавние статьи
Категории
Попробуйте Qorvia MapKit

Flutter SDK для навигации с голосовыми подсказками. Бесплатный старт.

Начать бесплатно