‏راهنمای مهاجرت MapLibre GL JS از ۵ به ۶

نسخهٔ ۶ کتابخونهٔ MapLibre GL JS فقط به شکل ES module منتشر می‌شه؛ باندل UMD و بیلد جدای CSP که تو نسخهٔ ۵ بودن حذف شدن و فایل باندل حالا maplibre-gl.mjs (و کنارش maplibre-gl-worker.mjs) هست. تو راهنمای رسمی مهاجرت اومده که اگه از npm با ایمپورت named استفاده می‌کردی، کدت بدون دست خوردن کار می‌کنه، چون v6 خودش به باندل ESM resolve می‌شه.

چیزی که واقعاً می‌شکنه ایمپورت پیش‌فرضه و باید به namespace یا named تبدیل بشه:

// before
import maplibregl from 'maplibre-gl';

// after
import * as maplibregl from 'maplibre-gl';

اگه کتابخونه رو با تگ اسکریپت ساده از CDN لود می‌کردی، باید بری سراغ اسکریپت ماژولی و مسیر maplibre-gl.mjs نسخهٔ ۶ رو ایمپورت کنی. نکتهٔ خوبش اینه که تو همین حالت ESM مستقیم مرورگر، آدرس worker خودش از import.meta.url پیدا می‌شه و لازم نیست setWorkerUrl رو صدا بزنی. ولی تو باندلرها — Vite، webpack، esbuild، rspack و Rollup — چون import.meta.url به‌طور مطمئن به فایل worker نمی‌رسه، هنوز یه فراخوانی یک‌باره لازمه.

برای CSP هم دیگه بیلد اختصاصی لازم نیست. راهنما می‌گه اگه MapLibre رو cross-origin از CDN می‌گیری، worker از یه Blob URL هم‌ریشه ساخته می‌شه و باید blob: رو تو worker-src مجاز کنی؛ ولی اگه فایل worker رو خودت هاست می‌کنی، worker-src 'self' کافیه. کسایی هم که تو شیدرهاشون #pragma mapbox داشتن باید بذارنش #pragma maplibre.

پارامتر zoomLevelsToOverscale که تو نسخهٔ ۵ آزمایشی بود حالا رفتار پیش‌فرضه؛ به گفتهٔ تیم کلی مشکل برچسب‌گذاری رو حل می‌کنه ولی رندر و خروجی queryRenderedFeatures رو هم کمی عوض می‌کنه، و برای برگشت به حالت قبل باید موقع ساخت نقشه مقدارش رو undefined بذاری. رویدادها هم همه کلاس شدن و توصیه شده به‌جای instanceof فیلد type رو چک کنی. لیسنر styleimagemissing هم دیگه نمی‌تونه خودش تصویر جاافتاده رو بده و جاش Map#setMissingStyleImageResolver نشسته که sync و async هر دو رو قبول می‌کنه.

نکات کلیدی:

• ایمپورت‌های named سالم می‌مونن؛ فقط ایمپورت پیش‌فرض باید به namespace یا named عوض بشه.
• لود از CDN باید با اسکریپت ماژولی و فایل maplibre-gl.mjs انجام بشه.
• setWorkerUrl فقط تو باندلرها لازمه، نه تو ESM مستقیم مرورگر.
• CDN کراس‌اوریجین به blob: تو worker-src نیاز داره، خودهاستینگ نه.
• styleimagemissing جاش رو به Map#setMissingStyleImageResolver داده.