کامپوننت mapbox-gl React

کامپوننت Mapbox gl React

برای استفاده از کیت توسعه‌ی نقشه وب ابتدا بایستی از طریق ثبت نام رایگان در پنل توسعه‌دهندگان نشان، اقدام به دریافت کلید دسترسی برای (API Key) برای وب‌سایت یا اپلیکیشن تحت وب خود نمایید.

کامپوننت React نقشه و مسیریاب نشان، برای راحتی بیشتر توسعه‌دهنده‌های وب ایجاد گشته و با Api ساده،قابلیت‌های نقشه و سرویس‌های نشان را در اختیار توسعه دهندگان React قرار می‌دهد.

این کامپوننت از نقشه‌ی mapbox-gl v1.13.2 استفاده می‌نماید. برای شخصی‌سازی کردن بیشتر نقشه، می‌توانید از داکیومنت‌های رسمی mapbox نیز استفاده نمایید.

پکیج mapbox-gl-react یک wrapper برای پکیج @neshan-maps-platform/mapbox-gl جهت استفاده در پروژه‌های ساخته شده با ReactJS با قابلیت پشتیبانی از TypeScript است. به کمک این پکیج، شما به راحتی می‌توانید درون پروژه‌ی ReactJS خود، از mapboxgl با استایل‌های نقشه‌ی نشان، به همراه قابلیت نمایش ترافیک و POIها، استفاده کنید.

وابستگی ها (Dependencies):

@neshan-maps-platform/mapbox-gl: ورژن 1.0.10 یا بالاتر
@types/mapbox-gl: ورژن 2.7.15 یا بالاتر
react: ورژن 18.2.0 یا بالاتر
react-dom: ورژن 18.2.0 یا بالاتر

شیوه نصب (Installation guide):

با استفاده از npm :

            npm install @neshan-maps-platform/mapbox-gl-react

با استفاده از yarn :

            yarn add @neshan-maps-platform/mapbox-gl-react

نحوه استفاده و راه اندازی نقشه

بعد از نصب کردن پکیج در پروژه‌ی خود، می‌توانید با استفاده از کامپوننت MapComponent، از نقشه استفاده کنید.

            // Your imports
import {MapComponent, MapTypes} from "@neshan-maps-platform/mapbox-gl-react";
import "@neshan-maps-platform/mapbox-gl-react/dist/style.css";

function App() {
    // Your Code
    return (
        {/*Your Component Structure*/}
        <MapComponent options={{mapKey: "YOUR_API_KEY", mapType: MapTypes.neshanRasterNight}}/>
        {/*Your Component Structure*/}
    );
}

export default App;

پارامترهای ورودی کامپوننت:

options: MapboxComponentInputOptions (object)

یک شیء که شامل مقادیر ورودی مورد نیاز برای mapbox-gl است. تمامی propertyهای زیر، اختیاری هستند و مقدار پیش‌فرض آنها نیز ذکر شده.

تنها ارائه‌ی mapKey برای کار کردن کامپوننت، اجباری است!

mapKey: از نوع string است. مقدار آن نشان دهنده‌ی کلید دسترسی ای است که از وبسایت پلتفرم نشان دریافت می‌کنید، است. در صورتی که مقدار آن، درست نباشد، نمی‌توانید از کامپوننت استفاده کنید. همچنین در console، با اروری مبنی بر درست نبودن مقدار آن مواجه خواهی شد.
mapType: از نوع string است. و نوع استایل نقشه را مشخص می‌کند. در حال حاضر، صرفا چهار استایل برای نقشه موجود است:

neshanVector | neshanVectorNight | neshanRaster | neshanRasterNight

برای مقدار دهی این property، می‌توانید از MapTypes که یک enum است و در همین پروژه موجود است، استفاده کنید.(به مثال بالا مراجعه کنید). مقدار پیش‌فرض این property برابر neshanVector است.
poi: از نوع boolean است. مشخص می‌کند که در ابتدا و بعد از لود شدن نقشه، poiها روی نقشه نمایش داده شوند یا نه. مقدار پیش‌فرض آن برابر false است.
traffic: از نوع boolean است. مشخص می‌کند که در ابتدا و بعد از لود شدن نقشه، لایه‌ی ترافیک فعال باشد یا خیر. مقدار پیش‌فرض آن برابر false است.
isTouchPlatform : از نوع boolean است. و نوع دستگاه(تاچ و موبایل یا دسکتاپ) را مشخص می‌کند. مقدار پیش‌فرض آن false است.
mapTypeControllerStatus: از نوع object است. مشخص می‌کند که آیا کنترل لایه‌ها و استایل‌های نقشه نمایش داده شود یا خیر و همچنین موقعیت آن را مشخص می‌کند:

            interface mapTypeControllerStatus {
    show: boolean,
        position: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
}

مقدار پیش‌فرض show برابر true و مقدار پیش‌فرض position برابر bottom-left است. می‌توان هر یک از این دو property را overwrite کرد.

دیگر propertyهای موجود در options، مربوط به خود mapbox-gl هستند. برای دیدن آنها به مستندات خود کتابخانه‌ی mapbox-gl مراجعه کنید.

نکته شما نمی‌توانید مقداری برای property تعیین کننده‌ی container پاس دهید.

mapSetter: (map: SDKMap) => void (optional)

از نوع تابع است و صرفا یک ورودی می‌گیرد. پاس دادن آن، اختیاری است. این تابع برای دسترسی شما به instance ایجاد شده از کلاس Map است. بعد از ایجاد شدن Map، مقدار آن به عنوان ورودی به این تابع، پاس داده می‌شود.

containerElementSetter: (el: HTMLDivElement) => void (optional)

از نوع تابع است و صرفا یک ورودی می‌گیرد. پاس دادن آن، اختیاری است. این تابع برای دسترسی شما به elementای که Map در آن رندر می‌شود، است. بعد از ایجاد شدن Map و رندر شدن آن، خود containerElement به عنوان ورودی به این تابع، پاس داده می‌شود.

توجه مواردی که ذکر شد، prop هایی بودند که مستقیما در عملکرد نقشه نقش داشتند و یا با نقشه سروکار دارند. اما این کامپوننت، propهای دیگری نیز می‌پذیرد. شما می‌توانید همه‌ی propهایی که یک HTMLDivElement قبول می‌کند را به کامپوننت پاس بدهید. همه‌ی این propها، به container نقشه پاس داده خواهند شد.

پشتیبانی از SSR و SSG
از آنجایی که خود کتابخانه mapboxGL از قابلیت SSR و SSG برای استفاده در فریمورک هایی مانند NEXTjs پشتیبانی نمی‌کند، به طبع کتابخانه MapboxGL نشان نیز از این قابلیت پشتیبانی نمی‌کند و بایستی کامپوننت نقشه را به صورت داینامیک در این فریم‌ورک ها لود نمایئد.

استفاده از کلاس‌های MapboxGL

همانطور که در بخش وابستگی‌ها مشاهده می‌شود، این کتابخانه از پکیج @neshan-maps-platform/mapbox-gl استفاده می‌کند. برای استفاده از دیگر کلاس‌ها و propertyهای MapboxGL، مانند Marker و …، باید آنها را از مسیر @neshan-maps-platform/mapbox-gl، در جایی که می‌خواهید، import کنید. مانند مثال زیر:

            //...
import nmp_mapboxgl from '@neshan-maps-platform/mapbox-gl';

function MyComponent(...){
  //Your code here
  const marker = new nmp_mapboxgl.Marker(...);
  return (...);
}

export default MyComponent