Open Source paket

jamit-maplibre-viewport

Lagan i potpuno tipiziran viewport i safe-area manager za MapLibre GL JS aplikacije sa dinamičkim UI overlayima.

Mjeri stvarnu geometriju korisničkog interfejsa, drži viewport proračune usklađenim sa promjenama layouta i prilagodi sadržaj mape prostoru koji korisnik zaista može vidjeti.

Pogledaj na GitHubu Pogledaj demo

Pregled

MapLibre upravljanje kamerom koje razumije tvoj interfejs

MapLibre GL JS pruža moćne camera API-je, ali ne zna koji su dijelovi mape prekriveni elementima korisničkog interfejsa. Sidebarovi, bottom sheetovi i floating detail paneli zato mogu prekriti markere ili važne dijelove mape čak i kada kamera tehnički pravilno uklopi map container.

jamit-maplibre-viewport povezuje DOM layout geometriju sa MapLibre camera operacijama. Registrovani overlayi se automatski mjere, promjene layouta se prate, a camera helperi mogu raditi sa dijelom mape koji je korisniku stvarno vidljiv.

Dinamičko mjerenje overlaya

Registruj sidebarove, bottom panele i druge elemente interfejsa i dozvoli paketu da mjeri njihovu stvarnu DOM geometriju umjesto korištenja hardkodiranih dimenzija.

Automatsko praćenje layouta

ResizeObserver održava viewport geometriju usklađenom kada registrovani overlayi ili map container promijene veličinu.

Obstacle-aware uklapanje koordinata

fitCoordinates() traži poziciju kamere i nivo zooma pri kojem sve proslijeđene koordinate ostaju vidljive izvan registrovanih UI prepreka.

Stvarno iskoristiv prostor mape

Djelimični overlayi blokiraju samo prostor koji stvarno zauzimaju. Slobodan prostor pored panela i dalje može ostati dostupan za sadržaj mape.

Izračunavanje safe area prostora

Pristupi trenutno dostupnom viewport paddingu i safe area prostoru kroz potpuno tipiziran API.

MapLibre camera helperi

Koristi viewport-aware fitBounds(), fitCoordinates(), flyTo() i easeTo() operacije bez ručnog usklađivanja UI dimenzija sa MapLibreom.

Dodatni sigurnosni padding

Dodaj podesivi razmak oko ivica mape i registrovanih prepreka kako markeri i drugi važni elementi ne bi bili postavljeni direktno uz elemente interfejsa.

Nezavisan od frameworka

Paket radi direktno sa MapLibreom i standardnim DOM API-jima i ne zahtijeva Vue, Nuxt, React niti neki drugi frontend framework.

SSR-safe arhitektura

Paket se može sigurno importovati u SSR okruženjima. Browser globalni objekti se koriste tek kada se stvarno radi sa mapom i overlay elementima.

Dinamički overlayDonji panel

Promijeni veličinu ovog panela i ponovo pokreni uklapanje koordinata.

Ivicadolje

Trenutna visina0 px

LIVE MAPLIBRE VIEWPORT DEMO

Uključi ili isključi bočni panel, promijeni veličinu donjeg panela i uporedi MapLibre operacije kamere dok viewport manager prati stvarnu geometriju interfejsa.

Registruj overlaye

Poveži DOM elemente koji prekrivaju dijelove mape.

Izmjeri geometriju

Viewport manager mjeri njihovu stvarnu poziciju i dimenzije u odnosu na map container.

Prati promjene

ResizeObserver prepoznaje dinamičke promjene layouta bez pollinga.

Izračunaj raspoloživi prostor

Overlay pravougaonici, safe area prostor i dodatni consumer padding pretvaraju se u iskoristivu viewport geometriju.

Pomjeri kameru

Camera helperi koriste izračunatu geometriju kako bi važan sadržaj mape ostao vidljiv.

pnpm

pnpm add jamit-maplibre-viewport maplibre-gl

npm

npm install jamit-maplibre-viewport maplibre-gl

MapLibre GL JS se koristi kao peer dependency.

Podržano: 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 overlayi

Poveži svoj korisnički interfejs

Registruj UI elemente koji prekrivaju dijelove mape. Paket mjeri njihove stvarne DOM pravougaonike i održava njihovu geometriju usklađenom.

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

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

Obstacle-aware uklapanje

Uklopi lokacije u prostor koji korisnik zaista može vidjeti

fitCoordinates() koristi stvarne pravougaonike registrovanih prepreka umjesto da cijelu mapu svodi na jednostavan pravougaoni edge padding.

Solver traži najveći odgovarajući nivo zooma i validan centar kamere, pri čemu proslijeđene koordinate ostaju izvan registrovanih overlaya.

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,
}

Dinamički layouti

Automatski usklađeno sa tvojim korisničkim interfejsom

Registrovani overlayi i map container prate se pomoću ResizeObservera. Kada se njihove dimenzije promijene, interna viewport geometrija se invalidira i ponovo izračunava prije naredne camera operacije.

To omogućava collapse sidebarove, responsive panele i bottom sheetove koji mijenjaju veličinu bez održavanja hardkodiranih layout dimenzija unutar map logike.

Ručno osvježavanje

Osvježi geometriju kada ti treba trenutna kontrola

refresh() prisilno pokreće trenutno ponovno izračunavanje geometrije. Time se kamera mape ne pomjera automatski.

viewport.refresh();

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

Lifecycle

Čist lifecycle

Destroy viewport managera odspaja observere, otkazuje zakazane animation frameove i oslobađa interne reference.

viewport.destroy();

Nezavisan od frameworka

Koristi ga svuda gdje radi MapLibre

jamit-maplibre-viewport zavisi od MapLibrea i standardnih browser API-ja, a ne od UI frameworka.

Vanilla TypeScript
Vue
Nuxt
React
Next.js
Svelte

SSR

Siguran za import na serveru

Paket se može importovati u server-side rendered aplikacijama bez potrebe za window, document, HTMLElement ili ResizeObserver tokom evaluacije modula.

DOM pristup počinje tek kada viewport manager počne raditi sa stvarnom MapLibre instancom i registrovanim elementima.

MapLibre GL JS 5.6
MapLibre GL JS 6.0
TypeScript
ResizeObserver

Bearing i pitch

fitCoordinates() trenutno podržava samo mape sa bearing 0 i pitch 0. Rotirane ili nagnute mape namjerno proizvode jasnu grešku umjesto netačnog rezultata kamere.

bearing = 0
pitch = 0

Antimeridijan

Grupe koordinata koje prelaze međunarodnu datumsku granicu trenutno se namjerno odbijaju. Puna world-wrapping podrška planirana je za buduću verziju.

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

Status projekta

Viewport upravljanje za MapLibre spremno za produkciju

Dinamičko mjerenje overlay elemenata, ResizeObserver praćenje promjena layouta, izračunavanje safe-area prostora, viewport-aware camera helperi i obstacle-aware uklapanje koordinata u potpunosti su implementirani i pokriveni automatizovanim testovima.

Paket je javno dostupan na npm-u i podržava MapLibre GL JS 5.6 i 6.0. Također uključuje TypeScript tipove, SSR-safe importe, automatizovane CI provjere i interaktivni live demo.

U razvoju

Open Source

Pogledaj izvorni kod

Kompletan izvorni kod, automatizovani testovi, MapLibre demo i historija izdanja dostupni su u javnom GitHub repozitoriju.

Otvori GitHub repozitorij