@urubad/earth-globe

Vue 3 + Three.js: интерактивный 3D-глобус Земли (метки, фокус, зум, день/облака).

Возможности

• Текстуры дня, рельеф, вода (по умолчанию с CDN) и слой облаков (PNG в составе пакета)
• Автоповорот, опциональный drag, CSS2D-метки, кастомный слот #item-label
• Фокус на одной точке в items и событие focus-complete
• TypeScript, ESM + CJS

Peer-зависимости: vue ^3.4, three ^0.162 (должны быть в приложении).

Установка

npm install @urubad/earth-globe vue three

import { EarthGlobe } from '@urubad/earth-globe'
import '@urubad/earth-globe/style.css'

Имя earth-globe в npm занято другим пакетом, поэтому используется scoped-имя @urubad/earth-globe.

Быстрый старт

<template>
  <div class="wrap">
    <EarthGlobe :items="cities" />
  </div>
</template>
<script setup lang="ts">
import { EarthGlobe, type EarthGlobeItem } from '@urubad/earth-globe'
import '@urubad/earth-globe/style.css'

const cities: EarthGlobeItem[] = [
  { id: 1, text: 'Москва', lat: 55.75, lng: 37.62, countryCode: 'RU' },
]
</script>
<style scoped>
.wrap {
  width: 100%;
  height: 400px;
}
</style>

• Контейнер обязан иметь ненулевую высоту (и при необходимости ширину).
• Nuxt 3 / SSR: оборачивайте в <ClientOnly> — WebGL только на клиенте.

Поведение items

items	Поведение
[]	Без меток, обычное вращение
1 точка	Фокус и остановка авто-вращения, затем focus-complete
2+	Метки на всех точках, вращение по autoRotate

countryCode (ISO 3166-1 alpha-2) — эмодзи-флаг во встроенной метке, если слот не задан.

Слот item-label

Переопределяет вид метки: параметр { item: EarthGlobeItem }. Без слота — флаг + text. Корневой DOM слота: классы earth-globe-item-label earth-globe-item-label--slot.

API (EarthGlobe)

Prop	Тип	По умолч.	Описание
autoRotate	boolean	true	Автоповорот
rotationSpeed	number	1	Множитель скорости
userRotate	boolean	true	Drag-вращение
showClouds	boolean	true	Слой облаков (если текстура загрузилась)
items	EarthGlobeItem[]	[]	См. таблицу выше
zoom	number	1	0.5…3
offset	{ x, y }	0,0	Смещение кадра
rotationPaused	boolean	false	Внешняя пауза авто-вращения

Событие	Payload
focus-complete	EarthGlobeItem
texture-error	Error

EarthGlobeItem: id, text, lat, lng, опционально countryCode. Экспортируются также EarthGlobeView, типы EarthGlobeViewProps, EarthGlobeItemLabelScope и др. (см. dist/index.d.ts).

EarthGlobeView — низкоуровневый вид (сцена + метки + камера) без логики фокуса из EarthGlobe. Для тонкой настройки смотрите исходник обёртки EarthGlobe.vue в репозитории.

Текстуры и лицензии

• В npm входят JS, CSS, типы и одна текстура (облака clouds.png в бандле). Карта дня, рельеф и вода по умолчанию грузятся с CDN (файлы из пакета three-globe, MIT, Vasco Asturiano). Полностью офлайн — только если подставить свои URL в код/форк.
• Снимки планеты (в т.ч. NASA Blue Marble) — обычно public domain; для продукта полезна атрибуция NASA.

Пакет globe.gl к загрузке текстур здесь не используется.

Производство

Бандл JS крупный — включите Brotli или gzip на CDN/сервере для статики.

Лицензия

MIT. Текстуры с внешних URL — согласно лицензиям и условиям соответствующих источников.

Репозиторий: github.com/UruBad/earth-component