هدف
این سند مراحل کلیدی ایجاد یک برنامه کاربردی فروشگاه یاب تعاملی را با استفاده از پلتفرم Google Maps، به‌ویژه Maps JavaScript API و Places UI Kit: Place Details Element را طی می‌کند. شما یاد خواهید گرفت که چگونه نقشه ای ایجاد کنید که مکان های فروشگاه را نشان دهد، به صورت پویا لیستی از فروشگاه های قابل مشاهده را به روز کند و اطلاعات مکان های غنی را برای هر فروشگاه نمایش دهد.
پیش نیازها
آشنایی با موارد زیر توصیه می شود:
- Maps JavaScript API - برای نمایش نقشه در صفحه شما و وارد کردن Places UI Kit استفاده می شود.
- نشانگرهای پیشرفته - برای نمایش نشانگرها روی نقشه استفاده می شود.
- Places UI Kit - برای نمایش اطلاعات فروشگاه های شما در UI استفاده می شود.
Maps JavaScript API و Places UI Kit را در پروژه خود فعال کنید.
قبل از شروع مطمئن شوید که Maps JavaScript API را بارگیری کرده اید و کتابخانه های مورد نیاز را برای نشانگرهای پیشرفته و کیت رابط کاربری مکان ها وارد کرده اید. این سند همچنین دانش کاری توسعه وب، از جمله HTML، CSS، و جاوا اسکریپت را فرض می‌کند.
راه اندازی اولیه
اولین قدم اضافه کردن نقشه به صفحه است. این نقشه برای نمایش پین‌های مربوط به مکان‌های فروشگاه شما استفاده می‌شود.
دو راه برای اضافه کردن نقشه به یک صفحه وجود دارد:
- استفاده از کامپوننت وب gmp-map HTML
- با استفاده از جاوا اسکریپت
روشی را انتخاب کنید که برای مورد استفاده شما بهترین کار را دارد. هر دو روش اجرای نقشه با این راهنما کار خواهند کرد.
نسخه ی نمایشی
این نسخه ی نمایشی نمونه ای از یاب فروشگاه را نشان می دهد که مکان های دفتر 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
}
در کد جاوا اسکریپت خود، داده‌های مکان‌های فروشگاه خود را واکشی کنید و برای هر کدام یک پین روی نقشه نمایش دهید.
نمونه ای از نحوه انجام این کار به شرح زیر است. این تابع یک شی حاوی جزئیات را برای فروشگاه ها می گیرد و یک نشانگر بر اساس مکان هر یک ایجاد می کند.
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 Viewport گوش دهید
برای بهینه‌سازی عملکرد و تجربه کاربری، برنامه خود را به‌روزرسانی کنید تا نشانگرها و جزئیات را تنها زمانی در نوار کناری نمایش دهد که مکان‌های مربوطه آنها در ناحیه نقشه قابل مشاهده (نمایشگاه) باشد. این شامل گوش دادن به تغییرات نمای نقشه، حذف این رویدادها، و سپس ترسیم مجدد فقط نشانگرهای ضروری است.
یک شنونده رویداد را به رویداد بیکار نقشه متصل کنید. این رویداد پس از اتمام هر عملیات پاننگ یا بزرگنمایی فعال می شود و یک نمای پایدار برای محاسبات شما فراهم می کند.
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 Maps به طور منحصربه‌فرد شناسایی می‌کند و برای واکشی جزئیات آن ضروری است. شما معمولاً این شناسه‌های مکان را از قبل دریافت می‌کنید و آنها را در هر یک از سوابق فروشگاه خود ذخیره می‌کنید.
ادغام Place Details Compact Element در برنامه
هنگامی که یک فروشگاه مشخص می شود که در نمای نقشه فعلی قرار دارد و در نوار کناری ارائه می شود، می توانید به صورت پویا یک عنصر فشرده جزئیات مکان را برای آن ایجاد و درج کنید.
برای فروشگاه فعلی در حال پردازش، شناسه مکان را از داده‌های خود بازیابی کنید. شناسه مکان برای کنترل مکان نمایش عنصر مورد استفاده قرار می گیرد.
در جاوا اسکریپت، به صورت پویا یک نمونه از 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 مراجعه کنید.
عنصر Compact Place Details از استایل سازی از طریق ویژگی های سفارشی CSS پشتیبانی می کند. این به شما امکان می‌دهد ظاهر آن (رنگ‌ها، فونت‌ها و غیره) را متناسب با طراحی برنامه خود تنظیم کنید. این ویژگی های سفارشی را در فایل CSS خود اعمال کنید. مستندات مرجع PlaceDetailsCompactElement را برای خصوصیات CSS پشتیبانی شده ببینید.
مثالی از اینکه برنامه شما چگونه می تواند در این مرحله به نظر برسد:
یاب فروشگاه را تقویت کنید
شما یک پایه محکم برای برنامه یاب فروشگاه خود ساخته اید. اکنون، چندین راه را برای گسترش عملکرد آن و ایجاد تجربه ای غنی تر و کاربر محورتر در نظر بگیرید.
تکمیل خودکار را اضافه کنید
با ادغام ورودی جستجو با تکمیل خودکار مکان ، نحوه یافتن مناطق را برای جستجوی فروشگاه‌ها توسط کاربران بهبود بخشید. هنگامی که کاربران آدرس، محله یا نقطه مورد علاقه خود را تایپ می کنند و پیشنهادی را انتخاب می کنند، نقشه را طوری برنامه ریزی کنید که به طور خودکار در آن مکان متمرکز شود و باعث به روز رسانی فروشگاه های اطراف شود. این کار را با افزودن یک فیلد ورودی و پیوست کردن قابلیت تکمیل خودکار مکان به آن انجام دهید. با انتخاب یک پیشنهاد، نقشه را می توان در آن نقطه در مرکز قرار داد. به یاد داشته باشید که آن را طوری پیکربندی کنید که بایاس یا محدود کردن نتایج به منطقه عملیاتی شما باشد.
تشخیص مکان
با اجرای عملکردی برای شناسایی موقعیت جغرافیایی فعلی آنها ، ارتباط فوری، به ویژه برای کاربران تلفن همراه ارائه دهید. پس از دریافت مجوز مرورگر برای شناسایی موقعیت مکانی آنها، به طور خودکار نقشه را روی موقعیت آنها متمرکز کنید و نزدیکترین فروشگاه ها را نمایش دهید. کاربران وقتی به دنبال گزینه های فوری هستند، برای این ویژگی Near Me ارزش زیادی قائل هستند. برای درخواست دسترسی به مکان، یک دکمه یا یک درخواست اولیه اضافه کنید.
فاصله و مسیرها را نشان دهید
هنگامی که کاربر یک فروشگاه مورد علاقه خود را شناسایی کرد، سفر خود را با یکپارچه سازی Routes API به طور قابل توجهی افزایش دهید. برای هر فروشگاهی که فهرست می‌کنید، فاصله از مکان فعلی کاربر یا مکان جستجو شده را محاسبه و نمایش دهید. علاوه بر این، دکمه یا پیوندی ارائه کنید که از Routes API برای ایجاد مسیری از مکان کاربر به فروشگاه انتخاب شده استفاده می کند. سپس می‌توانید این مسیر را روی نقشه‌تان نمایش دهید یا برای پیمایش به Google Maps پیوند دهید، و یک انتقال بی‌وقفه از یافتن یک فروشگاه تا رسیدن به آنجا ایجاد کنید.
با پیاده‌سازی این افزونه‌ها، می‌توانید از قابلیت‌های بیشتر پلتفرم نقشه‌های گوگل برای ایجاد مکان یاب فروشگاه جامع‌تر و راحت‌تر استفاده کنید که مستقیماً نیازهای مشترک کاربران را برطرف می‌کند.
نتیجه گیری
این راهنما مراحل اصلی ایجاد یک فروشگاه یاب تعاملی را نشان داده است. شما یاد گرفته‌اید که چگونه مکان‌های فروشگاه خود را با استفاده از Maps JavaScript API به‌روزرسانی کنید، فروشگاه‌های قابل مشاهده را بر اساس تغییرات درگاه نمایش به‌روز کنید، و به طور قابل توجهی چگونه داده‌های فروشگاه خود را مطابق با Places UI Kit نمایش دهید. با استفاده از اطلاعات فروشگاه موجود خود، از جمله شناسه‌های مکان، با عنصر جزئیات مکان، می‌توانید جزئیات غنی و استاندارد شده را برای هر یک از مکان‌های خود ارائه دهید و پایه‌ای قوی برای مکان یاب فروشگاهی کاربرپسند ایجاد کنید.
Maps JavaScript API و Places UI Kit را امتحان کنید تا ابزارهای قدرتمند و مبتنی بر مؤلفه برای توسعه سریع برنامه‌های پیچیده مبتنی بر مکان ارائه دهید. با ترکیب این ویژگی ها می توانید تجربیات جذاب و آموزنده ای برای کاربران خود ایجاد کنید.
مشارکت کنندگان
Henrik Valve | مهندس DevX