Навигационные виджеты

CesiumJS включает набор встроенных интерфейсных компонентов, предназначенных для управления сценой, режимами отображения и навигацией по виртуальному глобусу. Эти элементы интегрируются в объект Viewer и формируют слой управления поверх WebGL-сцены.

Навигационные виджеты в CesiumJS разделяются на несколько функциональных категорий:

  • управление положением камеры
  • переключение режимов сцены
  • работа с базовыми слоями карты
  • вспомогательные панели навигации
  • системные UI-элементы управления окном

Каждый компонент реализуется как отдельный модуль, но в стандартной конфигурации они создаются автоматически через Viewer.

Viewer как контейнер навигационных компонентов

Основная точка входа интерфейса CesiumJS — объект Viewer. Он инкапсулирует сцену, камеру, источники данных и набор UI-виджетов.

При создании Viewer можно управлять набором включённых навигационных элементов:

const viewer = new Cesium.Viewer("cesiumContainer", {
    homeButton: true,
    sceneModePicker: true,
    baseLayerPicker: true,
    navigationHelpButton: true,
    fullscreenButton: true,
    geocoder: true,
    animation: true,
    timeline: true
});

Каждый параметр отвечает за создание соответствующего виджета. При отключении параметра компонент не инициализируется, что снижает нагрузку на DOM и уменьшает количество обработчиков событий.

HomeButton: управление начальной позицией камеры

Компонент HomeButton обеспечивает возврат камеры к исходному состоянию сцены.

Внутренне он сохраняет состояние камеры при инициализации Viewer и восстанавливает его при активации.

Основные особенности:

  • фиксирует начальный экстент камеры
  • выполняет плавную анимацию перехода
  • взаимодействует с Camera.flyHome()

Поведение можно переопределить через событие:

viewer.homeButton.viewModel.command.beforeExecute.addEventListener(function (commandInfo) {
    commandInfo.cancel = true;
    viewer.camera.flyTo({
        destination: Cesium.Cartesian3.fromDegrees(0, 0, 20000000)
    });
});

Это позволяет полностью заменить стандартную логику возврата.

SceneModePicker: переключение режимов отображения

SceneModePicker управляет режимами визуализации сцены:

  • 3D Globe
  • 2D Map
  • Columbus View

Каждый режим соответствует внутреннему состоянию SceneMode:

  • Cesium.SceneMode.SCENE3D
  • Cesium.SceneMode.SCENE2D
  • Cesium.SceneMode.COLUMBUS_VIEW

Переключение сопровождается трансформацией матриц проекции и пересчётом камеры.

viewer.scene.morphTo2D();
viewer.scene.morphTo3D();
viewer.scene.morphToColumbusView();

Виджет синхронизируется с состоянием сцены через SceneModePickerViewModel.

BaseLayerPicker: управление подложками

BaseLayerPicker предоставляет интерфейс выбора базового слоя карты и глобуса.

Он работает с источниками изображений (imagery providers) и terrain providers.

Пример источников:

  • Cesium.IonImageryProvider
  • OpenStreetMapImageryProvider
  • ArcGisMapServerImageryProvider

Структура конфигурации:

const viewer = new Cesium.Viewer("cesiumContainer", {
    baseLayerPicker: true,
    imageryProviderViewModels: [
        new Cesium.ProviderViewModel({
            name: "OSM",
            iconUrl: "osm.png",
            creationFunction: () => new Cesium.OpenStreetMapImageryProvider()
        })
    ],
    terrainProviderViewModels: []
});

Каждый ProviderViewModel описывает источник данных и его отображение в UI.

NavigationHelpButton отображает панель с подсказками по управлению камерой и сценой.

Он включает информацию о:

  • вращении глобуса
  • масштабировании
  • перемещении камеры
  • жестах мыши и сенсорного ввода

Внутри реализован как всплывающий overlay с HTML-шаблоном, синхронизированным с событиями ScreenSpaceEventHandler.

FullscreenButton: управление полноэкранным режимом

FullscreenButton обеспечивает переключение контейнера CesiumJS в полноэкранный режим браузера.

Используется стандартный Fullscreen API:

  • requestFullscreen
  • exitFullscreen

