نسخه‌ی رسمی @neshan-maps-platform/mapbox-gl برای ReactJS

این پکیج، wrapper رسمی نشان برای @neshan-maps-platform/mapbox-gl جهت استفاده در پروژه‌های ساخته شده با ReactJS است. به کمک این پکیج، شما به راحتی می‌توانید درون پروژه‌ی ReactJS خود، از mapbox-gl، با استایل‌های نقشه‌ی نشان، به همراه قابلیت نمایش ترافیک و 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

Usage -- شیوه‌ی استفاده

1. ابتدا با ساخت حساب کاربری در پلتفرم نقشه‌ی نشان، یک API_KEY برای خود بسازید. توضیحات لازم در وبسایت پلتفرم نقشه‌ی نشان داده شده است.
2. سپس، با استفاده از package managerای که دارید استفاده می‌کنید، این پکیج را در پروژه‌ی خود نصب کنید.
3. بعد از نصب کردن پکیج در پروژه‌ی خود، می‌توانید با استفاده از کامپوننت 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;

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

Component Props -- ورودی‌های کامپوننت

options: MapboxComponentInputOptions (object)

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

• mapKey: از نوع string است. مقدار آن نشان دهنده‌ی API_KEYای که از وبسایت پلتفرم نشان دریافت می‌کنید، است. در صورتی که مقدار آن، درست نباشد، نمی‌توانید از کامپوننت استفاده کنید. همچنین در 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 نقشه پاس داده خواهند شد.

استفاده از کلاس‌های 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

پشتیبانی از SSR و SSG

این کتابخانه از ssr و ssg پشتیبانی نمی کند. در صورت نیاز به نمایش نقشه در صفحه‌ای با قابلیت ssr، لازم است برای کامپوننت نقشه ssr را غیرفعال کنید.