Open-Source-Paket

jamit-maplibre-viewport

Ein leichtgewichtiger und vollständig typisierter Viewport- und Safe-Area-Manager für MapLibre-GL-JS-Anwendungen mit dynamischen UI-Overlays.

Messe reale UI-Geometrie, halte Viewport-Berechnungen mit sich ändernden Layouts synchron und passe Karteninhalte an den Bereich an, den Benutzer tatsächlich sehen können.

Auf GitHub ansehen Demo ansehen

Überblick

MapLibre-Kamerasteuerung, die deine Benutzeroberfläche versteht

MapLibre GL JS bietet leistungsfähige Kamera-APIs, weiß aber nicht, welche Bereiche der Karte durch die Benutzeroberfläche verdeckt werden. Sidebars, Bottom Sheets und schwebende Detail-Panels können dadurch Marker oder wichtige Karteninhalte verdecken, obwohl die Kamera technisch gesehen in den Kartencontainer passt.

jamit-maplibre-viewport verbindet DOM-Layout-Geometrie mit MapLibre-Kameraoperationen. Registrierte Overlays werden automatisch vermessen, Layoutänderungen beobachtet und Kamera-Helper können mit dem Kartenbereich arbeiten, der für den Benutzer tatsächlich sichtbar bleibt.

Dynamische Overlay-Vermessung

Registriere Sidebars, Bottom Panels und andere UI-Elemente und lasse das Package ihre reale DOM-Geometrie messen, anstatt mit fest codierten Abmessungen zu arbeiten.

Automatische Layout-Beobachtung

ResizeObserver hält die Viewport-Geometrie synchron, wenn registrierte Overlays oder der Kartencontainer ihre Größe ändern.

Hindernisbewusstes Koordinaten-Fitting

fitCoordinates() sucht nach einer Kameraposition und Zoomstufe, bei der alle übergebenen Koordinaten außerhalb registrierter UI-Hindernisse sichtbar bleiben.

Tatsächlich nutzbarer Kartenbereich

Partielle Overlays blockieren nur den Bereich, den sie wirklich belegen. Freier Platz neben einem Panel kann weiterhin für Karteninhalte genutzt werden.

Safe-Area-Berechnung

Lies das aktuell verfügbare Viewport-Padding und die Safe Area über eine vollständig typisierte API aus.

MapLibre-Kamera-Helper

Nutze viewport-aware fitBounds(), fitCoordinates(), flyTo() und easeTo(), ohne UI-Abmessungen manuell mit MapLibre synchronisieren zu müssen.

Zusätzliches Sicherheits-Padding

Füge konfigurierbaren Abstand zu Kartenrändern und registrierten Hindernissen hinzu, damit Marker und andere wichtige Inhalte nicht direkt an UI-Elementen liegen.

Framework-unabhängig

Das Package arbeitet direkt mit MapLibre und Standard-DOM-APIs und benötigt weder Vue, Nuxt, React noch ein anderes Frontend-Framework.

SSR-sichere Architektur

Importiere das Package sicher in SSR-Umgebungen. Browser-Globals werden erst verwendet, wenn tatsächlich mit Karten- und Overlay-Elementen gearbeitet wird.

Dynamisches OverlayUnteres Panel

Veraendere die Groesse dieses Panels und fuehre Koordinaten einpassen erneut aus.

Kanteunten

Aktuelle Hoehe0 px

LIVE MAPLIBRE VIEWPORT DEMO

Blende die Sidebar ein oder aus, veraendere die Groesse des unteren Panels und vergleiche die MapLibre-Kameraoperationen, waehrend der Viewport-Manager die reale Interface-Geometrie beruecksichtigt.

Overlays registrieren

Verbinde die DOM-Elemente, die Teile deiner Karte verdecken.

Geometrie messen

Der Viewport-Manager misst ihre tatsächliche Position und Größe relativ zum Kartencontainer.

Änderungen beobachten

ResizeObserver erkennt dynamische Layoutänderungen ohne Polling.

Verfügbaren Bereich berechnen

Overlay-Rechtecke, Safe Areas und zusätzliches Consumer-Padding werden in nutzbare Viewport-Geometrie umgerechnet.

Kamera bewegen

Kamera-Helper verwenden die berechnete Geometrie, damit wichtige Karteninhalte sichtbar bleiben.

pnpm

pnpm add jamit-maplibre-viewport maplibre-gl

npm

npm install jamit-maplibre-viewport maplibre-gl

MapLibre GL JS wird als Peer Dependency bereitgestellt.

Unterstützt: MapLibre GL JS >= 5.6.0 < 7

import { Map } from 'maplibre-gl';
import { createMapLibreViewport } from 'jamit-maplibre-viewport';

const map = new Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [13.405, 52.52],
  zoom: 11,
});

const viewport = createMapLibreViewport(map);

UI-Overlays

Verbinde deine Benutzeroberfläche

Registriere die UI-Elemente, die Teile der Karte verdecken. Das Package misst ihre realen DOM-Rechtecke und hält deren Geometrie synchron.

