PlaceSearchElement की मदद से जगह की जानकारी ढूंढना

मकसद

Google Maps के साथ PlaceSearchElement को इंटिग्रेट करने का तरीका जानें, ताकि उपयोगकर्ता आस-पास की जगहें खोजने या टेक्स्ट खोज का इस्तेमाल करके जगहें ढूंढ सकें. इससे उन्हें दिलचस्पी की जगहों को एक्सप्लोर करने में मदद मिलेगी. अपने ऐप्लिकेशन में दिखाई गई जगहों के बारे में ज़्यादा जानकारी देने के लिए, 'जगह की जानकारी देने वाला कॉम्पैक्ट एलिमेंट' का इस्तेमाल करें.

PlaceSearchElement क्या है?

PlaceSearchElement, Maps JavaScript API में जगहों की जानकारी देने वाली यूआई किट का हिस्सा है. यह एक एचटीएमएल एलिमेंट है. यह किसी जगह की खोज के नतीजों को सीधे तौर पर आपके ऐप्लिकेशन में सूची के फ़ॉर्मैट में रेंडर करता है. इस एलिमेंट की मदद से, आस-पास की जगहों की जानकारी या टेक्स्ट से खोजें का इस्तेमाल करके मिली जगहों को आसानी से दिखाया जा सकता है. इससे लोगों को जगहें खोजने का बेहतर उपयोगकर्ता अनुभव मिलता है. जब कोई उपयोगकर्ता सूची में से किसी जगह को चुनता है, तो मैप पर उसकी जानकारी दिखाई जा सकती है. इसके लिए, अक्सर जानकारी वाली विंडो और Place Details एलिमेंट का इस्तेमाल किया जाता है.

जगह की खोज को विज़ुअलाइज़ करना

नीचे दी गई इमेज में, PlaceSearchElement का एक उदाहरण दिखाया गया है. बाईं ओर, रेस्टोरेंट की सूची दिखाई गई है (PlaceSearchElement). किसी रेस्टोरेंट को चुनने पर, उसकी जानकारी मैप पर मौजूद जानकारी वाली विंडो में दिखती है. साथ ही, मैप उस रेस्टोरेंट की जगह पर दिखता है.

जगह की जानकारी खोजने की सुविधा के इस्तेमाल के उदाहरण

PlaceSearchElement को इंटिग्रेट करने से, अलग-अलग इंडस्ट्री के कई ऐप्लिकेशन बेहतर बनाए जा सकते हैं:

• यात्रा और पर्यटन: पर्यटकों को किसी इलाके में घूमने-फिरने की जगहों, होटलों या खास तरह के पकवानों को खोजने की अनुमति दें.
• रीयल एस्टेट: संभावित खरीदारों या किरायेदारों को आस-पास के स्कूल, सुपरमार्केट या सार्वजनिक परिवहन के विकल्प ढूंढने की सुविधा दें.
• लॉजिस्टिक्स और सेवाएं: ड्राइवर को ईवी चार्जिंग स्टेशन, गैस स्टेशन या सर्विस सेंटर ढूंढने में मदद करना.

समस्या हल करने का वर्कफ़्लो: जगह की जानकारी खोजने की सुविधा लागू करना

इस सेक्शन में, मैप पर जगहों की जानकारी पाने के लिए PlaceSearchElement को इंटिग्रेट करने का तरीका बताया गया है. इसमें जगहों की जानकारी देने वाली यूआई किट के साथ इंटरैक्ट करने के लिए कोड स्निपेट भी शामिल हैं. मैप को शुरू करने और आस-पास की जगहों को खोजने और टेक्स्ट से खोजने की सुविधा को लागू करने का तरीका जानें. आखिर में, Place Details एलिमेंट का इस्तेमाल करें. इससे, जब कोई उपयोगकर्ता मैप पर किसी जगह के पिन पर क्लिक करता है, तो उसे उस जगह के बारे में ज़्यादा जानकारी दिखती है.

