दस्तावेज़ / मैप व्यू / MapView और स्टेट

MapView का जीवनचक्र और ईवेंट

नक्शा को दो चीजों से नियंत्रित किया जाता है: व्यू और स्टेट ऑब्जेक्ट। स्टेट (mapViewState) कैमरा, डिज़ाइन और इंटरैक्शन का इंटरफ़ेस है, जबकि व्यू को केवल प्रत्येक प्लेटफ़ॉर्म के UI ट्री में रखा जाता है। इनिशियलाइज़ेशन सामान्य चरणों में होता है, और लोडिंग पूरी होने और यूज़र इंटरैक्शन को ईवेंट के रूप में प्राप्त किया जाता है।

ANDROID

MapViewStateInterface

iOS

MapViewStateProtocol

REACT

MapViewStateInterface

डेमो देखेंस्टोर मैप · React ↗

प्लेटफ़ॉर्म

01 · mapViewState

mapViewState एक नक्शे के लिए स्टेट ऑब्जेक्ट है। प्रत्येक प्रोवाइडर का अपना कार्यान्वयन होता है, लेकिन सार्वजनिक सदस्य समान होते हैं, और ऐप कोड को केवल सामान्य इंटरफ़ेस पर ध्यान केंद्रित करने की आवश्यकता होती है।

स्टेट व्यू से अधिक समय तक जीवित रहता है। भले ही व्यू पुनः बनाया जाए, कैमरा स्थिति और डिज़ाइन स्टेट पक्ष में बनी रहती है, इसलिए नक्शा यथावत पुनर्स्थापित हो जाता है।

सदस्य

विवरण

स्टेट का पहचानकर्ता। यह व्यू के पुनर्निर्माण के बाद भी उसी नक्शे की ओर इशारा करता रहता है।

cameraPosition

वर्तमान कैमरा स्थिति। प्रदर्शन क्षेत्र (visibleRegion) भी यहीं से प्राप्त किया जा सकता है।

mapDesignType

वर्तमान मैप डिज़ाइन। असाइन करने पर यह तुरंत बदल जाता है।

moveCameraTo()

कैमरा को स्थानांतरित करता है। समय देने पर यह एनिमेट होता है।

fitBounds()

निर्दिष्ट सीमा के अनुरूप कैमरा को समायोजित करता है। तीनों प्लेटफ़ॉर्म पर यह स्टेट ऑब्जेक्ट की विधि है, जो आंतरिक रूप से कंट्रोलर को प्रतिनिधित्व देती है।

getMapViewHolder()

नेटिव मैप इंस्टेंस को लपेटे हुए होल्डर लौटाता है।

MapViewState · Jetpack Compose

// स्टेट remember* से बनाएँ, ताकि स्क्रीन घूमने पर भी वही मैप लौटे
val mapViewState =
    rememberGoogleMapViewState(
        mapDesign = GoogleMapDesign.Normal,
        cameraPosition = initCameraPosition,
    )

GoogleMapView(state = mapViewState, modifier = Modifier.fillMaxSize())

MapViewState · SwiftUI

// ObservableObject है: @StateObject से View में रखें
@StateObject private var mapLibreState = MapLibreViewState(
    mapDesignType: MapLibreDesign.OsmBright,
    cameraPosition: viewModel.initCameraPosition
)

MapLibreMapView(state: mapLibreState) { MapViewContent() }

MapViewState · React

const [mapViewState, setMapViewState] =
  useState<MapViewStateInterface<MapDesignTypeInterface<unknown>> | null>(null);

// MapViewContainer सैंपल ऐप का प्रोवाइडर बदलने वाला रैपर है — SDK के साथ नहीं आता
<MapViewContainer provider={provider} cameraPosition={INIT_CAMERA} onStateReady={setMapViewState}>
  <Markers states={markerStates} />
</MapViewContainer>

02 · इनिशियलाइज़ेशन का जीवनचक्र

नक्शे का इनिशियलाइज़ेशन किसी भी प्रोवाइडर के लिए समान चरणों का अनुसरण करता है। SDK लोड होना, व्यू बनना, मैप इंस्टेंस बनना, और फिर टाइल्स रेंडरिंग पूरा होना। चरणों को InitState के रूप में सामान्यीकृत किया गया है, इसलिए आपको "अभी तक हेरफेर नहीं करने की अवधि" को प्रोवाइडर के आधार पर याद रखने की आवश्यकता नहीं है।

कैमरा ऑपरेशन और ओवरले जोड़ना MapCreated के बाद स्वीकार किए जाते हैं और आंतरिक रूप से कतारबद्ध होते हैं। लोडिंग पूरी होने का इंतज़ार करने के बाद कुछ करने के लिए onMapLoaded का उपयोग करें।

