В MapLibre GL JS система источников данных построена вокруг реактивной модели загрузки и обновления информации. Каждый источник — будь то векторные тайлы, GeoJSON или растровые данные — генерирует события, отражающие текущее состояние загрузки, обновления и готовности данных к отрисовке. Работа с этими событиями позволяет контролировать жизненный цикл данных, синхронизировать интерфейс и реализовывать сложные сценарии взаимодействия с картой.
Вся система событий, связанных с источниками, основана на едином
событии data, которое эмитится картой при изменении
состояния любых данных. Однако внутри этого события содержится
информация, позволяющая различать конкретные источники и типы
изменений.
Основные категории:
dataloading)data)sourcedata)styledata)Каждое из этих событий отражает разные этапы пайплайна: от запроса тайлов до их готовности к рендерингу.
dataСобытие data является универсальным сигналом о том, что
в карте произошло изменение данных. Оно не привязано строго к одному
источнику, но содержит контекст:
map.on('data', (e) => {
console.log(e.sourceId);
console.log(e.isSourceLoaded);
console.log(e.dataType);
});Событие data может включать:
sourceId — идентификатор источника, который инициировал
событиеdataType — тип данных (source,
style, tile)isSourceLoaded — флаг завершения загрузки
источникаtile — ссылка на тайл (если событие связано с
тайлами)Событие может срабатывать многократно в процессе:
sourcedatasourcedata — ключевое событие для отслеживания состояния
конкретного источника. Оно вызывается каждый раз, когда источник
получает новые данные или изменяет своё состояние загрузки.
map.on('sourcedata', (e) => {
if (e.sourceId === 'cities') {
console.log('Обновление источника cities');
}
});Событие содержит более точную информацию, чем data, и
ориентировано на работу с конкретными источниками.
sourceId — идентификатор источникаisSourceLoaded — индикатор полной загрузки
источникаsource — объект самого источника (в зависимости от
типа)tile — тайл, если событие связано с векторными
тайламиtype — тип события (data)data и sourcedataНесмотря на схожесть, эти события имеют принципиально разную семантику.
datasourcedatadataloadingСрабатывает в момент начала загрузки данных для источника.
map.on('dataloading', (e) => {
console.log('Началась загрузка:', e.sourceId);
});Может вызываться многократно при:
styledataХотя формально не относится напрямую к источникам,
styledata влияет на них, так как стиль определяет:
map.on('styledata', () => {
console.log('Стиль обновлён, источники могли измениться');
});Типичный цикл работы источника можно представить как последовательность событий:
dataloading — старт загрузкиsourcedata — поступление данныхdata — обновление состояния картыsourcedata при догрузке тайловdata с isSourceLoaded: true — завершение
загрузкиВ реальных приложениях карта часто содержит несколько источников:
События позволяют фильтровать поток данных:
map.on('sourcedata', (e) => {
switch (e.sourceId) {
case 'roads':
// обработка дорожной сети
break;
case 'buildings':
// обработка зданий
break;
}
});Наиболее важный сценарий — определение момента полной готовности источника.
map.on('data', (e) => {
if (e.sourceId === 'places' && e.isSourceLoaded) {
console.log('Источник places полностью загружен');
}
});Логика isSourceLoaded учитывает:
Для векторных источников ключевым элементом являются тайлы. События могут содержать ссылку на конкретный тайл:
map.on('sourcedata', (e) => {
if (e.tile) {
console.log('Тайл обновлён:', e.tile.tileID);
}
});При работе с крупными картами важно ограничивать обработку событий только нужными источниками.
map.on('sourcedata', (e) => {
if (e.sourceId !== 'population') return;
// логика только для population
});map.on('data', (e) => {
if (!e.isSourceLoaded) return;
console.log('Источник готов:', e.sourceId);
});События источников часто используются для управления интерфейсом:
map.on('dataloading', (e) => {
showLoader(e.sourceId);
});
map.on('data', (e) => {
if (e.isSourceLoaded) {
hideLoader(e.sourceId);
}
});Каждое изменение viewport вызывает перерасчёт тайлов:
sourcedataПри быстром перемещении карты события могут приходить в большом количестве, поэтому требуется:
Один источник может генерировать несколько событий на один и тот же тайл из-за:
События приходят асинхронно, поэтому:
dataloading может опередить styledatasourcedata может прийти до полной готовности картыСобытия источников являются фундаментом реактивного слоя MapLibre GL JS. На их основе строятся:
Они формируют непрерывный поток состояния, отражающий изменения геоданных в реальном времени без необходимости ручного опроса состояния карты.