TTileMapFMX – Komponenty Delphi

Opis

Ta sama mapa kafelkowa co w VCL, ale jako kontrolka FireMonkey (TWebBrowser). Działa na Windows, macOS, Androidzie i iOS; marker główny może pokazywać pozycję GPS urządzenia.

Moduł: MapCommon.MapFMX · Klasa bazowa: TCustomMapFMX (TControl, TWebBrowser) · Platformy: FMX

TTileMapFMX – podgląd poglądowy — TTileMapFMX: styl tmsSatellite (Esri), marker z lokalizacji urządzenia i zaznaczony prostokąt wyszukiwania. *Podgląd poglądowy (nie zrzut z Delphi) – prawdziwa strona mapy komponentu w ramce imitującej formę.*

Demo na żywo

Mapa kafelkowa TTileMapFMX w ramce telefonu/tabletu: satelita, lokalizacja, zaznaczony obszar i wyszukiwanie w nim.

▶ Otwórz demo HTML

Funkcje

Style z listy: tmsOpenStreetMap, tmsSatellite (Esri), tmsTerrain (OpenTopoMap), tmsCustom (własny URL z kodu: CustomTileURL, CustomAttribution, CustomTileMaxZoom).
Punkt zerowy (domyślnie Warszawa) i marker główny – oba z własnym obrazkiem (ZeroIcon, MainMarkerIcon, typ TBitmap).
Okrąg promienia: kolor wypełnienia i linii, przezroczystość, grubość, styl linii, etykieta.
Przyciski nawigacji (szukaj, zoom, Home, moja lokalizacja, zaznacz obszar, styl) – każdy z własną ikoną, podpowiedzią i akcją.
Zaznaczanie obszaru: prostokąt, wielokąt, koło – i wyszukiwanie tylko w tym obszarze.
Wyszukiwarka adresów przez dowolnego dostawcę (TNominatimSearchProvider, TCustomUrlSearchProvider).
Automatyczne łączenie z TMapAreas i dostawcą wyszukiwania upuszczonym na formę.
Transport komunikatów JS→Delphi: BridgeTransport (mbtAuto, mbtWebView2, mbtIFrame, mbtLocation) z potwierdzeniami.

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).

FMX: na Windows TWebBrowser używa Edge; komunikaty ze strony przechodzą przez nawigację (mbtLocation/mbtIFrame) z potwierdzeniem ack, więc nic nie ginie.

Właściwości

Właściwość	Opis
Style	Styl mapy (enum `TTileMapStyle`), domyślnie `tmsOpenStreetMap`.
CenterLat, CenterLon, Zoom, Pitch, Bearing	Widok startowy / bieżący.
ZeroLat, ZeroLon	Punkt zerowy (domyślnie Warszawa 52,2297 / 21,0122) – cel przycisku „Home” i odniesienie dla odległości.
ZeroPointVisible, ZeroTitle, ZeroIcon	Znacznik punktu zerowego; `ZeroIcon` to własny obrazek (PNG/JPG/BMP).
MainMarkerSource	`mmsZeroPoint`, `mmsManual` lub `mmsDeviceLocation` (GPS, awaryjnie punkt zerowy).
MainMarkerIcon, MainMarkerIconWidth/Height	Własny obrazek markera głównego zamiast kropki.
MainMarkerColor, MainMarkerSize, PulseEnabled	Wygląd kropki markera głównego i pulsowanie.
RadiusVisible, RadiusMeters, RadiusCenter	Okrąg promienia wokół markera głównego, punktu zerowego lub dowolnego punktu.
RadiusColor, RadiusFillOpacity, RadiusLineColor, RadiusLineOpacity, RadiusLineWidth, RadiusLineStyle	Kolory, przezroczystość i styl linii okręgu (`mlsSolid`, `mlsDashed`, `mlsDotted`).
NavButtons	Kolekcja przycisków nawigacji: `Kind`, `Visible`, `Hint`, `Icon`, `Action`.
NavVisible, NavPosition, NavOrientation, NavButtonSize	Położenie i układ panelu przycisków.
AreaShape, AreaColor, AreaFillOpacity	Zaznaczanie obszaru: `masRectangle`, `masPolygon`, `masCircle`.
SearchOnAreaSelected, AreaSearchQuery	Automatyczne wyszukiwanie wewnątrz zaznaczonego obszaru.
SearchProvider	Dostawca wyszukiwania (np. TNominatimSearchProvider); łączony automatycznie po upuszczeniu na formę.
SearchProviderURL, SearchToken	Adres i token używane, gdy dostawca nie ma własnych.
Areas	Powiązany komponent TMapAreas (granice świata, kontynentów, państw).
AutoLinkComponents	True = mapa sama wykrywa dostawcę wyszukiwania, TMapAreas i TEditMap na formie.
BridgeTransport	Sposób przekazywania komunikatów ze strony mapy do Delphi.

Zdarzenia

Zdarzenie	Opis
OnMapReady	Strona mapy załadowana – od teraz można wywoływać metody.
OnMapClick, OnMarkerClick	Kliknięcie w mapę / marker (współrzędne, identyfikator markera).
OnMoveEnd, OnZoomChanged	Koniec przesuwania mapy, zmiana powiększenia.
OnSearchResults, OnSearchError, OnSearchResultSelected	Wyniki wyszukiwania, błąd (z rodzajem `pek*`) i wybór wyniku z listy.
OnAreaSelected	Użytkownik zakończył zaznaczanie obszaru.
OnNavButtonClick	Kliknięcie przycisku nawigacji (także przy `Action = nbaEventOnly`).
OnLocation, OnMainMarkerMoved	Nowa pozycja urządzenia; marker główny przeciągnięty przez użytkownika.
OnJSError	Błąd JavaScript strony mapy (diagnostyka).

