Navigation

Начало работы

Установи пакеты:

npm i

Types

Базовые типы, используемые в навигации: Coordinates, Point, RoutePart, Route

Пример использования:

import type { Point, Coordinates } from "@balady-tech/navigation"

Contexts

MapContext

Хранит в себе объект map c экземпляром карты, gltf плагина и основные параметры состояния карты. До момента загрузки карты map = undefined.

interface MapContextState {
	map?: {
		instance: Map
		gltfPlugin: GltfPlugin;
		state: MapState
	}
}
interface MapState {
	zoom: number;
	isDragging: boolean;
	floorLevelIndex?: number;
	floorLevelName?: string;
	floorPlanId?: string;
}

Примеры использования:

import { MapProvider } from "@balady-tech/navigation/contexts"

function App() {
	return (
		<MapProvider>
			...
		</MapProvider>
	)
}

import { useMap } from "@balady-tech/navigation/contexts"

function SomeComponent() {
    const { map } = useMap()
}

GeolocationContext

Хранит в себе текущие координаты клиента при включенном отслеживании координат (см. компонент LocationTracker).

interface GeolocationContextState {
	coordinates?: GeolocationCoordinates;
}

Примеры использования:

import { GeolocationProvider } from "@balady-tech/navigation/contexts"

function App() {
	return (
		<GeolocationProvider>
			...
		</GeolocationProvider>
	)
}

import { useGeolocation } from "@balady-tech/navigation/contexts"

function SomeComponent() {
    const { coordinates } = useGeolocation()
}

RoutingApiContext

Используется для передачи в компоненты приложения экземпляра Routing API, созданного при помощи функции createRoutingApi.

Примеры использования:

import { routingApi } from "./routingApi.ts"
import { RoutingApiProvider } from "@balady-tech/navigation/contexts"

function App() {
	return (
		<RoutingApiProvider routingApi={routingApi}>
			...
		</RoutingApiProvider>
	)
}

import { useRoutingApi } from "@balady-tech/navigation/contexts"

function SomeComponent() {
    const { queries, baseUrl } = useRoutingApi()
}

API

Routing API

Для использования Routing API в проекте, необходимо создать его экземпляр:

import { createRoutingApi } from "@balady-tech/navigation/api"

const routingApi = createRoutingApi({ apiKey: "YOUR_API_KEY" })

Get route

Метод, который строит маршрут из точки А в точку Б. Также есть возможность указания промежуточных точек. Подробнее в документации к API.

Пример использования с react-query:

const { data } = useQuery(routingApi.queries.getRoute({ points: [...] }))

Условный запрос маршрута:

const { data } = useQuery({
    ...routingApi.queries.getRoute({ points: [...] }),
    enabled: !someCheck,
    // Также можно переопределять другие параметры хука useQuery (кэшировани и т.д.)
})

Components

MapContainer

Компонент для отрисовки карты. Отрисовывает карту внутри себя и сохраняет инстанс карты в MapContext. Также осуществляет подписку на некоторые события карты (изменение зума, переключение этажей) для обновления соответствующих данных в MapContext. Есть возможность передать URL локально скрипта для работы карт без подключения к сети. Также можно подписаться на событие загрузки карты, чтобы загрузить стили и т.д.

Пример использования с react-query:

import { MapProvider } from "@balady-tech/navigation/contexts"
import { MapContainer } from "@balady-tech/navigation/components"

import { useCallback } from "react"
import type { Map, MapOptions } from "@2gis/mapgl/types"

const API_KEY = "YOUR_API_KEY"
const DEFAULT_OPTIONS: MapOptions = { zoom: 30, center: [37.617734, 55.751999], floorControl: 'centerRight' }

function App() {
	const onLoad = useCallback(({ instance }: { instance: Map }) => {
		// Тут можно загрузить какие-то стили для карты и др.
	}, [])

	return (
		<MapProvider>
			<MapContainer
				className="fixed inset-0"
				apiKey={API_KEY}
				options={DEFAULT_OPTIONS}
				onLoad={onLoad}
			/>
		</MapProvider>
	)
}

export default App

LocationTracker

Компонент, который отслеживает изменение местоположения пользователя и сохраняет его в GeolocationContext. Соответственно, должен использоваться внутри данного контекста. Есть параметры для настройки debounce эффекта, позволяющего регулировать частоту обновления координат в контексте для предотвращения слишком частых перерисовок. На все приложение должно существовать не более одного экземпляра данного компонента. Функционал выполнен в виде компонента для возможности условной отрисовки (отслеживание местоположения пользователя по условию, чтобы запрашивать права на получение местоположения у пользователя только когда это действительно необходимо).

Пример использования:

import { LocationTracker } from "@balady-tech/navigation/components"


function SomeComponent() {
    return {
        <LocationTracker/>
    }
}

Hooks

useChunks

Разбивает массив элементов на несколько массивов указанной длины

useGltfModels

При помощи gltf плагина добавляет указанные модели на карту

usePartnerLogos

Добавляет на карту логотипы партнеров, через проп параметр floorLevelIndexes можно указать на каких этажах логотипы должны отображаться.

Utils

getRouteKey

Создает ключ, которые используется в react-query для запроса Get route

parseLineStringWKT

Парсит строку типа LINESTRING(...) и возвращает массив чисел

toChunks

Разбивает массив на массивы указанной длины. Используется в основе хука useChunks