إنشاء أداة بحث تفاعلية عن المتاجر باستخدام حزمة أدوات واجهة مستخدم "الأماكن"

الهدف

يوضّح هذا المستند الخطوات الرئيسية لتطوير تطبيق تفاعلي للعثور على المتاجر باستخدام "منصة خرائط Google"، وتحديدًا Maps JavaScript API وPlaces UI Kit: عنصر تفاصيل المكان. ستتعلّم كيفية إنشاء خريطة تعرض المواقع الجغرافية للمتاجر، وتعديل قائمة المتاجر الظاهرة بشكل ديناميكي، وعرض معلومات غنية عن كل متجر.

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

يُنصح بالاطّلاع على ما يلي:

فعِّل Maps JavaScript API وPlaces UI Kit في مشروعك.

تأكَّد من أنّك حمّلت Maps JavaScript API واستوردت المكتبات المطلوبة لكل من علامات Advanced Markers وPlaces UI Kit قبل البدء. يفترض هذا المستند أيضًا توفّر معرفة عملية بتطوير الويب، بما في ذلك HTML وCSS وJavaScript.

الإعداد الأولي

الخطوة الأولى هي إضافة خريطة إلى الصفحة. سيتم استخدام هذه الخريطة لعرض دبابيس ذات صلة بالمواقع الجغرافية لمتاجرك.

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

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

اختَر الطريقة الأنسب لحالة الاستخدام. يمكنك استخدام أيّ من الطريقتَين لتنفيذ الخريطة، وسيكون هذا الدليل مفيدًا لك.

عرض توضيحي

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

تحميل وعرض المواقع الجغرافية للمتاجر

في هذا القسم، سنحمّل بيانات متجرك ونعرضها على الخريطة. يفترض هذا الدليل أنّ لديك مستودع معلومات عن متاجرك الحالية يمكنك استخدامه. يمكن أن تأتي بيانات متجرك من مصادر مختلفة، مثل قاعدة البيانات. في هذا المثال، نفترض ملف JSON محليًا (stores.json) يحتوي على مصفوفة من عناصر المتجر، يمثّل كل منها موقعًا جغرافيًا لمتجر واحد. يجب أن يحتوي كل عنصر على name وlocation (مع lat وlng) وplace_id على الأقل.

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

قد يبدو مثال إدخال تفاصيل المتجر في ملف stores.json على النحو التالي. تتضمّن هذه البيانات حقولاً للاسم والموقع الجغرافي (خطوط الطول والعرض) ومعرّف المكان. هناك عنصر لتخزين ساعات عمل المتجر (مختصرة). هناك أيضًا قيمتان منطقيتان للمساعدة في وصف الميزات المخصّصة لموقع المتجر.

{
  "name": "Example Store Alpha",
  "location": { "lat": 51.51, "lng": -0.12 },
  "place_id": "YOUR_STORE_PLACE_ID",
  "opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
  "new_store_design": true,
  "indoor_seating": false
}

في رمز JavaScript، استرجِع بيانات المواقع الجغرافية لمتاجرك، واعرض دبوسًا على الخريطة لكل موقع جغرافي.

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

function displayInitialMarkers(storeLocations) {
    if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
    storeLocations.forEach(store => {
        if (store.location) {
            const marker = new AdvancedMarkerElement({
                position: new LatLng(store.location.lat, store.location.lng),
                title: store.name
            });
            mapElement.appendChild(marker);
        }
    });
}

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

في ما يلي مثال على الشكل الذي قد يظهر به محدّد مواقع المتاجر في هذه المرحلة:

الصورة

الاستماع إلى التغييرات في إطار عرض الخريطة

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

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

map.addListener('idle', debounce(updateMarkersInView, 300));

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

function debounce(func, delay) {
    let timeoutId;
    return function(...args) {
        const context = this;
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
            func.apply(context, args);
        }, delay);
    };
}

الرمز أعلاه هو مثال على دالة إلغاء تكرار. تتطلّب هذه الدالة وسيطتَي الدالة والتأخير، ويمكن ملاحظة تمريرها في أداة معالجة الحدث غير النشط. ويكفي تأخير بمقدار 300 ملي ثانية لانتظار توقّف الخريطة عن الحركة، بدون إضافة تأخير ملحوظ إلى واجهة المستخدم. بعد انتهاء مهلة الانتظار هذه، يتم استدعاء الدالة التي تم تمريرها، وهي updateMarkersInView في هذه الحالة.

يجب أن تنفّذ الدالة updateMarkersInView الإجراءات التالية:

محو جميع العلامات الحالية من الخريطة

تحقَّق مما إذا كان موقع المتجر يقع ضمن حدود الخريطة الحالية، على سبيل المثال:

if (map.getBounds().contains(storeLatLng)) {
  // logic
}

