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

Одна метка

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

const label = new mapgl.Label(map, {
    coordinates: [37.615655, 55.768005],
    text: 'Текст метки',
});

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

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

const firstLabel = new mapgl.Label(map, {
    coordinates: [37.577620, 55.778375],
    text: 'Первая метка',
});
const secondLabel = new mapgl.Label(map, {
    coordinates: [37.608676, 55.766095],
    text: 'Вторая метка',
});
const thirdLabel = new mapgl.Label(map, {
    coordinates: [37.650029, 55.773766],
    text: 'Третья метка',
});

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

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

const label = new mapgl.Label(map, {
    coordinates: [37.615655, 55.768005],
    text: 'Первая строка\nВторая строка\nТретья строка',
});

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

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

// Горизонтальный и вертикальный центр (расположение по умолчанию)
const defaultPlacement = new mapgl.Label(map, {
    coordinates: [37.577620, 55.778375],
    text: 'Расположение по умолчанию',
});
// Выравнивание справа по центру
const rightCenterPlacement = new mapgl.Label(map, {
    coordinates: [37.608676, 55.766095],
    text: 'Выравнивание справа по центру',
    relativeAnchor: [0, 0.5],
});
// Выравнивание по левому верхнему краю с отступом
const leftTopPlacement = new mapgl.Label(map, {
    coordinates: [37.660029, 55.773766],
    text: 'Выравнивание по левому верхнему краю с отступом',
    offset: [-10, -10],
    relativeAnchor: [1, 1],
});

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

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

const label = new mapgl.Label(map, {
    coordinates: [37.615655, 55.768005],
    text: 'Текст с обводкой',
    color: '#0000ff',
    haloRadius: 2,
    haloColor: '#00ff0055',
});

Фон текста

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

const label = new mapgl.Label(map, {
    coordinates: [37.615655, 55.768005],
    text: 'Текст с фоном',
    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
});