Загрузка файлов

Работа с загрузкой файлов в Mapbox GL JS строится вокруг концепции источников данных (sources) и ассетов карты, которые подгружаются в виде сетевых ресурсов или локальных файлов. Архитектура движка предполагает асинхронную загрузку любых внешних данных, что позволяет комбинировать геоданные, растровые изображения, тайлы и пользовательские файлы в едином визуальном слое.

Внутренняя модель данных в Mapbox GL JS основана на источниках, подключаемых через map.addSource. Каждый источник определяет способ загрузки и формат данных.

GeoJSON как основной формат файлов

GeoJSON является наиболее часто используемым форматом для загрузки пользовательских файлов:

map.addSource('points', {
  type: 'geojson',
  data: 'https://example.com/data/points.geojson'
});

Возможны два основных сценария:

  1. Удалённая загрузка по URL
  2. Передача уже загруженного объекта
fetch('/data/polygons.geojson')
  .then(r => r.json())
  .then(data => {
    map.addSource('polygons', {
      type: 'geojson',
      data
    });
  });

GeoJSON-источники поддерживают динамическое обновление без пересоздания слоя:

map.getSource('points').setData(newData);

Загрузка локальных файлов через File API

Для работы с пользовательскими файлами используется стандартный браузерный File API.

Чтение GeoJSON из файла

const input = document.querySelector('input[type="file"]');

input.addEventListener('change', (event) => {
  const file = event.target.files[0];

  const reader = new FileReader();

  reader.onl oad = (e) => {
    const geojson = JSON.parse(e.target.result);

    map.addSource('uploaded', {
      type: 'geojson',
      data: geojson
    });
  };

  reader.readAsText(file);
});

Такой подход позволяет интегрировать локальные данные без серверной обработки.

Ограничения локальной загрузки

  • браузерные ограничения безопасности (CORS, sandbox)
  • необходимость валидного JSON
  • ограничение по размеру памяти при больших файлах
  • отсутствие потоковой обработки GeoJSON

Drag & Drop загрузка файлов

Интерактивная загрузка файлов часто реализуется через drag-and-drop интерфейс:

const dropZone = document.getElementById('map');

dropZone.addEventListener('drop', (e) => {
  e.preventDefault();

  const file = e.dataTransfer.files[0];
  const reader = new FileReader();

  reader.onl oad = (event) => {
    const geojson = JSON.parse(event.target.result);

    map.addSource('dropped', {
      type: 'geojson',
      data: geojson
    });
  };

  reader.readAsText(file);
});

dropZone.addEventListener('dragover', (e) => {
  e.preventDefault();
});

Такой механизм часто используется в GIS-инструментах для быстрого импорта данных.

Загрузка растровых изображений

Mapbox GL JS поддерживает работу с пользовательскими изображениями, которые можно добавлять как слои.

Добавление изображения в карту

map.loadImage('/images/icon.png', (error, image) => {
  if (error) throw error;

  map.addImage('custom-icon', image);

  map.addSource('image-source', {
    type: 'geojson',
    data: {
      type: 'FeatureCollection',
      features: [{
        type: 'Feature',
        geometry: {
          type: 'Point',
          coordinates: [30.5, 50.5]
        }
      }]
    }
  });

  map.addLayer({
    id: 'image-layer',
    type: 'symbol',
    source: 'image-source',
    layout: {
      'icon-image': 'custom-icon'
    }
  });
});

Ключевые особенности загрузки изображений

  • изображения кэшируются внутри WebGL контекста
  • поддерживаются PNG и JPEG
  • изображения могут быть динамически заменены через removeImage и addImage

Работа с тайлами (Vector и Raster Tiles)

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

Vector tiles

map.addSource('vector-source', {
  type: 'vector',
  tiles: [
    'https://example.com/tiles/{z}/{x}/{y}.pbf'
  ],
  minzoom: 0,
  maxzoom: 14
});

Raster tiles

map.addSource('raster-source', {
  type: 'raster',
  tiles: [
    'https://example.com/tiles/{z}/{x}/{y}.png'
  ],
  tileSize: 256
});

Особенности загрузки тайлов

  • ленивое подгружение по viewport
  • кэширование на уровне браузера и движка
  • приоритет загрузки по видимой области
  • поддержка прерывания запросов при панорамировании

Blob URL и локальные бинарные данные

При работе с динамически сформированными файлами используется Blob:

const geojsonBlob = new Blob([JSON.stringify(data)], {
  type: 'application/json'
});

const url = URL.createObjectURL(geojsonBlob);

map.addSource('blob-source', {
  type: 'geojson',
  data: url
});

Blob URL позволяет передавать данные как обычный файл без серверной загрузки.

Асинхронная модель загрузки ресурсов

Mapbox GL JS выполняет загрузку файлов через событийную модель:

  • style.load — стиль загружен
  • sourcedata — источник начал или завершил загрузку
  • data — обновление данных
  • error — ошибки загрузки ресурсов
map.on('sourcedata', (e) => {
  if (e.isSourceLoaded) {
    console.log('Источник загружен');
  }
});

Эта модель позволяет отслеживать состояние загрузки каждого файла в реальном времени.

Кэширование и повторное использование данных

Загрузка файлов оптимизируется через внутренний кэш:

  • GeoJSON источники пересчитываются только при изменении данных
  • тайлы повторно используются при возврате в область просмотра
  • изображения хранятся в GPU памяти до удаления слоя
map.removeSource('old-source');

Удаление источника освобождает память и GPU ресурсы.

Загрузка больших файлов и оптимизация

При работе с крупными наборами данных применяются следующие подходы:

Тесселяция GeoJSON

Разбиение данных на более мелкие файлы:

map.addSource('chunks', {
  type: 'geojson',
  data: '/data/chunk-1.geojson'
});

Преобразование в векторные тайлы

  • уменьшение размера передаваемых данных
  • ускорение рендеринга
  • снижение нагрузки на клиент

Фильтрация на сервере

Предварительное сокращение данных до необходимого набора перед загрузкой в карту.

Загрузка стилей и внешних JSON файлов

Стиль карты также является загружаемым файлом JSON:

map.setStyle('mapbox://styles/user/style-id');

или локальный стиль:

map.setStyle('/styles/custom-style.json');

Стиль включает:

  • источники данных
  • слои
  • изображения
  • источники тайлов

Управление порядком загрузки ресурсов

Загрузка файлов в Mapbox GL JS происходит в несколько этапов:

  1. загрузка style.json
  2. загрузка sources
  3. загрузка tiles
  4. загрузка images
  5. отрисовка слоёв

Каждый этап может быть перехвачен через события карты, что позволяет синхронизировать внешние процессы (например, UI индикаторы или прогресс-бары).

Оглавление