MapTiler SDK: Карти на JavaScript з надзвичайною потужністю - javascript.org.ua

Опубліковано 5 травня 2023 року

Що таке MapTiler SDK?

MapTiler створює комплексну екосистему картографії для бізнесу, включаючи передові інструменти для обробки даних, такі як Desktop/Engine, послуги зберігання та обробки даних, плагіни для QGIS, сервіси геокодування та геолокації, JavaScript бібліотеки, інструменти для стилізації карт та інше. До цього часу ми в основному покладалися на спільноту з відкритим вихідним кодом і MapLibre для відображення карт у вебі. Хоча це продовжуватиметься, ми виводимо це на новий рівень, створюючи власний SDK для кращої інтеграції наших карт з вашим вебсайтом. MapTiler SDK — це новий SDK для JavaScript та TypeScript, адаптований для MapTiler Cloud.

Код та приклад

MapTiler SDK

У цій статті ми детальніше розглянемо наш новий SDK, зокрема його цільову аудиторію, структуру, основні функції, як почати користуватися та наші плани на майбутнє.

Чому ми створили власний SDK?

Перш ніж розпочати розробку SDK, ми провели безліч внутрішніх обговорень щодо його створення: чи повинні ми будувати абсолютно нове рішення з нуля, чи базуватися на існуючому? Якщо так, то яке рішення найбільш підходить?

З бізнесової точки зору ми хотіли рішення, яке не вимагало б рік для розробки, адже основна функція SDK — полегшити реалізацію інших ідей (як наших, так і ваших). На той момент у нас вже були проекти, які добре інтегрувались би з SDK. Швидко стало зрозуміло, що MapLibre GL — ідеальний кандидат. Він швидкий, добре підтримується, і ми та наша спільнота вже знайомі з ним, що робило його ідеальною основою для нашого проєкту!

Тепер ви можете запитати: “Чому не внести безпосередній вклад у MapLibre?” — Ось дві основні причини:

Ми хочемо, щоб наш SDK був повністю інтегрований з нашими даними та послугами для забезпечення безперешкодного процесу розробки. Було б недоречно для MapLibre, проекту, який підтримується спільнотою, бути сильно прив'язаним до конкретного постачальника даних.
Як бізнес, у MapTiler є свій власний план випусків продуктів. Ми маємо функції, які хочемо випустити раніше, і не хочемо порушувати чи впливати на розвиток MapLibre, керуючись нашим графіком випусків.

Щодо другого пункту, наш SDK випущений під ліцензією з відкритим кодом (BSD-3), тому деякі його компоненти можуть бути передані до MapLibre в найближчому майбутньому.

Ще одне питання, яке ми передбачили: “Якщо я зберігаю свої дані (наприклад, плитки, GeoJSON файли тощо) на власному сервері або на сервері іншого постачальника даних, чи буде працювати MapTiler SDK?” — Так, ви без проблем можете продовжувати використовувати свої дані!

З самого початку ми переконалися, що наш SDK, навіть якщо базується на MapLibre, буде повністю сумісним з MapLibre. Наш SDK додає ярлики та функції, але вам не обов'язково їх використовувати. Тож не бійтеся використовувати свої дані з кастомного сервера або з іншого джерела — це залежить лише від вас!

Останній момент, який слід розглянути перед тим, як перейти до деталей нашого SDK, — це еволюція MapLibre. Ми плануємо активно підтримувати SDK, і він буде адаптований та розвиватися разом з майбутніми версіями MapLibre, використовуючи його нововведення.

Тепер давайте перейдемо до деталей!

Створення вашої першої карти з MapTiler SDK

Якщо ви вже знайомі з MapLibre, навчальна крива для нашого SDK буде майже рівною!

Перш за все: вам потрібно отримати API-ключ.
Це легко, і безкоштовний тариф досить щедрий, тож створіть акаунт у MapTiler Cloud і потім перейдіть до розділу API, щоб отримати ваш ключ.

