Стрелки

Вы можете добавить на карту анимированные стрелки-указатели с помощью объекта Arrow. Этот объект принимает координаты в виде вектора (набора точек, описывающих путь).

Основное практическое применение стрелок — визуализация входов в здание, информацию о которых можно получить через Places API. В ответе API для каждого входа возвращается поле geometry.vectors, которое содержит направленные отрезки от дороги к точке входа. Эти векторы представлены в формате WKT LINESTRING(startLon startLat, endLon endLat), что соответствует формату координат для Arrow.

Чтобы отобразить входы в здание на карте:

Получите данные о входах через Places API.
Создайте объект Arrow и используйте полученные векторы как координаты для стрелок.
Настройте отображение информации о входе при нажатии на стрелку и другие параметры.

Получение данных о входах

Чтобы получить данные о входах из справочника 2ГИС:

Получите ключ доступа к Places API. Дополнительно свяжитесь с отделом продаж 2ГИС, чтобы получить доступ к полю items.links.database_entrances с информацией о входах.
Отправьте GET-запрос к методу /3.0/items/byid и укажите ID нужного объекта (здания или организации) и параметр fields=items.links.database_entrances для включения данных о входах в ответ:
```
https://catalog.api.2gis.com/3.0/items/byid?id=5348660212691856&fields=items.links.database_entrances&key=YOUR_KEY
```

Ответ будет содержать массив items.links.database_entrances. Каждый элемент массива (отдельный вход) описывается полями:

id — идентификатор входа;
entity_name — отображаемое название входа (например, «2 подъезд»);
entity_number — номер входа;
is_visible_on_map — виден ли вход на карте;
has_poi — есть ли POI для входа;
geometry — геометрические данные входа:
- geometry.points — массив точек входа в формате WKT (POINT(долгота широта));
- geometry.vectors — массив направленных отрезков (векторов) от дороги до точки входа в формате WKT (LINESTRING(startLon startLat, endLon endLat));
- geometry.normals — массив нормалей к зданию в формате WKT.

Полную схему ответа см. в справочнике API.

Пример структуры данных для одного входа:

{
    "entity_name": "2 подъезд",
    "entity_number": "2",
    "geometry": {
        "normals": [
            "LINESTRING(31.339675 59.883814,30.34093 59.93391)"
        ],
        "points": [
            "POINT(30.340930109645146 59.933909825566758)"
        ],
        "vectors": [
            "LINESTRING(30.341108 59.933901,30.34093 59.93391)"
        ]
    },
    "has_poi": true,
    "id": "5349068278782309",
    "is_visible_in_ui": true,
    "is_visible_on_map": true,
    "name": "2"
}

Координаты для отрисовки стрелки содержатся в поле geometry.vectors.

Создание стрелки

Чтобы создать стрелку, создайте объект Arrow и передайте координаты из поля geometry.vectors в виде массива точек [долгота, широта]. Стрелка отрисовывается по заданным точкам, в последней точке располагается наконечник.

// Вектор входа из Places API: LINESTRING(30.341108 59.933901, 30.34093 59.93391)
const arrow = new mapgl.Arrow(map, {
    coordinates: [
        [30.341108, 59.933901],  // Начало вектора (у дороги)
        [30.34093, 59.93391],    // Конец вектора (точка входа), куда указывает наконечник
    ],
    color: '#0085a0',
    width: 4,
    strokeColor: '#ffffff',
    strokeWidth: 1,
    animate: true,
    interactive: true,
});

Основные параметры (полный список см. в ArrowOptions):

Параметр	Тип	По умолчанию	Описание
`coordinates`	`number[][]` \| `number[][][]`	—	Координаты пути стрелки. Наконечник располагается в конце пути.
`color`	`string`	`'#0085a0'`	Цвет заливки в формате HEX.
`strokeColor`	`string`	`'#ffffff'`	Цвет обводки в формате HEX.
`width`	`number`	`4`	Ширина линии в пикселях.
`animate`	`boolean`	`false`	Включение анимации наконечника.
`iterationCount`	`number`	`Infinity`	Количество повторений анимации.
`tipMovementAmplitude`	`number`	`6`	Амплитуда движения наконечника при анимации в пикселях.
`interactive`	`boolean`	`false`	Поддержка событий указателя: клик, наведение и другие.