viewport.addOverlay({
  id: 'sidebar',
  element: sidebar,
  edge: 'left',
});

viewport.addOverlay({
  id: 'bottom-panel',
  element: bottomPanel,
  edge: 'bottom',
});

Hindernisbewusstes Fitting

Passe Positionen an den Bereich an, den Benutzer tatsächlich sehen

fitCoordinates() verwendet die tatsächlichen Rechtecke registrierter Hindernisse, anstatt die gesamte Karte auf einfaches rechteckiges Edge-Padding zu reduzieren.

Der Solver sucht nach der höchsten passenden Zoomstufe und einem gültigen Kamerazentrum, während die übergebenen Koordinaten außerhalb registrierter Overlays bleiben.

viewport.fitCoordinates(
  [
    [13.405, 52.52],
    [13.35, 52.5],
    [13.46, 52.54],
  ],
  {
    padding: 40,
    maxZoom: 14,
    duration: 800,
  },
);

viewport.fitBounds(bounds, {
  padding: 40,
  maxZoom: 14,
  duration: 800,
});

viewport.flyTo({
  center: [13.405, 52.52],
  zoom: 14,
  padding: 40,
  duration: 1200,
});

viewport.easeTo({
  center: [13.46, 52.54],
  zoom: 13,
  padding: 40,
  duration: 800,
});

getPadding()

const padding = viewport.getPadding();

{
  top: 0,
  right: 0,
  bottom: 180,
  left: 320,
}

getSafeArea()

const safeArea = viewport.getSafeArea();

{
  x: 320,
  y: 0,
  width: 960,
  height: 540,
}

Dynamische Layouts

Automatisch mit deiner Benutzeroberfläche synchronisiert

Registrierte Overlays und der Kartencontainer werden mit ResizeObserver überwacht. Wenn sich ihre Abmessungen ändern, wird die interne Viewport-Geometrie invalidiert und vor der nächsten Kameraoperation neu berechnet.

Dadurch sind einklappbare Sidebars, responsive Panels und sich vergrößernde Bottom Sheets möglich, ohne fest codierte Layout-Abmessungen in der Kartenlogik pflegen zu müssen.

Manuelle Aktualisierung

Aktualisiere die Geometrie, wenn du sofortige Kontrolle brauchst

refresh() erzwingt eine sofortige Neuberechnung der Geometrie. Die Kartenkamera wird dadurch nicht automatisch bewegt.

viewport.refresh();

viewport.fitCoordinates(coordinates, {
  padding: 40,
});

Lifecycle

Sauberer Lifecycle

Beim Zerstören des Viewport-Managers werden Observer getrennt, geplante Animation Frames abgebrochen und interne Referenzen freigegeben.

viewport.destroy();

Framework-unabhängig

Nutze es überall dort, wo MapLibre läuft

jamit-maplibre-viewport hängt von MapLibre und Standard-Browser-APIs ab, nicht von einem UI-Framework.

Vanilla TypeScript
Vue
Nuxt
React
Next.js
Svelte

SSR

Sicher auf dem Server importierbar

Das Package kann in serverseitig gerenderten Anwendungen importiert werden, ohne während der Modulevaluierung window, document, HTMLElement oder ResizeObserver zu benötigen.

DOM-Zugriffe beginnen erst, wenn ein Viewport-Manager mit einer tatsächlichen MapLibre-Instanz und registrierten Elementen arbeitet.

MapLibre GL JS 5.6
MapLibre GL JS 6.0
TypeScript
ResizeObserver

Bearing und Pitch

fitCoordinates() unterstützt aktuell nur Karten mit Bearing 0 und Pitch 0. Gedrehte oder geneigte Karten erzeugen bewusst eine klare Fehlermeldung, anstatt ein falsches Kameraergebnis zu liefern.

bearing = 0
pitch = 0

Antimeridian

Koordinatengruppen, die die Datumsgrenze überschreiten, werden aktuell bewusst abgelehnt. Vollständiges World-Wrapping ist für eine spätere Version vorgesehen.

[
  [179, 10],
  [-179, 10],
]

Projektstatus

Produktionsreifes Viewport-Management für MapLibre

Dynamische Overlay-Vermessung, ResizeObserver-basiertes Layout-Tracking, Safe-Area-Berechnung, viewport-aware Kamera-Helper und hindernisbewusstes Koordinaten-Fitting sind vollständig implementiert und durch automatisierte Tests abgedeckt.

Das Package ist öffentlich auf npm verfügbar und unterstützt MapLibre GL JS 5.6 und 6.0. Zusätzlich enthält es TypeScript-Typdefinitionen, SSR-sichere Imports, automatisierte CI-Prüfungen und eine interaktive Live-Demo.

In Entwicklung

Open Source

Quellcode ansehen

Der vollständige Quellcode, automatisierte Tests, die MapLibre-Demo und der Release-Verlauf sind im öffentlichen GitHub-Repository verfügbar.

GitHub-Repository öffnen