Особенности реализации:

  • автоматическое определение контейнера Viewer
  • обработка несовместимых браузеров
  • синхронизация состояния кнопки с document.fullscreenElement
viewer.fullscreenButton.viewModel.command.afterExecute.addEventListener(() => {
    console.log("Fullscreen toggled");
});

Geocoder как навигационный инструмент

Хотя Geocoder относится к поисковым компонентам, он тесно связан с навигацией камеры.

Функциональность:

  • преобразование текстового запроса в координаты
  • центрирование камеры на результате
  • поддержка кастомных geocoder сервисов

Пример использования API:

viewer.geocoder.viewModel.searchText = "London";
viewer.geocoder.viewModel.search();

Результат поиска вызывает Camera.flyTo с рассчитанными координатами.

Animation и Timeline как элементы навигации во времени

CesiumJS включает временные навигационные компоненты:

  • Animation — управление воспроизведением времени
  • Timeline — визуализация временной шкалы

Они взаимодействуют с JulianDate и Clock.

Основные функции:

  • запуск/пауза временного потока
  • ускорение времени
  • перемотка по шкале
  • синхронизация с анимацией объектов сцены
viewer.clock.multiplier = 60;
viewer.clock.shouldAnimate = true;

Timeline отображает диапазон времени, связанный с Clock.startTime и Clock.stopTime.

Компоновка и позиционирование навигационных элементов

UI CesiumJS строится на DOM-структуре, где каждый виджет закреплён в определённой зоне:

  • верхняя панель (toolbar)
  • левая панель инструментов
  • нижняя временная шкала
  • плавающие кнопки поверх canvas

Стилизация осуществляется через классы:

  • .cesium-viewer-toolbar
  • .cesium-viewer-navigationContainer
  • .cesium-widget

Изменение расположения возможно через CSS:

.cesium-viewer-fullscreenContainer {
    position: absolute;
    right: 10px;
    top: 10px;
}

Управление виджетами через API Viewer

Все навигационные компоненты доступны через свойства viewer:

viewer.homeButton
viewer.sceneModePicker
viewer.baseLayerPicker
viewer.navigationHelpButton
viewer.fullscreenButton
viewer.geocoder
viewer.animation
viewer.timeline

Каждый объект содержит viewModel, отвечающий за состояние и команды.

Пример отключения виджета после инициализации:

viewer.homeButton.container.style.display = "none";

Кастомные навигационные элементы

Расширение стандартного интерфейса осуществляется через создание пользовательских DOM-компонентов, синхронизированных с камерой Cesium.Camera.

Типовой сценарий:

  • создание HTML-кнопки
  • привязка обработчика события
  • управление камерой через flyTo, lookAt, setView
const button = document.createElement("button");
button.textContent = "Перейти к точке";

button.oncl ick = () => {
    viewer.camera.flyTo({
        destination: Cesium.Cartesian3.fromDegrees(37.6173, 55.7558, 1000000)
    });
};

Кастомные элементы часто размещаются в cesium-viewer-toolbar.

Взаимодействие виджетов с камерой и сценой

Навигационные компоненты тесно связаны с системой камеры:

  • Camera управляет положением, ориентацией и масштабом
  • Scene обеспечивает рендеринг и режимы отображения
  • Clock синхронизирует временную ось

Любое действие UI преобразуется в операции над камерой:

  • flyTo — анимационный переход
  • setView — мгновенное позиционирование
  • lookAt — привязка к объекту

События камеры позволяют отслеживать изменения:

viewer.camera.changed.addEventListener(() => {
    console.log("Camera updated");
});

Синхронизация состояния UI и сцены

CesiumJS использует модель ViewModel для синхронизации интерфейса и состояния движка.

Каждый навигационный виджет содержит:

  • состояние активности
  • команды (commands)
  • наблюдаемые свойства (Knockout observables)

Это обеспечивает реактивное обновление интерфейса без ручного DOM-обновления.

Управление поведением стандартных контролов

Стандартные контролы могут быть модифицированы через перехват команд:

viewer.sceneModePicker.viewModel.command.beforeExecute.addEventListener((e) => {
    e.cancel = true;
});

Такая архитектура позволяет:

  • заменять стандартные переходы между режимами
  • внедрять ограничения на навигацию
  • интегрировать стороннюю логику управления сценой
Оглавление