Komponenty Delphi pomoc
Start › Komponenty Delphi › TTileMapVCL

TTileMapVCL

Mapa kafelkowa dla aplikacji Windows (VCL) – OpenStreetMap, zdjęcia satelitarne, mapa terenu.

VCLkontrolka
▶ Zobacz na żywo – demo HTML

Opis

Lekka mapa rastrowa w komponencie VCL (TCustomPanel + Edge WebView2). Punkt zerowy, marker główny z własną ikoną, okrąg promienia, przyciski nawigacji z własnymi obrazkami, zaznaczanie obszaru i wyszukiwanie adresów.

Moduł: MapCommon.MapVCL · Klasa bazowa: TCustomMapVCL (TCustomPanel, TEdgeBrowser) · Platformy: VCL

TTileMapVCL – podgląd poglądowy
TTileMapVCL: styl tmsOpenStreetMap, punkt zerowy w Warszawie, okrąg 1,5 km (mlsDashed) i markery restauracji. Podgląd poglądowy (nie zrzut z Delphi) – prawdziwa strona mapy komponentu w ramce imitującej formę.

Demo na żywo

Interaktywna mapa kafelkowa TTileMapVCL: styl OSM/satelita/teren, marker główny, promień, zaznaczanie obszaru, wyszukiwanie i dziennik zdarzeń Delphi.

▶ Otwórz demo HTML

Funkcje

Warunki kafli. OpenStreetMap: obowiązuje Tile Usage Policy OSMF (atrybucja, umiarkowany ruch, bez masowego pobierania). Esri World Imagery: bez klucza tylko do użytku niekomercyjnego. OpenTopoMap: CC-BY-SA, niewielki ruch. Do produkcji o dużym ruchu użyj własnego serwera kafli (tmsCustom).

Właściwości

WłaściwośćOpis
StyleStyl mapy (enum TTileMapStyle), domyślnie tmsOpenStreetMap.
CenterLat, CenterLon, Zoom, Pitch, BearingWidok startowy / bieżący.
ZeroLat, ZeroLonPunkt zerowy (domyślnie Warszawa 52,2297 / 21,0122) – cel przycisku „Home” i odniesienie dla odległości.
ZeroPointVisible, ZeroTitle, ZeroIconZnacznik punktu zerowego; ZeroIcon to własny obrazek (PNG/JPG/BMP).
MainMarkerSourcemmsZeroPoint, mmsManual lub mmsDeviceLocation (GPS, awaryjnie punkt zerowy).
MainMarkerIcon, MainMarkerIconWidth/HeightWłasny obrazek markera głównego zamiast kropki.
MainMarkerColor, MainMarkerSize, PulseEnabledWygląd kropki markera głównego i pulsowanie.
RadiusVisible, RadiusMeters, RadiusCenterOkrąg promienia wokół markera głównego, punktu zerowego lub dowolnego punktu.
RadiusColor, RadiusFillOpacity, RadiusLineColor, RadiusLineOpacity, RadiusLineWidth, RadiusLineStyleKolory, przezroczystość i styl linii okręgu (mlsSolid, mlsDashed, mlsDotted).
NavButtonsKolekcja przycisków nawigacji: Kind, Visible, Hint, Icon, Action.
NavVisible, NavPosition, NavOrientation, NavButtonSizePołożenie i układ panelu przycisków.
AreaShape, AreaColor, AreaFillOpacityZaznaczanie obszaru: masRectangle, masPolygon, masCircle.
SearchOnAreaSelected, AreaSearchQueryAutomatyczne wyszukiwanie wewnątrz zaznaczonego obszaru.
SearchProviderDostawca wyszukiwania (np. TNominatimSearchProvider); łączony automatycznie po upuszczeniu na formę.
SearchProviderURL, SearchTokenAdres i token używane, gdy dostawca nie ma własnych.
AreasPowiązany komponent TMapAreas (granice świata, kontynentów, państw).
AutoLinkComponentsTrue = mapa sama wykrywa dostawcę wyszukiwania, TMapAreas i TEditMap na formie.
WebView2UserDataFolder, DevToolsEnabledFolder danych WebView2, narzędzia deweloperskie.

Zdarzenia

ZdarzenieOpis
OnMapReadyStrona mapy załadowana – od teraz można wywoływać metody.
OnMapClick, OnMarkerClickKliknięcie w mapę / marker (współrzędne, identyfikator markera).
OnMoveEnd, OnZoomChangedKoniec przesuwania mapy, zmiana powiększenia.
OnSearchResults, OnSearchError, OnSearchResultSelectedWyniki wyszukiwania, błąd (z rodzajem pek*) i wybór wyniku z listy.
OnAreaSelectedUżytkownik zakończył zaznaczanie obszaru.
OnNavButtonClickKliknięcie przycisku nawigacji (także przy Action = nbaEventOnly).
OnLocation, OnMainMarkerMovedNowa pozycja urządzenia; marker główny przeciągnięty przez użytkownika.
OnJSErrorBłąd JavaScript strony mapy (diagnostyka).

