أداة البحث عن المتاجر باستخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن

الهدف

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

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

يُنصح بالإلمام بما يلي:

فعِّل Maps JavaScript API وحزمة أدوات واجهة المستخدم للأماكن في مشروعك.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تفترض الدالة التالية أنّه تم استيراد مكتبات حزمة أدوات "خرائط Google" الجاهزة للأماكن اللازمة وأنّها متاحة في النطاق الذي يتم فيه استدعاء هذه الدالة، وأنّ 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 JavaScript API، وتعديل المتاجر المرئية ديناميكيًا استنادًا إلى التغييرات في إطار العرض، والأهم من ذلك، كيفية عرض بيانات متاجرك بما يتوافق مع حزمة أدوات "خرائط Google" الجاهزة للأماكن. من خلال استخدام معلومات متجرك الحالية، بما في ذلك أرقام تعريف الأماكن، مع عنصر تفاصيل المكان، يمكنك تقديم تفاصيل غنية وموحّدة لكل موقع جغرافي من مواقعك الجغرافية، ما يوفّر أساسًا قويًا لمحدِّد مواقع متاجر سهل الاستخدام.

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

المساهمون

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