Далі, щоб встановити та використовувати SDK у вашому JS/TS проекті, у вас є два варіанти:














         ```  (Ви також можете знайти [цей приклад](https://docs.maptiler.com/sdk-js/examples/how-to-use/) та багато інших на [сторінках документації SDK](https://docs.maptiler.com/sdk-js/))  ``` npm install --save @maptiler/sdk ```  Далі, на одній зі сторінок фронтенду або у компоненті React імпортуйте ці елементи з SDK:  ``` import { Map, MapStyle, config } from '@maptiler/sdk';       // Встановіть ваш API ключ для MapTiler Cloud    config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';       const map = new Map({     container: 'map', // ID HTML елемента контейнера або React ref     style: MapStyle.STREETS, // Виберіть один із вбудованих стилів     center: [16.62662018, 49.2125578], // координати [довгота, широта]     zoom: 14,    }); ```  Як ви можете помітити, це дуже схоже на ініціалізацію MapLibre. Головна різниця тут — це спосіб, яким ви встановлюєте API токен (який раніше був частиною URL стилю) та `style`, який тепер є автозаповненим значенням серед великої кількості вбудованих стилів.  

## Ідеальний партнер для стеку даних MapTiler

MapTiler — це потужний виробник даних! Багато шарів даних розробляються в компанії, і наша команда з геоданих завжди зайнята! Я маю на увазі MapTiler Planet, Геокодування, Океан, кастомний 3D рельєф та багато іншого (подивіться на інші статті в цьому [розділі новин](https://www.maptiler.com/news/))! Ми також активно будуємо партнерства з великими гравцями, щоб надавати чудові дані нашим користувачам; було б шкода, якби ці дані не могли безперешкодно потрапляти до продуктів наших клієнтів. 

Одна з основних функцій нашого SDK — це безпроблемний доступ до даних!

**Ось що ви отримуєте з безкоштовним акаунтом MapTiler Cloud:**

- всі преміум стилі та плитки, які підтримуються нашими картографами
- інструмент для створення власних стилів з нуля або шляхом клонування існуючих
- сервіс хостингу для ваших геоданих (.geojson, .gpx, .kml, .shp, .zip shapefile), збережених як geojson
- сервіс для використання ваших даних (REST API та клієнтська TypeScript бібліотека)
- сервіс геокодування (REST API та клієнтська TypeScript бібліотека)
- сервіс IP геолокації (REST API та клієнтська TypeScript бібліотека)
- безліч навчальних посібників для початку та для виконання більш складних картографічних задач!
- щедрі квоти, яких більш ніж достатньо для ваших побічних проєктів!

## Легке створення стилів карт

Створення дизайну карти — це не проста задача, особливо коли карта повинна чітко передавати наміри та одночасно мінімізувати візуальний хаос.
Але ми подбали про вас!

Команда картографів та дизайнерів MapTiler постійно створює нові стилі для різних цілей: орієнтовані на вулиці, для пішохідних прогулянок і лижних трас, для візуалізації даних, орієнтовані на океан і багато іншого! Тепер ми підтримуємо великий список стилів, кожен з яких має свої унікальні характеристики та застосування.

Щоб зробити ці стилі легкими для впровадження у ваші проєкти, ми вирішили створити скорочення, які автоматично доповнюються описами при використанні TypeScript. Давайте подивимося, як це працює:

import { Map, MapStyle } from '@maptiler/sdk';

this.map = new Map({
container: someDiv,
style: MapStyle.DATAVIZ.DARK,
})
```

Тепер параметр style у конструкторі Map є необов'язковим (хоча в MapLibre він був обов'язковим), і якщо він не наданий, буде використовуватися наш стиль streets-v2 (скорочення: MapStyle.STREETS).

Ось переваги використання скорочень замість URL стилю:

не потрібно пам'ятати URL, скорочення автоматично доповнюються
не потрібно знати, яка остання версія, використовується найновіша (streets-v2? чи, можливо, v3?)
не потрібно додавати API ключ
варіанти стилів легше знаходити

Ось як автодоповнення виглядає у VSCode з проектом на TypeScript:

Автодоповнення, яке показує всі стилі

Автодоповнення, яке показує всі варіанти для даного стилю. Однак, оскільки MapTiler SDK повністю сумісний із MapLibre, ви все одно можете використовувати URL або опис стилю в об'єкті.

Слово про варіанти стилів: якщо ви введете MapStyle.DATAVIZ у VSCode, ви побачите автодоповнення з наступними варіантами:

MapStyle.DATAVIZ.DEFAULT: мінімалістичний стиль з невеликим дотиком кольору, еквівалентний використанню MapStyle.DATAVIZ
MapStyle.DATAVIZ.LIGHT: світло-сірий мінімалістичний варіант
MapStyle.DATAVIZ.DARK: темний мінімалістичний варіант

Більшість стилів мають кілька варіантів, і всі варіанти в межах одного стилю відображають ті самі дані; лише змінюється кольорова схема. Варіанти також існують для різних стилів, наприклад, для стилю DATAVIZ існує варіант у режимі DARK, так само як і для стилів STREETS, BRIGHT, BASIC тощо.

Ось чотири з наших найпопулярніших стилів:

Рельєф, зроблений ще простішим!

Одна з переваг відображення карт за допомогою WebGL — це можливість використовувати його можливості для рендерингу 3D елементів, таких як гори. Дивно, але незважаючи на те, що 3D рельєф був доступний деякий час, він ніколи не був надто простим для включення. Зазвичай це вимагало додавання джерела з URL плиток рельєфу, а потім включення цього джерела в карту дуже специфічним способом. Якщо ви хочете змінити перебільшення, вам доведеться повторити частину цього процесу, що може бути доволі обтяжливим.

У MapTiler ми володіємо та надаємо дані про рельєф, що дозволяє нам запропонувати прямий доступ і значно спростити використання 3D рельєфу! Ви можете увімкнути 3D рельєф безпосередньо під час ініціалізації Map:

const map = new Map({   
 container: someDiv,   
 style: MapStyle.OUTDOOR,   
 terrain: true, // НЕОБОВ'ЯЗКОВО. За замовчуванням це false   
 terrainExaggeration: 1.5, // НЕОБОВ'ЯЗКОВО. За замовчуванням це 1   
})

або пізніше, після ініціалізації карти:

// Без параметра коефіцієнт перебільшення дорівнює 1   
map.enableTerrain();   

// Або з коефіцієнтом перебільшення більшим за 1, щоб зробити гори ще більшими   
map.enableTerrain(1.5);

Щоб вимкнути рельєф і припинити отримання плиток рельєфу за лаштунками, просто використовуйте map.disableTerrain().

Гра з перебільшенням рельєфу на MapStyle.WINTER

За межами даних

Основний принцип дизайну для нас — це инкапсуляція складності, щоб вам не доводилося. Це включає створення прямих мостів до нашого стеку даних, як було згадано раніше, та більше.
У наступному розділі ви знайдете додаткові приклади того, як ми дотримуємось цього принципу.

Для простішого (розробницького) життя

Тепер ми знаємо, що є прямий доступ до стека даних MapTiler Cloud, що робить простим розблокування стилів та рельєфу. Однак є й інші допоміжні функції, тож давайте розглянемо їх детальніше:

геолокація: вкажіть geolocate: true (за замовчуванням: false) у конструкторі Map, і карта буде центрована на місцезнаходження користувача. За лаштунками це використовує IP-геолокаційне API MapTiler Cloud. Зверніть увагу, що це менш точно, ніж GPS, але також не потребує доступу до API геолокації браузера, тож це не порушує потік.
мова: за замовчуванням у SDK екземпляри карти будуть використовувати налаштування браузера для вибору мови користувача. Це можна змінити, вказавши параметр конструктора Map language: Language.ENGLISH або будь-яку іншу з 78 вбудованих мовних скорочень. Після створення карти ви також можете використовувати новий метод map.setLanguage(Language.SPANISH) для оновлення мови.
управління елементами: історично управління елементами було ще одним джерелом тертя, і більшість часу їх потрібно було ініціалізувати, а потім додавати до карти в колбеку події “load”. Для SDK ми вирішили спростити це і зробити всі класичні елементи управління доступними безпосередньо з конструктора. Для кожного елемента можна вказати true / false та позицію, наприклад, top-left або bottom-right. Ось список параметрів конструктора Map:
navigationControl (за замовчуванням: true, показується в top-right) показує кнопки для масштабування/повертання/орієнтації
terrainControl (за замовчуванням: false, показується в top-right, коли true) показує кнопку для перемикання 3D рельєфу
geolocateControl (за замовчуванням: true, показується в top-right) показує кнопку для геолокації користувача за допомогою API геолокації браузера (найімовірніше GPS)
scaleControl (за замовчуванням: false, показується в bottom-right, коли true) показує масштабну лінійку
fullscreenControl (за замовчуванням: false, показується в top-right, коли true) показує кнопку для перемикання на повний екран
геокодування: SDK MapTiler включає бібліотеку TypeScript MapTiler Cloud API Client і також надає доступ до неї. Це означає, що ми можемо легко використовувати такі функції, як геокодування, ось так: geocoding.forward("paris")

Яка перевага перед… визнаєтещо?

Мета SDK MapTiler разом із нашими даними — зменшити криву навчання, надаючи чудовий стартовий набір, і ми сподіваємося, що це зробить інтерактивні карти більш доступними, щоб більше людей могло показувати свої дані світу.
Втім, є кілька популярних альтернатив, які ви можете розглянути, і вони всі популярні з певної причини. Але давайте спробуємо побачити, як SDK виглядає в порівняльній таблиці:

Потрібна підтримка?

SDK постачається з детальною документацією та численними прикладами, що є чудовою відправною точкою! Якщо ви використовуєте такі функції, як геокодування, IP-геолокація або отримання даних з MapTiler Cloud, пам'ятайте, що SDK включає бібліотеку API Client, яка також має дуже гарну документацію!

Ми також хочемо врахувати ваші відгуки щодо SDK!

Ви помітили якісь проблеми?
Хотіли б ви побачити нову функцію?

Будь ласка, дайте нам знати безпосередньо через GitHub Issues, і ми зробимо все можливе, щоб відповісти швидко!

Останні слова

Підсумовуючи, наша мета — зменшити складність і зробити створення вражаючих карт і візуалізацій географічних даних легким навіть для початківців-розробників!

Методи для досягнення цього можуть здатися простими і в основному включають:

Скорочення відстані між вами і потрібними даними
Перетворення найбільш поширених будівельних блоків у однорядкові функції
Включення зручних налаштувань за замовчуванням
Надання корисної документації як в Інтернеті, так і безпосередньо в редакторі коду

З досвіду ми розуміємо, що інкапсуляція складності може бути часозатратною справою і часто вимагає серйозних інженерних зусиль, але саме в цьому напрямку ми хочемо рухати наш SDK!

Знайдіть MapTiler SDK

Будь ласка, спробуйте самі; це open-source (BSD-3), і пам'ятайте, що MapTiler Cloud має дуже щедрий безкоштовний тариф, який постачає свіжі стилі карт і тайлсети!

Ось кілька посилань, які можуть вас зацікавити:
Основна сторінка MapTiler SDK Main page

Документація API
Офіційні приклади
На GitHub
На NPM
Основна сторінка бібліотеки MapTiler Client (не потрібно її встановлювати, вона включена в SDK)

Ми не можемо дочекатися, щоб побачити, що ви створите з нашим новим SDK, тож будь ласка, повідомте нас у Twitter @maptiler !

Майбутнє MapTiler SDK

Концепція «екосистеми» — це те, чому ми надаємо великого значення. Кожного разу, коли ми маємо ідею для нової функції, ми завжди ставимо собі питання: «Чи повинна це бути частина SDK?» Відповіді немає універсальної; інколи це «так», і ми реалізуємо це або додаємо до нашого дорожнього плану, а інколи — «ні». Отже, що ж далі? Ми вирішили розробляти «модулі», які безшовно працюють з нашим SDK, дозволяють легкий доступ до даних без додаткової складності та вводять нові функції у вашому додатку. У певному сенсі, модулі — це як пакети-ускорювачі!

Підсумовуючи, SDK тільки на початку свого шляху! Ми продовжуватимемо додавати нові функції, безпосередньо пов’язані як з даними MapTiler, так і зі спрощенням деяких компонентів MapLibre, щоб ще більше зменшити тертя між розробниками і їх наступним додатком!

Ми в MapTiler теж є розробниками, і, як і всі, ми цінуємо простоту.
Кожного разу, коли ми стикаємося з якимось дивним моментом і змушені занурюватися в глибини StackOverflow або вихідний код бібліотеки, щоб зрозуміти, чому щось не працює як очікувалося, ми бачимо можливість зробити все більш зрозумілим! Візьмемо, наприклад, шари MapLibre: деякі з них дуже хороші та настроювані, але не завжди легко налаштовуються, правда? Можливо, це те, з чим варто попрацювати в наступній версії MapTiler SDK!

А поки що, до зустрічі!