В Mapbox GL JS текстовые подписи на карте формируются через систему glyphs, основанную на растрово-векторных тайлах шрифтов в формате PBF. Вместо привычных TTF/OTF-файлов движок использует заранее сгенерированные наборы глифов, разбитые по диапазонам Unicode. Это обеспечивает быстрый рендеринг текста в WebGL и стабильную производительность при масштабировании и поворотах карты.
Ключевым элементом является свойство стиля:
"glyphs": "mapbox://fonts/{fontstack}/{range}.pbf"Здесь:
fontstack — имя или набор шрифтов, разделённых
запятойrange — диапазон Unicode-символов (обычно 0–255,
256–511 и т.д.)Каждый тайл содержит набор символов, необходимых для отображения текста в текущем экстенте карты.
Отрисовка текста в слоях управляется свойством
text-font, которое принимает массив строк:
"text-font": ["Open Sans Regular", "Arial Unicode MS Regular"]Каждый элемент массива — это отдельный шрифт. Система работает по принципу fallback: если глиф отсутствует в первом шрифте, он берётся из следующего.
Важно учитывать, что Mapbox GL JS ожидает, что эти шрифты уже существуют в glyphs-источнике, иначе символы будут отображаться как пустые квадраты.
В экосистеме Mapbox используются предустановленные шрифты, доступные через Mapbox Studio и стандартный glyphs endpoint. Наиболее распространённые семейства:
Эти шрифты оптимизированы под SDF (Signed Distance Field) рендеринг, что позволяет сохранять чёткость при любом масштабе.
Для использования собственного шрифта необходимо обеспечить генерацию и публикацию glyphs-тайлов.
Структура endpoint выглядит следующим образом:
https://example.com/fonts/{fontstack}/{range}.pbfПроцесс включает несколько этапов:
Mapbox GL JS будет запрашивать необходимые диапазоны автоматически при рендеринге текста.
Для создания совместимых glyph-тайлов используются специализированные
инструменты, такие как fontnik и утилиты на основе
node-canvas.
Типичный пайплайн включает:
Пример концептуальной генерации:
TTF → SDF atlas → glyph range (0–255) → PBF tilesОсобое значение имеет корректная настройка диапазонов: слишком крупные диапазоны увеличивают размер запросов, слишком мелкие — количество HTTP-запросов.
После публикации glyphs endpoint он указывается в стиле Mapbox GL JS:
const map = new mapboxgl.Map({
container: "map",
style: {
version: 8,
glyphs: "https://example.com/fonts/{fontstack}/{range}.pbf",
sources: {
streets: {
type: "vector",
url: "mapbox://mapbox.mapbox-streets-v8"
}
},
layers: [
{
id: "labels",
type: "symbol",
source: "streets",
"source-layer": "road",
layout: {
"text-field": ["get", "name"],
"text-font": ["Custom Sans Regular"],
"text-size": 14
}
}
]
}
});В данном случае движок будет запрашивать:
https://example.com/fonts/Custom%20Sans%20Regular/0-255.pbf
https://example.com/fonts/Custom%20Sans%20Regular/256-511.pbfMapbox GL JS использует Signed Distance Field (SDF) для текстовых глифов. Это позволяет:
Однако SDF требует предварительной генерации шрифта. Обычные bitmap fonts не подходят, так как не содержат distance field информации.
В экосистеме Mapbox шрифты часто управляются через Mapbox Studio. При загрузке кастомного шрифта:
Стиль после публикации получает доступ к шрифтам через стандартный
mapbox://fonts/ endpoint, без необходимости ручного
хостинга.
Font stack — ключевая концепция при работе с многоязычными картами.
"text-font": [
"Noto Sans Regular",
"Arial Unicode MS Regular"
]Принцип работы:
Это критично при работе с кириллицей, китайским и арабским текстом, где один шрифт редко покрывает весь Unicode диапазон.
При отказе от Mapbox-hosted шрифтов требуется собственный сервер, поддерживающий:
{fontstack}/{range}.pbfРекомендуется использовать CDN-слой, так как количество запросов к glyphs может быть значительным при плотной карте с множеством подписей.
Производительность системы шрифтов напрямую зависит от структуры glyphs:
Дополнительно важно учитывать, что каждый уникальный
fontstack увеличивает количество HTTP-запросов при первом
рендере слоя.
Отсутствие символов Причина: глифы не включены в диапазон или отсутствуют в SDF генерации.
Разрыв текста (tofu boxes) Причина: несоответствие
text-font и доступных glyphs на сервере.
Ошибки загрузки PBF Причина: неверный MIME-type или отсутствие CORS-заголовков.
Несовпадение шрифтов Причина: fontstack в стиле не совпадает с именем, использованным при генерации glyphs.
Низкая производительность Причина: слишком большое количество fontstack или некэшируемые запросы диапазонов.
При изменении масштаба карты Mapbox GL JS не перерисовывает весь текст заново, а использует уже загруженные glyph-atlas. Это возможно благодаря:
Это делает систему шрифтов одной из ключевых причин высокой производительности Mapbox GL JS при работе с большим количеством подписей на карте.