CDN использование

CDN (Content Delivery Network) — наиболее простой способ подключения CesiumJS к веб-приложению без установки пакетов через npm и без настройки системы сборки. Все необходимые файлы загружаются напрямую с удалённого сервера, что позволяет быстро развернуть прототип, учебный проект или демонстрационный стенд.

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

Что включает CesiumJS

Для корректной работы движка требуется подключение двух основных ресурсов:

  • JavaScript-файла библиотеки;
  • CSS-файла со стилями интерфейса.

Cesium использует собственные элементы управления, виджеты, панели и контейнеры, поэтому подключение CSS является обязательным.

Базовая структура страницы выглядит следующим образом:

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">
    <title>Cesium CDN Example</title>

    <link
        href="https://cesium.com/downloads/cesiumjs/releases/1.133/Build/Cesium/Widgets/widgets.css"
        rel="stylesheet"
    />

    <style>
        html,
        body,
        #cesiumContainer {
            width: 100%;
            height: 100%;
            margin: 0;
            padding: 0;
            overflow: hidden;
        }
    </style>
</head>
<body>

<div id="cesiumContainer"></div>

<script src="https://cesium.com/downloads/cesiumjs/releases/1.133/Build/Cesium/Cesium.js"></script>

<script>
    const viewer = new Cesium.Viewer("cesiumContainer");
</script>

</body>
</html>

После открытия страницы в браузере появится трёхмерный глобус с базовым набором инструментов навигации.

Структура CDN-ссылок

Обычно ссылка на релиз Cesium имеет следующий формат:

https://cesium.com/downloads/cesiumjs/releases/VERSION/Build/Cesium/

Где:

VERSION

заменяется на номер версии.

Например:

1.133

Тогда пути будут выглядеть так:

<script src="https://cesium.com/downloads/cesiumjs/releases/1.133/Build/Cesium/Cesium.js"></script>

<link
    href="https://cesium.com/downloads/cesiumjs/releases/1.133/Build/Cesium/Widgets/widgets.css"
    rel="stylesheet"
/>

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

Создание контейнера для сцены

Cesium отображает карту внутри HTML-элемента.

Пример:

<div id="map"></div>

Контейнер должен иметь заданные размеры.

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

html,
body,
#map {
    width: 100%;
    height: 100%;
    margin: 0;
}

Инициализация:

const viewer = new Cesium.Viewer("map");

Аргументом передаётся идентификатор DOM-элемента.

Минимальная конфигурация Viewer

По умолчанию Viewer создаёт множество элементов интерфейса:

  • переключатель базовых карт;
  • кнопку домашнего положения камеры;
  • полноэкранный режим;
  • геолокацию;
  • временную шкалу;
  • анимацию;
  • выбор режима отображения.

Для минималистичного интерфейса можно отключить ненужные компоненты:

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

Такой подход уменьшает количество создаваемых DOM-элементов и упрощает интерфейс.

Использование ES-модулей через CDN

Современные браузеры поддерживают подключение JavaScript-модулей напрямую.

Пример:

<script type="module">
    import * as Cesium from "https://cesium.com/downloads/cesiumjs/releases/1.133/Build/Cesium/index.js";

    const viewer = new Cesium.Viewer("map");
</script>

Преимущества:

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

Недостатком является зависимость от поддержки ES Modules браузером.

Проверка успешного подключения

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

Проверка:

console.log(Cesium);

Либо:

console.log(Cesium.VERSION);

Результат:

1.133

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

Настройка Ion Access Token

Большая часть современных возможностей Cesium использует сервис Cesium Ion.

Перед созданием Viewer обычно задаётся токен доступа:

Cesium.Ion.defaultAccessToken =
    "ВАШ_ТОКЕН";

После этого создаётся экземпляр Viewer:

const viewer = new Cesium.Viewer("map");

Полный порядок действий:

Cesium.Ion.defaultAccessToken = "TOKEN";

const viewer = new Cesium.Viewer("map");

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

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

Помимо официального сервера доступны сторонние CDN-провайдеры.

Пример через jsDelivr:

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/cesium@1.133/Build/Cesium/Widgets/widgets.css"
/>

<script src="https://cdn.jsdelivr.net/npm/cesium@1.133/Build/Cesium/Cesium.js"></script>

Преимущества:

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

Асинхронная загрузка скрипта

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

Вариант с defer:

<script
    defer
    src="https://cesium.com/downloads/cesiumjs/releases/1.133/Build/Cesium/Cesium.js">
</script>

После загрузки документа:

<script>
document.addEventListener("DOMContentLoaded", () => {

    const viewer = new Cesium.Viewer("map");

});
</script>

Использование defer позволяет браузеру не блокировать построение DOM во время загрузки библиотеки.

Создание первой сцены после подключения CDN

После успешного подключения можно выполнить простую настройку камеры.

const viewer = new Cesium.Viewer("map");

viewer.camera.flyTo({
    destination: Cesium.Cartesian3.fromDegrees(
        37.6173,
        55.7558,
        15000
    )
});

Камера плавно переместится к координатам Москвы.

Добавление объекта на карту

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

Добавление точки:

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(
        37.6173,
        55.7558
    ),
    point: {
        pixelSize: 10
    }
});

Добавление подписи:

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(
        37.6173,
        55.7558
    ),
    label: {
        text: "Москва"
    }
});

Работа без системы сборки

CDN-подключение позволяет создавать приложения в одном HTML-файле.

Структура может состоять всего из:

index.html

Внутри располагаются:

  • разметка страницы;
  • CSS-стили;
  • подключение Cesium;
  • прикладной JavaScript-код.

Такой подход часто используется для:

  • учебных примеров;
  • демонстраций;
  • быстрых прототипов;
  • экспериментов с API;
  • публикации через GitHub Pages.

Ограничения CDN-подхода

Несмотря на простоту использования, CDN имеет ряд ограничений.

Большой размер библиотеки

Cesium содержит значительный объём кода:

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

Из-за этого время загрузки может быть заметным при медленном соединении.

Отсутствие tree shaking

При CDN-подключении загружается весь пакет.

Даже если используется только часть функциональности, браузер получает полный набор модулей.

Ограниченная оптимизация

Невозможно:

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

Для крупных проектов обычно используются npm, Vite, Webpack или другие современные инструменты сборки.

Практические рекомендации

Для обучения и первых проектов

Использовать официальный CDN и фиксированную версию:

<script src="https://cesium.com/downloads/cesiumjs/releases/1.133/Build/Cesium/Cesium.js"></script>

Для демонстрационных страниц

Подключать библиотеку через jsDelivr или официальный CDN с кешированием браузера.

Для производственных систем

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

Для стабильности

Не использовать ссылки вида:

latest

Лучше явно указывать номер версии:

1.133

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

Оглавление