هدف اصلی
این سند مراحل کلیدی برای توسعه برنامه تعاملی فروشگاهیاب بااستفاده از «پلاتفرم Google Maps»، بهویژه Maps JavaScript API و «کیت میانای کاربر جاها»: عنصر جزئیات جا را بهطور کامل توضیح میدهد. یاد خواهید گرفت که چگونه نقشهای ایجاد کنید که مکانهای فروشگاه را نمایش دهد، فهرستی از فروشگاههای قابلمشاهده را بهطور پویا بهروزرسانی کنید، و اطلاعات غنی مکان را برای هر فروشگاه نمایش دهید.
پیشنیازها
آشنایی با موارد زیر توصیه میشود:
- Maps JavaScript API - برای نشان دادن نقشه در صفحهتان و وارد کردن «کیت میانای کاربر جاها» استفاده میشود.
- نشانگرهای پیشرفته - برای نمایش نشانگرها روی نقشه استفاده میشود.
- کیت میانای کاربر «جاها» - برای نمایش اطلاعات مربوط به فروشگاههایتان در میانای کاربر استفاده میشود.
میانای برنامهسازی کاربردی جاوا اسکریپت Maps و کیت میانای کاربر «جاها» را در پروژهتان فعال کنید.
قبلاز شروع، مطمئن شوید که Maps JavaScript API را بار کردهاید و کتابخانههای لازم برای نشانگرهای پیشرفته و کیت میانای کاربر «جاها» را وارد کردهاید. این سند همچنین فرض میکند که شما دانش کاربردی از توسعه وب، ازجمله HTML، CSS، و JavaScript دارید.
راهاندازی اولیه
اولین قدم افزودن نقشه به صفحه است. از این نقشه برای نمایش سنجاقهای مربوط به مکانهای فروشگاهتان استفاده خواهد شد.
دو روش برای افزودن نقشه به صفحه وجود دارد:
- استفاده از مؤلفه وب HTML gmp-map
- استفاده از 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
}
در کد جاوا اسکریپت خود، دادههای مکانهای فروشگاهتان را واکشی کنید و برای هرکدام یک سنجاق روی نقشه نمایش دهید.
نمونهای از نحوه انجام این کار در زیر آمده است. این تابع شیئی را میگیرد که حاوی جزئیات فروشگاهها است و براساس مکان هرکدام، نشانگری ایجاد میکند.
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);
};
}
کد بالا نمونهای از تابع لرزشگیر است. این تابع یک تابع و آرگومان تأخیر میگیرد که میتوان آن را در شنونده بیکار مشاهده کرد. تأخیر ۳۰۰ میلیثانیهای برای توقف حرکت نقشه کافی است و تأخیر قابلتوجهی به میانای کاربر اضافه نمیکند.
وقتی این مهلت زمانی منقضی شد، تابع ردشده فراخوانی میشود، در این مورد،
updateMarkersInView.
تابع updateMarkersInView باید کنشهای زیر را انجام دهد:
پاک کردن همه نشانگرهای موجود از نقشه
بررسی کنید که آیا مکان فروشگاه در مرزهای نقشه فعلی قرار دارد یا نه، برای مثال:
if (map.getBounds().contains(storeLatLng)) {
// logic
}
در عبارت if بالا، کدی بنویسید تا اگر مکان فروشگاه در نمای نقشه قرار دارد، نشانگرها و جزئیات فروشگاه را در نوار کناری نمایش دهد.
نمایش جزئیات غنی مکان بااستفاده از «عنصر جزئیات مکان»
در این مرحله، برنامه همه مکانهای فروشگاه را نمایش میدهد و کاربران میتوانند آنها را براساس ناحیه نمایش نقشه فیلتر کنند. برای بهبود این تجربه، جزئیات غنی درباره هر فروشگاه، مانند عکسها، مرورها، و اطلاعات دسترسپذیری، بااستفاده از «عنصر جزئیات مکان» اضافه میشود. این مثال بهطور خاص از عنصر فشرده جزئیات مکان استفاده میکند.
هر مکان فروشگاه در منبع داده شما باید شناسه مکان مربوطه را داشته باشد. این شناسه بهطور منحصربهفرد مکان را در Google Maps شناسایی میکند و برای واکشی جزئیات آن ضروری است. معمولاً این «شناسههای مکان» را ازقبل دریافت میکنید و آنها را در مقابل هریک از سوابق فروشگاهتان ذخیره میکنید.
ادغام کردن «عنصر فشرده جزئیات جا» در برنامه
وقتی مشخص شود فروشگاهی در نمای نقشه فعلی قرار دارد و در نوار کناری ارائه شود، میتوانید بهطور پویا «عنصر فشرده جزئیات مکان» برای آن ایجاد و درج کنید.
برای فروشگاه فعلی که درحال پردازش است، «شناسه مکان» را از دادههایتان بازیابی کنید. از «شناسه مکان» برای کنترل اینکه کدام مکان نمایش داده شود استفاده میشود.
در جاوا اسکریپت، بهصورت پویا نمونهای از PlaceDetailsCompactElement ایجاد کنید. PlaceDetailsPlaceRequestElement جدیدی نیز ایجاد میشود، «شناسه مکان» به آن منتقل میشود، و این به PlaceDetailsCompactElement اضافه میشود. درنهایت، از
PlaceContentConfigElement برای پیکربندی محتوایی که عنصر نمایش خواهد داد استفاده کنید.
تابع زیر فرض میکند که کتابخانههای لازم «کیت میانای کاربر جاها»
وارد شدهاند و در دامنهای که این تابع فراخوانی میشود دردسترس هستند، و
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 خود اعمال کنید. برای اطلاع از ویژگیهای CSS پشتیبانیشده،
اسناد مرجع
PlaceDetailsCompactElement
را ببینید.
نمونهای از اینکه درخواست شما در این مرحله چگونه میتواند باشد:

بهبود فروشگاهیاب
شما یک پایه محکم برای برنامه فروشگاهیاب خود ساختهاید. اکنون، چند روش را برای گسترش عملکرد آن و ایجاد تجربهای غنیتر و کاربرمحورتر درنظر بگیرید.
افزودن تکمیل خودکار
با ادغام کردن ورودی جستجو با تکمیل خودکار جا، نحوه پیدا کردن مناطق برای جستجوی فروشگاهها را برای کاربران بهبود دهید. وقتی کاربران نشانی، محله، یا مکان جالب را تایپ میکنند و پیشنهادی را انتخاب میکنند، نقشه را طوری برنامهریزی کنید که بهطور خودکار روی آن مکان متمرکز شود و بهروزرسانی فروشگاههای اطراف را راهاندازی کند. برای این کار، فیلد ورودی اضافه کنید و عملکرد «تکمیل خودکار جا» را به آن پیوست کنید. با انتخاب پیشنهاد، نقشه میتواند روی آن نقطه متمرکز شود. بهیاد داشته باشید که آن را طوری پیکربندی کنید که نتایج را به منطقه عملیاتی شما محدود کند یا به آن سوگیری دهد.
تشخیص مکان
با پیادهسازی عملکردی برای تشخیص مکان جغرافیایی فعلی کاربران، بهویژه کاربران تلفن همراه، ارتباط فوری ارائه دهید. پساز دریافت اجازه مرورگر برای تشخیص مکان آنها، نقشه را بهطور خودکار روی موقعیت آنها متمرکز کنید و نزدیکترین فروشگاهها را نمایش دهید. کاربران هنگام جستجوی گزینههای فوری، ارزش زیادی برای این ویژگی اطراف من قائل هستند. دکمه یا پیامواره اولیهای برای درخواست دسترسی به مکان اضافه کنید.
نمایش فاصله و مسیرها
وقتی کاربر فروشگاه موردعلاقهاش را شناسایی کرد، با ادغام کردن Routes API، سفر او را بهطور قابلتوجهی بهبود دهید. برای هر فروشگاهی که فهرست میکنید، فاصله از مکان فعلی کاربر یا از مکان جستجوشده را محاسبه و نمایش دهید. علاوهبراین، دکمه یا پیوندی ارائه دهید که از Routes API برای تولید مسیر از مکان کاربر به فروشگاه انتخابشده استفاده میکند. سپس میتوانید این مسیر را در نقشهتان نمایش دهید یا برای ناوبری به Google Maps پیوند دهید، و انتقالی یکپارچه از پیدا کردن فروشگاه تا رسیدن به آنجا ایجاد کنید.
با پیادهسازی این افزونهها، میتوانید از قابلیتهای بیشتری از Google Maps Platform برای ساختن یک مکانیاب فروشگاه جامعتر و راحتتر استفاده کنید که مستقیماً به نیازهای رایج کاربران پاسخ میدهد.
نتیجهگیری
این راهنما مراحل اصلی ساختن فروشگاهیاب تعاملی را نشان داده است. یاد گرفتید که چگونه مکانهای فروشگاه خود را بااستفاده از Maps JavaScript API روی نقشه نمایش دهید، فروشگاههای قابلمشاهده را براساس تغییرات نمای هدف بهطور پویا بهروز کنید، و مهمتر از همه، چگونه دادههای فروشگاه خود را مطابق با «کیت میانای کاربر جاها» نمایش دهید. بااستفاده از اطلاعات فروشگاه موجودتان، ازجمله «شناسههای جا»، با «عنصر جزئیات جا»، میتوانید جزئیات غنی و استانداردشدهای را برای هریک از مکانهایتان ارائه دهید و پایهای قوی برای مکانیاب فروشگاه کاربرپسند ایجاد کنید.
Maps JavaScript API و کیت میانای کاربر «جاها» را امتحان کنید تا ابزارهای قدرتمند و مبتنی بر مؤلفه را برای توسعه سریع برنامههای پیچیده مبتنی بر مکان ارائه دهید. با ترکیب این ویژگیها، میتوانید تجربههای جذاب و آموزندهای برای کاربران خود ایجاد کنید.
همیاران
هنریک والو | مهندس DevX