ज़रूरी शर्तें

हमारा सुझाव है कि आप इन दस्तावेज़ों को पढ़ लें:

• PlaceSearchElement - इसका इस्तेमाल, आस-पास की जगहों की जानकारी या टेक्स्ट खोज की सुविधा का इस्तेमाल करके जगहों की जानकारी दिखाने के लिए किया जाता है
• जगह की जानकारी देने वाला एलिमेंट - इसका इस्तेमाल किसी जगह की जानकारी दिखाने के लिए किया जाता है
• Maps JavaScript API - इसका इस्तेमाल आपके पेज पर मैप दिखाने और जगहों की जानकारी देने वाली यूआई किट को इंपोर्ट करने के लिए किया जाता है

अपने प्रोजेक्ट में Maps JavaScript API और Places UI Kit चालू करें.

शुरू करने से पहले, पुष्टि करें कि आपने Maps JavaScript API लोड कर लिया हो और ज़रूरी लाइब्रेरी इंपोर्ट कर ली हों. इस दस्तावेज़ में यह भी माना गया है कि आपको वेब डेवलपमेंट की बुनियादी जानकारी है. जैसे, एचटीएमएल, सीएसएस, और JavaScript.

पेज में मैप जोड़ना

सबसे पहले, अपने पेज में मैप जोड़ें. इस मैप का इस्तेमाल, PlaceSearchElement के नतीजों को चुनने लायक पिन के तौर पर दिखाने के लिए किया जाएगा.

किसी पेज में मैप जोड़ने के दो तरीके हैं:

1. gmp-map एचटीएमएल वेब कॉम्पोनेंट का इस्तेमाल करके.
2. JavaScript का इस्तेमाल करके.

इस पेज पर मौजूद कोड स्निपेट, JavaScript मैप का इस्तेमाल करके जनरेट किए गए थे.

मैप को किसी ऐसी जगह पर सेंटर किया जा सकता है जिसके आस-पास उपयोगकर्ता को खोज करनी है. जैसे, कोई होटल. इसके अलावा, मैप को इस तरह से शुरू किया जा सकता है कि वह उपयोगकर्ता से उसकी मौजूदा जगह की जानकारी मांगे, ताकि मैप को सेंटर किया जा सके. इस दस्तावेज़ के लिए, हम खोज को ऐंकर करने के लिए एक तय जगह का इस्तेमाल करेंगे.

अगर आपको किसी तय जगह, जैसे कि होटल के आस-पास की जगहों को विज़ुअलाइज़ करना है, तो इस जगह को दिखाने के लिए मैप पर मार्कर लगाएं. उदाहरण के लिए:

मैप में सैन फ़्रैंसिस्को को सेंटर में दिखाया गया है. साथ ही, नीले पिन से उस जगह को दिखाया गया है जिसे हम आस-पास खोज रहे हैं. पिन के रंग को PinElement का इस्तेमाल करके पसंद के मुताबिक बनाया गया है. मैप टाइप कंट्रोल को यूज़र इंटरफ़ेस (यूआई) से छिपा दिया गया है.

PlaceSearchElement सेट अप करें

अब PlaceSearchElement को दिखाने के लिए, एचटीएमएल और सीएसएस सेट अप करें. इस उदाहरण में, एलिमेंट को मैप की बाईं ओर फ़्लोट किया गया है. हालांकि, अपने ऐप्लिकेशन के हिसाब से अलग-अलग लेआउट आज़माए जा सकते हैं.

PlaceSearchElement में डिक्लेरेटिव अप्रोच का इस्तेमाल किया जाता है. इसे पूरी तरह से JavaScript में कॉन्फ़िगर करने के बजाय, सीधे तौर पर अपने एचटीएमएल में खोज का टाइप तय करें. इसके लिए, मुख्य <gmp-place-search> कॉम्पोनेंट में <gmp-place-nearby-search-request> जैसे अनुरोध एलिमेंट को नेस्ट करें.

अपने एचटीएमएल कोड में, <gmp-place-search> एलिमेंट को शुरू करें. नतीजों पर क्लिक इवेंट चालू करने के लिए, selectable एट्रिब्यूट का इस्तेमाल करें. इसमें <gmp-place-nearby-search-request> जोड़ें, ताकि यह पता चल सके कि इस एलिमेंट का इस्तेमाल आस-पास की खोज के लिए किया जाएगा.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

शुरुआती खोज करने और नतीजे दिखाने के लिए, हम JavaScript का इस्तेमाल करके नेस्ट किए गए अनुरोध एलिमेंट का रेफ़रंस पाएंगे और उसकी प्रॉपर्टी सेट करेंगे. locationRestriction के तौर पर इस्तेमाल करने के लिए, एक सर्कल शुरू करें. इसके लिए, पिछले चरण में मार्कर की पोज़िशन को केंद्र बिंदु के तौर पर इस्तेमाल करें. इसके बाद, खोज को ट्रिगर करने के लिए, अनुरोध एलिमेंट पर locationRestriction और includedPrimaryTypes प्रॉपर्टी सेट करें.

इसके लिए कोड स्निपेट यहां दिया गया है:

// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");

// Define the location restriction for the search
const circleRestriction = new Circle({
    center: marker.position,
    radius: 500
});

// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];

इस चरण में, आवेदन कैसा दिख सकता है, इसका उदाहरण यहां दिया गया है:

उपयोगकर्ता को खोजने की अनुमति दें

PlaceSearchElement में खोज के दो विकल्प मिलते हैं:

• <gmp-place-nearby-search-request> - जगह के टाइप का इस्तेमाल करके, आस-पास की जगहों के लिए खोज के नतीजे रेंडर करता है.
• <gmp-place-text-search-request> - जगहों के बारे में टेक्स्ट से खोजें से खोज के नतीजे रेंडर करता है. इसके लिए, "सैन फ़्रांसिस्को में सुशी" जैसे फ़्री टेक्स्ट इनपुट का इस्तेमाल किया जाता है.

ये <gmp-place-search> के अंदर नेस्ट किए गए एलिमेंट हैं. इसके बाद, JavaScript का इस्तेमाल करके उस नेस्ट किए गए अनुरोध एलिमेंट पर प्रॉपर्टी सेट करके, खोजों को ट्रिगर किया जाता है.

इस सेक्शन में, दोनों तरीकों को लागू करने का तरीका बताया गया है.

आस-पास की जगहों की जानकारी

उपयोगकर्ताओं को आस-पास की जगहें खोजने की सुविधा देने के लिए, आपको सबसे पहले उनके लिए एक यूज़र इंटरफ़ेस (यूआई) एलिमेंट की ज़रूरत होगी. इससे वे जगह का टाइप चुन पाएंगे. अपने ऐप्लिकेशन के लिए, चुनने का सबसे सही तरीका चुनें. उदाहरण के लिए, जगह के टाइप चुनने के लिए ड्रॉप-डाउन सूची.

हमारा सुझाव है कि आप अपने इस्तेमाल के उदाहरण के हिसाब से, टाइप का सबसेट चुनें. उदाहरण के लिए, अगर आपको ऐसा ऐप्लिकेशन बनाना है जो पर्यटकों को होटल के आस-पास की जगहें दिखाए, तो आपको ये विकल्प चुनने चाहिए: bakery, coffee_shop, museum, restaurant, और tourist_attraction.

आपके एचटीएमएल में <gmp-place-search> एलिमेंट होना चाहिए, जिसमें <gmp-place-nearby-search-request> नेस्ट किया गया हो.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

इसके बाद, जगह के टाइप चुनने वाले कंट्रोल पर change इवेंट के लिए JavaScript लिसनर बनाएं. यह लिसनर, एक ऐसे फ़ंक्शन को कॉल करेगा जो <gmp-place-nearby-search-request> एलिमेंट की प्रॉपर्टी को अपडेट करता है. इससे, नई खोज अपने-आप ट्रिगर हो जाती है और सूची अपडेट हो जाती है.

// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');

// Function to update the place search based on the selected type
function updatePlaceList() {
    const selectedType = placeTypeSelect.value;
    if (!selectedType) {
        // If no type is selected, don't perform a search.
        // You could optionally hide the list or clear previous results here.
        placeSearchElement.style.display = 'none';
        return;
    }
    placeSearchElement.style.display = 'block';

    // Set properties on the request element to trigger a new search
    placeSearchRequestElement.locationRestriction = searchCircle;
    placeSearchRequestElement.maxResultCount = 8;
    placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}

सेटअप चरण में इस्तेमाल किया गया searchCircle, locationRestriction के लिए भी इस्तेमाल किया जाता है. includedPrimaryTypes प्रॉपर्टी को उपयोगकर्ता के चुने गए विकल्प के हिसाब से सेट किया जाता है. नतीजों की संख्या सीमित करने के लिए, एक वैकल्पिक maxResultCount भी सेट किया जाता है.

टेक्स्ट से खोजें

टेक्स्ट खोज की सुविधा चालू करने के लिए, आपको अपने एचटीएमएल कॉन्फ़िगरेशन में बदलाव करना होगा. आस-पास की जगहों को खोजने के अनुरोध के बजाय, <gmp-place-text-search-request> एलिमेंट को नेस्ट करें.

<gmp-place-search selectable>
  <gmp-place-text-search-request>
  </gmp-place-text-search-request>
</gmp-place-search>

अपने यूज़र इंटरफ़ेस (यूआई) में टेक्स्ट इनपुट और खोज बटन जोड़ें. बटन के click इवेंट के लिए, JavaScript लिसनर बनाएं. इवेंट हैंडलर, उपयोगकर्ता के इनपुट को लेगा और खोज करने के लिए, <gmp-place-text-search-request> एलिमेंट की प्रॉपर्टी अपडेट करेगा.

// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');

textSearchButton.addEventListener('click', performTextSearch);

function performTextSearch() {
    const query = textSearchInput.value.trim();
    if (!query) {
        console.log("Search query is empty.");
        return;
    }
    // Set properties on the request element to trigger a new search
    placeTextSearchRequestElement.textQuery = query;
    placeTextSearchRequestElement.locationBias = map.getBounds();
    placeTextSearchRequestElement.maxResultCount = 8;
}

यहां, हम उपयोगकर्ता के इनपुट के साथ textQuery प्रॉपर्टी सेट करते हैं. हम मौजूदा मैप बाउंड्री का इस्तेमाल करके locationBias भी उपलब्ध कराते हैं. इससे एपीआई को उस इलाके के नतीजे दिखाने के लिए कहा जाता है. हालांकि, ऐसा करना ज़रूरी नहीं होता. ज़रूरी नहीं है maxResultCount से, दिखाए गए नतीजों की संख्या सीमित की जाती है.

जगह के पिन और जानकारी दिखाना

अब ऐप्लिकेशन, जगह की जानकारी खोज सकता है और एलिमेंट को भर सकता है. अगले चरण में, हम इसकी सुविधाओं को बेहतर बनाएंगे. इसके लिए, हम ये काम करेंगे:

• PlaceSearchElement में मौजूद हर जगह के लिए, मैप पर पिन दिखाना.
• उपयोगकर्ता को किसी जगह के बारे में ज़्यादा जानकारी दिखाने के लिए, PlaceSearchElement में मौजूद किसी पिन या जगह पर क्लिक करने की अनुमति देना.

इस चरण का सिद्धांत एक जैसा होता है. भले ही, ऐप्लिकेशन आस-पास की जगहें खोजने की सुविधा का इस्तेमाल कर रहा हो या टेक्स्ट खोज की सुविधा का.

सबसे पहले, अपने JavaScript कोड में एक ग्लोबल वैरिएबल जोड़ें, ताकि प्लेस मार्कर सेव किए जा सकें. इससे आपको खोज के नतीजे बदलने पर, उन्हें हटाने और क्लिक इवेंट मैनेज करने में मदद मिलेगी.

let markers = {};

मैप में मार्कर जोड़ने के लिए, एक फ़ंक्शन बनाएं. खोज के नए नतीजे लोड होने पर, इस फ़ंक्शन को कॉल किया जाएगा. इससे:

• मैप से, जगह के सभी मौजूदा मार्कर हटाएं.
• PlaceSearchElement से मिले नतीजों को लूप करें और हर नतीजे के लिए एक मार्कर जोड़ें.
• मैप की सीमाओं को इस तरह से अडजस्ट करें कि सभी नए मार्कर दिखें.

खोज के नतीजे उपलब्ध होने पर सुनने के लिए, <gmp-place-search> एलिमेंट में gmp-load इवेंट लिसनर जोड़ें. यह इवेंट, खोज पूरी होने और नतीजे रेंडर होने के बाद ट्रिगर होता है.

हम लिसनर को अपनी खोज सुविधा (जैसे, updatePlaceList) में जोड़ेंगे. साथ ही, { once: true } विकल्प का इस्तेमाल करके यह पक्का करेंगे कि यह सिर्फ़ मौजूदा खोज के नतीजों के लिए ट्रिगर हो.

// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });

addMarkers फ़ंक्शन ऐसा दिखता है:

async function addMarkers() {
    const { LatLngBounds } = await google.maps.importLibrary("core");
    const bounds = new LatLngBounds();

    if (placeSearchElement.places.length > 0) {
        // Remove existing markers
        for (const m in markers) {
            markers[m].map = null;
        }
        markers = {};

        // Loop through each place from the search results
        // and add a marker for each one.
        for (const place of placeSearchElement.places) {
            const marker = new google.maps.marker.AdvancedMarkerElement({
                map: map,
                position: place.location,
            });

            markers[place.id] = marker;
            bounds.extend(place.location);
            marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;

            // Add a click listener for each marker.
            marker.addListener('gmp-click', (event) => {
                // The main logic for showing details will go here.
            });
        }
        // Position the map to display all markers.
        map.setCenter(bounds.getCenter());
        map.fitBounds(bounds);
    }
}

यह चरण पूरा होने के बाद, ऐप्लिकेशन इस तरह दिखेगा. इसमें PlaceSearchElement से मिली हर जगह के लिए मार्कर दिखाने की सुविधा होगी:

अब हमारे पास मैप पर मार्कर हैं. आखिरी चरण में, मार्कर और एलिमेंट पर क्लिक करने से जुड़े इवेंट को मैनेज करना है. इससे जगह की जानकारी वाली विंडो दिखेगी. यह जानकारी, जगह की ज़्यादा जानकारी देने वाले एलिमेंट से मिलती है. इस उदाहरण के लिए, हम जगह की जानकारी देने वाले कॉम्पैक्ट एलिमेंट का इस्तेमाल करेंगे.

अपने कोड में, Place Details कॉम्पैक्ट एलिमेंट का एचटीएमएल जोड़ें. उदाहरण के लिए:

<gmp-place-details-compact orientation="vertical" style="display: none;">
    <gmp-place-all-content></gmp-place-all-content>
    <gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>

style को display: none पर सेट किया गया है. यह तब तक नहीं दिखेगा, जब तक इसकी ज़रूरत नहीं होगी. gmp-place-all-content को सभी एलिमेंट का कॉन्टेंट रेंडर करने के लिए पास किया जाता है. कौनसा कॉन्टेंट रेंडर करना है, यह चुनने के लिए जगह की जानकारी देने वाले कॉम्पैक्ट एलिमेंट का दस्तावेज़ देखें.

JavaScript में एक ग्लोबल वैरिएबल बनाएं, ताकि Place Details Compact Element का रेफ़रंस सेव किया जा सके. साथ ही, इसे अपने इनिशियलाइज़ेशन कोड में भरें. उदाहरण के लिए:

let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');

addMarkers फ़ंक्शन में, हर मार्कर के लिए gmp-click इवेंट लिसनर जोड़ें. साथ ही, Place Details कॉम्पैक्ट एलिमेंट को कॉन्फ़िगर करें, ताकि वह मौजूदा मार्कर का जगह का आईडी पास करके Place Details दिखा सके.

ऐसा करने के बाद, जानकारी वाली विंडो खुलती है. इसमें जगह की जानकारी देने वाला कॉम्पैक्ट एलिमेंट दिखता है. यह मार्कर पर ऐंकर होता है.

आखिर में, मैप को चुनी गई जगह के व्यूपोर्ट पर सेट किया जाता है, ताकि वह दिख सके.

async function addMarkers() {
          ...
            marker.addListener('gmp-click', (event) => {
                //Set up Place Details Compact Widget
                placeDetailsElement.style.display = "block";
                // Remove any existing place request element
                const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
                if (existingPlaceRequest) {
                    existingPlaceRequest.remove();
                }
                // Create and configure the new place request element
                const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
                // Prepend the new place request element to the main widget
                placeDetailsElement.prepend(placeRequestElement);
                if (infoWindow.isOpen) {
                    infoWindow.close();
                }
                infoWindow.setOptions({
                    content: placeDetailsElement
                });
                infoWindow.open({
                    anchor: marker,
                    map: map
                });
                // Position the map to show the selected place
                placeDetailsElement.addEventListener('gmp-load', () => {
                    map.fitBounds(place.viewport, { top: 500, left: 400 });
                });
            });
          ...
        });
    }
}

उपयोगकर्ता को जगह की सूची वाले एलिमेंट में मौजूद किसी जगह पर क्लिक करके, जगह की जानकारी वाले कॉम्पैक्ट एलिमेंट को दिखाने की सुविधा चालू करने के लिए, configureFromSearchNearbyRequest को कॉल करने के बाद, JavaScript कोड में यह जोड़ें.

placeSearchElement.addEventListener("gmp-select", ({ place }) => {
    if (markers[place.id]) {
        markers[place.id].click();
    }
});

यह चरण पूरा होने के बाद, ऐप्लिकेशन, जगह की सूची वाले एलिमेंट को भरने के लिए, आस-पास की जगहों की जानकारी या टेक्स्ट से खोजें की सुविधा का इस्तेमाल कर पाएगा. इसके नतीजों में, मैप पर पिन दिखेंगे. साथ ही, पिन या Place List Element में मौजूद किसी जगह पर क्लिक करने से, जगह की जानकारी वाली विंडो दिखेगी. यह जानकारी, Place Details Compact Element से मिलती है.

ऐप्लिकेशन कुछ इस तरह दिखेगा:

नतीजा

PlaceSearchElement को Place Details कॉम्पैक्ट एलिमेंट के साथ इस्तेमाल करने से, Google Maps Platform के ऐप्लिकेशन में जगह ढूंढने से जुड़ी बेहतर सुविधाएं आसानी से जोड़ी जा सकती हैं.

आज ही Places UI Kit आज़माएं. इससे आपके उपयोगकर्ताओं को आस-पास की जगहों और टेक्स्ट, दोनों का इस्तेमाल करके जगहों को खोजने और एक्सप्लोर करने में मदद मिलेगी. साथ ही, उन्हें जगहों की ज़्यादा जानकारी दिखेगी. इससे, जगहों की जानकारी खोजने के लिए, आपके ऐप्लिकेशन के इस्तेमाल के मामलों के साथ उनका इंटरैक्शन बेहतर होगा.

योगदानकर्ता

हेनरिक वाल्व | DevX इंजीनियर