مکان‌ها را با عنصر جستجوی مکان و API جاوا اسکریپت Maps کشف کنید

هدف

یاد بگیرید که چگونه عنصر جستجوی مکان را با نقشه‌های گوگل ادغام کنید تا به کاربران کمک کنید مکان‌ها را با استفاده از جستجوی نزدیک یا جستجوی متنی پیدا کنند و توانایی آنها را در کشف نقاط مورد علاقه افزایش دهید. از عنصر فشرده جزئیات مکان برای ارائه جزئیات بیشتر در مورد مکان‌های نمایش داده شده در برنامه خود استفاده کنید.

عنصر جستجوی مکان چیست؟

عنصر جستجوی مکان بخشی از کیت رابط کاربری مکان‌ها در API جاوا اسکریپت Maps است. این یک عنصر HTML است که نتایج جستجوی مکان را مستقیماً در قالب لیست در برنامه شما ارائه می‌دهد. این عنصر فرآیند نمایش مکان‌های یافت شده با استفاده از جستجوی نزدیک یا جستجوی متنی را ساده می‌کند و یک تجربه کاربری یکپارچه برای کشف مکان ارائه می‌دهد. هنگامی که کاربر مکانی را از لیست انتخاب می‌کند، می‌توانید جزئیات آن را روی نقشه نمایش دهید، اغلب با استفاده از یک پنجره اطلاعات و عنصر جزئیات مکان.

کشف مکان را تجسم کنید

تصویر زیر نمونه‌ای از عنصر جستجوی مکان را در عمل نشان می‌دهد. در سمت چپ، لیستی از رستوران‌ها نمایش داده می‌شود (عنصر جستجوی مکان). وقتی یک رستوران انتخاب می‌شود، جزئیات آن در یک پنجره اطلاعات روی نقشه ظاهر می‌شود و نقشه بر روی مکان آن متمرکز می‌شود.

تصویر

موارد استفاده برای کشف مکان

ادغام عنصر جستجوی مکان می‌تواند کاربردهای مختلفی را در صنایع مختلف بهبود بخشد:

  • سفر و گردشگری: به گردشگران اجازه دهید جاذبه‌ها، هتل‌ها یا انواع خاصی از غذاها را در یک منطقه جستجو کنند.
  • املاک و مستغلات: به خریداران یا مستاجران بالقوه این امکان را بدهید که مدارس، سوپرمارکت‌ها یا گزینه‌های حمل و نقل عمومی نزدیک خود را پیدا کنند.
  • تدارکات و خدمات: به رانندگان در یافتن ایستگاه‌های شارژ خودروهای برقی، پمپ بنزین‌ها یا مراکز خدمات خاص کمک کنید.

گردش کار راهکار: پیاده‌سازی کشف مکان

این بخش شما را با مراحل ادغام عنصر جستجوی مکان برای کشف مکان‌ها روی نقشه، از جمله قطعه کدهایی برای تعامل با کیت رابط کاربری مکان‌ها، آشنا می‌کند. ما مقداردهی اولیه نقشه و پیاده‌سازی قابلیت‌های جستجوی نزدیک و جستجوی متن را پوشش خواهیم داد. در نهایت، از عنصر جزئیات مکان برای نمایش جزئیات بیشتر در مورد یک مکان خاص، با کلیک روی پین آن روی نقشه، استفاده خواهیم کرد.

پیش‌نیازها

آشنایی با مستندات زیر توصیه می‌شود:

API جاوا اسکریپت Maps و کیت رابط کاربری Places را در پروژه خود فعال کنید.

قبل از شروع، مطمئن شوید که API جاوا اسکریپت Maps را بارگذاری کرده و کتابخانه‌های مورد نیاز را وارد کرده‌اید . این سند همچنین دانش عملی در مورد توسعه وب، از جمله HTML، CSS و جاوا اسکریپت را فرض می‌کند.

اضافه کردن نقشه به صفحه

اولین قدم اضافه کردن یک نقشه به صفحه شماست. این نقشه برای نمایش نتایج جستجوی مکان به صورت پین‌های قابل انتخاب استفاده خواهد شد.

دو روش برای اضافه کردن نقشه به صفحه وجود دارد:

  1. استفاده از یک کامپوننت وب HTML gmp-map .
  2. با استفاده از جاوا اسکریپت .

قطعه کدهای این صفحه با استفاده از یک نقشه جاوا اسکریپت تولید شده‌اند.

نقشه می‌تواند یا در مرکز مکانی که می‌خواهید کاربر در اطراف آن جستجو کند، مانند یک هتل، قرار گیرد، یا طوری تنظیم شود که موقعیت فعلی کاربر را برای قرار دادن در مرکز نقشه درخواست کند. برای اهداف این سند، ما از یک مکان ثابت برای تثبیت جستجو استفاده خواهیم کرد.

اگر مکان‌هایی را در نزدیکی یک مکان ثابت، مانند هتل، تجسم می‌کنید ، یک نشانگر روی نقشه قرار دهید تا این مکان را نشان دهد. به عنوان مثال:

تصویر

نقشه در مرکز سانفرانسیسکو قرار دارد و یک پین آبی رنگ برای نشان دادن مکانی که در نزدیکی آن جستجو می‌کنیم، در نظر گرفته شده است. رنگ پین با استفاده از PinElement سفارشی شده است. کنترل نوع نقشه از رابط کاربری پنهان شده است.

عنصر جستجوی مکان را تنظیم کنید

حالا می‌توانیم HTML و CSS را برای نمایش عنصر جستجوی مکان تنظیم کنیم. برای این مثال، ما قصد داریم عنصر را در سمت چپ نقشه شناور کنیم، اما توصیه می‌شود طرح‌بندی‌های مختلفی را متناسب با برنامه خود امتحان کنید.

عنصر جستجوی مکان از یک رویکرد اعلانی استفاده می‌کند. به جای پیکربندی کامل آن در جاوا اسکریپت، نوع جستجو را مستقیماً در HTML خود با قرار دادن یک عنصر درخواست، مانند <gmp-place-nearby-search-request> ، درون مؤلفه اصلی <gmp-place-search> تعریف می‌کنید.

درون کد HTML خود، یک عنصر <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>

برای انجام جستجوی اولیه و نمایش نتایج، از جاوا اسکریپت برای دریافت ارجاع به عنصر درخواست تو در تو و تنظیم ویژگی‌های آن استفاده خواهیم کرد. یک دایره را برای استفاده به عنوان 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'];

نمونه‌ای از چگونگی نگاه برنامه به این مرحله به شرح زیر است:

تصویر

عنصر جستجوی مکان دو گزینه جستجو را ارائه می‌دهد:

اینها عناصر تو در تو درون <gmp-place-search> هستند. سپس با تنظیم ویژگی‌هایی روی آن عنصر درخواست تو در تو با استفاده از جاوا اسکریپت، جستجوها را آغاز می‌کنید.

این بخش پیاده‌سازی هر دو روش را شرح می‌دهد.

تصویر

برای اینکه به کاربران اجازه دهید جستجویی در نزدیکی خود انجام دهند، ابتدا به یک عنصر رابط کاربری نیاز دارید تا بتوانند نوع مکان را انتخاب کنند. روش انتخابی را انتخاب کنید که برای برنامه شما بهترین عملکرد را داشته باشد، به عنوان مثال، یک لیست کشویی که با مجموعه‌ای از انواع مکان‌ها پر شده باشد.

توصیه می‌شود زیرمجموعه‌ای از انواع را انتخاب کنید که به مورد استفاده شما مرتبط باشند. برای مثال، اگر در حال توسعه برنامه‌ای برای نمایش مکان‌های نزدیک هتل به گردشگران هستید، می‌توانید موارد زیر را انتخاب کنید: bakery ، coffee_shop ، museum ، restaurant و tourist_attraction .

کد HTML شما باید شامل عنصر <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 در انتخابگر نوع مکان خود ایجاد کنید. این شنونده تابعی را فراخوانی می‌کند که ویژگی‌های عنصر <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 اختیاری نیز برای محدود کردن تعداد نتایج تنظیم شده است.

جستجوی متن

تصویر

برای فعال کردن جستجوی متن، پیکربندی HTML شما باید تغییر کند. به جای درخواست جستجوی نزدیک، یک عنصر <gmp-place-text-search-request> را در آن قرار می‌دهید.

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

یک ورودی متن و یک دکمه جستجو به رابط کاربری خود اضافه کنید. یک شنونده جاوا اسکریپت برای رویداد click دکمه ایجاد کنید. کنترل‌کننده رویداد، ورودی کاربر را دریافت کرده و ویژگی‌های عنصر <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 ارائه می‌دهیم که به API می‌گوید نتایج درون آن منطقه را بدون محدود کردن دقیق آنها ترجیح دهد. یک maxResultCount اختیاری تعداد نتایج برگشتی را محدود می‌کند.

پین‌ها و جزئیات مکان نمایش

اکنون برنامه می‌تواند جستجوی مکان را انجام دهد و عنصر را پر کند. در مرحله بعدی، عملکرد آن را با موارد زیر افزایش خواهیم داد:

  • نمایش پین‌ها روی نقشه برای هر مکان ثبت‌شده در عنصر جستجوی مکان.
  • به کاربر اجازه می‌دهد تا روی یک پین یا مکان درون عنصر جستجوی مکان کلیک کند تا جزئیات بیشتری در مورد آن مکان خاص نمایش داده شود.

اصول این مرحله چه از جستجوی نزدیک و چه از جستجوی متنی استفاده کند، یکسان است.

ابتدا، یک متغیر سراسری به کد جاوا اسکریپت خود اضافه کنید تا نشانگرهای مکان را ذخیره کند. این به شما امکان می‌دهد هنگام تغییر جستجو، آنها را حذف کنید و رویدادهای کلیک را مدیریت کنید.

let markers = {};

یک تابع برای اضافه کردن نشانگرها به نقشه ایجاد کنید. این تابع هر زمان که نتایج جستجوی جدید بارگذاری شوند، فراخوانی می‌شود. این تابع:

  • هرگونه نشانگر مکان موجود را از نقشه حذف کنید.
  • نتایج عنصر جستجوی مکان را مرور کنید و برای هر کدام یک نشانگر اضافه کنید.
  • مرزهای نقشه را طوری تنظیم کنید که همه نشانگرهای جدید قابل مشاهده باشند.

برای اینکه بفهمید چه زمانی نتایج جستجو در دسترس هستند، یک شنونده رویداد gmp-load به عنصر <gmp-place-search> اضافه کنید. این رویداد پس از اتمام جستجو و نمایش نتایج، اجرا می‌شود.

ما شنونده را درون تابع جستجوی خود (مثلاً 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);
    }
}

پس از تکمیل این مرحله، برنامه به شکل زیر خواهد بود، با این قابلیت که نشانگرهایی را برای هر مکان که توسط عنصر جستجوی مکان برگردانده می‌شود، نشان دهد:

تصویر

حالا که نشانگرها را روی نقشه داریم، آخرین مرحله مدیریت رویدادهای کلیک نشانگر و عنصر برای نمایش یک پنجره اطلاعات با جزئیات مکان است که توسط عنصر جزئیات مکان ارائه می‌شود. برای این مثال، از عنصر فشرده جزئیات مکان استفاده خواهیم کرد.

عنصر فشرده جزئیات مکان (Place Details Compact Element) را به کد HTML خود اضافه کنید، برای مثال:

<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 برای رندر کردن تمام محتوای عنصر ارسال می‌شود. برای انتخاب اینکه کدام محتوا رندر شود، به مستندات Place Details Compact Element مراجعه کنید.

یک متغیر سراسری در جاوا اسکریپت ایجاد کنید تا ارجاعی به عنصر فشرده جزئیات مکان را در خود نگه دارد و آن را در کد مقداردهی اولیه خود قرار دهید، برای مثال: 

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

درون تابع addMarkers ، یک شنونده رویداد gmp-click به هر نشانگر اضافه کنید و عنصر فشرده جزئیات مکان را طوری پیکربندی کنید که با ارسال شناسه مکان نشانگر فعلی، جزئیات مکان را نشان دهد.

پس از انجام این کار، یک پنجره اطلاعات باز می‌شود تا عنصر فشرده جزئیات مکان، که روی نشانگر ثابت شده است، نمایش داده شود.

در نهایت، نقشه در نمای مکان انتخاب شده قرار می‌گیرد و آن را قابل مشاهده می‌کند. 

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 اضافه کنید. 

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

پس از تکمیل این مرحله، برنامه قادر خواهد بود از جستجوی نزدیک یا جستجوی متنی برای پر کردن عنصر فهرست مکان‌ها استفاده کند. نتایج این کار، پین‌هایی را روی نقشه نشان می‌دهد و کلیک روی یک پین یا یک مکان در عنصر فهرست مکان‌ها، یک پنجره اطلاعات با جزئیات مکان را نشان می‌دهد که توسط عنصر فشرده جزئیات مکان ارائه شده است.

ظاهر اپلیکیشن به شکل زیر خواهد بود:

تصویر

نتیجه‌گیری

عنصر جستجوی مکان در ترکیب با عنصر فشرده جزئیات مکان، روشی ساده برای افزودن ویژگی‌های غنی کشف مکان به برنامه‌های پلتفرم نقشه‌های گوگل شما فراهم می‌کند.

همین امروز کیت رابط کاربری Places را امتحان کنید تا به کاربران خود این امکان را بدهید که با استفاده از جستجوی متنی و جستجوی نزدیک، مکان‌ها را پیدا و کاوش کنند و جزئیات غنی مکان را نمایش دهند و تعامل آنها را با موارد استفاده از کشف مکان شما افزایش دهند.

مشارکت‌کنندگان

هنریک والو | مهندس DevX

،

هدف

یاد بگیرید که چگونه عنصر جستجوی مکان را با نقشه‌های گوگل ادغام کنید تا به کاربران کمک کنید مکان‌ها را با استفاده از جستجوی نزدیک یا جستجوی متنی پیدا کنند و توانایی آنها را در کشف نقاط مورد علاقه افزایش دهید. از عنصر فشرده جزئیات مکان برای ارائه جزئیات بیشتر در مورد مکان‌های نمایش داده شده در برنامه خود استفاده کنید.

عنصر جستجوی مکان چیست؟

عنصر جستجوی مکان بخشی از کیت رابط کاربری مکان‌ها در API جاوا اسکریپت Maps است. این یک عنصر HTML است که نتایج جستجوی مکان را مستقیماً در قالب لیست در برنامه شما ارائه می‌دهد. این عنصر فرآیند نمایش مکان‌های یافت شده با استفاده از جستجوی نزدیک یا جستجوی متنی را ساده می‌کند و یک تجربه کاربری یکپارچه برای کشف مکان ارائه می‌دهد. هنگامی که کاربر مکانی را از لیست انتخاب می‌کند، می‌توانید جزئیات آن را روی نقشه نمایش دهید، اغلب با استفاده از یک پنجره اطلاعات و عنصر جزئیات مکان.

کشف مکان را تجسم کنید

تصویر زیر نمونه‌ای از عنصر جستجوی مکان را در عمل نشان می‌دهد. در سمت چپ، لیستی از رستوران‌ها نمایش داده می‌شود (عنصر جستجوی مکان). وقتی یک رستوران انتخاب می‌شود، جزئیات آن در یک پنجره اطلاعات روی نقشه ظاهر می‌شود و نقشه بر روی مکان آن متمرکز می‌شود.

تصویر

موارد استفاده برای کشف مکان

ادغام عنصر جستجوی مکان می‌تواند کاربردهای مختلفی را در صنایع مختلف بهبود بخشد:

  • سفر و گردشگری: به گردشگران اجازه دهید جاذبه‌ها، هتل‌ها یا انواع خاصی از غذاها را در یک منطقه جستجو کنند.
  • املاک و مستغلات: به خریداران یا مستاجران بالقوه این امکان را بدهید که مدارس، سوپرمارکت‌ها یا گزینه‌های حمل و نقل عمومی نزدیک خود را پیدا کنند.
  • تدارکات و خدمات: به رانندگان در یافتن ایستگاه‌های شارژ خودروهای برقی، پمپ بنزین‌ها یا مراکز خدمات خاص کمک کنید.

گردش کار راهکار: پیاده‌سازی کشف مکان

این بخش شما را با مراحل ادغام عنصر جستجوی مکان برای کشف مکان‌ها روی نقشه، از جمله قطعه کدهایی برای تعامل با کیت رابط کاربری مکان‌ها، آشنا می‌کند. ما مقداردهی اولیه نقشه و پیاده‌سازی قابلیت‌های جستجوی نزدیک و جستجوی متن را پوشش خواهیم داد. در نهایت، از عنصر جزئیات مکان برای نمایش جزئیات بیشتر در مورد یک مکان خاص، با کلیک روی پین آن روی نقشه، استفاده خواهیم کرد.

پیش‌نیازها

آشنایی با مستندات زیر توصیه می‌شود:

API جاوا اسکریپت Maps و کیت رابط کاربری Places را در پروژه خود فعال کنید.

قبل از شروع، مطمئن شوید که API جاوا اسکریپت Maps را بارگذاری کرده و کتابخانه‌های مورد نیاز را وارد کرده‌اید . این سند همچنین دانش عملی در مورد توسعه وب، از جمله HTML، CSS و جاوا اسکریپت را فرض می‌کند.

اضافه کردن نقشه به صفحه

اولین قدم اضافه کردن یک نقشه به صفحه شماست. این نقشه برای نمایش نتایج جستجوی مکان به صورت پین‌های قابل انتخاب استفاده خواهد شد.

دو روش برای اضافه کردن نقشه به صفحه وجود دارد:

  1. استفاده از یک کامپوننت وب HTML gmp-map .
  2. با استفاده از جاوا اسکریپت .

قطعه کدهای این صفحه با استفاده از یک نقشه جاوا اسکریپت تولید شده‌اند.

نقشه می‌تواند یا در مرکز مکانی که می‌خواهید کاربر در اطراف آن جستجو کند، مانند یک هتل، قرار گیرد، یا طوری تنظیم شود که موقعیت فعلی کاربر را برای قرار دادن در مرکز نقشه درخواست کند. برای اهداف این سند، ما از یک مکان ثابت برای تثبیت جستجو استفاده خواهیم کرد.

اگر مکان‌هایی را در نزدیکی یک مکان ثابت، مانند هتل، تجسم می‌کنید ، یک نشانگر روی نقشه قرار دهید تا این مکان را نشان دهد. به عنوان مثال:

تصویر

نقشه در مرکز سانفرانسیسکو قرار دارد و یک پین آبی رنگ برای نشان دادن مکانی که در نزدیکی آن جستجو می‌کنیم، در نظر گرفته شده است. رنگ پین با استفاده از PinElement سفارشی شده است. کنترل نوع نقشه از رابط کاربری پنهان شده است.

عنصر جستجوی مکان را تنظیم کنید

حالا می‌توانیم HTML و CSS را برای نمایش عنصر جستجوی مکان تنظیم کنیم. برای این مثال، ما قصد داریم عنصر را در سمت چپ نقشه شناور کنیم، اما توصیه می‌شود طرح‌بندی‌های مختلفی را متناسب با برنامه خود امتحان کنید.

عنصر جستجوی مکان از یک رویکرد اعلانی استفاده می‌کند. به جای پیکربندی کامل آن در جاوا اسکریپت، نوع جستجو را مستقیماً در HTML خود با قرار دادن یک عنصر درخواست، مانند <gmp-place-nearby-search-request> ، درون مؤلفه اصلی <gmp-place-search> تعریف می‌کنید.

درون کد HTML خود، یک عنصر <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>

برای انجام جستجوی اولیه و نمایش نتایج، از جاوا اسکریپت برای دریافت ارجاع به عنصر درخواست تو در تو و تنظیم ویژگی‌های آن استفاده خواهیم کرد. یک دایره را برای استفاده به عنوان 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'];

نمونه‌ای از چگونگی نگاه برنامه به این مرحله به شرح زیر است:

تصویر

عنصر جستجوی مکان دو گزینه جستجو را ارائه می‌دهد:

اینها عناصر تو در تو درون <gmp-place-search> هستند. سپس با تنظیم ویژگی‌هایی روی آن عنصر درخواست تو در تو با استفاده از جاوا اسکریپت، جستجوها را آغاز می‌کنید.

این بخش پیاده‌سازی هر دو روش را شرح می‌دهد.

تصویر

برای اینکه به کاربران اجازه دهید جستجویی در نزدیکی خود انجام دهند، ابتدا به یک عنصر رابط کاربری نیاز دارید تا بتوانند نوع مکان را انتخاب کنند. روش انتخابی را انتخاب کنید که برای برنامه شما بهترین عملکرد را داشته باشد، به عنوان مثال، یک لیست کشویی که با مجموعه‌ای از انواع مکان‌ها پر شده باشد.

توصیه می‌شود زیرمجموعه‌ای از انواع را انتخاب کنید که به مورد استفاده شما مرتبط باشند. برای مثال، اگر در حال توسعه برنامه‌ای برای نمایش مکان‌های نزدیک هتل به گردشگران هستید، می‌توانید موارد زیر را انتخاب کنید: bakery ، coffee_shop ، museum ، restaurant و tourist_attraction .

کد HTML شما باید شامل عنصر <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 در انتخابگر نوع مکان خود ایجاد کنید. این شنونده تابعی را فراخوانی می‌کند که ویژگی‌های عنصر <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 اختیاری نیز برای محدود کردن تعداد نتایج تنظیم شده است.

جستجوی متن

تصویر

برای فعال کردن جستجوی متن، پیکربندی HTML شما باید تغییر کند. به جای درخواست جستجوی نزدیک، یک عنصر <gmp-place-text-search-request> را در آن قرار می‌دهید.

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

یک ورودی متن و یک دکمه جستجو به رابط کاربری خود اضافه کنید. یک شنونده جاوا اسکریپت برای رویداد click دکمه ایجاد کنید. کنترل‌کننده رویداد، ورودی کاربر را دریافت کرده و ویژگی‌های عنصر <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 ارائه می‌دهیم که به API می‌گوید نتایج درون آن منطقه را بدون محدود کردن دقیق آنها ترجیح دهد. یک maxResultCount اختیاری تعداد نتایج برگشتی را محدود می‌کند.

پین‌ها و جزئیات مکان نمایش

اکنون برنامه می‌تواند جستجوی مکان را انجام دهد و عنصر را پر کند. در مرحله بعدی، عملکرد آن را با موارد زیر افزایش خواهیم داد:

  • نمایش پین‌ها روی نقشه برای هر مکان ثبت‌شده در عنصر جستجوی مکان.
  • به کاربر اجازه می‌دهد تا روی یک پین یا مکان درون عنصر جستجوی مکان کلیک کند تا جزئیات بیشتری در مورد آن مکان خاص نمایش داده شود.

اصول این مرحله چه از جستجوی نزدیک و چه از جستجوی متنی استفاده کند، یکسان است.

ابتدا، یک متغیر سراسری به کد جاوا اسکریپت خود اضافه کنید تا نشانگرهای مکان را ذخیره کند. این به شما امکان می‌دهد هنگام تغییر جستجو، آنها را حذف کنید و رویدادهای کلیک را مدیریت کنید.

let markers = {};

یک تابع برای اضافه کردن نشانگرها به نقشه ایجاد کنید. این تابع هر زمان که نتایج جستجوی جدید بارگذاری شوند، فراخوانی می‌شود. این تابع:

  • هرگونه نشانگر مکان موجود را از نقشه حذف کنید.
  • نتایج عنصر جستجوی مکان را مرور کنید و برای هر کدام یک نشانگر اضافه کنید.
  • مرزهای نقشه را طوری تنظیم کنید که همه نشانگرهای جدید قابل مشاهده باشند.

برای اینکه بفهمید چه زمانی نتایج جستجو در دسترس هستند، یک شنونده رویداد gmp-load به عنصر <gmp-place-search> اضافه کنید. این رویداد پس از اتمام جستجو و نمایش نتایج، اجرا می‌شود.

ما شنونده را درون تابع جستجوی خود (مثلاً 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);
    }
}

پس از تکمیل این مرحله، برنامه به شکل زیر خواهد بود، با این قابلیت که نشانگرهایی را برای هر مکان که توسط عنصر جستجوی مکان برگردانده می‌شود، نشان دهد:

تصویر

حالا که نشانگرها را روی نقشه داریم، آخرین مرحله مدیریت رویدادهای کلیک نشانگر و عنصر برای نمایش یک پنجره اطلاعات با جزئیات مکان است که توسط عنصر جزئیات مکان ارائه می‌شود. برای این مثال، از عنصر فشرده جزئیات مکان استفاده خواهیم کرد.

عنصر فشرده جزئیات مکان (Place Details Compact Element) را به کد HTML خود اضافه کنید، برای مثال:

<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 برای رندر کردن تمام محتوای عنصر ارسال می‌شود. برای انتخاب اینکه کدام محتوا رندر شود، به مستندات Place Details Compact Element مراجعه کنید.

یک متغیر سراسری در جاوا اسکریپت ایجاد کنید تا ارجاعی به عنصر فشرده جزئیات مکان را در خود نگه دارد و آن را در کد مقداردهی اولیه خود قرار دهید، برای مثال: 

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

درون تابع addMarkers ، یک شنونده رویداد gmp-click به هر نشانگر اضافه کنید و عنصر فشرده جزئیات مکان را طوری پیکربندی کنید که با ارسال شناسه مکان نشانگر فعلی، جزئیات مکان را نشان دهد.

پس از انجام این کار، یک پنجره اطلاعات باز می‌شود تا عنصر فشرده جزئیات مکان، که روی نشانگر ثابت شده است، نمایش داده شود.

در نهایت، نقشه در نمای مکان انتخاب شده قرار می‌گیرد و آن را قابل مشاهده می‌کند. 

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 اضافه کنید. 

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

پس از تکمیل این مرحله، برنامه قادر خواهد بود از جستجوی نزدیک یا جستجوی متنی برای پر کردن عنصر فهرست مکان‌ها استفاده کند. نتایج این کار، پین‌هایی را روی نقشه نشان می‌دهد و کلیک روی یک پین یا یک مکان در عنصر فهرست مکان‌ها، یک پنجره اطلاعات با جزئیات مکان را نشان می‌دهد که توسط عنصر فشرده جزئیات مکان ارائه شده است.

ظاهر اپلیکیشن به شکل زیر خواهد بود:

تصویر

نتیجه‌گیری

عنصر جستجوی مکان در ترکیب با عنصر فشرده جزئیات مکان، روشی ساده برای افزودن ویژگی‌های غنی کشف مکان به برنامه‌های پلتفرم نقشه‌های گوگل شما فراهم می‌کند.

همین امروز کیت رابط کاربری Places را امتحان کنید تا به کاربران خود این امکان را بدهید که با استفاده از جستجوی متنی و جستجوی نزدیک، مکان‌ها را پیدا و کاوش کنند و جزئیات غنی مکان را نمایش دهند و تعامل آنها را با موارد استفاده از کشف مکان شما افزایش دهند.

مشارکت‌کنندگان

هنریک والو | مهندس DevX