Текстовые метки

Одна метка

Чтобы добавить текстовую метку на карту, нужно указать ее координаты и текст:

const label = new mapgl.Label(map, {
    coordinates: [55.31878, 25.23584],
    text: 'Your label text',
});

Несколько меток

На карту можно добавить несколько текстовых меток:

const firstLabel = new mapgl.Label(map, {
    coordinates: [55.27414, 25.25757],
    text: 'First label',
});
const secondLabel = new mapgl.Label(map, {
    coordinates: [55.28925, 25.21161],
    text: 'Second label',
});
const thirdLabel = new mapgl.Label(map, {
    coordinates: [55.34418, 25.21534],
    text: 'Third label',
});

Многострочный текст

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

const label = new mapgl.Label(map, {
    coordinates: [55.31878, 25.23584],
    text: 'First line\nSecond line\nThird line',
});

Выравнивание текста

По умолчанию текст центрируется относительно указанных координат. Чтобы изменить расположение текста, нужно указать параметры relativeAnchor и offset (см. LabelOptions для подробного описания):

// Горизонтальный и вертикальный центр (расположение по умолчанию)
const defaultPlacement = new mapgl.Label(map, {
    coordinates: [55.32878, 25.23584],
    text: 'Default label placement',
});
// Выравнивание справа по центру
const rightCenterPlacement = new mapgl.Label(map, {
    coordinates: [55.32878, 25.24584],
    text: 'Right center placement',
    relativeAnchor: [0, 0.5],
});
// Выравнивание по левому верхнему краю с отступом
const leftTopPlacement = new mapgl.Label(map, {
    coordinates: [55.30878, 25.22584],
    text: 'Left top placement and offset',
    offset: [-10, -10],
    relativeAnchor: [1, 1],
});

Текст с обводкой

Чтобы добавить обводку для текста, нужно указать параметры haloColor (цвет обводки) и haloRadius (толщина обводки):

const label = new mapgl.Label(map, {
    coordinates: [55.27414, 25.25757],
    text: 'First label',
    color: '#0000ff',
    haloRadius: 2,
    haloColor: '#00ff0055',
});

Фон текста

Чтобы добавить фоновое изображение для текста, нужно указать параметр image. Для фонового изображения можно ограничить области, которые будут растягиваться под размер текста. Для этого используются параметры stretchX (разрешено растягивание по горизонтали) и stretchY (разрешено растягивание по вертикали).

const label = new mapgl.Label(map, {
    coordinates: [55.31878, 25.23584],
    text: 'Label with image',
    fontSize: 64,
    image: {
        url: 'https://docs.2gis.com/img/mapgl/tooltip-big.svg',
        size: [500, 250],
        // Области изображения, которые будут растягиваться горизонтально (синие)
        stretchX: [
            [50, 200], // пиксели между X=50 и X=200 (50 ≤ X ≤ 200)
            [300, 450], // пиксели между X=300 и X=450 (300 ≤ X ≤ 450)
        ],
        // Области изображения, которые будут растягиваться вертикально (красные)
        stretchY: [
            [50, 150], // пиксели между Y=50 и Y=150 (50 ≤ Y ≤ 150)
        ],
        // Отступы вокруг текста (как в CSS)
        padding: [50, 50, 100, 50],
    },
});

Чтобы корректно отобразить на карте несколько текстовых меток с фоновыми изображениями, важно указать для каждой метки параметр zIndex с уникальным значением:

const bottomLabel = new mapgl.Label(map, {
    ...
    zIndex: 1
});
const middleLabel = new mapgl.Label(map, {
    ...
    zIndex: 2
});
const topLabel = new mapgl.Label(map, {
    ...
    zIndex: 3
});