@djawad98/frotel-map NPM

Frotel Map

این پکیج به صورت اختصاصی برای «فروتل» (نوآوري بازارساز پايدار) توسعه داده شده است.

این پکیج از فایل های جی اس و سی اس اس ارائه شده توسط نشان استفاده میکند. این فایلها در واقع یک wrapper برای کتابخانه معروف leaflet می باشد. لذا مطالعه مستندات مربوط به کتابخانه leaflet ضروری است.

لیست فیچر/ماژول ها

🖋️ Polygon ( رسم چند ضلعی )
🔎 Search ( جستجو )
📌 Pin ( قراردادن پین )
🗺️ Locate ( موقعیت یابی )
🌏 Geocoding ( تبدیل مختصات به آدرس متنی )
📍 CenteralPin ( قراردادن پین به سبک اسنپ )

نحوه استفاده

با دستور زیر پکیج را از npm نصب کنید
```
    npm i @djawad98/frotel-map -S
```

این پکیج دو نوع خروجی esmodule و umd را در اختیار شما قرار میدهد. لذا باید از یک باندلر مثل webpack یا vite یا ... استفاده کنید.

تگ اسکریپت زیر را در <head> داکیومنت خود اضافه کنید
```
<script src="https://static.neshan.org/sdk/leaflet/1.4.0/leaflet.js"></script>
```

سپس فراخوانی کنید

    import { Map } from "@djawad98/frotel-map";


    const mapp = new Map('map_id', {
      key: 'xxxx',
      serviceKey: 'zzzz'
    })

حالا امکان مشاهده نقشه را خواهید داشت. توجه داشته باشید که باید کلیدهای مربوط به نمایش نقشه web key و دسترسی به سرویس service key را از پنل خود در نشان بدست بیاورید و در فیلدهای بالا قرار دهید.

const mapp = new Map( el, ?options{} )

