В наши дни карты являются важной функцией многих веб-приложений. Все больше платформ начинают предлагать услуги, использующие технологию определения местоположения. TomTom позволяет интегрировать функции определения местоположения в ваши веб-приложения с помощью своих комплектов разработки программного обеспечения (SDK) и API-интерфейсов, написав всего несколько строк кода и затрачивая минимум времени на разработку.

TomTom Maps SDK эффективно интегрируется со многими популярными внешними платформами, включая Gatsby, генератор статических веб-сайтов с открытым исходным кодом, который можно использовать для создания прогрессивных веб-приложений, безопасных и оптимизированных для скорости. Объединение TomTom Maps SDK с Gatsby позволяет с легкостью создавать оптимизированные интерактивные карты.

В этом руководстве мы покажем, как интегрировать карты TomTom в сайт Gatsby, используя современные методы React, такие как refs. Мы также увидим, как отображать на карте данные из внешнего источника. Наконец, мы рассмотрим, как строить маршруты к определенным пунктам назначения и из них, которые можно изменять в зависимости от типа перевозимых товаров.

Предпосылки

Чтобы следовать этому руководству, вам необходимо иметь:

  • Базовое понимание React.
  • Node.js установлен на вашем компьютере.
  • Учетная запись разработчика в TomTom и ключ API для авторизации вашего запроса на использование службы.

Настройка нового приложения Gatsby

Чтобы создать новое приложение Gatsby, нам нужен интерфейс командной строки (CLI) Gatsby, установленный на вашем компьютере. Это позволит вам запускать команды для разработки сайтов Gatsby.

Чтобы установить CLI, откройте терминал на своем компьютере и выполните следующую команду. Он устанавливает CLI глобально или обновляет вашу версию до самого последнего выпуска.

npm install -g gatsby-cli

Затем используйте команду cd, чтобы перейти туда, где вы хотите создать свой сайт Gatsby. Например:

cd Desktop

Для создания сайта Gatsby мы будем использовать начальный шаблон Gatsby. Этот готовый шаблон позволяет нам быстро приступить к разработке. В этом уроке мы будем использовать официальный Hello World Starter Гэтсби.

Внутри каталога вашего сайта запустите эту команду (заменив name-of-your-project-here на имя вашего проекта):

npx gatsby new name-of-your-project-here https://github.com/gatsbyjs/gatsby-starter-hello-world

Когда установка будет завершена, вы должны увидеть это сообщение:

Перейдите в каталог, который вы создали для сайта, и запустите gatsby develop, который запустит сервер разработки, на котором вы сможете предварительно просмотреть свой сайт. Вы можете просмотреть его по адресу http://localhost:8000 в веб-браузере. Результат должен выглядеть так:

Добавление карты TomTom

Теперь, когда приложение Gatsby запущено и работает, мы готовы добавить карту TomTom на наш сайт. Во-первых, нам понадобится установленный в нашем проекте TomTom Maps Web SDK.

В терминале в корневом каталоге сайта выполните команду ниже, чтобы установить SDK и его зависимости:

npm install @tomtom-international/web-sdk-maps

После установки SDK пришло время написать код для отображения карты TomTom. Откройте файл index.js в папке src/pages вашего приложения Gatsby. Очистите весь код внутри него и заполните его следующим кодом:

import * as React from "react"
import { useEffect, useRef } from "react"
// TomTom SDK
import * as tt from "@tomtom-international/web-sdk-maps"
import "@tomtom-international/web-sdk-maps/dist/maps.css"

Это импортирует ресурсы, которые нам понадобятся для отображения карты TomTom на сайте React, включая хуки useEffect и useRef React, а также TomTom maps JavaScript SDK и его таблицу стилей по умолчанию.

Далее мы определяем функциональный компонент Home, где будет жить приложение.

export default function Home() {
  const API_KEY = "YOUR_API_KEY"
  const AMSTERDAM = { lon: 4.896029, lat: 52.371807 }
const map = useRef()
const mapContainer = useRef()
useEffect(() => {
    map.current = tt.map({
      key: API_KEY,
      container: mapContainer.current.id,
      center: AMSTERDAM,
      zoom: 10,
      language: "en-GB",
    })
map.current.addControl(new tt.FullscreenControl())
    map.current.addControl(new tt.NavigationControl())
return () => {
      map.current.remove()
    }
    //eslint-disable-next-line
  }, [])
return (
    <div className="">
      <div className="container">
        <nav className="nav">
          <h1> TomTom Maps in Gatsby</h1>
        </nav>
        <div ref={mapContainer} className="map" id="map" />
      </div>
    </div>
  )
}

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

Во-первых, переменные API_KEY и AMSTERDAM хранят значение ключа TomTom API, которое вам понадобится для использования сервиса. Он также включает координаты долготы и широты Амстердама в Нидерландах, нашего примерного местоположения, поэтому карту можно центрировать вокруг него.

Не забудьте заменить YOUR_API_KEY ключом API из вашей учетной записи разработчика TomTom.