चित्र · InitState कैसे आगे बढ़ता है

NotStarted

अभी कुछ शुरू नहीं हुआ है।

Initializing

इनिशियलाइज़ेशन शुरू होता है — कुंजी की जाँच और SDK का लोड होना।

SdkInitialized

मैप SDK खुद लोड हो चुका है।

MapViewCreated

प्लेटफ़ॉर्म व्यू (MapView / UIView / DOM एलिमेंट) बन जाता है।

MapCreating

व्यू के भीतर मैप इंस्टेंस बनाया जा रहा है।

MapCreated

मैप इंस्टेंस उपयोग लायक है; कैमरा मूव और ओवरले लगने लगते हैं।

MapLoaded

टाइल खिंच चुकी हैं। onMapLoaded इसी चरण पर चलता है।

Failed

इनिशियलाइज़ेशन विफल — गलत कुंजी, नेटवर्क का न होना, वगैरह।

ये चरण Android, iOS और React पर एक ही enumeration के रूप में घोषित हैं, इसलिए प्रोवाइडर बदलने पर आप जिसका इंतज़ार करते हैं वह नहीं बदलता।

01 sdkInitialize

मानचित्र SDK लोड करता है। वेब पर स्क्रिप्ट इंजेक्शन, मोबाइल पर आरंभीकरण प्रक्रिया। विफल होने पर Failed में आगे बढ़ता है।

02 createHolder

नेटिव मानचित्र इंस्टैंस को होल्डर में लपेटता है। इसके बाद, SDK-विशिष्ट प्रकार यहां छिप जाते हैं।

03 createController

होल्डर को कंट्रोलर से लपेटता है और सामान्य API और इवेंट वायरिंग तैयार करता है। स्थिति से कंट्रोलर जुड़ा होता है।

RESTORE

स्क्रीन रोटेशन / पुनर्निर्माण के पार

Android में स्थिति rememberSaveable में सहेजी जाती है, और स्क्रीन रोटेशन या कॉन्फ़िगरेशन बदलने के बाद भी कैमरा की स्थिति और डिज़ाइन पुनर्स्थापित होता है। कॉन्फ़िगरेशन बदलने के दौरान मानचित्र दृश्य को नष्ट नहीं करके पुन: उपयोग किया जाता है।

TEARDOWN

नष्ट किए जाने पर

वास्तविक निस्तारण (स्क्रीन छोड़ना) में कंट्रोलर द्वारा ओवरले प्रबंधन, टाइल सर्वर के मार्ग, और कोरूटीन स्कोप को एक साथ मुक्त किया जाता है। प्रदाता बदलने पर भी उसी मार्ग से पुराना मानचित्र साफ़ किया जाता है।

वीडियो में दिखाया गया कार्यान्वयन · Android + MapLibreKotlin · Jetpack Compose

var ready by remember { mutableStateOf(false) }

MapLibreMapView(
    state = mapViewState,
    // Called once, when the tiles have finished drawing
    onMapLoaded = { state ->
        ready = true
        state.fitBounds(routeBounds, padding = 48)
    },
) {
    // Declarations here are not lost before MapCreated — they are queued internally
    Marker(markerState)
}

if (!ready) {
    // Your own loading overlay, if you want one. The map does not need blocking
    Box(Modifier.fillMaxSize()) { CircularProgressIndicator() }
}

सैंपल वीडियो · इनिशियलाइज़ेशन की प्रगति

वीडियो अभी नहीं बनानक्शा बनने के बाद से ऑपरेशन स्वीकार करने तक, InitState के चरणबद्ध रूप से आगे बढ़ने का दृश्य। लोडिंग के दौरान का प्रदर्शन और बदलने का समय देखने से समझना आसान हो जाता है।

03 · ईवेंट

व्यू को पास किए जाने वाले हैंडलर तीनों प्लेटफ़ॉर्म पर समान संरचना के होते हैं। प्रकार भी समान हैं, लोडिंग पूरी होना स्टेट ऑब्जेक्ट प्राप्त करता है, टैप निर्देशांक प्राप्त करता है, और कैमरा परिवर्तन कैमरा स्थिति प्राप्त करता है।

ईवेंट

प्राप्त मान

विवरण

onMapLoaded

MapViewState

मानचित्र लोड पूरा हुआ। तर्क स्थिति वस्तु को रखना और बाद के संचालन के लिए उपयोग करना एक आदर्श अभ्यास है।

onMapClick

GeoPoint

मानचित्र टैप। सूचना बुलबुले को बंद करने, पिन लगाने आदि के लिए।

onMapLongClick

GeoPoint

लंबा दबाव।

onCameraMoveStart

MapCameraPosition

