الهدف
يشرح هذا المستند الخطوات الرئيسية لتطوير تطبيق تفاعلي للعثور على المتاجر باستخدام "منصة خرائط Google"، وتحديدًا واجهة برمجة تطبيقات JavaScript لخدمة "خرائط Google" ومجموعة أدوات واجهة المستخدم لأماكن: عنصر ملفّق تفاصيل الأماكن. ستتعرّف على كيفية إنشاء خريطة تعرض مواقع المتاجر، وتعديل قائمة المتاجر المرئية بشكل ديناميكي، وعرض معلومات مفيدة عن كل متجر.
المتطلبات الأساسية
يُنصح بالاطّلاع على ما يلي:
- Maps JavaScript API: تُستخدَم لعرض خريطة على صفحتك واستيراد حِزمة أدوات واجهة المستخدم في "الأماكن".
- العلامات المتقدّمة - تُستخدَم لعرض العلامات على الخريطة.
- حزمة أدوات واجهة مستخدم "الأماكن": تُستخدَم لعرض معلومات عن متاجرك في واجهة المستخدم.
فعِّل واجهة برمجة التطبيقات لخدمة "خرائط Google" المبنية على JavaScript ومجموعة أدوات واجهة مستخدم "الأماكن" في مشروعك.
تأكَّد من تحميل واجهة برمجة التطبيقات برمجة JavaScript لتطبيق "خرائط Google" واستيراد المكتبات المطلوبة لالعلامات المتقدمة ومجموعة أدوات واجهة مستخدم "الأماكن" قبل البدء. يفترض هذا المستند أيضًا معرفة عملية بتطوير الويب، بما في ذلك HTML وCSS وJavaScript.
الإعداد الأولي
الخطوة الأولى هي إضافة خريطة إلى الصفحة. سيتم استخدام هذه الخريطة لعرض العلامات المرتبطة بالمواقع الجغرافية لمتاجرك.
هناك طريقتان لإضافة خريطة إلى صفحة:
- استخدام عنصر ويب HTML من gmp-map
- استخدام JavaScript
اختَر الطريقة الأنسب لحالة الاستخدام. يمكن استخدام كلتا الطريقتَين لتنفيذ الخريطة مع هذا الدليل.
عرض توضيحي
يعرض هذا العرض التقديمي مثالاً على أداة "العثور على متجر" أثناء استخدامها، حيث تعرض مواقع مكاتب Google في منطقة خليج سان فرانسيسكو. يتم عرض عنصر "تفاصيل المكان" لكل موقع جغرافي، إلى جانب بعض أمثلة السمات.
تحميل المواقع الجغرافية للمتاجر وعرضها
في هذا القسم، سنحمّل بيانات متجرك ونعرضها على الخريطة. يفترض هذا الدليل
أنّ لديك مستودعًا للمعلومات عن متاجرك الحالية التي يمكنك
الاستناد إليها. يمكن أن تأتي بيانات متجرك من مصادر مختلفة، مثل قاعدة بياناتك.
في هذا المثال، نفترض أنّ لدينا ملف JSON على الجهاز (stores.json) يتضمّن مصفوفة من
عناصر المتاجر، يمثّل كلّ منها موقعًا جغرافيًا لمتجر. يجب أن يحتوي كل عنصر على
name وlocation (مع lat وlng) وplace_id على الأقل.
هناك مجموعة متنوعة من الطرق لاسترداد أرقام تعريف الأماكن لمواقع متاجرك إذا لم تكن لديك هذه الأرقام. اطّلِع على مستندات رقم تعريف المكان للحصول على مزيد من المعلومات.
في ما يلي مثال على إدخال تفاصيل المتجر في ملف stores.json:
تتوفّر حقول للاسم والموقع الجغرافي (lat/lng) ورقم تعريف المكان. هناك عنصر
لعرض ساعات عمل المتجر (مقتطع). هناك أيضًا قيمتان منطقيتان للمساعدة في وصف الميزات المخصّصة لموقع المتجر.
{
"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 لضبط المحتوى الذي سيعرضه العنصر.
تفترض الدالة التالية أنّه تم
استيراد مكتبات 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 المتوافقة.
في ما يلي مثال على الشكل الذي قد يظهر به طلبك في هذه المرحلة:
تحسين أداة البحث عن المتاجر
لقد وضعت أساسًا متينًا لتطبيق "عثر على متجر". ننصحك الآن بالاطّلاع على عدة طرق لتوسيع وظائفه وتوفير تجربة أكثر إثراءً وتركيزًا على المستخدم.
إضافة ميزة "الإكمال التلقائي"
يمكنك تحسين طريقة عثور المستخدمين على مناطق للبحث عن المتاجر من خلال دمج إدخال بحث مع ميزة "إكمال تلقائي" لأماكن. عندما يكتب المستخدمون عنوانًا أو حيًا أو نقطة اهتمام ويختارون أحد الاقتراحات، يمكنك برمجة الخريطة لتوسيط هذا الموقع الجغرافي تلقائيًا، ما يؤدي إلى تعديل المتاجر المجاورة. يمكنك إجراء ذلك من خلال إضافة حقل إدخال وإرفاق وظيفية "الإكمال التلقائي للأماكن" به. عند اختيار اقتراح، يمكن توسيط الخريطة في تلك النقطة. تذكَّر ضبطه لتفضيل نتائج البحث أو حصرها في منطقتك التشغيلية.
رصد الموقع الجغرافي
تقديم محتوى ذي صلة فورًا، خاصةً لمستخدمي الأجهزة الجوّالة، من خلال تنفيذ وظائف لرصد موقعهم الجغرافي الحالي بعد الحصول على إذن browser لرصد موقعه الجغرافي، يتم تلقائيًا وضع الخريطة في منتصف شاشة الجهاز وعرض أقرب المتاجر. يقدّر المستخدمون هذه الميزة بالقرب مني عند البحث عن خيارات فورية. أضِف زرًا أو طلبًا أوليًا لطلب الوصول إلى الموقع الجغرافي.
عرض المسافة والاتجاهات
بعد أن يحدّد المستخدم متجرًا يهمّه، يمكنك تحسين تجربته بشكل كبير من خلال دمج Routes API. احتسِب المسافة من الموقع الجغرافي الحالي للمستخدم أو من الموقع الجغرافي الذي تم البحث عنه، ثم اعرضها لكل متجر تُدرجه. بالإضافة إلى ذلك، يجب توفير زر أو رابط يستخدم واجهة برمجة التطبيقات Routes API لإنشاء مسار من موقع المستخدم الجغرافي إلى المتجر المحدّد. يمكنك بعد ذلك عرض هذا المسار على خريطتك أو إنشاء رابط يؤدي إلى "خرائط Google" للتنقّل، ما يسهّل الانتقال من العثور على متجر إلى الوصول إليه.
من خلال تطبيق هذه الإضافات، يمكنك الاستفادة من المزيد من إمكانات "منصّة خرائط Google" لإنشاء أداة أكثر شمولاً وملاءمةً لتحديد المواقع الجغرافية للمتاجر، والتي تلبّي مباشرةً احتياجات المستخدمين الشائعة.
الخاتمة
لقد شرح هذا الدليل الخطوات الأساسية لإنشاء أداة بحث تفاعلية عن المتاجر. لقد تعرّفت على كيفية عرض مواقع متاجرك على خريطة باستخدام واجهة برمجة التطبيقات JavaScript API في "خرائط Google"، وكيفية تعديل المتاجر المرئية ديناميكيًا استنادًا إلى تغييرات مساحة العرض، وكيفية عرض بيانات متاجرك بما يتوافق مع واجهة برمجة التطبيقات Kit لمستخدمي "أماكن Google". باستخدام معلومات متاجرك الحالية، بما في ذلك أرقام تعريف الأماكن، مع عنصر تفاصيل المكان، يمكنك تقديم تفاصيل غنية ومُعيارَة لكلٍّ من مواقعك الجغرافية، ما يؤدّي إلى إنشاء أساس متين لنظام تحديد المواقع الجغرافية للمتاجر الذي يسهل على المستخدمين استخدامه.
جرِّب واجهة برمجة تطبيقات JavaScript للخرائط ومجموعة أدوات واجهة مستخدم "الأماكن" لتقديم أدوات فعالة تستند إلى المكوّنات من أجل تطوير التطبيقات المتقدّمة المبنية على الموقع الجغرافي بسرعة. ومن خلال الجمع بين هذه الميزات، يمكنك إنشاء تجارب تفاعلية ومفيدة للمستخدمين.
المساهمون
Henrik Valve | مهندس DevX