Хук useRef определяет переменные map и mapContainer, в которых хранятся ссылки на нашу карту и элемент DOM, в который она встроена. Это необходимо, потому что React работает с так называемым виртуальным DOM, который является виртуальным представлением реального DOM. Мы не можем визуализировать карту TomTom для части виртуального DOM React — нам нужно работать с реальными элементами DOM, доступ к которым можно получить только через ссылки.

Эти переменные определяются как ссылки, а не обычные переменные JavaScript, потому что в React весь компонент перерисовывается всякий раз, когда обновляется переменная, что приводит к потере данных в компоненте. Так как мы не хотим терять эти данные, мы оборачиваем их в refs, чтобы их значение сохранялось между повторными рендерами компонентов, и вы могли обновлять их значения без повторного рендеринга.

Хук useEffect инициирует карту TomTom при загрузке страницы, вызывая функцию tt.map с необходимыми настройками. Эти конфигурации включают наш ключ API, параметр контейнера, который принимает ID HTML-элемента, в который должна быть встроена карта, и параметр центра, который центрирует карту вокруг Амстердама. Обратите внимание, что для инициализации карты TomTom достаточно вызвать функцию!

Наконец, оператор return возвращает HTML для отображения в браузере.

На данном этапе мы успешно добавили карту TomTom на наш сайт Gatsby. Тем не менее, сайт был бы немного мрачным, если бы его просматривали прямо сейчас. Чтобы решить эту проблему, мы создадим новый файл CSS в папке src с именем styles.css. Обратите внимание: если вы хотите назвать свое имя как-то иначе, вам необходимо убедиться, что оно правильно импортировано в ваш компонент React.

Создав файл, мы заполняем его следующими стилями CSS:

* {
  padding: 0;
  margin: 0;
  box-sizing: border-box;
}
.container {
  width: 100vw;
  height: 100vh;
  display: flex;
  flex-direction: column;
  justify-content: space-around;
  align-items: center;
  position: relative;
}
.nav {
  display: flex;
  justify-content: space-around;
  align-items: center;
  width: 100%;
  height: 10%;
  background-color: #000;
  color: #ffffff;
}
.nav h1 {
  padding-top: 0.3125rem;
  padding-bottom: 0.3125rem;
  margin-right: 1rem;
  font-size: 1.25rem;
  text-decoration: none;
  white-space: nowrap;
}
.map {
  width: 100%;
  height: 90%;
}

Теперь импортируйте таблицу стилей в верхней части файла index.js, которая применяет стили, чтобы она выглядела лучше, чем HTML без стилей.

// CSS styles
import "../styles.css"

При работающем сервере разработки сохраните новые изменения и перейдите на localhost:8000 в веб-браузере. Когда страница обновится, она должна выглядеть так:

Добавление маркеров на карту TomTom

TomTom позволяет отображать на карте различную информацию, включая геозоны, навигационные маршруты, изображения и видео. Это также позволяет нам отображать маркеры, которые представляют собой настраиваемые значки, которые добавляют информацию и интерактивность к нашим картам.

Чтобы продемонстрировать, давайте используем маркеры, чтобы показать расположение некоторых ресторанов с самым высоким рейтингом в Амстердаме. В папке src создайте файл JSON с именем store.json и введите следующий код:

[
{
"coordinates": [
4.88427,
52.37243
],
"address": "Reestraat 8, 1016 DN Amsterdam"
},
{
"coordinates": [
4.87631,
52.36366
],
"address": "Eerste Helmersstraat 33, 1054 CZ Amsterdam"
},
{
"coordinates": [
4.94036,
52.36357
],
"address": "Javaplein 23, 1095 CJ Amsterdam"
},
{
"coordinates": [
4.92089,
52.38213
],
"address": "Gedempt Hamerkanaal 201, 1021 KP Amsterdam"
},
{
"coordinates": [
4.91191,
52.36619
],
"address": "Plantage Middenlaan 30A, 1018 DG Amsterdam"
},
{
"coordinates": [
4.87896,
52.37257
],
"address": "Rozengracht 133A, 1016 LV Amsterdam"
}
]

Здесь у нас есть массив объектов, где каждый объект имеет свойство координаты. Эта координата представляет собой массив, в котором хранятся координаты долготы и широты местоположения — здесь ресторана — и его почтовый адрес. Эти координаты получаются из службы нечеткого поиска в TomTom API Explorer, которая возвращает геолокационные данные адреса, такие как координаты долготы и широты и точки интереса (POI).

В верхней части файла index.js под операторами импорта импортируйте файл JSON:

Import stores from "../stores.json"

Теперь, чтобы отобразить маркеры на странице, вставьте приведенный ниже код в хук useEffect прямо над оператором return.