कैमरा संचालन शुरू। इसे उपयोगकर्ता संचालन और प्रोग्राम स्थानांतरण दोनों पर बुलाया जाता है।

onCameraMove

MapCameraPosition

स्थानांतरण के दौरान लगातार बुलाया जाता है। प्रदर्शित निर्देशांक प्रदर्शन आदि के लिए।

onCameraMoveEnd

MapCameraPosition

जब स्थानांतरण रुक जाता है। डेटा पुनः प्राप्त करना मूल रूप से यहीं किया जाता है।

GoogleMapView · ईवेंट प्राप्त करना

GoogleMapView(
    state = mapViewState,
    onMapLoaded = { state -> viewModel.onMapLoaded(state) },
    onMapClick = { point -> viewModel.onMapClick(point) },
    onCameraMove = { camera -> viewModel.onCameraChanged(camera) },
    onCameraMoveEnd = { camera -> viewModel.onCameraSettled(camera) },
) { /* markers, overlays */ }

MapLibreMapView · ईवेंट प्राप्त करना

MapLibreMapView(
    state: mapLibreState,
    onMapLoaded: { state in viewModel.onMapLoaded(state) },
    onCameraMoveStart: viewModel.onMapCameraMoveStart,
    onCameraMove: viewModel.onCameraChanged,
    onCameraMoveEnd: viewModel.onMapCameraMoveEnd
) {
    MapViewContent()
}

MapViewBaseProps · ईवेंट प्राप्त करना

<MapViewContainer
  provider={provider}
  cameraPosition={INIT_CAMERA}
  onMapClick={() => setSelected(null)}
  onCameraMove={setCameraPosition}
>
  <Markers states={markerStates} />
</MapViewContainer>

कैमरा प्रकार के ईवेंट स्थिति वस्तु के cameraPosition को भी एक साथ अपडेट करते हैं, इसलिए हैंडलर लगाए बिना भी नवीनतम कैमरा हमेशा पढ़ा जा सकता है। स्थानांतरण के दौरान पुनः प्राप्त करने से बचना चाहते हैं तो कृपया केवल onCameraMoveEnd का उपयोग करें।

04 · नेटिव के लिए भागने का रास्ता

सामान्य API के पर्याप्त न होने पर, नेटिव मानचित्र इंस्टेंस पर जाने के लिए एक रास्ता तैयार किया गया है। आमतौर पर इसका उपयोग नहीं किया जाता है, लेकिन यदि आप प्रदाता-विशिष्ट सुविधा का उपयोग केवल एक जगह पर करना चाहते हैं तो यह एक भागने का रास्ता है।

MapViewHolder

नेटिव मानचित्र को लपेटने वाला होल्डर

होल्डर में प्लेटफ़ॉर्म का व्यू और मानचित्र इंस्टैंस — ये दो चीज़ें होती हैं। SDK-विशिष्ट कोड को यहां से आगे कैद करके, सामान्य कोड में लीक न होने देने की व्यवस्था है।

toScreenOffset / fromScreenOffset

निर्देशांक और स्क्रीन स्थिति का रूपांतरण

भौगोलिक निर्देशांक और स्क्रीन पर पिक्सेल स्थिति को आपस में बदला जा सकता है। मानचित्र के ऊपर कस्टम UI ओवरले करते समय इसका उपयोग किया जाता है।

होल्डर निकालना

// सिर्फ़ तभी निकालें जब नेटिव API सचमुच चाहिए
val holder = mapViewState.getMapViewHolder()
val nativeMap = holder?.map // GoogleMap / MapLibreMap / ...
val offset = holder?.toScreenOffset(point)

होल्डर निकालना

if let holder = mapViewState.getMapViewHolder() {
    let nativeMap = holder.map
    let offset = holder.toScreenOffset(position: point)
}

होल्डर निकालना

const holder = mapViewState.getMapViewHolder();
const nativeMap = holder?.map; // google.maps.Map / maplibregl.Map / ...

होल्डर का उपयोग करने वाला कोड प्रदाता पर निर्भर करता है। सामान्य रूप से बनाए रखने के लिए भाग और जानबूझकर विशिष्ट API का उपयोग करने वाले भाग को ध्यान से अलग करें।

MapView का जीवनचक्र और ईवेंट

01 · mapViewState

02 · इनिशियलाइज़ेशन का जीवनचक्र

स्क्रीन रोटेशन / पुनर्निर्माण के पार

नष्ट किए जाने पर

03 · ईवेंट

04 · नेटिव के लिए भागने का रास्ता

नेटिव मानचित्र को लपेटने वाला होल्डर

निर्देशांक और स्क्रीन स्थिति का रूपांतरण

संबंधित पेज

कैमरा

मानचित्र डिज़ाइन (टाइल)

प्रदाता बदलें