Metody

MetodaOpis
SetView, FlyTo, GoHome, FitBounds, FitMarkersPrzesuwanie i dopasowanie widoku.
SetZeroPoint, SetMainMarker, UpdateMyLocationPunkt zerowy, marker główny, odświeżenie lokalizacji.
ShowRadius, ClearRadiusPokazanie / ukrycie okręgu promienia.
AddMarker, RemoveMarker, ClearMarkers, OpenMarkerPopupWłasne markery (kolor lub ikona) z dymkami.
SearchAddress, SearchStructured, ReverseGeocode, SearchInAreaWyszukiwanie adresu, adres z punktu, szukanie w obszarze.
StartAreaSelection, CancelAreaSelection, SetArea, ClearAreaZaznaczanie obszaru z kodu.
MainMarkerDistanceFromZero, MainMarkerBearingFromZero, DistanceFromMainMarkerOdległość (m) i kierunek względem punktu zerowego / markera.
CheckSearchConnection, DetectLinkedComponentsTest połączenia z dostawcą, ponowne wykrycie komponentów.

Przykłady

Szybki start

procedure TForm1.FormCreate(Sender: TObject);
begin
  TileMap1.Style := tmsOpenStreetMap;     // tmsSatellite, tmsTerrain
  TileMap1.ZeroLat := 52.2297;            // punkt zerowy (przycisk Home)
  TileMap1.ZeroLon := 21.0122;
  TileMap1.Zoom := 13;
  TileMap1.SearchToken := GetEnvironmentVariable('MAP_SEARCH_TOKEN');
  TileMap1.ZeroIcon.LoadFromFile('zero.png');
  TileMap1.RadiusMeters := 1500;
  TileMap1.RadiusLineStyle := mlsDashed;
  TileMap1.RadiusVisible := True;
end;

procedure TForm1.TileMap1MapReady(Sender: TObject);
begin
  // restauracje w promieniu 1,5 km
  TileMap1.AddMarker('r1', 52.2319, 21.0067, clRed, 'Restauracja A', 'Kuchnia polska, 12–22');
  TileMap1.AddMarker('r2', 52.2240, 21.0190, clRed, 'Restauracja B', 'Pizza, 11–23');
  TileMap1.FitMarkers;
end;

Pełna lista API

