Text-field и text-font

В библиотеке Mapbox GL JS текстовые подписи отображаются при помощи слоёв типа symbol. Внешний вид, содержимое и форматирование текста задаются через свойства блока layout, среди которых центральную роль играют:

  • text-field — определяет текст подписи;
  • text-font — определяет используемый шрифт.

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

Свойство text-field

Свойство text-field отвечает за содержимое текстовой подписи.

Простейший пример:

map.addLayer({
    id: 'cities',
    type: 'symbol',
    source: 'cities',
    layout: {
        'text-field': 'Город'
    }
});

В данном случае каждая метка будет содержать одинаковый текст.

Отображение данных из источника

Чаще всего текст берётся из атрибутов объекта.

Предположим, GeoJSON содержит данные:

{
  "type": "Feature",
  "properties": {
    "name": "Москва"
  }
}

Тогда подпись можно вывести следующим образом:

layout: {
    'text-field': ['get', 'name']
}

Полный пример:

map.addLayer({
    id: 'city-labels',
    type: 'symbol',
    source: 'cities',
    layout: {
        'text-field': ['get', 'name']
    }
});

Для каждого объекта будет отображаться значение свойства name.

Старый и новый синтаксис

Ранее использовалась запись через фигурные скобки:

'text-field': '{name}'

Современный стиль основан на выражениях Mapbox Expressions:

'text-field': ['get', 'name']

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

Объединение нескольких полей

Текст можно формировать из нескольких свойств объекта.

Исходные данные:

{
  "name": "Москва",
  "population": 13000000
}

Формирование подписи:

'text-field': [
    'concat',
    ['get', 'name'],
    ' (',
    ['to-string', ['get', 'population']],
    ')'
]

Результат:

Москва (13000000)

Условный вывод текста

Выражения позволяют динамически изменять подписи.

Например:

'text-field': [
    'case',
    ['>', ['get', 'population'], 1000000],
    'Мегаполис',
    'Город'
]

Результат зависит от значения поля population.

Использование нескольких строк

Текст может содержать переносы строк.

Пример:

'text-field': [
    'concat',
    ['get', 'name'],
    '\n',
    ['get', 'country']
]

Отображение:

Москва
Россия

Многострочные подписи активно применяются при отображении:

  • городов;
  • объектов недвижимости;
  • туристических объектов;
  • транспортных узлов.

Форматирование текста через format

Обычный текст отображается единым стилем. Для создания сложных подписей используется выражение format.

Пример:

'text-field': [
    'format',
    ['get', 'name'],
    {
        'font-scale': 1.3
    },
    '\n',
    {},
    ['get', 'country'],
    {
        'font-scale': 0.8
    }
]

Результат:

  • название города отображается крупнее;
  • страна отображается меньшим размером.

Изменение цвета отдельных фрагментов

Через format можно задавать различные цвета внутри одной подписи.

'text-field': [
    'format',
    'Температура: ',
    {},
    ['get', 'temp'],
    {
        'text-color': '#ff0000'
    }
]

Часть текста будет отображаться красным цветом.

Масштабирование текста внутри text-field

Размер отдельных элементов регулируется параметром font-scale.

Пример:

'text-field': [
    'format',
    'A',
    {
        'font-scale': 2
    },
    'BC',
    {
        'font-scale': 1
    }
]

Буква A будет заметно крупнее остальных символов.

Работа с числами

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

Пример:

'text-field': [
    'to-string',
    ['get', 'population']
]

Без преобразования некоторые выражения могут работать некорректно.

Работа с датами

Даты часто хранятся как строки.

Исходные данные:

{
  "date": "2025-07-01"
}

Вывод:

'text-field': ['get', 'date']

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

Проверка существования поля

Если свойство может отсутствовать, используется оператор coalesce.

'text-field': [
    'coalesce',
    ['get', 'name'],
    'Без названия'
]

Если поле name отсутствует, появится текст:

Без названия

Использование локализации

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

Например:

'text-field': [
    'get',
    'name_ru'
]

или

'text-field': [
    'get',
    'name_en'
]

Также возможно переключение языка через программную логику приложения.

Свойство text-font

Свойство text-font определяет набор шрифтов для отображения текста.

Простейший пример:

layout: {
    'text-font': ['Open Sans Regular']
}

Почему используется массив

Даже если указывается один шрифт, значение записывается в виде массива.

'text-font': ['Open Sans Regular']

Это связано с механизмом резервных шрифтов.

Резервные шрифты

Можно перечислить несколько вариантов:

'text-font': [
    'Open Sans Regular',
    'Arial Unicode MS Regular'
]

Если первый шрифт не содержит нужных символов, будет использован следующий.

Такой подход особенно важен для:

  • кириллицы;
  • китайских символов;
  • японских иероглифов;
  • арабского письма.

Популярные встроенные шрифты

Наиболее распространённые варианты в стилях Mapbox:

'Open Sans Regular'
'Open Sans Bold'
'Open Sans Semibold'
'Arial Unicode MS Regular'

Пример:

'text-font': [
    'Open Sans Bold',
    'Arial Unicode MS Regular'
]

Изменение шрифта слоя

Создание слоя с жирным шрифтом:

map.addLayer({
    id: 'capital-labels',
    type: 'symbol',
    source: 'capitals',
    layout: {
        'text-field': ['get', 'name'],
        'text-font': [
            'Open Sans Bold'
        ]
    }
});

Все подписи слоя будут отображаться жирным начертанием.

Динамический выбор шрифта

Шрифт можно выбирать на основе атрибутов объекта.

Пример:

'text-font': [
    'match',
    ['get', 'type'],
    'capital',
    ['literal', ['Open Sans Bold']],
    ['literal', ['Open Sans Regular']]
]

Столицы будут выделяться более жирным шрифтом.

Использование literal

При возврате массива внутри выражения применяется оператор literal.

Пример:

[
    'literal',
    ['Open Sans Bold']
]

Без него Mapbox попытается интерпретировать массив как выражение.

Совместимость шрифтов со стилем карты

Шрифт должен присутствовать в наборе glyphs используемого стиля.

Если стиль не содержит необходимые ресурсы, текст может:

  • не отображаться;
  • отображаться частично;
  • использовать резервный вариант.

Поэтому выбор шрифтов всегда связан с настройками стиля карты.

Влияние шрифта на производительность

Каждый дополнительный набор символов требует загрузки glyph-данных.

При большом количестве различных шрифтов:

  • увеличивается объём загружаемых ресурсов;
  • растёт потребление памяти;
  • возрастает время первоначальной отрисовки карты.

Практикой считается использование ограниченного набора гарнитур.

Комбинирование text-field и text-font

Чаще всего оба свойства используются совместно.

Пример:

map.addLayer({
    id: 'places',
    type: 'symbol',
    source: 'places',
    layout: {
        'text-field': [
            'concat',
            ['get', 'name'],
            '\n',
            ['get', 'category']
        ],
        'text-font': [
            'Open Sans Semibold',
            'Arial Unicode MS Regular'
        ]
    }
});

Результат:

  • отображается название объекта;
  • ниже выводится категория;
  • используется полужирный шрифт;
  • поддерживаются различные языки.

Практический пример: подписи ресторанов

GeoJSON:

{
  "type": "Feature",
  "properties": {
    "name": "Bella Italia",
    "rating": 4.8
  }
}

Слой:

map.addLayer({
    id: 'restaurants',
    type: 'symbol',
    source: 'restaurants',
    layout: {
        'text-field': [
            'concat',
            ['get', 'name'],
            '\n★ ',
            ['to-string', ['get', 'rating']]
        ],
        'text-font': [
            'Open Sans Bold',
            'Arial Unicode MS Regular'
        ]
    }
});

На карте появится:

Bella Italia
★ 4.8

Практический пример: выделение столиц

map.addLayer({
    id: 'cities',
    type: 'symbol',
    source: 'cities',
    layout: {
        'text-field': ['get', 'name'],
        'text-font': [
            'match',
            ['get', 'capital'],
            true,
            ['literal', ['Open Sans Bold']],
            ['literal', ['Open Sans Regular']]
        ]
    }
});

Столицы визуально отличаются от остальных населённых пунктов.

Типичные ошибки

Использование строки вместо массива для text-font

Неверно:

'text-font': 'Open Sans Regular'

Правильно:

'text-font': ['Open Sans Regular']

Отсутствующее поле в text-field

Неверно:

'text-field': ['get', 'title']

Если поле отсутствует, подпись не появится.

Лучше использовать:

'text-field': [
    'coalesce',
    ['get', 'title'],
    'Нет данных'
]

Использование неподдерживаемого шрифта

Неверно:

'text-font': ['MyCustomFont']

Если шрифт отсутствует в glyph-ресурсах стиля, текст может отображаться некорректно.

Отсутствие резервного шрифта

Нежелательно:

'text-font': ['Open Sans Regular']

Предпочтительно:

'text-font': [
    'Open Sans Regular',
    'Arial Unicode MS Regular'
]

Это обеспечивает корректную работу с различными языками и наборами символов.

Рекомендации по использованию

  • Формировать подписи через выражения, а не через устаревший шаблонный синтаксис.
  • Использовать coalesce для защиты от отсутствующих данных.
  • Добавлять резервные шрифты для международных проектов.
  • Ограничивать количество используемых гарнитур.
  • Применять format для сложных многоуровневых подписей.
  • Использовать переносы строк для повышения читаемости.
  • Выполнять преобразование чисел через to-string.
  • Подбирать шрифты с учётом языков, используемых в приложении.
  • Формировать содержимое text-field максимально близко к структуре исходных данных, избегая чрезмерно сложных выражений.
Оглавление