ضمن عبارة if أعلاه، اكتب رمزًا لعرض العلامات وتخزين تفاصيل المتجر في الشريط الجانبي، إذا كان موقع المتجر يقع ضمن إطار عرض الخريطة.

عرض تفاصيل غنية حول المكان باستخدام "عنصر تفاصيل المكان"

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

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

دمج العنصر المضغوط "تفاصيل المكان" في التطبيق

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

بالنسبة إلى المتجر الحالي الذي تتم معالجته، استردِد رقم تعريف المكان من بياناتك. يتم استخدام معرّف المكان للتحكّم في المكان الذي سيتم عرض العنصر فيه.

في JavaScript، أنشئ مثيلاً من PlaceDetailsCompactElement بشكلٍ ديناميكي. يتم أيضًا إنشاء PlaceDetailsPlaceRequestElement جديد، ويتم تمرير معرّف المكان إليه، ويتم إلحاق ذلك بالـ PlaceDetailsCompactElement. أخيرًا، استخدِم PlaceContentConfigElement لضبط المحتوى الذي سيعرضه العنصر.

تفترض الدالة التالية أنّه تم استيراد مكتبات Place UI Kit اللازمة وأنّها متاحة في النطاق الذي يتم فيه استدعاء هذه الدالة، وأنّ storeData الذي تم تمريره إلى الدالة يحتوي على place_id.

ستعرض هذه الدالة العنصر، وسيكون الرمز البرمجي الذي يستدعيها مسؤولاً عن إلحاقه بـ DOM.

function createPlaceDetailsCompactElement(storeData) {
    // Create the main details component
    const detailsCompact = new PlaceDetailsCompactElement();
    detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'

    // Specify the Place ID
    const placeRequest = new PlaceDetailsPlaceRequestElement();
    placeRequest.place = storeData.place_id;
    detailsCompact.appendChild(placeRequest);

    // Configure which content elements to display
    const contentConfig = new PlaceContentConfigElement();
    // For this example, we'll render media, rating, accessibility, and attribution:
    contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
    contentConfig.appendChild(new PlaceRatingElement());
    contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
    // Configure attribution
    const placeAttribution = new PlaceAttributionElement();
    placeAttribution.setAttribute('light-scheme-color', 'gray');
    placeAttribution.setAttribute('dark-scheme-color', 'gray');
    contentConfig.appendChild(placeAttribution);
    detailsCompact.appendChild(contentConfig);
    // Return the element
    return detailsCompact;
}

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

يتيح العنصر المضغوط "تفاصيل المكان" تطبيق الأنماط من خلال سمات CSS المخصّصة. يتيح لك ذلك تخصيص مظهره (الألوان والخطوط وما إلى ذلك) ليتوافق مع تصميم تطبيقك. طبِّق هذه الخصائص المخصّصة في ملف CSS. اطّلِع على المستندات المرجعية الخاصة بـ PlaceDetailsCompactElement لمعرفة خصائص CSS المتوافقة.

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

الصورة

تحسين أداة البحث عن المتاجر

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

إضافة ميزة "الإكمال التلقائي"

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

رصد الموقع الجغرافي

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

عرض المسافة والاتجاهات

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

من خلال تنفيذ هذه الإضافات، يمكنك الاستفادة من المزيد من إمكانات Google Maps Platform لإنشاء أداة بحث عن المتاجر أكثر شمولاً وملاءمةً تلبي احتياجات المستخدمين الشائعة بشكل مباشر.

الخاتمة

أوضح هذا الدليل الخطوات الأساسية لإنشاء أداة تفاعلية للعثور على المتاجر. لقد تعلّمت كيفية عرض مواقع متاجر خاصة بك على خريطة باستخدام Maps JavaScript API، وكيفية تعديل المتاجر الظاهرة بشكل ديناميكي استنادًا إلى التغييرات في إطار العرض، والأهم من ذلك، كيفية عرض بيانات متجرك الخاص بما يتوافق مع Places UI Kit. باستخدام معلومات متجرك الحالية، بما في ذلك معرّفات الأماكن، مع عنصر تفاصيل المكان، يمكنك عرض تفاصيل غنية وموحّدة لكل من مواقعك الجغرافية، ما يؤدي إلى إنشاء أساس قوي لأداة بحث عن المتاجر سهلة الاستخدام.

جرِّب Maps JavaScript API وPlaces UI Kit لتقديم أدوات فعّالة تستند إلى المكوّنات من أجل تطوير تطبيقات متطورة تستند إلى الموقع الجغرافي بسرعة. ومن خلال الجمع بين هذه الميزات، يمكنك تقديم تجارب جذابة وغنية بالمعلومات للمستخدمين.

المساهمون

هنريك فالف | مهندس DevX