Generowana z deklaracji w kodzie (Source/*.pas): wszystkie opublikowane właściwości i zdarzenia TTileMapVCL (także dziedziczone), właściwości publiczne i metody publiczne.

Właściwości opublikowane (107)

WłaściwośćTypDomyślnieOpis
Align(dziedziczona)Standardowa właściwość kontrolki VCL
Anchors(dziedziczona)Standardowa właściwość kontrolki VCL
Constraints(dziedziczona)Standardowa właściwość kontrolki VCL
Margins(dziedziczona)Standardowa właściwość kontrolki VCL
AlignWithMargins(dziedziczona)Standardowa właściwość kontrolki VCL
Padding(dziedziczona)Standardowa właściwość kontrolki VCL
TabOrder(dziedziczona)Standardowa właściwość kontrolki VCL
TabStop(dziedziczona)Standardowa właściwość kontrolki VCL
Visible(dziedziczona)Standardowa właściwość kontrolki VCL
Enabled(dziedziczona)Standardowa właściwość kontrolki VCL
Color(dziedziczona)$00DCE4E8Standardowa właściwość kontrolki VCL
ParentBackground(dziedziczona)FalseStandardowa właściwość kontrolki VCL
StyleTTileMapStyletmsOpenStreetMapStyl mapy (enum): kafle OSM / satelita / teren / własne (TTileMap*) lub styl wektorowy (T3DMap*)
CenterLat(dziedziczona)Środek mapy – szerokość geogr. (start / bieżący)
CenterLon(dziedziczona)Środek mapy – długość geogr.
Zoom(dziedziczona)Powiększenie 0..22
Pitch(dziedziczona)Pochylenie w stopniach
Bearing(dziedziczona)Obrót w stopniach
Language(dziedziczona)Język etykiet (pl, en, de …)
ShowScale(dziedziczona)Podziałka (przy wczytaniu strony)
ShowNavigationControl(dziedziczona)Kontrolka MapLibre (zoom/kompas) obok panelu przycisków
LoadingText(dziedziczona)Tekst podczas ładowania
AllowPopupHTML(dziedziczona)False = dymki jako czysty tekst (bezpieczne)
ZeroLat(dziedziczona)Punkt zerowy – szerokość (domyślnie Warszawa 52.2297)
ZeroLon(dziedziczona)Punkt zerowy – długość (domyślnie 21.0122)
ZeroPointVisible(dziedziczona)Rysuj znacznik punktu zerowego
ZeroTitle(dziedziczona)Podpowiedź znacznika punktu zerowego
ZeroIconWidth(dziedziczona)Szerokość ikony ZeroIcon (px)
ZeroIconHeight(dziedziczona)Wysokość ikony ZeroIcon (px)
HomeUsesZeroPoint(dziedziczona)Przycisk „Home” leci do punktu zerowego
HomeLat(dziedziczona)Cel „Home”, gdy HomeUsesZeroPoint = False
HomeLon(dziedziczona)jw. – długość
HomeZoom(dziedziczona)Zoom po „Home”
MainMarkerSource(dziedziczona)mmsZeroPoint / mmsManual / mmsDeviceLocation (awaryjnie punkt zerowy)
MainMarkerVisible(dziedziczona)Widoczność markera głównego
MainMarkerLat(dziedziczona)Pozycja przy mmsManual – szerokość
MainMarkerLon(dziedziczona)Pozycja przy mmsManual – długość
MainMarkerSize(dziedziczona)Średnica kropki (bez ikony), px
MainMarkerSquare(dziedziczona)Kwadrat zamiast koła
MainMarkerBorderWidth(dziedziczona)Grubość obramowania
MainMarkerBorderDashed(dziedziczona)Obramowanie przerywane
MainMarkerOpacity(dziedziczona)Przezroczystość 0..1
MainMarkerTitle(dziedziczona)Podpowiedź
MainMarkerDraggable(dziedziczona)Użytkownik może przeciągać (OnMainMarkerMoved)
MainMarkerIconWidth(dziedziczona)Szerokość ikony MainMarkerIcon
MainMarkerIconHeight(dziedziczona)Wysokość ikony MainMarkerIcon
MainMarkerIconScale(dziedziczona)Skala ikony
PulseEnabled(dziedziczona)Pulsujący pierścień
PulseDurationMs(dziedziczona)Czas jednego pulsu (ms)
LocationTimeoutMs(dziedziczona)Limit czasu czujnika lokalizacji
RadiusVisible(dziedziczona)Okrąg promienia
RadiusMeters(dziedziczona)Promień w metrach
RadiusCenter(dziedziczona)rcMainMarker / rcZeroPoint / rcManual
RadiusLat(dziedziczona)Środek przy rcManual – szerokość
RadiusLon(dziedziczona)Środek przy rcManual – długość
RadiusFillOpacity(dziedziczona)Krycie wypełnienia 0..1
RadiusLineOpacity(dziedziczona)Krycie obrysu 0..1
RadiusLineWidth(dziedziczona)Grubość obrysu px (0 = brak)
RadiusLineStyle(dziedziczona)mlsSolid / mlsDashed / mlsDotted
RadiusLabel(dziedziczona)Tekst w środku, np. „2 km”
NavVisible(dziedziczona)Panel przycisków nawigacji
NavPosition(dziedziczona)Narożnik panelu
NavOrientation(dziedziczona)Pionowo / poziomo
NavButtonSize(dziedziczona)Rozmiar przycisku px
SearchPlaceholder(dziedziczona)Podpowiedź pola wyszukiwania
SearchNoResultsText(dziedziczona)Tekst „brak wyników”
SearchSearchingText(dziedziczona)Tekst „szukam…”
SearchMinChars(dziedziczona)Minimalna liczba znaków
SearchLive(dziedziczona)Szukaj podczas pisania (uwaga na limity!)
SearchShowDistance(dziedziczona)Odległość od markera głównego w wynikach
SearchUseArea(dziedziczona)Pole wyszukiwania szuka w zaznaczonym obszarze
SearchProviderURL(dziedziczona)Zapasowy adres Nominatim, gdy SearchProvider pusty
SearchToken(dziedziczona)Token – NIGDY w DFM, ustaw w kodzie
AreaShape(dziedziczona)Kształt przycisku „Zaznacz obszar”
AreaFillOpacity(dziedziczona)Krycie wypełnienia obszaru
SearchOnAreaSelected(dziedziczona)Po zaznaczeniu uruchom AreaSearchQuery
AreaSearchQuery(dziedziczona)np. „restauracja”, „hydraulik”
BoundariesURL(dziedziczona)Kafelki wektorowe / TileJSON / PMTiles z granicami (źródło danych, nie styl)
BoundariesKind(dziedziczona)mbkVectorTiles / mbkTileJSON / mbkPMTiles
BoundariesSourceLayer(dziedziczona)Warstwa źródłowa
BoundariesVisible(dziedziczona)Pokaż granice
MainMarkerColor(dziedziczona)Kolor markera głównego
MainMarkerBorderColor(dziedziczona)Kolor obramowania
PulseColor(dziedziczona)Kolor pulsu
RadiusColor(dziedziczona)Kolor wypełnienia promienia
RadiusLineColor(dziedziczona)Kolor obrysu (clNone = RadiusColor)
AreaColor(dziedziczona)Kolor zaznaczanego obszaru
BoundariesColor(dziedziczona)Kolor granic
MainMarkerIcon(dziedziczona)Ikona markera głównego (TPicture / TBitmap, PNG/SVG)
ZeroIcon(dziedziczona)Ikona punktu zerowego
NavButtons(dziedziczona)Kolekcja przycisków panelu nawigacji (rodzaj, widoczność, podpowiedź, kolejność)
SearchProvider(dziedziczona)Powiązany dostawca wyszukiwania (TNominatimSearchProvider / TCustomUrlSearchProvider)
Areas(dziedziczona)Powiązany komponent TMapAreas (granice, regiony, własne GeoJSON)
Edit(dziedziczona)
Weather(dziedziczona)
WeatherInfo(dziedziczona)
WeatherClickMode(dziedziczona)
WeatherPointModeMinZoom(dziedziczona)
Aircraft(dziedziczona)
AircraftInfo(dziedziczona)
Boats(dziedziczona)
BoatsInfo(dziedziczona)
AutoLinkComponents(dziedziczona)Automatycznie łącz pierwszy dostawcę wyszukiwania / TMapAreas / TEditMap z formy
WebView2UserDataFolder(dziedziczona)Folder danych użytkownika WebView2 ('' = folder danych aplikacji)
WebView2BrowserFolder(dziedziczona)Folder wersji stałej (Fixed Version) runtime WebView2; '' = runtime systemowy
DevToolsEnabled(dziedziczona)Narzędzia deweloperskie przeglądarki (F12) – tylko do debugowania
OpenLinksExternally(dziedziczona)Linki z dymków otwieraj w przeglądarce systemowej

Zdarzenia (15)

ZdarzenieTypOpis
OnResize(dziedziczone)Standardowa właściwość kontrolki VCL
OnMapReady(dziedziczone)Strona i styl gotowe
OnMapClick(dziedziczone)Kliknięcie (Lat, Lon)
OnMarkerClick(dziedziczone)Kliknięcie markera (Id)
OnZoomChanged(dziedziczone)Zmiana zoomu
OnMoveEnd(dziedziczone)Koniec przesuwania (View)
OnSearchResults(dziedziczone)Wyniki wyszukiwania
OnSearchError(dziedziczone)Błąd wyszukiwania (ErrorKind pek*, HTTP, komunikat PL/EN)
OnSearchResultSelected(dziedziczone)Wybór wyniku w polu wyszukiwania
OnJSError(dziedziczone)Błąd strony / WebView2 / mostu
OnStyleLoaded(dziedziczone)Styl wczytany
OnAreaSelected(dziedziczone)Zaznaczono obszar (prostokąt/wielokąt/koło)
OnNavButtonClick(dziedziczone)Kliknięto przycisk panelu (Kind)
OnLocation(dziedziczone)Wynik lokalizacji urządzenia
OnMainMarkerMoved(dziedziczone)Marker główny przeciągnięty

Właściwości publiczne – tylko w kodzie (11)

WłaściwośćTypOpis
CoreTMapCoreWspólny rdzeń mapy (TMapCore) – dla zaawansowanych
BrowserTEdgeBrowserWewnętrzna kontrolka przeglądarki (TEdgeBrowser / TWebBrowser)
IsMapReadyBooleanTrue po OnMapReady
ViewTMapViewBieżący widok (środek, zoom, pochylenie, obrót, granice)
MarkerCountIntegerLiczba markerów
LastResultsTMapGeoResultsOstatnie wyniki wyszukiwania
AreaTMapAreaZaznaczony obszar (kształt, punkty, prostokąt, koło)
HasAreaBooleanCzy obszar jest zaznaczony
CustomTileURLstringTylko w kodzie: szablon kafli {z}/{x}/{y} dla Style = tmsCustom
CustomAttributionstringAtrybucja kafli własnych
CustomTileMaxZoomIntegerMaksymalny zoom kafli własnych

Metody publiczne (42)

MetodaOpis
function ResolveUserDataFolder: stringZwraca (i tworzy) folder danych WebView2
procedure ReloadPrzeładowuje stronę; cały stan jest odtwarzany
function EffectiveWeatherClickTarget: TWeatherClickTarget
procedure DetectLinkedComponentsWyszukuje na formie i łączy dostawcę / TMapAreas / TEditMap
function MapCore: TMapCoreIMapCoreProvider – rdzeń dla TEditMapRaster
procedure ExecuteJS(const Script: string)Wykonuje JavaScript na stronie mapy
procedure RequestJSON(const Cmd, ArgsJSON: string; const Handler: TMapResultProc)Polecenie strony z odpowiedzią JSON (callback)
procedure SetView(const Lat, Lon, AZoom: Double; Animate: Boolean = False)Ustawia środek / zoom / pochylenie / obrót
procedure FlyTo(const Lat, Lon: Double; const AZoom: Double = -1; DurationMs: Integer = 1500)Animowany przelot do punktu
procedure FitBounds(const South, West, North, East: Double; PaddingPx: Integer = 40; const MaxZoom: Double = 17)Dopasuj widok do prostokąta
procedure FitMarkers(PaddingPx: Integer = 50; const MaxZoom: Double = 16; IncludeMainMarker: Boolean = False)Dopasuj widok do markerów
procedure SetInteractive(Enabled: Boolean)Włącza / wyłącza interakcję (przesuwanie, zoom)
procedure GoHomeJak przycisk „Home”
procedure SetZeroPoint(const Lat, Lon: Double)Ustawia punkt zerowy
procedure AddMarkerCSS(const Id: string; const Lat, Lon: Double; const CSSColor: string; const Title: string = ''; const PopupText: string = ''; const PopupHTML: string = '')Marker z kolorem CSS
procedure RemoveMarker(const Id: string)Usuwa marker
procedure ClearMarkersUsuwa wszystkie markery
function HasMarker(const Id: string): BooleanCzy marker o Id istnieje
function TryGetMarker(const Id: string; out Marker: TMapMarker): BooleanOdczyt markera po Id
procedure OpenMarkerPopup(const Id: string)Otwiera dymek markera
procedure SetMainMarker(const Lat, Lon: Double; Visible: Boolean = True)Ustawia pozycję markera głównego (mmsManual)
procedure UpdateMyLocationOdczyt lokalizacji urządzenia (OnLocation)
procedure ShowRadius(const Meters: Double; const LabelText: string = '')Pokazuje okrąg promienia
procedure ClearRadiusUkrywa okrąg promienia
function MainMarkerDistanceFromZero: DoubleOdległość markera głównego od punktu zerowego (m)
function MainMarkerBearingFromZero: DoubleAzymut markera głównego od punktu zerowego
procedure MainMarkerPixelOffsetFromZero(Zoom: Integer; out DX, DY: Double)Przesunięcie w pikselach względem punktu zerowego
function DistanceFromMainMarker(const Lat, Lon: Double): DoubleOdległość punktu od markera głównego (m)
procedure StartAreaSelectionRozpoczyna zaznaczanie obszaru
procedure CancelAreaSelectionPrzerywa zaznaczanie
procedure SetArea(const Area: TMapArea)Ustawia obszar z kodu
procedure ClearAreaCzyści obszar
procedure ShowSearchBox(Show: Boolean = True; const Query: string = '')Pokazuje / ukrywa pole wyszukiwania
procedure SearchAddress(const Query: string)Wyszukiwanie adresu (OnSearchResults)
procedure SearchStructured(const Q: TNominatimStructuredQuery)Wyszukiwanie strukturalne (ulica, miasto, kod…)
procedure SearchInArea(const Query: string)Wyszukiwanie w zaznaczonym obszarze
procedure ReverseGeocode(const Lat, Lon: Double; Zoom: Integer = 18)Adres dla współrzędnych
procedure LookupOsmIds(const OsmIds: string)Wyszukiwanie po identyfikatorach OSM
procedure CheckSearchConnectionSprawdza połączenie z serwerem wyszukiwania
procedure NextStyleNastępny styl (jak przycisk „Styl”)
procedure SetRasterEdit(const ArgsJSON: string)Ustawienia edycji / stylizacji rastra (używane przez TEditMapRaster)
procedure RefreshTile(Z, X, Y: Integer)Odświeża kafel z/x/y (cache-busting; z < 0 = wszystkie)

Pełny opis wszystkich właściwości: dokumentacja komponentów map.

Zobacz też