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

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

Dependencies -- وابستگی‌ها

• @neshan-maps-platform/mapbox-gl: ورژن 1.0.10 یا بالاتر
• @types/mapbox-gl: ورژن 2.7.17 یا بالاتر
• vue: ورژن 3.3.4 یا بالاتر

Installation guide -- شیوه‌ی نصب

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

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

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

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

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

1. ابتدا با ساخت حساب کاربری در پلتفرم نقشه‌ی نشان، یک API_KEY برای خود بسازید. توضیحات لازم در وبسایت پلتفرم نقشه‌ی نشان داده شده است.
2. سپس، با استفاده از package managerای که دارید استفاده می‌کنید، این پکیج را در پروژه‌ی خود نصب کنید.
3. بعد از نصب کردن پکیج در پروژه‌ی خود، می‌توانید با استفاده از کامپوننت MapComponent، از نقشه استفاده کنید:

<script setup>
  //...
  import {MapComponent, MapTypes} from "@neshan-maps-platform/mapbox-gl-vue";
  import "@neshan-maps-platform/mapbox-gl-vue/dist/style.css";
  //...
</script>

<template>
  <!--  Your component structure-->
  <MapComponent :options="{mapKey:'YOUR_API_KEY',mapType:MapTypes.neshanVectorNight}"/>
  <!--  Your component structure-->
</template>

<style>
//  Your styles
</style>

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

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

v-bind: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 پاس دهید.

v-bind:map-setter : (map: SDKMap) => void (optional)

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

v-bind:container-element-setter : (el: HTMLDivElement) => void (optional)

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

دیگر موارد

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

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

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

<script setup>
  //...
  import nmp_mapboxgl from "@neshan-maps-platform/mapbox-gl";
  const marker = new nmp_mapboxgl.Marker(...);
  //...
</script>

<template>
  <!--  Your component structure-->
</template>

<style>
  //  Your styles
</style>