# نمایش شعب روی نقشه

<span id="branches-page"></span>

در این راهنما شعب کسب‌وکار خود را روی نقشه نمایش می‌دهید. انتخاب هر شعبه در فهرست، نقشه را به همان نقطه می‌برد.

## پیش‌نیازها

- یک نقشهٔ MapLibre آماده؛ اگر نقشه ندارید، [نمایش اولین نقشه](/dashboard/docs/quick-start-map) را ببینید.
- فهرست شعب با مختصات و یک مسیر در سرور برنامهٔ خودتان که داده‌ها را در `/api/branches` برگرداند.
- یک عنصر HTML با شناسهٔ `branches` و دکمه‌هایی با شناسهٔ هر شعبه؛ نمونهٔ عناصر در کد آمده است.

## مراحل

1. فهرست شعب را از سامانهٔ مدیریت محتوا یا API خودتان با شناسهٔ پایدار، نام، آدرس، مختصات و ساعات کاری دریافت کنید.
2. برای هر شعبه یک نشانگر بسازید و کارت متناظر را با همان شناسه به آن متصل کنید.
3. با انتخاب هر دکمه، نقشه را روی شعبه ببرید.
4. برای دسترس‌پذیری، شعب در فهرست HTML باقی بمانند و انتخاب نشانگر تنها راه دسترسی به اطلاعات نباشد.

## داده شعب متعلق به کسب‌وکار

```json
[
  {
    "id": "ferdowsi",
    "name": "شعبه میدان فردوسی",
    "address": "تهران، میدان فردوسی",
    "lat": 35.7042,
    "lng": 51.4197,
    "hours": "۸ تا ۲۲"
  },
  {
    "id": "vanak",
    "name": "شعبه میدان ونک",
    "address": "تهران، میدان ونک",
    "lat": 35.7576,
    "lng": 51.4090,
    "hours": "۸ تا ۲۳"
  }
]
```

## اتصال فهرست شعب به نقشهٔ MapLibre

```javascript
// این نمونه پس از ساخت نقشهٔ MapLibre با فایل style بلد اجرا می‌شود؛
// متغیر map همان نقشهٔ ساخته‌شده است.
// در HTML، فهرست شعب را با شناسهٔ branches قرار دهید؛ برای نمونه:
// <div id="branches">
//   <button type="button" data-branch-id="ferdowsi">شعبه میدان فردوسی</button>
//   <button type="button" data-branch-id="vanak">شعبه میدان ونک</button>
// </div>

const branches = await fetch("/api/branches").then(r => r.json());
const list = document.querySelector("#branches");

for (const branch of branches) {
  const marker = new maplibregl.Marker()
    .setLngLat([branch.lng, branch.lat])
    .setPopup(new maplibregl.Popup().setText(branch.name))
    .addTo(map);

  marker.getElement().addEventListener("click", () => {
    const cards = Array.from(list.querySelectorAll("[data-branch-id]"));
    cards.find(card => card.dataset.branchId === branch.id)?.focus();
  });
}

list.addEventListener("click", event => {
  const card = event.target.closest("[data-branch-id]");
  if (!card) return;
  const branch = branches.find(item => item.id === card.dataset.branchId);
  if (!branch) return;
  map.flyTo({ center: [branch.lng, branch.lat], zoom: 16 });
});
```

## نتیجهٔ مورد انتظار

برای هر شعبه یک نشانگر دیده می‌شود. با انتخاب نام شعبه در فهرست، نقشه به آن نقطه می‌رود؛ انتخاب نشانگر، فوکوس را روی دکمهٔ همان شعبه در فهرست می‌گذارد.

[![نقشهٔ واقعی بلد با دو نشانگر و فهرست دو شعبهٔ نمونه در تهران](/dashboard/docs/assets/branches-example.webp)](/dashboard/docs/assets/branches-example.webp)

در این تصویر نقشه از بلد دریافت شده و نام و نشانی شعب، دادهٔ فرضی برای آموزش هستند.

## نکات

- مسیر `/api/branches` متعلق به برنامهٔ شماست و فهرست شعب کسب‌وکارتان را برمی‌گرداند؛ این مسیر بخشی از API بلد نیست.
- مختصات تأییدشدهٔ شعب را ذخیره کنید؛ تبدیل نشانی به مختصات در هر بار بارگذاری صفحه هم کندتر است و هم مصرف غیرضروری ایجاد می‌کند.
- برای یافتن نزدیک‌ترین شعبه، فاصله را روی سرور یا با فرمول Haversine محاسبه کنید و اجازهٔ موقعیت مکانی مرورگر را فقط پس از اقدام کاربر بخواهید.
- نمونهٔ بالا فاصله یا شعب داخل کادر نقشه را محاسبه نمی‌کند؛ در صورت نیاز، این قابلیت‌ها را در برنامهٔ خود اضافه کنید.

## منابع تکمیلی

- [نمونه واقعی Store Locator استارباکس](https://www.starbucks.com/store-locator)
- [آموزش معماری Store Locator](https://docs.mapbox.com/help/tutorials/building-a-store-locator/)

[مرجع نقشهٔ برداری](/dashboard/docs/tile-vector) · [همهٔ آموزش‌های کاربردی](/dashboard/docs/guides)