کامپوننت 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/dist/NeshanMapboxGl.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 کرد.
mapSetter: (map: SDKMap) => void (optional)
از نوع تابع است و صرفا یک ورودی میگیرد. پاس دادن آن، اختیاری است. این تابع برای دسترسی شما به instance ایجاد شده از کلاس Map است. بعد از ایجاد شدن Map، مقدار آن به عنوان ورودی به این تابع، پاس داده میشود.
containerElementSetter: (el: HTMLDivElement) => void (optional)
از نوع تابع است و صرفا یک ورودی میگیرد. پاس دادن آن، اختیاری است. این تابع برای دسترسی شما به elementای که Map در آن رندر میشود، است. بعد از ایجاد شدن Map و رندر شدن آن، خود containerElement به عنوان ورودی به این تابع، پاس داده میشود.
در حال حاضر کامپوننت ریاکت نشان از قابلیت SSR و SSG پشتیبانی نمیکند.
استفاده از کلاسهای 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