el : آیدی عنصر مورد نظر که نقشه در داخل آن نمایش داده میشود (بدون علامت # ابتدایی)

options: آبجکتی شامل آپشن های نقشه

متد add

با استفاده از متد add روی اینستنس اصلی نقشه میتوانید این ماژول را اضافه کنید. این متد در جواب، اینستنس مربوط به ماژول Polygon برمیگرداند.

mapInstance.add( moduleName, moduleOptions)

آپشن های نقشه

`key`

type: string

default: null

کلید مربوط به نمایش نقشه. (از طریق پنل کاربری خود در نشان بدست بیاورید.)

`servicekey`

type: string

default: null

کلید مربوط به استفاده از سرویس های نشان. به عنوان مثال سرویس جستجو یا تبدیل متخصات به آدرس متنی. (از طریق پنل کاربری خود در نشان بدست بیاورید.)

`readonly`

type: boolean

default: false

همه اینترکشن ها و فیچرهای مپ غیرفعال میشوند.به جز امکان زوم. فعال کردن این آپشن روی ماژول ها تاثیر میگذارد.

`center`

type: array|object

default: [35.699739, 51.338097] | { lat: 35.699739, lng: 51.338097 }

مختصات نمای نقشه هنگام لود اولیه.

`zoom`

type: number

default: 12

میزان بزرگنمایی نقشه هنگام لود اولیه

`leaflet`

type: object

default: {}

اگر مایلید مستقیما آپشنی را به هسته اصلی leaflet پاس بدهید از این طریق اقدام کنید. تمام آپشن هایی که در مستندات leaflet آورده شده اند معتبر است.

`onReady`

type: function

default: () => {}

یک تابع تعریف کنید تا هنگامی که مپ به صورت کامل لود شد اجرا شود.

🖋️ Polygon

ماژول Polygon را از پکیج فراخوانی کنید.

    import { Map, Polygon } from "@djawad98/frotel-map";

    const mapInstance = new Map('map_id', {
      key: 'xxxx',
      serviceKey: 'zzzz'
    })

به هسته نقشه اضافه اش کنید

    const polygonInstance = mapInstance.add(Polygon, { options });

متد مورد نظر را فراخوانی کنید

    polygonInstance.drawPolygon( [ [1.324,2.32423], [4.324,2.32423],... ] )

🖋️ آپشن های Polygon

`canSelectArea`

type: boolean

default: false

برای نمایش دکمه رسم چند ضلعی در پائین سمت راست نقشه

`drawMode`

type: boolean

default: false

برای فعال کردن دکمه رسم پالیگان به صورت پیشفرض هنگام لود نقشه

`preventIntersection`

type: boolean

default: false

برای فعال کردن حالت همپوشانی چند ضلعی جاری با چند ضلعی های موجود

`editableAfterShapeClosed`

type: boolean

default: false

با فعال کردن این ویژگی، بعد از رسم چندضلعی و بستن شکل، قابلیت ادیت چند ضلعی فراهم میشود.

`onShapeClosed`

type: function

default: (coords) => {}

تابعی به این آپشن پاس دهید تا هنگام بسته شدن شکل فراخوانی شود. این تابع در آرگومان اول مختصات چند ضلعی رسم شده را بر میگرداند. مطابق زیر:

    const polygonInstance = mapInstance.add(Polygon, {

      onShapeClosed: coords => {
        console.log(coord)
      }

    });

`onDrawing`

type: function

default: (coords) => {}

تابعی پاس دهید تا هنگام رسم چندضلعی به صورت پشت سرهم فراخوانی شود. به عنوان آرگومان اول، مختصات شکل در حال رسم را برمیگرداند.

`onEditedPolygon`

type: function

default: (coords) => {}

تابعی پاس دهید تا هنگام ویرایش چندضلعی فراخوانی شود. به عنوان آرگومان اول، مختصات شکل در حال ویرایش را برمیگرداند.

🖋️ متدهای Polygon

getCoordinates
```
    polygonInstance.getCoordinates()
```

**returns** مختصات پالیگان حال حاضر (چه در حالت رسم چه در حالت بسته بودن )

`[[lat, lng], [lat, lng], ...]`

**parameters** *no parameters*

drawPolygon برای رسم چندضلعی با مختصات داده شده. مطابق زیر
```
polygonInstance.drawPolygon( [ [lat, lng], [lat, lng], [lat, lng], ... ] , "blue")
```

parameters

coords: مختصات پالیگان مورد نظر
color: رنگ پالیگان موردنظر

drawEditablePolygon برای رسم چندضلعی قابل ویرایش با مختصات داده شده. مطابق زیر

    polygonInstance.drawEditablePolygon( [ [lat, lng], [lat, lng], [lat, lng], ... ] , "blue")

**parameters**

- `coords`: مختصات پالیگان مورد نظر

- `color`: رنگ پالیگان موردنظر

🔎 Search

ماژول Search را از پکیج فراخوانی کنید

    import { Map, Search } from "@djawad98/frotel-map";

    const mapInstance = new Map('map', {
      key: 'xxxx',
      ...
    })

    const searchInstance = mapInstance.add(Search, { options });

🔎 آپشن های Search

`noPin`

type: boolean

default: false

برای فعال یا غیرفعال کردن قراردادن پین هنگام انتخاب یک موقعیت از لیست نتایج جستجو

📌 Pin

ماژول Pin را از پکیج فراخوانی کنید.

    import { Map, Pin } from "@djawad98/frotel-map";

    const mapInstance = new Map('map', {
      key: 'xxxx',
      ...
    })

    const pinInstance = mapInstance.add(Pin, { options });

📌 آپشن های Pin

`editMode`

type: boolean

default: false

با فعال کردن این آپشن امکان قرار دادن پین جدید از طریق دکمه مربوط به پین در پائین در سمت راست وجود نخواهد داشت.

`initialLatLng`

type: array | object

default: null

مختصات نمای ابتدایی نقشه که هنگام لود ابتدایی روی آن فوکوس میکند. مشابه کاری که متد setView در leaflet انجام میدهد.

این آپشن به هسته اصلی نقشه منتقل خواهد شد

`renderButton`

type: boolean

default: true

تعیین می کند که آیا دکمه قراردادن پین در پائین سمت راست نقشه نمایش داده شود یا خیر.

`centerMode`

type: boolean

default: false

این آپشن دکمه افزودن پین را غیر فعال میکند و امکان استفاده از ماژول CentralPin را فراهم میکند. فعال کردن این آپشن هنگام استفاده از ماژول CentralPin ضروری است.

`maxPinCount`

type: number

default: 1000

حداکثر تعداد پین هایی که کاربر می تواند از طریق دکمه قرارداده شده در پائین سمت راست نقشه اضافه کند را مشخص میکند. توجه داشته باشید که تعداد پین هایی که میتوان از طریق متد addPin اضافه کرد نامحدود هستند و این آپشن محدودیتی برای اضافه کردن پین از طریق این متد اعمال نمیکند.

`onPin`

type: function

default: (coords) => {}

تابعی پاس بدهید تا هنگام قرار دادن پین روی نقشه توسط کاربر، فراخوانی شود. به عنوان آرگومان اول مختصات نقظه ای که پین قرارداده شده را برمیگرداند.

📌 متدهای Pin

addPin: یک پین یا مارکر جدید در مختصات داده شده قرار میدهد.

    pinInstance.addPin([lat, lng])

🗺️ Locate

این ماژول برای یافتن موقعیت کنونی کاربر استفاده میشود. توجه داشته باشید برای اینکه این ماژول به درستی کار کند نیاز به سرور امن https است. اگر روی لوکال تست می کنید حتما از مرورگر edge یا firefox استفاده کنید.

ماژول Locate را از پکیج فراخوانی کنید.

    import { Map, Locate } from "@djawad98/frotel-map";

    const mapInstance = new Map('map', {
      key: 'xxxx',
      ...
    })

    const locateInstance = mapInstance.add(Locate, { options });

🗺️ آپشن های Locate

`noPin`

type: boolean

default: false

معین میکند که آیا موقع یافتن موقعیت کنونی کاربر در آن نقطه پین یا مارکر جدید قرار بدهد یا خیر

🗺️ متدهای Locate

findmyplace: موقعیت کنونی کاربر را بر روی نقشه پیدا میکند و فوکوس نقشه را به آن موقعیت میبرد.
```
    pin.findmyplace()
```

🌏 Geocoding

برای تبدیل مختصات به آدرس متنی استفاده میشود. نا صحیح این فیچر reverse geocoding است.

ماژول Geocoding را از پکیج فراخوانی کنید.

    import { Map, Geocoding } from "@djawad98/frotel-map";

    const mapInstance = new Map('map', {
      key: 'xxxx',
      ...
    })

    const geocodingInstance = mapInstance.add(Geocoding, { options });

🌏 متدهای Geocoding

getAddress آدرس متنی مختصات داده شده را برمیگرداند.

    geocodingInstance.getAddress( [ lat, lng ] )

parameters

latlng: مختصات نقطه مورد نظر

returns آبجکتی حاوی اطلاعات آدرس نقطه مورد نظر، با ساختار زیر

توجه: این متد یک متد async است. مطابق زیر استفاده کنید.

    await geocodingInstance.getAddress([lat, lng])



    // result object
    {
        "status": "OK",
        "formatted_address": "تهران، دکتر فاطمی، حجاب، سازمان آب، بین دائمی و عبداله زاده",
        "route_name": "سازمان آب",
        "route_type": "secondary",
        "neighbourhood": "فاطمي",
        "city": "تهران",
        "state": "استان تهران",
        "place": null,
        "municipality_zone": "6",
        "in_traffic_zone": "true",
        "in_odd_even_zone": "true",
        "village": null,
        "district": "بخش مرکزی شهرستان تهران",
    }

با توجه به نقطه انتخابی ممکن است تعدادی از فیلدها ارائه نشوند. اطلاعات بیشتر

📍 CenteralPin

برای انتخاب نقطه ای روی نقشه به سبک انتخاب مبدا و مقصد در اسنپ

`enableAddress`

type: boolean

default: true

معین میکند آیا بعد از قرارگرفتن پین روی نقشه آدرس متنی آن نقطه محاسبه شود یا خیر. با استفاده از آپشن onFoundAddress به نتیجه محاسبه دسترسی خواهید داشت.

`enablePopup`

type: boolean

default: true

معین میکند آیا پاپ آپ مربوط به آدرس نقطه روی پین نمایش داده شود یا خیر

`onPinUp`

type: function

default: (latlng) => {}

تابعی پاس بدهید تا هنگامی که پین از روی مپ برداشته/بلند میشود فراخوانی شود. به عنوان آرگومان اول محتضات نقطه را برمیگرداند.

`onPinDown`

type: function

default: (latlng) => {}

تابعی پاس بدهید تا هنگامی که پین روی مپ قرار میگیرد فراخوانی شود. به عنوان آرگومان اول محتضات نقطه را برمیگرداند.

`onFoundAddress`

type: function

default: (address) => {}

اگر آپشن enableAddress فعال باشد، هنگامی که پین روی مپ مینشیند این تابع با کمی تاخیر فراخوانی میشود. به عنوان آرگومان اول اطلاعات آدرسی نقطه ر برمیگرداند.

UX Shortcuts

Undo polygon point: to undo the last point, right-click anywhere on the map.
Closing the shape: to close the shape when drawing, just double click to close the shape automatically.
Cancel pin: to discard current pin, right click on the map