stores.map((store) => {
      const address = store?.address
      const location = store?.coordinates
      return new tt.Marker()
        .setLngLat(location)
        .setPopup(new tt.Popup({ offset: 35 }).setHTML(address))
        .addTo(map.current)
    })

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

  • Получает его адрес и координаты.
  • Создает новый маркер, вызывая класс tt.Marker.
  • Устанавливает этот маркер вокруг географического положения ресторана, передавая координаты долготы и широты ресторана методу setLngLat.
  • Вызывает метод setPopup, который отображает отменяемое всплывающее окно, показывающее адрес ресторана при щелчке маркера.
  • Прикрепляет маркер к карте.

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

При нажатии на маркер отображается всплывающее окно.

Маршрутизация

Среди многих функций, которые TomTom предлагает разработчикам через свои SDK, маршрутизация является одной из самых ценных и простых в реализации. Например, как в приложении для совместного использования водители могут определить наилучшие маршруты до пункта назначения? Или для тех, кто работает в сфере доставки, как они могут оптимизировать свой ежедневный маршрут? В обоих этих случаях жизненно важен доступ к информации о маршруте.

Служба TomTom Calculate Route решает эту проблему с помощью API-интерфейса маршрутизации, который определяет возможные маршруты между двумя точками на основе определенных параметров, таких как тип транспортного средства, груз, который он перевозит, и расчетное время прибытия водителя.

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

Во-первых, нам нужно установить SDK веб-сервисов TomTom, который позволит нам интегрировать сервисы TomTom в наш проект, поскольку они не предлагаются в веб-SDK TomTom Maps.

В терминале в корневом каталоге вашего сайта выполните следующую команду:

npm install @tomtom-international/web-sdk-services

После установки добавьте его в начало файла index.js, чтобы импортировать его.

import * as tts from "@tomtom-international/web-sdk-services"

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

В компоненте Home, чуть выше хука useEffect, где инициализируется карта, объявите функцию createRoute:

function createRoute() { 
    ...
}

Затем внутри функции вставьте следующий объект:

const routeOptions = {
      key: API_KEY,
      locations: [
        [4.87631, 52.36366],
        [4.91191, 52.36619],
      ],
      travelMode: "truck",
      vehicleEngineType: "electric",
      vehicleCommercial: true,
    }

Этот объект содержит конфигурации, которые передаются службе «Рассчитать маршрут», такие как ключ API, который авторизует службу, координаты долготы и широты двух ресторанов, вокруг которых должен быть построен маршрут, тип транспортного средства на маршруте (здесь , грузовик) или тип двигателя транспортного средства.

Под объектом routeOptions вставьте этот код:

tts.services.calculateRoute(routeOptions).then(response => {
      console.log(response.toGeoJson())
      console.log(response)
      var geojson = response.toGeoJson()
      map.current.addLayer({
        id: "route",
        type: "line",
        source: {
          type: "geojson",
          data: geojson,
        },
        paint: {
          "line-color": "#a51414",
          "line-width": 8,
        },
      })
var bounds = new tt.LngLatBounds()
      geojson.features[0].geometry.coordinates.forEach(function (point) {
        bounds.extend(tt.LngLat.convert(point)) // creates a bounding area
      })
      map.current.fitBounds(bounds, {
        duration: 300,
        padding: 50,
        maxZoom: 14,
      }) // zooms the map to the searched route
    })

Здесь функция tts.services.calculateRoute вызывает службу расчета маршрута, передавая объект routeOptions в качестве аргумента. Это создает маршрут, рисует его путь на карте и увеличивает его.

Далее нам нужно иметь возможность вызвать сервис на нашем сайте. Вставьте этот код в HTML, который возвращает компонент Home:

<button
    className="btn"
    onClick={e => {
    e.preventDefault()
        createRoute()
    }}
    >
      calculate route
</button>
Add these CSS styles to the styles.css file:
.btn {
  position: fixed;
  bottom: 4rem;
  left: 50%;
  border-radius: 0.5rem;
  transform: translate(-50%, 0);
  border: none;
  padding: 1.2rem 1rem;
  background: #000;
  color: #fff;
  font-size: 1.3rem;
  cursor: pointer;
}

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

Чтобы доказать, что маршрут между двумя маркерами меняется в зависимости от типа груза, указанного в грузовике, добавьте это свойство в объект routeOptions:

vehicleLoadType: ["otherHazmatHarmfulToWater"]

Это свойство позволяет указать, какой тип товаров находится в транспортном средстве. Передача этого значения в массив сообщает службе расчета маршрута, что грузовик загружен товарами, загрязняющими воду. В результате служба строит другой маршрут, по которому транспортное средство может двигаться, чтобы избежать близости к воде.

Вот результат:

Подведение итогов

В этом руководстве мы создали веб-приложение с помощью Gatsby, которое отображает карту TomTom и строит изменяемый маршрут между двумя местоположениями маркеров с помощью TomTom Maps Web SDK.

Если вы хотите интегрировать такие функции в свое приложение, нет лучшего поставщика технологий определения местоположения, чем TomTom. Зарегистрируйте бесплатную учетную запись разработчика, чтобы интегрировать службы определения местоположения TomTom в свое приложение уже сегодня. Удачного картографирования!

Эта статья изначально была опубликована на страницеdeveloper.tomtom.com/blog.