Несколько стрелок в одном объекте

Если у входа несколько векторов (например, подъезд доступен с разных сторон здания), вы можете передать все пути в один объект Arrow в формате number[][][] (массив массивов точек):

// Вход с двумя векторами: доступ с двух сторон
const arrow = new mapgl.Arrow(map, {
    coordinates: [
        [   // Вектор 1: подход с одной стороны
            [30.340455, 59.933728],
            [30.340498, 59.933815],
        ],
        [   // Вектор 2: подход с другой стороны
            [30.340606, 59.934033],
            [30.340563, 59.933946],
        ],
    ],
    color: '#0085a0',
    animate: true,
});

Стрелка по ломаной

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

const arrow = new mapgl.Arrow(map, {
    coordinates: [
        [30.339214, 59.934282],
        [30.339027, 59.933919],
        [30.339372, 59.933880],
        [30.339603, 59.933883],
        [30.339900, 59.933817],
        [30.340129, 59.933814],
        [30.340350, 59.933809],
    ],
    color: '#d81b60',
    animate: true,
});

Стрелка отрисовывается через все указанные точки. Наконечник всегда располагается в конце пути — у последней точки массива.

Анимация

Объект Arrow поддерживает встроенную анимацию наконечника. Чтобы включить анимацию, установите параметр animate: true:

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    animate: true,
});

Количество повторов анимации задаётся параметром iterationCount:

Infinity (по умолчанию) — бесконечный цикл, наконечник непрерывно пульсирует.
1 — один цикл анимации, затем стрелка останавливается.
Любое положительное число N — анимация повторяется N раз.

Амплитуда движения наконечника настраивается параметром tipMovementAmplitude в пикселях (значение по умолчанию — 6). Чем больше значение, тем заметнее движение:

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    animate: true,
    iterationCount: 3,         // Три цикла анимации
    tipMovementAmplitude: 10,  // Увеличенная амплитуда
});

В готовом примере стрелки входов анимируются бесконечно (iterationCount: Infinity), а ломаная стрелка (путь от соседнего здания) — 3 раза (iterationCount: 3).

Интерактивность

По умолчанию объект Arrow не реагирует на события указателя (interactive: false). Чтобы включить интерактивность, установите параметр interactive: true:

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    interactive: true,
});

Объект Arrow поддерживает все стандартные события для динамических объектов.

Настройка внешнего вида

Цвет и обводка

Основной цвет стрелки задаётся параметром color, цвет обводки — strokeColor. Оба значения указываются в формате HEX (RGB или RGBA):

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    color: '#e65100',       // Цвет заливки
    strokeColor: '#ffffff', // Цвет обводки
    width: 5,               // Ширина линии (пиксели)
    strokeWidth: 2,         // Ширина обводки (пиксели)
});

Параметр roundingRadius задаёт скругление углов в местах изгиба ломаной в пикселях (значение по умолчанию — 2). Рекомендуется подбирать значение пропорционально width.

Размер наконечника

Размеры наконечника стрелки управляются множителями относительно ширины линии (width):

tipWidthMultiplier (по умолчанию 1.5) — множитель ширины наконечника;
tipHeightMultiplier (по умолчанию 2.8) — множитель высоты наконечника.

const arrow = new mapgl.Arrow(map, {
    coordinates: [...],
    width: 6,
    tipWidthMultiplier: 2.0,   // Ширина наконечника — 2× от ширины линии
    tipHeightMultiplier: 3.5,  // Высота наконечника — 3.5× от ширины линии
});

Удаление стрелки

Чтобы удалить стрелку с карты, вызовите метод destroy():

arrow.destroy();

Пример

В примере ниже для каждого входа здания создаётся анимированный объект Arrow. Координаты стрелок берутся из поля geometry.vectors — направленных отрезков от дороги к входу. При нажатии на стрелку отображается попап с названием входа.

Демонстрация с готовыми данными

В примере блок запроса к Places API закомментирован, для иллюстрации используются заранее подготовленные данные о входах.

Получение данных о входах​

Создание стрелки​

Несколько стрелок в одном объекте​

Стрелка по ломаной​

Анимация​

Интерактивность​

Настройка внешнего вида​

Цвет и обводка​

Размер наконечника​

Удаление стрелки​

Пример​