Opis
Komponent niewidoczny, który rysuje obszary z plików GeoJSON na mapie (kafelkowej i 3D). Wybór jest hierarchiczny: Cały świat → kontynenty → państwa. W Object Inspectorze kontynenty i państwa zaznaczasz w drzewie z polami wyboru.
Moduł: MapCommon.Areas · Klasa bazowa: TComponent · Platformy: VCL + FMX
Demo na żywo
Województwa Polski, kraje Europy Środkowej lub cały świat; podświetlenie, OnAreaClick, kolory na żywo.
Funkcje
ShowAdministrative+AdminLevel(malCountry / malAdmin1 / malAdmin2); Polska + admin-1 = województwa.- Admin-2: geoBoundaries ADM2 per kraj (CC BY 4.0) – nie ma na serwerze map.
SettingsFile/ AutoLoad / AutoSave (JSON) + localStorage w stronie.WholeWorld: wszystkie państwa świata (WorldDetail: państwa lub regiony admin-1).Continents: zbiór kontynentów (macEurope,macAfrica,macAsia,macNorthAmerica,macCentralAmerica,macSouthAmerica,macOceania).Countries: filtr kodów ISO-2 (np.PL,CZ,SK); pliki kontynentów dobierane automatycznie.- Edytor w IDE: drzewo Świat → kontynenty → państwa z polami wyboru.
- Styl: kolor i krycie wypełnienia, linia, podświetlenie po najechaniu, etykiety.
- Pamięć podręczna plików (
CacheFolder,UseCache) i kontrola wersji danych (CheckVersion). - Własne pliki GeoJSON:
LoadFromFile,LoadFromURL,LoadFromString.
Brak osobnego pliku Antarktydy – jest widoczna tylko przy
WholeWorld.Pliki pobierane są w częściach (chunked) do strony mapy i trzymane w pamięci podręcznej.
Pliki danych
Pliki GeoJSON z serwera https://mapa.imetroll.com/geojson/, dobierane według hierarchii:
| Wybór | Plik | Zawartość | Rozmiar |
|---|---|---|---|
| WholeWorld (mwdCountries) | countries.geojson | 258 państw | 14,6 MB |
| WholeWorld (mwdProvinces) | ne_10m_admin_1_states_provinces.geojson | regiony admin-1 świata | 40,7 MB |
| macEurope | europe_full.geojson | państwa + regiony | 33,8 MB |
| macAfrica | africa_full.geojson | państwa + regiony | 21,5 MB |
| macAsia | asia_full.geojson | państwa + regiony | 53,8 MB |
| macNorthAmerica | north_america_full.geojson | państwa + regiony | 23,2 MB |
| macCentralAmerica | central_america_full.geojson | państwa + regiony | 3,9 MB |
| macSouthAmerica | south_america_full.geojson | państwa + regiony | 15,0 MB |
| macOceania | oceania_full.geojson | państwa + regiony | 6,3 MB |
Wersja danych: versiongeojson.json (sprawdzana przy CheckVersion = True).
Właściwości
| Właściwość | Opis |
|---|---|
| WholeWorld, WorldDetail | Cały świat; poziom szczegółów. |
| Continents | Zbiór kontynentów (edytor drzewa). |
| ShowAdministrative, AdminLevel, Admin2BaseURL | Jawne granice admin: malCountry / malAdmin1 / malAdmin2 (geoBoundaries CC BY 4.0). Polska + admin-1 = województwa. |
| CountryStyle, Admin1Style, Admin2Style | Wypełnienie / obrys / grubość per poziom. |
| SettingsFile, AutoLoad, AutoSave | JSON map-areas-settings v1; AutoSave przy każdej zmianie; localStorage w stronie. |
| Countries | Kody ISO-2 oddzielone przecinkami (edytor drzewa). |
| ShowCountryOutlines, ShowRegions | Granice państw, regiony wewnętrzne. |
| HierarchyStyle | Styl obszarów z hierarchii (FillColor, FillOpacity, LineColor, LabelProperty…). |
| Items | Dodatkowe zestawy obszarów (własne pliki). |
| CacheFolder, UseCache, CheckVersion | Pamięć podręczna i wersja danych. |
| Timeout, FitOnLoad, Active | Limit czasu pobierania, dopasowanie widoku, włączenie. |
Zdarzenia
| Zdarzenie | Opis |
|---|---|
| OnAreaClick | Kliknięcie obszaru: kod ISO-2, nazwa, właściwości JSON. |
| OnAreaHover | Najechanie na obszar. |
| OnAreaLoaded | Zestaw wczytany i narysowany. |
| OnValidationError | Plik GeoJSON odrzucony. |
Metody
| Metoda | Opis |
|---|---|
| ShowCountry, FitToArea | Pokaż państwo / dopasuj widok. |
| LoadFromFile, LoadFromURL, LoadFromString | Własne dane. |
| BeginUpdate, EndUpdate, Refresh | Zmiany grupowe, przerysowanie. |
| ClearCache, Clear | Pamięć podręczna, usunięcie zestawów. |
Przykłady
Świat, kontynenty, państwa
// cały świat – 258 państw
MapAreas1.WholeWorld := True;
MapAreas1.WorldDetail := mwdCountries; // mwdProvinces = regiony admin-1
// wybrane kontynenty
MapAreas1.WholeWorld := False;
MapAreas1.Continents := [macEurope, macAfrica];
MapAreas1.ShowCountryOutlines := True;
MapAreas1.ShowRegions := True; // regiony wewnątrz państw
// konkretne państwa (kontynent wynika z kodów ISO)
MapAreas1.BeginUpdate;
try
MapAreas1.Continents := [];
MapAreas1.Countries := 'PL,CZ,SK';
finally
MapAreas1.EndUpdate;
end;
MapAreas1.ShowCountry('PL'); // filtr + przybliżenieZdarzenia i własne pliki
procedure TForm1.MapAreas1AreaClick(Sender: TObject; const SetId: string;
const Lat, Lon: Double; const CountryISO2, FeatureName, PropertiesJSON: string);
begin
Caption := FeatureName + ' (' + CountryISO2 + ')';
end;
// własny plik GeoJSON, np. strefy dostaw
Item := MapAreas1.LoadFromFile('C:\dane\strefy.geojson', 'Strefy dostaw');
Item.Style.FillColor := '#2e7d32';
Item.Style.FillOpacity := 0.2;
MapAreas1.FitToArea(Item);Pełna lista API
Generowana z deklaracji w kodzie (Source/*.pas): wszystkie opublikowane właściwości i zdarzenia TMapAreas (także dziedziczone), właściwości publiczne i metody publiczne.
Właściwości opublikowane (25)
| Właściwość | Typ | Domyślnie | Opis |
|---|---|---|---|
Active | Boolean | True | False = nic nie jest wczytywane ani pokazywane |
EditPopupEnabled | Boolean | True | RMB + long-press (~500 ms) otwierają edytor stylu obszaru; False wyłącza oba |
Edit | TEditMapRaster | ||
AutoLinkComponents | Boolean | True | Automatycznie łącz pierwszy dostawcę wyszukiwania / TMapAreas / TEditMap z formy |
WholeWorld | Boolean | False | Cały świat w jednym pliku (państwa lub admin-1) |
WorldDetail | TMapWorldDetail | mwdCountries | mwdCountries / mwdAdmin1 dla WholeWorld |
Continents | TMapAreaContinents | [] | Kontynenty do wczytania (zestaw) |
Countries | string | Filtr ISO w wybranych kontynentach (np. PL,DE,CZ) | |
ShowCountryOutlines | Boolean | True | Obrysy państw / regionów admin-1 z plików kontynentów |
ShowRegions | Boolean | False | Wypełnienie regionów |
HierarchyStyle | TMapAreaStyle | Styl hierarchii (wypełnienie, obrys, grubość, etykiety) | |
ShowAdministrative | Boolean | False | Jawne granice administracyjne wybranych państw na poziomie AdminLevel |
AdminLevel | TMapAdminLevel | malCountry | malCountry / malAdmin1 (województwa, Natural Earth) / malAdmin2 (powiaty, geoBoundaries) |
CountryStyle | TMapAreaStyle | Styl poziomu państw (wypełnienie, kolor obrysu, grubość) | |
Admin1Style | TMapAreaStyle | Styl poziomu admin-1 | |
Admin2Style | TMapAreaStyle | Styl poziomu admin-2 | |
SettingsFile | string | Plik JSON ustawień (map-areas-settings v1) | |
AutoLoad | Boolean | True | Wczytaj SettingsFile przy otwarciu |
AutoSave | Boolean | False | Zapisuj SettingsFile po każdej zmianie |
Items | TMapAreaItems | Własne pliki / URL / teksty GeoJSON (kolekcja ze stylem) | |
CacheFolder | string | Folder cache GeoJSON ('' = folder danych aplikacji) | |
UseCache | Boolean | True | Używaj cache plików |
CheckVersion | Boolean | True | Porównuj versiongeojson.json z cache (raz na uruchomienie) |
Timeout | Integer | 60000 | Limit czasu pobierania (ms) |
FitOnLoad | Boolean | False | Dopasuj widok po wczytaniu |
Zdarzenia (6)
| Zdarzenie | Typ | Opis |
|---|---|---|
OnAreaClick | TMapAreaEvent | Kliknięcie obszaru (SetId, Lat, Lon, właściwości) |
OnAreaHover | TMapAreaEvent | Najechanie na obszar |
OnAreaLoaded | TMapAreaLoadedEvent | Zestaw wczytany (liczba obiektów / błąd) |
OnValidationError | TMapAreaValidationEvent | Błąd walidacji GeoJSON / ustawień |
OnSettingsLoaded | TNotifyEvent | Wczytano plik ustawień |
OnSettingsSaved | TNotifyEvent | Zapisano plik ustawień |
Właściwości publiczne – tylko w kodzie (3)
| Właściwość | Typ | Opis |
|---|---|---|
BaseURL | string | Adres katalogu GeoJSON (tylko w kodzie) |
Admin2BaseURL | string | Szablon URL ADM2 ({ISO}/{iso}); domyślnie geoBoundaries (CC BY 4.0) |
ServerVersion | string | Wersja danych na serwerze |
Metody publiczne (22)
| Metoda | Opis |
|---|---|
procedure AttachAreasTarget(const Target: IMapAreasTarget) | Wewnętrzne: rejestracja mapy |
procedure DetachAreasTarget(const Target: IMapAreasTarget) | Wewnętrzne: wyrejestrowanie mapy |
procedure ReplayAreasTo(const Target: IMapAreasTarget) | Wewnętrzne: odtworzenie zestawów na mapie |
procedure BeginUpdate | Wstrzymuje przebudowę do EndUpdate |
procedure EndUpdate | Przebudowuje po zmianach |
procedure Refresh | Ponownie wczytuje hierarchię i pliki |
function LoadFromFile(const FileName: string; const ACaption: string = ''): TMapAreaItem | Dodaje własny plik GeoJSON |
function LoadFromURL(const URL: string; const ACaption: string = ''): TMapAreaItem | Dodaje GeoJSON z URL |
function LoadFromString(const GeoJSON: string; const ACaption: string = ''): TMapAreaItem | Dodaje GeoJSON z tekstu |
procedure Clear | Usuwa własne pliki |
procedure FitToArea(const SetId: string; PaddingPx: Integer = 30; const MaxZoom: Double = 12) | Dopasowuje widok do zestawu |
procedure ShowCountry(const ISO: string) | Wybiera państwo i przybliża |
function HierarchySetIds: TArray<string> | Identyfikatory zestawów hierarchii |
function HierarchyState(const SetId: string): TMapAreaState | Stan zestawu (pobieranie / gotowy / błąd) |
procedure ClearCache | Usuwa pliki z cache |
function SaveToJSON(Indent: Integer = 2): string | Ustawienia jako JSON (map-areas-settings v1) |
function LoadFromJSON(const JSONText: string): Boolean | Stosuje ustawienia z JSON |
function SaveSettingsToFile(const FileName: string = ''): Boolean | Zapisuje ustawienia do pliku |
function LoadSettingsFromFile(const FileName: string = ''): Boolean | Wczytuje ustawienia z pliku |
procedure EnsureAutoLoaded | Wykonuje AutoLoad teraz |
procedure ShowAdministrativeCountry(const ISO: string; Level: TMapAdminLevel = malAdmin1) | Pokazuje państwo z podziałem (np. PL + województwa) |
function GetAreaFileText(const FileName: string; out Text, ErrorMessage: string): Boolean |
Pełny opis wszystkich właściwości: dokumentacja komponentów map.
