کیت توسعه جاوااسکریپت
کیت توسعه نمایک روی MapLibre GL JS: نصب با تگ اسکریپت یا ماژول، گزینه‌های نقشه، همه توابع، جعبه جست‌وجو و خطاها.
نصب
کیت توسعه یک لایه نازک تایپ‌دار روی MapLibre GL JS 5 است (حدود ۸ کیلوبایت فشرده). MapLibre داخل کیت نیست: یا با تگ اسکریپت از سرور نمایک، یا با NamayekMaps.load()، یا از باندلر خودتان با use().
نصب
<link rel="stylesheet" href="https://maps.namayek.com/sdk/v1/1.2.0/maplibre-gl.css" integrity="sha384-uTttxo/aOKbdE5RlD/SPzSDoDmNvGlUYPjONi2MN/b7c9HPSvW07OIuyP7uL6jxK" crossorigin="anonymous"><script src="https://maps.namayek.com/sdk/v1/1.2.0/maplibre-gl.js" integrity="sha384-5+cfbwT0iiub6VsQAdn6yz16nr6sDiQoHx6tm4O8OVYXHYOxcffFmCJBL0dgdvGp" crossorigin="anonymous"></script><script src="https://maps.namayek.com/sdk/v1/1.2.0/namayek-maps.js" integrity="sha384-iSjkl164pbPaQaOuNplJF8w4f+TQEB0H0tGBhL5vSh6veBfSsOApYH+VgJATidNT" crossorigin="anonymous"></script><script src="https://maps.namayek.com/sdk/v1/1.2.0/namayek-maps.js" integrity="sha384-…" crossorigin="anonymous"></script><script> NamayekMaps.load().then(() => { new NamayekMaps.Map({ container: "map", key: "nmk_pk_YOUR_PUBLISHABLE_KEY" }); });</script>import * as NamayekMaps from "https://maps.namayek.com/sdk/v1/1.2.0/namayek-maps.mjs"; await NamayekMaps.load(); // MapLibre همراه کیت، با SRIconst map = new NamayekMaps.Map({ container: "map", key: "nmk_pk_YOUR_PUBLISHABLE_KEY" });// npm i maplibre-gl@5import maplibregl from "maplibre-gl";import "maplibre-gl/dist/maplibre-gl.css";import * as NamayekMaps from "https://maps.namayek.com/sdk/v1/1.2.0/namayek-maps.mjs"; NamayekMaps.use(maplibregl);NamayekMaps.config({ baseUrl: "https://maps.namayek.com" });<div id="map" style="height: 420px"></div><script> const map = new NamayekMaps.Map({ container: "map", key: "nmk_pk_YOUR_PUBLISHABLE_KEY", // کلید عمومی، محدود به دامنه شما style: "namayek-light", center: [51.389, 35.6892], // [طول، عرض] zoom: 12, lang: "fa", }); map.addMarker([51.389, 35.6892], { text: "دفتر مرکزی" });</script>گزینه‌های نقشه
| پارامتر | نوع | لزوم | پیش‌فرض | توضیح |
|---|---|---|---|---|
container | string | HTMLElement | لازم | — | عنصر یا شناسه عنصر نقشه؛ ارتفاع آن را خودتان تعیین کنید. |
key | string | لازم | — | کلید عمومی nmk_pk_ محدود به دامنه شما. |
style | string | StyleSpecification | اختیاری | namayek-light | سبک آماده، سبک شما (u-…)، نشانی سبک یا شیء سبک. |
lang | fa | en | fa-en | اختیاری | fa | زبان برچسب‌ها؛ با setLanguage بی بارگذاری دوباره عوض می‌شود. |
tileset | string | اختیاری | پیش‌فرض سرور (iran) | مجموعه داده. |
baseUrl | string | اختیاری | جایی که کیت بارگذاری شده | نشانی سرویس نقشه. |
rtl | boolean | اختیاری | true | افزونه شکل‌دهی فارسی (فقط MapLibre 5، تنبل). |
attribution | { compact?: boolean } | اختیاری | { compact: true } | انتساب همیشه نمایش داده می‌شود؛ فقط فشرده بودنش قابل تنظیم است. |
transformRequest | RequestTransformFunction | اختیاری | — | تبدیل درخواست شما، پس از تبدیل کیت اجرا می‌شود. |
center / zoom / … | MapOptions | اختیاری | — | همه گزینه‌های دیگر MapLibre همان‌طور پذیرفته می‌شوند. |
توابع
| نام | امضا | کار |
|---|---|---|
new Map | new NamayekMaps.Map(options: MapOptions) | نقشه MapLibre کامل (همه API آن کار می‌کند) به‌علاوه متدهای نمایک. |
SearchControl | new NamayekMaps.SearchControl(options?) | جعبه جست‌وجوی فارسی برای map.addControl. |
autocomplete | (q, opts: ApiOptions & { near?, limit?, lang?, bbox?, countries?, types? }) => Promise<SearchResponse> | پیشنهاد خودکار؛ پرسشی که پس از یکدست‌سازی خالی است بی درخواست پاسخ خالی می‌گیرد. |
search | (q, opts: همان autocomplete) => Promise<SearchResponse> | جست‌وجوی کامل. |
geocode | (input: string | { street?, houseNumber?, city?, county?, state?, postcode?, country? }, opts: ApiOptions & { limit?, lang? }) => Promise<GeocodeResponse> | نشانی‌یابی آزاد یا ساختاریافته. |
reverse | (at: LngLatLike, opts: ApiOptions & { zoom?, detail?, lang?, digits? }) => Promise<ReverseResponse> | نشانی از مختصات. |
route | (from, to, opts: ApiOptions & { via?, profile?, alternatives?, steps?, geometry?, overview?, exclude?, lang?, digits? }) => Promise<RouteResponse> | مسیریابی با دستور فارسی. |
matrix | (coordinates: LngLatLike[], opts: ApiOptions & { sources?, destinations?, profile?, annotations? }) => Promise<MatrixResponse> | ماتریس فاصله و زمان. |
staticUrl | (opts: StaticOptions) => string | نشانی یکتای نقشه ایستا؛ مسیر با polyline6 و پیش‌فرض‌ها حذف. |
styleUrl | (style, opts: { key, lang?, tileset?, baseUrl? }) => string | نشانی سند سبک برای MapLibre خودتان. |
load | (opts?: { baseUrl?, css? }) => Promise<maplibregl> | MapLibre همراه کیت را با SRI بارگذاری می‌کند. |
use | (maplibregl) => void | MapLibre باندلر خودتان را به کیت بدهید. |
config | (opts: { baseUrl? }) => void | نشانی سرویس نقشه را سراسری تنظیم می‌کند. |
supported | () => boolean | آیا مرورگر WebGL دارد. |
isSystemStyle | (style: string) => boolean | آیا شناسه یکی از چهار سبک آماده است. |
version / maplibreVersion | string | نسخه کیت و MapLibre همراه. |
| نام | امضا | کار |
|---|---|---|
addMarker | (lngLat, { color?, text?, draggable? }) => Marker | نشانگر؛ text به شکل متن (نه HTML) در پنجره کوچک می‌آید. |
geolocate | ({ highAccuracy?, zoom?, timeoutMs? }) => Promise<{ lng, lat, accuracy }> | موقعیت کاربر (فقط HTTPS و با اجازه). |
autocomplete / search | (q, opts?) => Promise<SearchResponse> | با کلید، زبان و مرکز همین نقشه. |
reverse | (at?, { zoom?, detail?, digits? }) => Promise<ReverseResponse> | پیش‌فرض مرکز نقشه. |
route | (from, to, opts?) => Promise<RouteResponse> | با زبان همین نقشه. |
showRoute | (RouteResponse | route | LineString, { id?, color?, width?, fit? }) => string | خط مسیر زیر برچسب‌ها و قاب‌بندی خودکار. |
clearRoute | (id?) => void | پاک کردن خط مسیر. |
setLanguage | (lang) => void | تعویض زبان برچسب‌ها با diff سبک. |
- همه توابع شبکه‌ای Promise برمی‌گردانند و خطای اعتبارسنجی را هم با reject اعلام می‌کنند.
- با
signal(AbortController) درخواست را لغو کنید؛ لغو با خطای بومیAbortErrorرد می‌شود. - نوع پاسخ‌ها دقیقا همان قرارداد API است (
SearchResponse،GeocodeResponse،ReverseResponse،RouteResponse،MatrixResponse) و فایلnamayek-maps.d.tsکنار هر نسخه است.
جعبه جست‌وجو
جعبه جست‌وجوی فارسی با پیشنهاد خودکار، کلیدهای جهت، Enter (بی ردیف انتخابی جست‌وجوی کامل) و Escape. هر نویسه تازه درخواست قبلی را لغو می‌کند و نتیجه‌ها همیشه به شکل متن (نه HTML) نمایش داده می‌شوند.
map.addControl( new NamayekMaps.SearchControl({ placeholder: "جستجوی مکان", countries: ["ir"], onSelect(item) { console.log(item.title, item.lat, item.lng); }, }),);| پارامتر | نوع | لزوم | پیش‌فرض | توضیح |
|---|---|---|---|---|
placeholder | string | اختیاری | جستجوی مکان | متن راهنمای جعبه. |
limit | 1..10 | اختیاری | 5 | تعداد پیشنهاد. |
minChars | 1..5 | اختیاری | 2 | حداقل نویسه یکدست‌شده پیش از درخواست. |
debounceMs | 100..1000 | اختیاری | 250 | مکث پس از تایپ؛ هر نویسه تازه درخواست قبلی را لغو می‌کند. |
types / countries / bbox | مثل autocomplete | اختیاری | — | محدود کردن نتیجه‌ها. |
flyTo | boolean | اختیاری | true | رفتن دوربین به مکان انتخاب‌شده. |
marker | boolean | اختیاری | true | گذاشتن نشانگر روی مکان انتخاب‌شده. |
onSelect | (item: SearchItem) => void | اختیاری | — | پس از انتخاب صدا زده می‌شود. |
خطاها
خطاها NamayekMapsError با سه فیلدند: code (ثابت برای برنامه)، status (HTTP؛ صفر برای خطای سمت کیت) و message (فارسی). کدهای سرور همان‌طور عبور می‌کنند.
try { await NamayekMaps.search("تهران", { key: "nmk_pk_YOUR_PUBLISHABLE_KEY" });} catch (e) { if (e.name === "AbortError") return; // لغو کاربر switch (e.code) { case "ORIGIN_NOT_ALLOWED": // دامنه را به کلید اضافه کنید case "RATE_LIMITED": // کمی صبر و تلاش دوباره case "UPSTREAM_UNAVAILABLE": // سرویس در حال آماده‌سازی default: console.warn(e.code, e.status, e.message); // پیام فارسی آماده نمایش }}| کد | HTTP | معنی و اقدام |
|---|---|---|
KEY_INVALID | کیت | کلید API معتبر نیستکلید عمومی nmk_pk_ کامل را بدهید. |
BROWSER_USE_FORBIDDEN | کیت | کلید محرمانه در مرورگر مجاز نیستکلید عمومی بدهید؛ هر تابع کیت کلید محرمانه را رد می‌کند. |
COORDINATES_INVALID | کیت | مختصات معتبر نیست[lng, lat] با lng بین -180 و ۱۸۰ و lat بین -90 و ۹۰. |
STYLE_INVALID | کیت | نام سبک معتبر نیستشناسه سبک سیستمی یا u-… بدهید. |
PARAM_INVALID | کیت | پارامتر … معتبر نیستنام پارامتر در پیام آمده است؛ آن را با جدول پارامترها تطبیق دهید. |
NETWORK | کیت | ارتباط با سرویس نقشه برقرار نشداتصال اینترنت را بررسی کنید و دوباره تلاش کنید. |
HTTP_ERROR | کیت | درخواست به سرویس نقشه ناموفق بودپاسخ JSON نبود (مثلا خطای شبکه میانی)؛ status را ببینید. |
MAPLIBRE_MISSING | کیت | کتابخانه نقشه بارگذاری نشده استmaplibre-gl.js را پیش از کیت بگذارید یا NamayekMaps.load() را صدا بزنید. |
BASE_URL_INVALID | کیت | نشانی سرویس نقشه معتبر نیستbaseUrl باید نشانی http یا https باشد. |
ROUTE_INVALID | کیت | مسیر معتبر نیستمسیر را با geometry=geojson (پیش‌فرض) بگیرید و پاسخ NO_ROUTE را جدا رسیدگی کنید. |
GEO_DENIED | کیت | اجازه دسترسی به موقعیت داده نشداز کاربر بخواهید دسترسی موقعیت را در مرورگر بدهد. |
نسخه و سنجاق کردن
- نشانی نسخه‌دار
https://maps.namayek.com/sdk/v1/1.2.0/namayek-maps.jsهرگز تغییر نمی‌کند و یک سال کش می‌شود؛ با SRI بگذارید. - نشانی بی نسخه
/sdk/v1/namayek-maps.jsآخرین نسخه ۱٫x را می‌دهد و یک ساعت کش می‌شود؛ برای آزمایش مناسب است، نه تولید. - نسخه‌ها semver هستند؛ تغییر ناسازگار فقط با نسخه اصلی تازه (
/sdk/v2/) می‌آید. - آخرین نسخه منتشرشده:
1.2.0.
آخرین به‌روزرسانی: