استكشاف الأماكن باستخدام عنصر البحث عن الأماكن وMaps JavaScript API

الهدف

تعرَّفوا على كيفية دمج عنصر "البحث عن الأماكن" مع "خرائط Google" لمساعدة المستخدمين في العثور على الأماكن باستخدام ميزة "بحث في الجوار" أو "البحث النصي"، ما يعزّز قدرتهم على استكشاف النقاط المهمة. استخدِموا عنصر "التفاصيل الموجزة للمكان" لتقديم مزيد من التفاصيل عن الأماكن التي تظهر في تطبيقكم.

ما هو عنصر "البحث عن الأماكن"؟

عنصر "البحث عن الأماكن" هو جزء من حزمة أدوات "خرائط Google" الجاهزة للأماكن في Maps JavaScript API. وهو عنصر HTML يعرض نتائج البحث عن مكان معيّن مباشرةً بتنسيق قائمة ضمن تطبيقكم. يُبسّط هذا العنصر عملية عرض الأماكن التي تم العثور عليها باستخدام ميزة "بحث في الجوار" أو "البحث النصي"، ما يوفّر تجربة سلسة للمستخدمين لاكتشاف الأماكن. عندما يختار المستخدم مكانًا من القائمة، يمكنكم عرض تفاصيله على الخريطة، غالبًا باستخدام "نافذة المعلومات" وعنصر "تفاصيل المكان".

تصوُّر عملية اكتشاف الأماكن

تعرض الصورة التالية مثالاً على عنصر "البحث عن الأماكن" أثناء العمل. على يمين الشاشة، تظهر قائمة بالمطاعم (عنصر "البحث عن الأماكن"). عند اختيار مطعم، تظهر تفاصيله في "نافذة معلومات" على الخريطة، ويتم توسيط الخريطة على موقعه الجغرافي.

الصورة

حالات استخدام ميزة "اكتشاف الأماكن"

يمكن أن يؤدي دمج عنصر "البحث عن الأماكن" إلى تحسين تطبيقات مختلفة في قطاعات متنوعة:

  • السفر والسياحة: يمكن للسياح البحث عن المعالم السياحية أو الفنادق أو أنواع معيّنة من المأكولات في منطقة معيّنة.
  • العقارات: يمكن للمشترين أو المستأجرين المحتملين العثور على المدارس أو محلات السوبرماركت أو خيارات النقل العام القريبة.
  • الخدمات والخدمات اللوجستية: يمكن مساعدة السائقين في العثور على محطات شحن المركبات الكهربائية أو محطات الوقود أو مراكز الخدمة معيّنة.

سير عمل الحل: تنفيذ ميزة "اكتشاف الأماكن"

يشرح هذا القسم خطوات دمج عنصر "البحث عن الأماكن" لاكتشاف الأماكن على الخريطة، بما في ذلك مقتطفات الرموز البرمجية للتفاعل مع حزمة أدوات "خرائط Google" الجاهزة للأماكن. سنشرح كيفية تهيئة الخريطة وتنفيذ وظيفتَي "بحث في الجوار" و"البحث النصي". أخيرًا، سنستخدم عنصر "تفاصيل المكان" لعرض مزيد من التفاصيل عن مكان معيّن عند النقر على مؤشره على الخريطة.

المتطلبات الأساسية

يُفضّل الإلمام بالمستندات التالية:

يُرجى تفعيل Maps JavaScript API وPlaces UI Kit في مشروعكم.

يُرجى التأكّد من تحميل Maps JavaScript API واستيراد المكتبات المطلوبة قبل البدء. تفترض هذه المستندات أيضًا معرفة عملية بتطوير الويب، بما في ذلك HTML وCSS وJavaScript.

إضافة خريطة إلى الصفحة

الخطوة الأولى هي إضافة خريطة إلى صفحتكم. ستُستخدم هذه الخريطة لعرض نتائج عنصر "البحث عن الأماكن" كمؤشرات قابلة للنقر.

هناك طريقتان لإضافة خريطة إلى صفحة:

  1. باستخدام مكوّن ويب HTML ‏gmp-map ‏‏ ‏
  2. باستخدام JavaScript.

تم إنشاء مقتطفات الرموز البرمجية في هذه الصفحة باستخدام خريطة JavaScript.

يمكن توسيط الخريطة على موقع جغرافي تريدون أن يبحث المستخدمون حوله، مثل فندق، أو يمكن تهيئتها لطلب الموقع الجغرافي الحالي للمستخدم لتوسيط الخريطة. لأغراض هذه المستندات، سنستخدم موقعًا جغرافيًا ثابتًا لربط البحث.

إذا كنتم تصوّرون الأماكن القريبة من موقع جغرافي ثابت، مثل فندق، ضَعوا علامة على الخريطة لتمثيل هذا المكان. على سبيل المثال:

الصورة

تتوسّط الخريطة مدينة سان فرانسيسكو، مع مؤشر أزرق يمثّل المكان الذي نبحث عنه في الجوار. تم تخصيص لون المؤشر باستخدام PinElement. تم إخفاء عنصر التحكّم "نوع الخريطة" من واجهة المستخدم.

إعداد عنصر "البحث عن الأماكن"

الآن، يمكننا إعداد HTML وCSS لعرض عنصر "البحث عن الأماكن". في هذا المثال، سنضع العنصر على الجانب الأيمن من الخريطة، ولكن يُنصح بتجربة تنسيقات مختلفة لتناسب تطبيقكم.

يستخدم عنصر "البحث عن الأماكن" نهجًا إعلانيًا. بدلاً من ضبطه بالكامل في JavaScript، يمكنكم تحديد نوع البحث مباشرةً في HTML من خلال تضمين عنصر طلب، مثل <gmp-place-nearby-search-request>، داخل المكوّن الرئيسي <gmp-place-search> component.

ضمن رمز 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>

لإجراء بحث أولي وعرض النتائج، سنستخدم 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'];

في هذه المرحلة، يمكن أن يبدو التطبيق على النحو التالي:

الصورة

يتيح عنصر "البحث عن الأماكن" خيارَي بحث:

هذه عناصر مضمّنة داخل <gmp-place-search>. بعد ذلك، يمكنكم تفعيل عمليات البحث من خلال ضبط خصائص عنصر الطلب المضمّن باستخدام JavaScript.

يشرح هذا القسم كيفية تنفيذ كلتا الطريقتَين.

الصورة

للسماح للمستخدمين بإجراء بحث في الجوار، تحتاجون أولاً إلى عنصر في واجهة المستخدم لهم ليختاروا نوع مكان. اختاروا طريقة الاختيار التي تناسب تطبيقكم، على سبيل المثال، قائمة منسدلة تتضمّن مجموعة مختارة من أنواع الأماكن.

يُفضّل اختيار مجموعة فرعية من الأنواع ذات الصلة بحالة الاستخدام. على سبيل المثال، إذا كنتم تطوّرون تطبيقًا لعرض الأماكن القريبة من فندق للسياح، يمكنكم اختيار: 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>

بعد ذلك، أنشئوا مستمع JavaScript لحدث 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>

أضيفوا حقل إدخال نص وزر بحث إلى واجهة المستخدم. أنشئوا مستمع JavaScript لحدث 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 باستخدام حدود الخريطة الحالية، ما يطلب من واجهة برمجة التطبيقات تفضيل النتائج ضمن تلك المنطقة بدون حصرها بشكل صارم. يحدّ maxResultCount الاختياري من عدد النتائج المعروضة.

عرض مؤشرات الأماكن وتفاصيلها

يمكن للتطبيق الآن إجراء بحث عن مكان وتعبئة العنصر. في الخطوة التالية، سنعزّز وظائفه من خلال:

  • عرض مؤشرات على الخريطة لكل مكان يتم تعبئته في عنصر "البحث عن الأماكن"
  • السماح للمستخدم بالنقر على مؤشر أو على المكان ضمن عنصر "البحث عن الأماكن" لعرض مزيد من التفاصيل عن هذا المكان تحديدًا

مبدأ هذه الخطوة هو نفسه سواء كان التطبيق يستخدم ميزة "بحث في الجوار" أو "البحث النصي".

أولاً، أضيفوا متغيّرًا شاملاً إلى رمز JavaScript لتخزين علامات الأماكن. سيسمح لكم ذلك بإزالتها عند تغيير البحث والتعامل مع أحداث النقر.

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);
    }
}

بعد إكمال هذه الخطوة، سيبدو التطبيق على النحو التالي، مع إمكانية عرض علامات لكل مكان يعرضه عنصر "البحث عن الأماكن":

الصورة

بعد وضع العلامات على الخريطة، تتمثل الخطوة الأخيرة في التعامل مع أحداث النقر على العلامات و العناصر لعرض "نافذة معلومات" تتضمّن تفاصيل المكان، والتي يوفّرها عنصر "تفاصيل المكان". في هذا المثال، سنستخدم عنصر "التفاصيل الموجزة للمكان".

أضيفوا رمز 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 لعرض كل محتوى العنصر. لاختيار المحتوى الذي سيتم عرضه، يُرجى الاطّلاع على مستندات عنصر "التفاصيل الموجزة للمكان ".

أنشئوا متغيّرًا شاملاً في JavaScript لتخزين مرجع لعنصر "التفاصيل الموجزة للمكان"، واملأوا هذا المتغيّر في رمز التهيئة، على سبيل المثال:

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

للسماح للمستخدم بالنقر على مكان في عنصر "قائمة الأماكن" لعرض عنصر "التفاصيل الموجزة للمكان"، أضيفوا ما يلي إلى رمز JavaScript بعد استدعاء configureFromSearchNearbyRequest.

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

بعد إكمال هذه الخطوة، سيتمكّن التطبيق من استخدام ميزة "بحث في الجوار" أو "البحث النصي" لتعبئة عنصر "قائمة الأماكن". ستعرض النتائج مؤشرات على الخريطة، وسيؤدي النقر على مؤشر أو مكان في عنصر "قائمة الأماكن" إلى عرض "نافذة معلومات" تتضمّن تفاصيل المكان، والتي يوفّرها عنصر "التفاصيل الموجزة للمكان".

سيبدو التطبيق على النحو التالي:

الصورة

الخاتمة

يوفّر عنصر "البحث عن الأماكن" مع عنصر "التفاصيل الموجزة للمكان" طريقة مبسطة لإضافة ميزات اكتشاف الأماكن الغنية إلى تطبيقاتكم على Google Maps Platform.

جرِّبوا حزمة أدوات "خرائط Google" الجاهزة للأماكن اليوم لتمكين المستخدمين من العثور على الأماكن واستكشافها باستخدام ميزتَي "بحث في الجوار" و"البحث النصي" وعرض تفاصيل الأماكن الغنية، ما يعزّز تفاعلهم مع حالات استخدام ميزة "اكتشاف الأماكن".

المساهمون

هنريك صمام | DevX مهندس