Початок роботи з MapLibre GL⚓︎

Вступ⚓︎

MapLibre GL JS — це бібліотека TypeScript, яка використовує WebGL для вбудовування мап. Вона використовує відкриту ліцензію BSD, тому її можна інтегрувати в будь-який сайт без юридичних проблем. Її вихідний код доступний на GitHub.

Тут ми обмежимося невеликим, самостійним прикладом, а для детального ознайомлення зверніться до офіційних навчальних посібників та документації.

Швидкий старт⚓︎

Для показу мапи потрібні три речі: джерело даних, стиль мапи та сайт, на якому все це розміщується. Ми будемо використовувати тайли Shortbread від OpenStreetMap Foundation, стиль Versatiles Colorful та вебсайт, який ви запустите.

Хостинг

Деякі функції вебоглядача вимагають, щоб сторінка обслуговувалася з безпечного місця. Це вебсайт з HTTPS або ваш локальний компʼютер. Ми припускаємо, що у вас є вебхостинг для «example.com», який дозволяє обслуговувати файли з диска, і що ви знаєте, як копіювати файли на вебхостинг.

Встановлення програмного забезпечення⚓︎

Нам потрібна Node.js 18 або пізніша версія. Якщо у вас Ubuntu 24.04 або пізніша версія, або Debian 12 або пізніша версія, ви можете встановити їх за допомогою

sudo apt-get install nodejs

Для інших операційних систем зверніться до їхньої документації. Ви можете перевірити версію Node.js, яку ви маєте, за допомогою команди node --version. Якщо вона нижча за 18, вам потрібно буде встановити власну версію Node. Один зі способів зробити це — за допомогою nvm.

Створення стилю⚓︎

Ми будемо використовувати яскравий стиль VersaTiles, базовий стиль, який використовує тайли Shortbread. Схема векторних тайлів Shortbread — це універсальна схема векторних тайлів для даних OpenStreetMap. Щоб отримати тайли, ми будемо використовувати службу тайлів Shortbread від OpenStreetMap Foundation.

Використання векторних тайлів регулюється політикою використання векторних тайлів. Ця веб-сторінка відповідає вимогам, але не існує SLA або гарантії щодо використання векторних тайлів. Якщо вам це потрібно, ви повинні розмістити їх самостійно або скористатися послугами комерційного хостингу.

Стиль вимагає визначення стилю, файлів спрайтів для будь-яких піктограм та файлів гліфів для будь-яких шрифтів. Ми створимо визначення стилю, яке вказуватиме на наші власні файли спрайтів та гліфів.

Почніть зі створення нової теки для зберігання файлів, які ви будете створювати. У документації ми назвемо її style, але ви можете назвати її як завгодно. У цій теці ми створимо всі необхідні файли та розмістимо їх у підтеці release.

mkdir style
cd style
mkdir release

Створення спрайтів і гліфів може бути складним процесом, але оскільки нам не потрібно їх модифікувати, ми будемо використовувати готові.

curl -OL https://github.com/versatiles-org/versatiles-style/releases/download/v5.7.0/sprites.tar.gz
mkdir -p release/sprites
tar -C release/sprites -xzf sprites.tar.gz

curl -OL https://github.com/versatiles-org/versatiles-fonts/releases/download/v2.0.0/fonts.tar.gz
mkdir -p release/fonts
tar -C release/fonts -xzf fonts.tar.gz

Тепер нам потрібно створити стиль, щоб він використовував нашу нову копію гліфів і спрайтів.

Скопіюйте наступний вміст у файл build.ts, але замініть «example.com» на URL-адресу, з якої ви будете надавати тайли, включаючи ваше доменне імʼя.

build.ts

import { colorful } from "@versatiles/style";
import { writeFileSync } from "node:fs";

const style = colorful({
    baseUrl: "https://example.com",
    glyphs: "/fonts/{fontstack}/{range}.pbf",
    sprite: "/sprites/basics/sprites",
    tiles: ["https://vector.openstreetmap.org/shortbread_v1/{z}/{x}/{y}.mvt"]
});
writeFileSync("release/style.json", JSON.stringify(style));

У тій самій теці встановіть TypeScript і стилі VersaTiles, а потім запустіть вищевказаний скрипт, щоб створити свій стиль..

npm install tsx @versatiles/style@~5.7.0
node_modules/.bin/tsx build.ts

Скопіюйте наступний вміст у файл maplibre.html і помістіть його в теку release.

maplibre.html

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
  <script src='https://unpkg.com/maplibre-gl@5.6/dist/maplibre-gl.js'></script>
  <link href='https://unpkg.com/maplibre-gl@5.6/dist/maplibre-gl.css' rel='stylesheet' />

  <style>
    #map {position: absolute; top: 0; right: 0; bottom: 0; left: 0;}
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
    maplibregl.setRTLTextPlugin(
        'https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.3.0/dist/mapbox-gl-rtl-text.js',
        true // Lazy load the plugin
    );

    const map = new maplibregl.Map({
      style: new URL('style.json', window.location.href).href,
      container: 'map',
      center: [0, 0],
      zoom: 1,
      hash: true,
      maxZoom: 19
    });
  </script>
</body>
</html>

Випуск стилю⚓︎

Скопіюйте вміст теки release у вибране раніше місце, з якого ви будете обслуговувати файли. Зазвичай це робиться за допомогою команди scp або rsync, або через вебінтерфейс.

Поширені проблеми⚓︎

`node_modules/.bin/tsx build.ts` не вдається запустити⚓︎

Якщо у вас застаріла версія node, ця команда не буде працювати. Ви можете виправити це, встановивши оновлену версію за допомогою nvm, як описано раніше.

На вебсторінці нічого не завантажується⚓︎

Відкрийте інструменти розробника у своєму вебоглядачі та подивіться в консоль. Найпоширенішою причиною відсутності відображення є неправильні URL-адреси.