Metody

Metoda	Opis
SetView, FlyTo, GoHome, FitBounds, FitMarkers	Przesuwanie i dopasowanie widoku.
SetZeroPoint, SetMainMarker, UpdateMyLocation	Punkt zerowy, marker główny, odświeżenie lokalizacji.
ShowRadius, ClearRadius	Pokazanie / ukrycie okręgu promienia.
AddMarker, RemoveMarker, ClearMarkers, OpenMarkerPopup	Własne markery (kolor lub ikona) z dymkami.
SearchAddress, SearchStructured, ReverseGeocode, SearchInArea	Wyszukiwanie adresu, adres z punktu, szukanie w obszarze.
StartAreaSelection, CancelAreaSelection, SetArea, ClearArea	Zaznaczanie obszaru z kodu.
MainMarkerDistanceFromZero, MainMarkerBearingFromZero, DistanceFromMainMarker	Odległość (m) i kierunek względem punktu zerowego / markera.
CheckSearchConnection, DetectLinkedComponents	Test połączenia z dostawcą, ponowne wykrycie komponentów.

Przykłady

Szybki start

procedure TForm1.FormCreate(Sender: TObject);
begin
  TileMap1.Style := tmsSatellite;              // zdjęcia Esri (tylko niekomercyjnie)
  TileMap1.MainMarkerSource := mmsDeviceLocation;  // GPS telefonu
  TileMap1.AreaShape := masRectangle;
  TileMap1.SearchUseArea := True;
end;

procedure TForm1.SearchButtonClick(Sender: TObject);
begin
  TileMap1.SearchAddress(EditQuery.Text);      // wyniki w OnSearchResults
end;

procedure TForm1.TileMap1SearchResults(Sender: TObject; Kind: TMapSearchKind;
  const Query: string; const Results: TMapGeoResults; const RawJSON: string);
begin
  ListBox1.Clear;
  for var R in Results do
    ListBox1.Items.Add(R.DisplayName);
end;

Pełna lista API

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

Właściwości opublikowane (102)

Właściwość	Typ	Domyślnie	Opis
`Align`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Anchors`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Margins`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Padding`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Position`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Width`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Height`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Size`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Visible`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Enabled`	`(dziedziczona)`		Standardowa właściwość kontrolki FMX
`Style`	`TTileMapStyle`	`tmsOpenStreetMap`	Styl 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
`BridgeTransport`	`(dziedziczona)`		Kanał komunikacji strona ↔ Delphi: mbtAuto / WebView2 / WebBrowser (FMX)

Zdarzenia (15)

Zdarzenie	Typ	Opis
`OnResized`	`(dziedziczone)`	Standardowa właściwość kontrolki FMX
`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 (12)

Właściwość	Typ	Opis
`Core`	`TMapCore`	Wspólny rdzeń mapy (TMapCore) – dla zaawansowanych
`Browser`	`TWebBrowser`	Wewnętrzna kontrolka przeglądarki (TEdgeBrowser / TWebBrowser)
`IsMapReady`	`Boolean`	True po OnMapReady
`View`	`TMapView`	Bieżący widok (środek, zoom, pochylenie, obrót, granice)
`MarkerCount`	`Integer`	Liczba markerów
`LastResults`	`TMapGeoResults`	Ostatnie wyniki wyszukiwania
`Area`	`TMapArea`	Zaznaczony obszar (kształt, punkty, prostokąt, koło)
`HasArea`	`Boolean`	Czy obszar jest zaznaczony
`BridgeMessagesSeen`	`Integer`	Licznik odebranych komunikatów mostu (diagnostyka)
`CustomTileURL`	`string`	Tylko w kodzie: szablon kafli {z}/{x}/{y} dla Style = tmsCustom
`CustomAttribution`	`string`	Atrybucja kafli własnych
`CustomTileMaxZoom`	`Integer`	Maksymalny zoom kafli własnych

Metody publiczne (41)

Metoda	Opis
`procedure Reload`	Przeładowuje stronę; cały stan jest odtwarzany
`function EffectiveWeatherClickTarget: TWeatherClickTarget`
`procedure DetectLinkedComponents`	Wyszukuje na formie i łączy dostawcę / TMapAreas / TEditMap
`function MapCore: TMapCore`	IMapCoreProvider – 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 GoHome`	Jak 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 ClearMarkers`	Usuwa wszystkie markery
`function HasMarker(const Id: string): Boolean`	Czy marker o Id istnieje
`function TryGetMarker(const Id: string; out Marker: TMapMarker): Boolean`	Odczyt 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 UpdateMyLocation`	Odczyt lokalizacji urządzenia (OnLocation)
`procedure ShowRadius(const Meters: Double; const LabelText: string = '')`	Pokazuje okrąg promienia
`procedure ClearRadius`	Ukrywa okrąg promienia
`function MainMarkerDistanceFromZero: Double`	Odległość markera głównego od punktu zerowego (m)
`function MainMarkerBearingFromZero: Double`	Azymut 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): Double`	Odległość punktu od markera głównego (m)
`procedure StartAreaSelection`	Rozpoczyna zaznaczanie obszaru
`procedure CancelAreaSelection`	Przerywa zaznaczanie
`procedure SetArea(const Area: TMapArea)`	Ustawia obszar z kodu
`procedure ClearArea`	Czyś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 CheckSearchConnection`	Sprawdza połączenie z serwerem wyszukiwania
`procedure NextStyle`	Nastę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)