عندك قائمة بفروع شركتك، أو بالمدارس في مدينتك، أو بمواقع المشاريع التي تتابعها، في جدول Excel أو في قاعدة بيانات، وتريد أن يراها الزائر على خريطة في موقعك: يكبر ويصغر، ويضغط على النقطة فيرى الاسم، والأسماء على الخريطة بالعربية. والطريقة المعتادة أن تنسخ مثالاً جاهزاً من موقع مزود خرائط، فيعمل في دقائق، ثم تبدأ الأسئلة: لماذا تظهر العلامات تحت الخريطة؟ لماذا الصفحة بيضاء عندما أفتح الملف مباشرة؟ لماذا أصبحت الصفحة بطيئة عندما وضعت خمسة آلاف نقطة؟ ولماذا ظهر فرعي في بحر إيجة؟ وكل هذه الأسئلة لها إجابة واحدة تقريباً: أنك لم تعرف بعد كيف تفكر المكتبة التي ترسم الخريطة.
وفي هذا المقال نبني خريطة تفاعلية خطوة بخطوة بمكتبة MapLibre GL JS المفتوحة المصدر، ونرى بعد كل خطوة صورة حقيقية من المتصفح، ونفتعل الأخطاء التي يقع فيها الجميع ونقرأ رسائلها. وقد شرحنا في خرائطك على سيرفرك كيف تستضيف خريطة الأساس نفسها بملف PMTiles على سيرفرك، أما هنا فنركز على ما يكتبه المطور في الصفحة فوق هذه الخريطة. وسوف نناقش في هذا المقال ما يلي:
- كيف تفكر MapLibre: ملف التنسيق Style، والمصادر Sources، والطبقات Layers، وترتيب الرسم.
- أول خريطة في صفحة، ثم تنسيق نكتبه من الصفر دون أي خريطة أساس.
- خريطة أساس متجهة Vector Tiles بأسماء عربية، وماذا حدث لإضافة النصوص من اليمين إلى اليسار RTL Text Plugin.
- العلامات Markers والنوافذ Popups، وfitBounds التي تعرض كل النقاط مهما كان حجم الشاشة.
- بيانات GeoJSON حقيقية من 5,172 مكاناً، مع التجميع Clustering والألوان بحسب التصنيف.
- الأداء: نفس النقاط كعلامات HTML وكطبقة واحدة، بالأرقام.
- ستة أعطال حقيقية قابلناها في التجربة، مع رسالة كل منها وحلها.
لماذا MapLibre GL JS؟
هناك ثلاثة خيارات معروفة لرسم خريطة في صفحة ويب، ولكل منها مكانه:
- واجهة مزود تجاري مثل Google Maps JavaScript API: أسهل بداية، وخريطة جاهزة وبحث ومسارات، ولكن البيانات والعرض ملك المزود، والدفع بعدد الطلبات، والشروط تمنعك من عرض بياناته على خريطة أخرى، كما فصلنا في قسم الرخص من مقال «من يرسم خريطة الشارع؟».
- مكتبة Leaflet: مكتبة مفتوحة خفيفة وممتازة، ترسم المربعات النقطية Raster Tiles كصور، وتضع العلامات كعناصر HTML، وتكفي لخريطة فيها عشرات النقاط فوق مربعات جاهزة.
- مكتبة MapLibre GL JS: ترسم المربعات المتجهة Vector Tiles بال WebGL في متصفح الزائر، فتغير الألوان واللغة دون مربعات جديدة، وتدير التقريب والدوران دون أن تتقطع الصورة، وتتحمل آلاف النقاط كطبقة واحدة. وهي بحسب مستودع المشروع نسخة مفتوحة بدأت من mapbox-gl-js قبل أن تنتقل Mapbox إلى رخصة غير مفتوحة في ديسمبر 2020، ورخصتها BSD-3-Clause.
وقد يتساءل البعض: إذا كانت Leaflet أبسط فلماذا لا نبدأ بها؟ والإجابة أن الخريطة التي تعرض أسماء عربية بخط واضح، وتستضيف بياناتها على سيرفرك، وتعرض آلاف الأماكن، هي بالضبط ما صممت له MapLibre، ولو بدأت بغيرها ستعيد الكتابة بعد أول طلب بتغيير اللغة أو إضافة طبقة. والإصدار الذي نستخدمه 6.18.0، وهو الأحدث في سجل التغييرات عند كتابة المقال.
كيف تفكر MapLibre: التنسيق والمصادر والطبقات
أهم فكرة في هذا المقال كله أن MapLibre لا تعرف شيئاً اسمه «خريطة جاهزة». كل ما تراه يأتي من ملف تنسيق Style بصيغة JSON، مكتوب بحسب مواصفة التنسيق، وفيه أربعة أجزاء رئيسية، والصورة التالية تبينها:

- المصادر Sources: من أين تأتي البيانات. مصدر متجه
vectorمن مربعات MVT أو ملف PMTiles، أو مصدرgeojsonمن ملف أو كائن JavaScript، أو مصدر نقطيrasterلصور جاهزة مثل صور الأقمار الصناعية. والمصدر وحده لا يرسم شيئاً. - الطبقات Layers: كيف ترسم البيانات. كل طبقة تأخذ مصدراً، واختيارياً طبقة داخلية منه Source Layer، ونوع رسم:
fillللمضلعات، وlineللخطوط، وcircleللنقاط كدوائر، وsymbolللنصوص والأيقونات، وbackgroundللخلفية. والترتيب في المصفوفة هو ترتيب الرسم: الأولى في الأسفل والأخيرة في الأعلى. - الخطوط Glyphs: رابط لملفات الخطوط مقسمة إلى مجموعات من 256 حرفاً، فلا يحمل المتصفح إلا الحروف التي يحتاجها.
- الأيقونات Sprite: صورة واحدة فيها كل الأيقونات وملف JSON يقول أين كل أيقونة فيها.
وهناك جزء خامس لا يدخل في ملف التنسيق: العلامات Marker والنوافذ Popup وأدوات التحكم Controls، فهي عناصر HTML عادية تضعها المكتبة فوق لوحة الرسم Canvas وتحركها مع الخريطة. وهذا الفرق بين ما يرسم داخل WebGL وما يوضع فوقه كعناصر HTML هو سبب نصف المشاكل التي سنقابلها، وسبب فرق الأداء الكبير الذي سنقيسه.
من أين تأتي خريطة الأساس؟
المكتبة ترسم، ولكنها لا تأتي بخريطة، فقبل أن تكتب أي كود يجب أن تعرف من أين تأتي المربعات والخطوط والأيقونات، وأمامك أربعة طرق:
- التنسيق التجريبي العام: مثل
demotiles.maplibre.orgالذي استخدمناه في الخطوة الأولى، وهو خريطة دول بسيطة جداً بلا طرق ولا مدن، مخصصة للأمثلة والتجارب، فلا تبن عليها موقعاً. - سيرفرات مربعات OpenStreetMap: وهي مربعات نقطية، وسياسة استخدامها تقول إنها خدمة بأفضل جهد دون اتفاقية مستوى خدمة، وإن الاستخدام الثقيل قد يحجب دون إنذار، فهي ليست لموقع تجاري يزوره الآلاف.
- مزود مربعات تجاري: تدفع اشتراكاً وتحصل على رابط تنسيق جاهز ومفتاح API، وهذا مناسب إذا لم يكن لديك وقت لاستضافة الخريطة، ولكن كل زيارة تمر على سيرفر المزود وتدخل في فاتورته.
- ملف PMTiles على سيرفرك: وهو ما فعلناه في الخطوة 3، ملف واحد لمنطقتك يقدمه nginx، والتكلفة هي التخزين وحركة البيانات على سيرفرك، والخصوصية كاملة لأن الزائر لا يتصل بأي جهة أخرى. وقد شرحنا تفاصيله، من قص المنطقة إلى طلبات النطاق، في مقال الخرائط على سيرفرك.
والجميل في MapLibre أن الكود لا يتغير كثيراً بين هذه الطرق، فالذي يتغير هو رابط التنسيق أو المصدر فقط، لذلك تستطيع أن تبدأ بمزود تجاري في النسخة الأولى من تطبيقك، ثم تنقل الخريطة إلى سيرفرك عندما تكبر الفاتورة، دون أن تعيد كتابة طبقات بياناتك وعلاماتك ونوافذك. وهذا بالضبط عكس ما يحدث عندما تبني على واجهة مزود مغلقة، لأن الكود هناك مكتوب لمكتبته وحدها.
التجربة العملية: خريطة أماكن المدينة المنورة
نبني الصفحات على سيرفر nginx في Container، وكل الملفات من سيرفرنا: المكتبات، وخريطة الأساس بملف PMTiles لمستطيل المدينة المنورة، وملف GeoJSON فيه 5,172 مكاناً من بيانات Overture Maps التي حملناها في مقال «من يرسم خريطة الشارع؟». ونلتقط كل صورة في هذا المقال من Chrome بلا واجهة Headless، فما تراه هو ما رسمه المتصفح فعلاً.
تجهيز الملفات
نحمل المكتبات بإصدارات مثبتة إلى مجلد web/lib، والخطوط والأيقونات من basemaps-assets إلى web/assets:
mkdir -p web/lib web/assets web/tiles web/data web/js && cd web/lib
for f in maplibre-gl.mjs maplibre-gl-worker.mjs maplibre-gl.css; do
curl -sfLO https://unpkg.com/[email protected]/dist/$f
done
curl -sfL -o pmtiles.mjs https://unpkg.com/[email protected]/dist/esm/index.js
curl -sfL -o fflate.mjs https://unpkg.com/[email protected]/esm/browser.js
curl -sfL -o basemaps.mjs https://unpkg.com/@protomaps/[email protected]/dist/esm/index.js
cd ../assets
curl -sfL -o assets.zip https://github.com/protomaps/basemaps-assets/archive/refs/heads/main.zip
unzip -q assets.zip && mv basemaps-assets-main/fonts basemaps-assets-main/sprites . && rm -rf basemaps-assets-main assets.zip
cd ../..ولاحظ أن الإصدار 6 من MapLibre يأتي كوحدات ES Modules فقط، ولا يوجد ملف maplibre-gl.js القديم الذي تجده في أمثلة كثيرة على الإنترنت، فإذا نسخت مثالاً يحمل maplibre-gl.js بوسم script عادي من الإصدار 6 فلن يجده. ثم نقص مستطيل المدينة المنورة من بناء Protomaps اليومي بأداة pmtiles، كما شرحنا بالتفصيل في مقال الخرائط على سيرفرك:
docker run --rm --name lab-webmap-pmtiles -v "$PWD/web/tiles:/data" protomaps/go-pmtiles:v1.31.2 \
extract https://build.protomaps.com/20261116.pmtiles /data/madinah.pmtiles --bbox=39.50,24.38,39.75,24.56والمخرج سوف يكون كما يلي (حذفنا أسطر شريط التقدم):
2026/11/16 22:06:00 extract.go:441: Region tiles 656, result tile entries 648
2026/11/16 22:06:00 extract.go:450: fetching 648 tiles, 56 chunks, 32 requests
2026/11/16 22:06:25 extract.go:606: Completed in 52.766734968s with 4 download threads (12.280464205203806 tiles/s).
2026/11/16 22:06:25 extract.go:611: Extract required 43 total requests.
2026/11/16 22:06:25 extract.go:612: Extract transferred 3.0 MB (overfetch 0.05) for an archive size of 2.9 MBأي ملف واحد حجمه 2.9 ميغابايت فيه المدينة كلها من المستوى 0 إلى 15. وفي المحاولة الأولى فشل الأمر برسالة TLS handshake timeout بسبب الشبكة، فأعدناه كما هو ونجح، لذلك إذا رأيتها فأعد المحاولة قبل أن تبحث عن خطأ في الأمر.
وملف الأماكن نصنعه من ملف Overture المحلي بأداة DuckDB، ونترك فيه الحقول التي تحتاجها الخريطة فقط. ملف lab/slim.py:
# Keep only what the map needs from the Overture places: 6.4 MB -> a small GeoJSON
import duckdb
c = duckdb.connect(); c.execute("LOAD spatial; SET geometry_always_xy = true")
c.execute("""COPY (
SELECT id, names."primary" AS name, taxonomy."primary" AS category,
round(confidence, 2) AS confidence, sources[1].dataset AS source,
ST_ReducePrecision(geometry, 0.000001) AS geometry
FROM '/data/place.parquet' WHERE names."primary" IS NOT NULL
) TO '/web/data/places.geojson' WITH (FORMAT gdal, DRIVER 'GeoJSON', LAYER_CREATION_OPTIONS 'RFC7946=YES')""")
print(c.execute("SELECT count(*) FROM ST_Read('/web/data/places.geojson')").fetchall())وأول سجل في الملف الناتج:
{ "type": "Feature", "properties": { "id": "f7f8ee2b-1b1e-49de-b2a3-cb21a9e90a87", "name": "أمانة منطقة المدينة المنورة", "category": "government_office", "confidence": 0.87, "source": "meta" }, "geometry": { "type": "Point", "coordinates": [ 39.506543, 24.384293 ] } }لاحظ ترتيب الإحداثيات: خط الطول 39.5 أولاً ثم خط العرض 24.4، وهذا ترتيب GeoJSON بحسب المواصفة RFC 7946، وهو نفس ترتيب MapLibre، وسوف نرى ماذا يحدث إذا عكسته. والخيار RFC7946=YES يجعل GDAL يلتزم بالمواصفة، وST_ReducePrecision يقص الإحداثيات إلى ست خانات عشرية، أي قرابة 11 سنتيمتراً، وهي أكثر من كافية لنقطة على خريطة كما شرحنا في كيف تعمل الخرائط الرقمية.
السيرفر
ملف lab/nginx.conf:
server {
listen 80;
root /usr/share/nginx/html;
types {
text/html html;
text/css css;
text/javascript js mjs;
application/json json;
application/geo+json geojson;
image/png png;
application/x-protobuf pbf;
application/vnd.pmtiles pmtiles;
}
gzip on;
gzip_types application/geo+json application/json text/javascript text/css;
location / { try_files $uri $uri/ =404; }
}docker run -d --name lab-webmap -p 127.0.0.1:18735:80 \
-v "$PWD/web:/usr/share/nginx/html:ro" -v "$PWD/nginx.conf:/etc/nginx/conf.d/default.conf:ro" nginx:1.29-alpine
curl -s -r 0-126 -o /dev/null -w "%{http_code} %{size_download}\n" http://127.0.0.1:18735/tiles/madinah.pmtiles
curl -s -o /dev/null -w "plain %{size_download}\n" http://127.0.0.1:18735/data/places.geojson
curl -s -H "Accept-Encoding: gzip" -o /dev/null -w "gzip %{size_download}\n" http://127.0.0.1:18735/data/places.geojsonوالمخرج سوف يكون كما يلي:
206 127
plain 1396033
gzip 333698في الإعداد والمخرج أعلاه لاحظ التالي:
- طلب النطاق على ملف PMTiles رجع بالحالة 206 و127 بايتاً، أي أن nginx يدعم طلبات النطاق التي تحتاجها PMTiles دون أي إعداد.
- أنواع الملفات MIME Types محددة يدوياً، لأن المتصفح يرفض تشغيل وحدة JavaScript من ملف
.mjsإذا لم يصل بنوع JavaScript. - ملف الأماكن 1.4 ميغابايت، ومع الضغط gzip ينزل إلى 334 كيلوبايت، أي ربع حجمه تقريباً، لأن JSON نص متكرر يضغط جيداً. فلا تنس
gzip_typesلنوعapplication/geo+json، لأن nginx لا يضغط إلاtext/htmlافتراضياً.
الخطوة 1: أول خريطة
أبسط صفحة ممكنة، بتنسيق MapLibre التجريبي العام demotiles.maplibre.org، وهو خريطة دول بسيطة مخصصة للأمثلة والتجارب، وليست خريطة لموقع حقيقي. ملف web/01-hello.html:
<!doctype html>
<html lang="ar" dir="rtl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>أول خريطة</title>
<link rel="stylesheet" href="/lib/maplibre-gl.css">
<style>html, body, #map { margin: 0; height: 100%; }</style>
</head>
<body>
<div id="map"></div>
<script type="module">
import * as maplibregl from '/lib/maplibre-gl.mjs';
const map = new maplibregl.Map({
container: 'map', // the id of the div
style: 'https://demotiles.maplibre.org/style.json', // MapLibre's public demo style
center: [39.61, 24.47], // [longitude, latitude]
zoom: 4
});
map.addControl(new maplibregl.NavigationControl());
window.map = map;
</script>
</body>
</html>
في الكود أعلاه لاحظ التالي:
containerهو معرف الـ div الذي ترسم فيه الخريطة، ويجب أن يكون له ارتفاع، وهذا سبب السطرheight: 100%في CSS. والخريطة في div ارتفاعه صفر لا تظهر أبداً، ولا تعطي أي خطأ.centerبالترتيب [خط الطول، خط العرض]، وzoomمستوى التقريب من 0 للعالم كله.- أزرار التقريب ظهرت في الزاوية العليا اليمنى، وهي الزاوية الافتراضية لأي
addControlمهما كان اتجاه الصفحة. وفي صفحة عربية يبدأ القارئ من اليمين، وقد تغطي الأزرار عنواناً أو شعاراً تضعه هناك، فإذا أردت نقلها فمرر الموضع كوسيط ثان، مثلmap.addControl(new maplibregl.NavigationControl(), 'top-left')، وكذلك مقياس الرسم وزر ملء الشاشة. window.map = mapليس ضرورياً، ولكنه يجعل الخريطة متاحة في أدوات المطور Console، وهذا أسرع طريقة للتجربة: اكتبmap.getZoom()أوmap.getStyle().layers.lengthوسوف ترى الإجابة فوراً.
الخطوة 2: تنسيق من الصفر
حتى تفهم المصادر والطبقات، نكتب التنسيق بأنفسنا دون أي خريطة أساس: خلفية بلون واحد، ومصدر GeoJSON، وطبقة دوائر. ملف web/02-own-style.html:
<!doctype html>
<html lang="ar" dir="rtl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>تنسيق من الصفر</title>
<link rel="stylesheet" href="/lib/maplibre-gl.css">
<style>html, body, #map { margin: 0; height: 100%; }</style>
</head>
<body>
<div id="map"></div>
<script type="module">
import * as maplibregl from '/lib/maplibre-gl.mjs';
const map = new maplibregl.Map({
container: 'map',
center: [39.61, 24.47],
zoom: 11,
style: {
version: 8,
sources: {
places: { type: 'geojson', data: '/data/places.geojson',
attribution: 'Overture Maps Foundation (Meta, Microsoft, Foursquare…)' }
},
layers: [
{ id: 'bg', type: 'background', paint: { 'background-color': '#F4EFE6' } },
{ id: 'places', type: 'circle', source: 'places',
paint: { 'circle-radius': 3, 'circle-color': '#E95420', 'circle-opacity': 0.7 } }
]
}
});
window.map = map;
</script>
</body>
</html>
لاحظ أن شكل المدينة ظهر من النقاط وحدها، فالمركز الكثيف حول المسجد النبوي، والأطراف أقل كثافة. وطبقة الدوائر circle مرسومة كلها داخل WebGL، فلا يوجد عنصر HTML لكل نقطة، وسوف نعود إلى هذه النقطة في قسم الأداء. والحقل attribution في المصدر هو ما يظهر في زاوية الخريطة، وهذا مكان النسبة التي تطلبها رخصة البيانات.
الخطوة 3: خريطة أساس متجهة بالعربية
الآن نضيف خريطة الأساس من ملف PMTiles على سيرفرنا. ولأن كل الصفحات التالية تحتاجها، نضعها في وحدة واحدة web/js/basemap.mjs:
// The basemap of every page: Protomaps layers over our own PMTiles file, labels in Arabic
import * as maplibregl from '/lib/maplibre-gl.mjs';
import { Protocol } from '/lib/pmtiles.mjs';
import { layers, namedFlavor } from '/lib/basemaps.mjs';
maplibregl.addProtocol('pmtiles', new Protocol().tile);
export function basemapStyle(lang = 'ar') {
return {
version: 8,
glyphs: '/assets/fonts/{fontstack}/{range}.pbf',
sprite: `${location.origin}/assets/sprites/v4/light`,
sources: {
protomaps: {
type: 'vector',
url: 'pmtiles:///tiles/madinah.pmtiles',
attribution: '<a href="https://www.openstreetmap.org/copyright">© OpenStreetMap</a>'
}
},
layers: layers('protomaps', namedFlavor('light'), { lang })
};
}
export { maplibregl };وصفحة web/03-basemap.html:
<!doctype html>
<html lang="ar" dir="rtl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>خريطة أساس بالعربية</title>
<link rel="stylesheet" href="/lib/maplibre-gl.css">
<style>html, body, #map { margin: 0; height: 100%; } .maplibregl-popup-content { font: 15px/1.6 system-ui, sans-serif; }</style>
<script type="importmap">{ "imports": { "fflate": "/lib/fflate.mjs" } }</script>
</head>
<body>
<div id="map"></div>
<script type="module">
import { maplibregl, basemapStyle } from '/js/basemap.mjs';
const map = new maplibregl.Map({ container: 'map', style: basemapStyle('ar'), center: [39.61, 24.47], zoom: 12 });
map.addControl(new maplibregl.NavigationControl());
map.addControl(new maplibregl.ScaleControl());
window.map = map;
</script>
</body>
</html>
في الكود أعلاه لاحظ التالي:
addProtocol('pmtiles', ...)يعلم MapLibre قراءة الروابط التي تبدأ بـpmtiles://بطلبات النطاق، فلا تحتاج سيرفر مربعات.- الدالة
layers()من مكتبة basemaps تبني عشرات الطبقات جاهزة، والخيارlang: 'ar'يجعل كل طبقات النصوص تعرضname:arإذا وجد، وإلا الاسم الأصلي. - الـ Import Map في رأس الصفحة يحول اسم المكتبة
fflateالتي تستوردها pmtiles إلى الملف المحلي، وبدونها تفشل الوحدة في التحميل.
النصوص العربية وإضافة RTL Text Plugin
إذا بحثت عن «MapLibre عربي» فسوف تجد في أغلب النتائج أنك تحتاج إضافة النصوص من اليمين إلى اليسار mapbox-gl-rtl-text وسطراً يستدعي setRTLTextPlugin قبل إنشاء الخريطة، وإلا ظهرت الحروف منفصلة ومعكوسة. وهذا كان صحيحاً حتى وقت قريب، ولكن سجل التغييرات في الإصدار 6.9.0 يقول إن المكتبة أصبحت ترسم العربية والعبرية بشكل صحيح دون تحميل الإضافة، وإن setRTLTextPlugin وgetRTLTextPluginStatus أصبحتا مهملتين Deprecated. وقد قارنا الإصدار القديم 5.24.0 مع الإضافة وبدونها بالصور في مقال الخرائط على سيرفرك، فلن نعيد ذلك هنا.
والسؤال العملي هنا: ماذا يحدث إذا كان كودك القديم ما زال يستدعي الإضافة بعد الترقية إلى الإصدار 6؟ اختبرنا ذلك بالصفحة web/broken/e5-rtl-plugin.html، وهي صفحة الخطوة 3 نفسها مع السطر التالي قبل إنشاء الخريطة:
maplibregl.setRTLTextPlugin('https://unpkg.com/@mapbox/[email protected]/dist/mapbox-gl-rtl-text.js', true);والنتيجة: لم تظهر أي رسالة في Console، وعدد الطلبات في الصفحة 27، وهو العدد نفسه دون السطر، أي أن المتصفح لم يطلب ملف الإضافة أصلاً، والخريطة مطابقة للصورة أعلاه. والسبب أن الوسيط الثاني true يعني التحميل الكسول Lazy، أي لا تحمل الإضافة إلا عند الحاجة، والمكتبة الجديدة لم تعد تحتاجها. فالسطر لا يضر الآن، ولكن احذفه في أول ترقية، لأن الدالة المهملة قد تحذف في إصدار رئيسي قادم، وأي سطر في الكود لا يفعل شيئاً يربك من يقرأه بعدك.
ولكن الإضافة ليست كل قصة العربية على الخريطة، فقد قابلنا مشكلتين أخريين في التجربة. الأولى أن الأسماء تأتي من البيانات، فالمكان الذي ليس له name:ar في OpenStreetMap يظهر باسمه الإنجليزي مهما كانت لغة الصفحة، والحل في البيانات لا في الكود. والثانية في عناصر HTML فوق الخريطة، فالصفحة مكتوبة بالاتجاه dir="rtl"، فورث مقياس الرسم الاتجاه من الصفحة، وأصبح يعرض الوحدة قبل الرقم، مع أن النص داخل العنصر صحيح:

وفي أدوات المطور كان الاتجاه المحسوب للعنصر rtl والنص 1 km، وبعد إضافة السطر التالي أصبح الاتجاه ltr والعرض صحيحاً:
.maplibregl-ctrl-scale { direction: ltr; } /* "1 km", not "km 1", on an RTL page */والقاعدة العامة: اترك الصفحة rtl، وأعد إلى ltr كل عنصر محتواه أرقام ووحدات أو كود، وانتبه للنصوص المختلطة في النوافذ، كما سوف نرى في نافذة المكان بعد قليل.
ماذا يحمل المتصفح ليرسم العربية؟
الخطوط في التنسيق لا تحمل كملف واحد، وإنما كمجموعات من 256 حرفاً بحسب أرقامها في Unicode، والرابط {range} في glyphs يصبح مثلاً 0-255.pbf للحروف اللاتينية الأساسية. ولنعرف ما حمله المتصفح فعلاً لصفحاتنا، قرأنا سجل nginx بعد التجربة:
docker logs lab-webmap 2>&1 | grep -o "GET /assets/fonts/[^ ]*" | sort | uniq -c | sort -rn | head -8والمخرج سوف يكون كما يلي:
29 GET /assets/fonts/Noto%20Sans%20Regular/0-255.pbf
29 GET /assets/fonts/Noto%20Sans%20Medium/65024-65279.pbf
29 GET /assets/fonts/Noto%20Sans%20Medium/0-255.pbf
29 GET /assets/fonts/Noto%20Sans%20Italic/0-255.pbf
28 GET /assets/fonts/Noto%20Sans%20Regular/65024-65279.pbf
24 GET /assets/fonts/Noto%20Sans%20Regular/64256-64511.pbf
24 GET /assets/fonts/Noto%20Sans%20Regular/1536-1791.pbf
7 GET /assets/fonts/Noto%20Sans%20Regular/8192-8447.pbfفي المخرج أعلاه لاحظ التالي:
- المجموعة
1536-1791هي المجال U+0600 إلى U+06FF، أي الحروف العربية الأساسية كما تخزن في البيانات. - المجموعتان
64256-64511و65024-65279هما المجالان U+FB00 إلى U+FBFF وU+FE00 إلى U+FEFF، وفيهما أشكال العرض العربية Arabic Presentation Forms، أي شكل الحرف في أول الكلمة ووسطها وآخرها. وطلب هذه المجموعات دليل عملي على أن المكتبة تشكل الحروف وتصلها بنفسها، وهو بالضبط ما كانت تفعله إضافة RTL في الإصدارات القديمة. - كل ملف من هذه حجمه بين 69 و111 كيلوبايت، والمتصفح يحملها مرة واحدة ثم يخزنها، فلا تقلق من عدد الطلبات، ولكن ضعها على سيرفرك نفسه، لأن الخريطة لا ترسم أي اسم حتى تصل.
الخطوة 4: علامات ونوافذ وfitBounds
الآن نضع خمس علامات لأماكن معروفة، لكل منها نافذة Popup تظهر عند الضغط، ثم نجعل الخريطة تعرضها كلها. ملف web/04-markers.html:
<!doctype html>
<html lang="ar" dir="rtl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>علامات ونوافذ</title>
<link rel="stylesheet" href="/lib/maplibre-gl.css">
<style>html, body, #map { margin: 0; height: 100%; } .maplibregl-popup-content { font: 15px/1.6 system-ui, sans-serif; }</style>
<script type="importmap">{ "imports": { "fflate": "/lib/fflate.mjs" } }</script>
</head>
<body>
<div id="map"></div>
<script type="module">
import { maplibregl, basemapStyle } from '/js/basemap.mjs';
const sites = [
{ name: 'المسجد النبوي', lngLat: [39.6111, 24.4672] },
{ name: 'مسجد قباء', lngLat: [39.6173, 24.4393] },
{ name: 'مسجد القبلتين', lngLat: [39.5789, 24.4841] },
{ name: 'محطة قطار الحرمين', lngLat: [39.6997, 24.4732] },
{ name: 'مطار الأمير محمد بن عبدالعزيز', lngLat: [39.7058, 24.5503] }
];
const map = new maplibregl.Map({ container: 'map', style: basemapStyle('ar'), center: [39.61, 24.47], zoom: 11 });
const bounds = new maplibregl.LngLatBounds();
for (const s of sites) {
new maplibregl.Marker({ color: '#E95420' })
.setLngLat(s.lngLat)
.setPopup(new maplibregl.Popup({ offset: 25 }).setHTML(`<b>${s.name}</b><br>${s.lngLat[1]}, ${s.lngLat[0]}`))
.addTo(map);
bounds.extend(s.lngLat);
}
map.fitBounds(bounds, { padding: 60, maxZoom: 15 }); // show all markers, whatever the screen size
window.map = map;
</script>
</body>
</html>وعند الضغط على علامة المسجد النبوي، النص داخل النافذة كما قرأناه من الصفحة:
المسجد النبوي
24.4672, 39.6111
×
في الكود أعلاه لاحظ التالي:
- لم نحدد مستوى التقريب بأنفسنا، وإنما جمعنا الإحداثيات في
LngLatBoundsثم استدعيناfitBounds، فاختارت الخريطة 11.94 بالضبط على شاشة 1280 × 800، وعلى شاشة هاتف سوف تختار مستوى أصغر. وهذا ما تريده دائماً بدل رقم ثابت يناسب شاشتك وحدها. padding: 60يترك هامشاً حتى لا تقع العلامة على حافة الشاشة تحت الأزرار، وmaxZoom: 15يمنع التقريب الشديد إذا كانت كل العلامات في مبنى واحد.- النافذة تأخذ HTML عبر
setHTML، فإذا كان الاسم يأتي من مستخدم أو من مصدر خارجي فلا تضعه في HTML مباشرة، واستخدمsetTextأو نظف النص أولاً، لأن اسماً فيه وسمscriptسوف ينفذ في صفحتك.
الخطوة 5: 5,172 مكاناً مع التجميع Clustering
العلامات مناسبة لعدد قليل من الأماكن، أما خمسة آلاف مكان فتحتاج طريقة أخرى: مصدر GeoJSON مع التجميع، وطبقات تعرض المجموعات والأرقام والنقاط المنفردة. ملف web/05-cluster.html:
<!doctype html>
<html lang="ar" dir="rtl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>تجميع النقاط</title>
<link rel="stylesheet" href="/lib/maplibre-gl.css">
<style>html, body, #map { margin: 0; height: 100%; } .maplibregl-popup-content { font: 15px/1.6 system-ui, sans-serif; }</style>
<script type="importmap">{ "imports": { "fflate": "/lib/fflate.mjs" } }</script>
</head>
<body>
<div id="map"></div>
<script type="module">
import { maplibregl, basemapStyle } from '/js/basemap.mjs';
const map = new maplibregl.Map({ container: 'map', style: basemapStyle('ar'), center: [39.61, 24.47], zoom: 11,
maxBounds: [[39.45, 24.34], [39.80, 24.60]] }); // a little wider than our PMTiles box
map.on('load', () => {
map.addSource('places', {
type: 'geojson', data: '/data/places.geojson',
cluster: true, clusterRadius: 50, clusterMaxZoom: 15,
attribution: 'Overture Maps Foundation'
});
map.addLayer({ id: 'clusters', type: 'circle', source: 'places', filter: ['has', 'point_count'],
paint: {
'circle-color': ['step', ['get', 'point_count'], '#F6B26B', 50, '#E95420', 300, '#8E2C0B'],
'circle-radius': ['step', ['get', 'point_count'], 16, 50, 22, 300, 30],
'circle-stroke-width': 2, 'circle-stroke-color': '#fff'
} });
map.addLayer({ id: 'cluster-count', type: 'symbol', source: 'places', filter: ['has', 'point_count'],
layout: { 'text-field': ['get', 'point_count_abbreviated'], 'text-font': ['Noto Sans Medium'], 'text-size': 13 },
paint: { 'text-color': '#fff' } });
map.addLayer({ id: 'place', type: 'circle', source: 'places', filter: ['!', ['has', 'point_count']],
paint: {
'circle-radius': 6, 'circle-stroke-width': 1.5, 'circle-stroke-color': '#fff',
'circle-color': ['match', ['get', 'category'],
'hotel', '#3F78E0', 'muslim_place_of_worship', '#1F8A55',
['coffee_shop', 'cafe'], '#8D5A2B', 'pharmacy', '#C62828', '#5F6470']
} });
map.on('click', 'clusters', async (e) => {
const f = e.features[0];
const zoom = await map.getSource('places').getClusterExpansionZoom(f.properties.cluster_id);
map.easeTo({ center: f.geometry.coordinates, zoom });
});
map.on('click', 'place', (e) => {
const p = e.features[0].properties;
new maplibregl.Popup().setLngLat(e.lngLat)
.setHTML(`<b>${p.name}</b><br>${p.category ?? 'بدون تصنيف'} · ثقة ${p.confidence}`).addTo(map);
});
for (const id of ['clusters', 'place']) {
map.on('mouseenter', id, () => map.getCanvas().style.cursor = 'pointer');
map.on('mouseleave', id, () => map.getCanvas().style.cursor = '');
}
});
window.map = map;
</script>
</body>
</html>
في الكود أعلاه لاحظ التالي:
cluster: trueفي المصدر يجعل المكتبة تجمع النقاط القريبة في كل مستوى تقريب داخل Web Worker، فلا تتجمد الصفحة، وclusterRadius: 50نصف قطر التجميع بالبكسل، وclusterMaxZoom: 15آخر مستوى فيه تجميع.- المجموعة تأتي كمعلم له الخاصية
point_count، لذلك نفصل الطبقات بالشرط['has', 'point_count']وعكسه. - اللون والحجم بالتعبير
step: أقل من 50 برتقالي فاتح، ومن 50 إلى 300 برتقالي، وأكثر من 300 بني. ولون النقطة المنفردة بالتعبيرmatchعلى التصنيف: الفنادق بالأزرق، والمساجد بالأخضر، والمقاهي بالبني، والصيدليات بالأحمر. وهذه التعبيرات Expressions تقيم داخل المكتبة لكل معلم دون أي حلقة في JavaScript. getClusterExpansionZoomترجع Promise منذ الإصدار 4.0.0، والأمثلة القديمة التي تمرر لها دالة Callback لن تعمل.
وعند الضغط على أكبر مجموعة، وفيها 701 مكان، قرأنا من الصفحة أن التقريب كان 11.33، وبعد الضغط أصبح 12، وهو المستوى الذي تنقسم فيه هذه المجموعة بحسب getClusterExpansionZoom. ثم قرأنا عدد ما رسم على الشاشة حول المسجد النبوي في كل مستوى بالدالة queryRenderedFeatures:
zoom 11.5 {"clusters":71,"points":6}
zoom 13 {"clusters":169,"points":11}
zoom 14 {"clusters":128,"points":27}
zoom 15 {"clusters":101,"points":33}
zoom 16 {"clusters":0,"points":650}
لاحظ التغير الكبير بين المستويين 15 و16: من 101 مجموعة إلى 650 نقطة، لأن التجميع يتوقف عند clusterMaxZoom. وحول الحرم المزدحم بالفنادق يعني ذلك أن الشاشة تمتلئ فجأة بنقاط متداخلة، والحل أن ترفع clusterMaxZoom إلى 17 أو 18 في المناطق الكثيفة، أو تصغر clusterRadius حتى تتفكك المجموعات تدريجياً. والصورة التالية من المستوى 15.5، ومعها نافذة مطعم ضغطنا عليه:

والنص في النافذة كما قرأناه من الصفحة:
Karam Golden Madinah
arabian_restaurant · ثقة 0.79ولكن في الصورة ظهر السطر الثاني «0.79 ثقة · arabian_restaurant»، أي أن ترتيب الأجزاء تغير، لأن خوارزمية الاتجاه في المتصفح رتبت النص المختلط العربي والإنجليزي والأرقام بحسب اتجاه الصفحة. والحل أن تضع كل جزء إنجليزي أو رقمي في عنصر معزول، مثل <bdi>arabian_restaurant</bdi>، أو أن تضع كل معلومة في سطر خاص بها، وهذا ما ننصح به في النوافذ.
التعبيرات Expressions: البيانات تقرر الشكل
في الخطوة 5 استخدمنا step وmatch دون أن نتوقف عندهما، وهما جزء من لغة كاملة اسمها التعبيرات Expressions في مواصفة التنسيق، وهي أهم ما يميز MapLibre عن المكتبات التي ترسم كل نقطة بكود JavaScript. والفكرة أنك تكتب القاعدة مرة واحدة كمصفوفة JSON، والمكتبة تطبقها على كل معلم في الـ Worker أو في كرت الشاشة، فلا توجد حلقة على خمسة آلاف عنصر في الصفحة. وأهم التعبيرات التي ستحتاجها:
['get', 'category']يقرأ خاصية من المعلم، وهو أساس كل ما بعده.matchيختار قيمة بحسب قيمة نصية، مثل لون لكل تصنيف، مع قيمة افتراضية في آخره لكل ما لم تذكره، وهذا ما جعل الأماكن بلا تصنيف رمادية في الصورة.stepيقسم رقماً إلى درجات ثابتة، مثل ثلاثة ألوان بحسب عدد الأماكن في المجموعة.interpolateيحسب قيمة متدرجة بين نقطتين، وأشهر استخدام له أن يكبر نصف قطر الدائرة مع التقريب، مثل['interpolate', ['linear'], ['zoom'], 10, 2, 16, 8]، أي نقطتين في المستوى 10 وثماني نقاط في المستوى 16، فلا تبدو الخريطة مزدحمة من بعيد ولا فارغة من قريب.caseوعمليات المقارنة مثل['>=', ['get', 'confidence'], 0.7]، فتستطيع مثلاً أن تجعل الأماكن ضعيفة الثقة شفافة، وهي فكرة مفيدة مع بيانات Overture التي رأينا فيها سجلات مكررة بدرجات ثقة منخفضة.
وقد يتساءل البعض: لماذا لا أحسب اللون في JavaScript وأضعه في خصائص كل معلم قبل إضافته؟ والإجابة أن هذا يعمل، ولكنه يجعل تغيير الألوان يحتاج إعادة معالجة البيانات وإرسالها، بينما التعبير يتغير بسطر واحد عبر map.setPaintProperty، ويعمل كذلك على المربعات المتجهة التي لا تستطيع أن تعدل خصائصها في المتصفح أصلاً.
الخطوة 6: الأداء، علامات أم طبقة؟
قد يتساءل البعض: لماذا لا أضع كل مكان كعلامة Marker كما في الخطوة 4، فهي أسهل وتقبل أي HTML؟ والإجابة بالأرقام. الصفحة web/06-perf.html تحمل النقاط نفسها، ثم تضيفها إما كعلامات أو كطبقة دوائر بحسب الرابط، وتقيس زمن الإضافة، وعدد عناصر الصفحة، وكم إطاراً رسم المتصفح خلال ثلاث ثوان من التحريك:
<!doctype html>
<html lang="ar" dir="rtl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Markers أم طبقة؟</title>
<link rel="stylesheet" href="/lib/maplibre-gl.css">
<style>html, body, #map { margin: 0; height: 100%; }</style>
<script type="importmap">{ "imports": { "fflate": "/lib/fflate.mjs" } }</script>
</head>
<body>
<div id="map"></div>
<script type="module">
import { maplibregl, basemapStyle } from '/js/basemap.mjs';
const q = new URLSearchParams(location.search);
const mode = q.get('mode') || 'layer'; // dom | layer
const n = +(q.get('n') || 100000); // how many points to draw
const map = new maplibregl.Map({ container: 'map', style: basemapStyle('ar'), center: [39.61, 24.47], zoom: 12 });
map.on('load', async () => {
const data = await (await fetch('/data/places.geojson')).json();
data.features = data.features.slice(0, n);
const t0 = performance.now();
if (mode === 'dom') {
for (const f of data.features)
new maplibregl.Marker({ scale: 0.5 }).setLngLat(f.geometry.coordinates).addTo(map);
} else {
map.addSource('places', { type: 'geojson', data });
map.addLayer({ id: 'places', type: 'circle', source: 'places',
paint: { 'circle-radius': 5, 'circle-color': '#E95420' } });
}
window.addMs = Math.round(performance.now() - t0); // the JavaScript loop alone
// wait for the first frame that draws the points, then give the map 10 s to settle
const drawn = new Promise(r => map.once('render', r));
map.triggerRepaint(); // DOM markers alone do not make the map draw a new frame
await drawn;
const added = performance.now() - t0;
await new Promise(r => setTimeout(r, 10000));
{
// pan for 3 seconds and count the frames the browser managed to draw
let frames = 0, end = performance.now() + 3000;
const tick = () => { frames++; if (performance.now() < end) { map.panBy([4, 0], { duration: 0 }); requestAnimationFrame(tick); } };
requestAnimationFrame(tick);
await new Promise(r => setTimeout(r, 3200));
window.result = { mode, points: data.features.length, addMs: window.addMs, addAndRenderMs: Math.round(added),
domNodes: document.getElementsByTagName('*').length, fps: Math.round(frames / 3) };
console.log(JSON.stringify(window.result));
}
});
window.map = map;
</script>
</body>
</html>وشغلنا الطريقتين مرتين على 5,172 نقطة، ومرة بعلامات على 500 نقطة فقط بالرابط ?mode=dom&n=500:
{"mode":"dom","points":500,"addMs":93,"addAndRenderMs":106,"domNodes":10023,"fps":7}
{"mode":"dom","points":5172,"addMs":943,"addAndRenderMs":984,"domNodes":103463,"fps":2}
{"mode":"layer","points":5172,"addMs":5,"addAndRenderMs":57,"domNodes":23,"fps":11}
{"mode":"dom","points":5172,"addMs":790,"addAndRenderMs":850,"domNodes":103463,"fps":2}
{"mode":"layer","points":5172,"addMs":7,"addAndRenderMs":56,"domNodes":23,"fps":12}
في المخرج أعلاه لاحظ التالي:
- كل علامة تضيف قرابة 20 عنصراً إلى الصفحة، لأن العلامة الافتراضية صورة SVG فيها عدة مسارات داخل div، فخمسة آلاف علامة أصبحت 103,463 عنصراً، مقابل 23 عنصراً فقط مع الطبقة، لأن الطبقة كلها مرسومة داخل Canvas واحد.
- إضافة العلامات أخذت 790 إلى 943 ملي ثانية تتجمد فيها الصفحة، مقابل 5 إلى 7 ملي ثانية للطبقة.
- أثناء التحريك رسم المتصفح إطارين في الثانية مع العلامات، لأنه يعيد حساب موضع كل عنصر في كل إطار، مقابل 11 إلى 12 مع الطبقة. وحتى 500 علامة فقط نزلت بالإطارات إلى 7.
- هذه الأرقام من Chrome بلا واجهة يرسم WebGL برمجياً، فالأرقام المطلقة أبطأ من جهاز حقيقي بكرت شاشة، ولكن النسبة بين الطريقتين هي ما يهم، وهي تتكرر على أي جهاز.
وفي أول نسخة من صفحة القياس انتظرنا الحدث idle بعد إضافة العلامات، فلم يصل أبداً حتى بعد 400 ثانية، وظننا أن الصفحة تجمدت. والسبب الحقيقي أن العلامات عناصر HTML لا تطلب من الخريطة أن ترسم إطاراً جديداً، فالخريطة كانت في حالة idle قبل أن نسجل الحدث، ولن تخرج منها لتعود إليها. لذلك أضفنا map.triggerRepaint() قبل انتظار الحدث render. وهذا درس عام: الأحداث في MapLibre مرتبطة بالرسم داخل Canvas، وما تفعله في HTML فوقها لا يحركها.
والقاعدة العملية: العلامات لعدد قليل من الأماكن تحتاج HTML غنياً، مثل موقع فرعك أو سيارة مندوب تتحرك، وحتى بضع عشرات، أما القوائم الطويلة فطبقة circle أو symbol من مصدر GeoJSON، مع التجميع إذا تجاوزت الآلاف، والنوافذ تفتح عند الضغط بالحدث click على الطبقة كما في الخطوة 5.
الأحداث Events: متى تضيف ومتى تقرأ؟
نصف الأعطال التي قابلناها كانت أخطاء في التوقيت، لذلك يستحق ترتيب الأحداث في MapLibre قسماً خاصاً:
load: يحدث مرة واحدة عندما يحمل التنسيق وتصبح الخريطة جاهزة لإضافة المصادر والطبقات، وهو مكان كلaddSourceوaddLayer.render: يحدث بعد كل إطار ترسمه الخريطة، وقد يحدث عشرات المرات في الثانية أثناء الحركة، فلا تضع فيه عملاً ثقيلاً.idle: يحدث عندما تنتهي الخريطة من الرسم وتحميل كل المربعات الظاهرة ولا يوجد انتقال جار، وهو المناسب لالتقاط صورة أو قياس، بشرط أن تسجله قبل أن تبدأ الخريطة الرسم، وإلا انتظرته كما انتظرناه دون فائدة.moveend: يحدث بعد أن يتوقف المستخدم عن التحريك أو التقريب، وهو المكان المناسب لطلب البيانات من واجهتك البرمجية بحسب ما يظهر على الشاشة، بقراءةmap.getBounds()وإرسال المستطيل إلى السيرفر، بدل أن تحمل كل الأماكن مقدماً.error: كل خطأ في تحميل مربع أو ملف أو تنسيق يأتي هنا، وإذا لم تسجل له دالة فالمكتبة تطبعه في Console فقط، لذلك سجله في الإنتاج وأرسله إلى نظام المراقبة عندك.
وللقراءة من الخريطة دالتان يخلط بينهما الكثيرون. الأولى queryRenderedFeatures، وترجع ما رسم فعلاً على الشاشة في نقطة أو مستطيل، وهي التي استخدمناها لعد المجموعات في كل مستوى، ولذلك نتيجتها تتغير مع التقريب والفلاتر. والثانية querySourceFeatures، وترجع المعالم في المربعات المحملة من المصدر سواءً ظهرت أم لا، وقد ترجع المعلم الواحد أكثر من مرة إذا كان في مربعين. فإذا أردت أن تعرف ما يراه المستخدم فاستخدم الأولى، وإذا أردت أن تبحث في البيانات المحملة فالثانية، أما إذا أردت كل البيانات فارجع إلى المصدر نفسه، أي ملفك أو واجهتك البرمجية، لا إلى الخريطة.
ستة أعطال قابلناها، ورسالة كل منها
جمعنا الأعطال التي ظهرت أثناء التجربة، وكل واحد منها أعدنا إنتاجه في صفحة داخل المجلد web/broken، والصورة التالية تلخصها قبل التفصيل:

الصفحة بيضاء عندما تفتح الملف مباشرة
فتحنا 01-hello.html بالضغط عليه من مستكشف الملفات بدل السيرفر، فبقيت الصفحة بيضاء، وفي Console الرسالة التالية:
Access to script at 'file:///C:/lib/maplibre-gl.mjs' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: chrome, chrome-experimental-site-token-provider, chrome-extension, chrome-untrusted, data, http, https, isolated-app.وفي الرسالة خطآن معاً. الأول أن المتصفح لا يحمل وحدات JavaScript من المسار file:// لأسباب أمنية، فلا تعمل الوحدات ولا طلبات fetch للتنسيق والبيانات. والثاني أن المسار /lib/maplibre-gl.mjs الذي يبدأ بشرطة أصبح file:///C:/lib/، أي جذر القرص لا مجلد المشروع. والحل واحد: قدم الصفحات دائماً من سيرفر ويب، ولو كان سطراً واحداً مثل nginx في Container كما فعلنا، أو python3 -m http.server للتجربة السريعة على الصفحات التي لا تستخدم PMTiles، لأن هذا السيرفر لا يدعم طلبات النطاق كما رأينا في مقال الخرائط على سيرفرك.
Style is not done loading
الصفحة web/broken/e2-too-early.html هي صفحة الخطوة 3 مع سطر يضيف مصدراً مباشرة بعد إنشاء الخريطة:
map.addSource('places', { type: 'geojson', data: '/data/places.geojson' }); // too earlyوالنتيجة خطأ في Console يوقف باقي الكود:
Uncaught Error: Style is not done loading.والسبب أن إنشاء الخريطة لا ينتظر تحميل ملف التنسيق، فالتنسيق يحمل من الشبكة بعد السطر، والإضافة قبل اكتماله ممنوعة. والحل أن تضع كل addSource وaddLayer داخل map.on('load', ...) كما في الخطوة 5. ولاحظ أن الخطأ أوقف السطر التالي أيضاً، window.map = map، فأصبح window.map في Console هو عنصر الـ div نفسه، لأن المتصفح يعرف تلقائياً كل عنصر له id كمتغير عام، وهذا يربكك أكثر عندما تحاول أن تفحص الخريطة.
العلامة في بحر إيجة
في الصفحة web/broken/e4-swapped.html عكسنا إحداثيات المسجد النبوي فقط، فأصبحت [24.4672, 39.6111] بدل [39.6111, 24.4672]، ووضعناها على الخريطة التجريبية حتى نرى العالم:

لم يظهر أي خطأ، لأن 24.47 خط طول صحيح و39.61 خط عرض صحيح، فالمكتبة لا تستطيع أن تعرف أنك أخطأت، ولا ترمي خطأ إلا إذا تجاوز خط العرض 90. والأسوأ أن fitBounds صغرت الخريطة لتعرض العلامة الخاطئة مع الصحيحة، فأصبح الخطأ في نقطة واحدة يفسد الخريطة كلها. والقاعدة: MapLibre وGeoJSON يأخذان [خط الطول، خط العرض] دائماً، أما خرائط Google ونماذج كثيرة في قواعد البيانات فتكتب العرض أولاً، لذلك حول الترتيب في مكان واحد عند قراءة البيانات، وتحقق أن كل نقاطك داخل مستطيل منطقتك قبل عرضها.
العلامات والأزرار تحت الخريطة
الصفحة web/broken/e6-no-css.html هي صفحة العلامات دون سطر maplibre-gl.css. الخريطة رسمت بشكل طبيعي، ولكن العلامات والنسبة اختفت، ولا يوجد أي خطأ في Console:

وعندما قرأنا مواضع العناصر من الصفحة وجدنا أن العلامات الخمس أصبحت بعرض 1280 بكسلاً وفي المواضع من 994 إلى 1551 عمودياً، أي تحت الخريطة خارج الشاشة، وارتفاع الصفحة كلها أصبح 1592 بكسلاً. والسبب أن ملف CSS هو الذي يجعل العلامات والأزرار عناصر بموضع مطلق فوق الخريطة، ودونه تصبح عناصر عادية تتراص تحت الـ div. فإذا رأيت شريط تمرير لم تضعه، أو علامات أسفل الصفحة، فابدأ بملف CSS.
شريط رمادي على أطراف الخريطة
في أول نسخة من صفحة التجميع كان المركز 24.47 والتقريب 11، فظهر في أسفل الشاشة شريط رمادي بلا طرق ولا أسماء. والسبب أن ملف PMTiles يغطي المستطيل الذي قصصناه فقط، وجنوبه ينتهي عند خط العرض 24.38، والشاشة في هذا التقريب تصل إلى ما بعده. والحل في الصفحة نفسها، الخيار maxBounds بحدود أوسع قليلاً من الملف، فلا يستطيع المستخدم أن يسحب الخريطة إلى منطقة بلا بيانات، ولاحظ أن الخريطة رفعت التقريب تلقائياً من 11 إلى 11.33 حتى تبقى الشاشة كلها داخل الحدود.
نصوص دون ملف خطوط
كانت القاعدة في المكتبات القديمة أن طبقة symbol فيها text-field تحتاج glyphs في التنسيق، وإلا ظهر خطأ وتوقفت الطبقة. واختبرنا ذلك بالصفحة web/broken/e3-no-glyphs.html، وهي تنسيق الخطوة 2 مع طبقة أسماء دون أي glyphs، فكانت النتيجة مختلفة عما توقعنا:

رسمت المكتبة الأسماء بالعربية والإنجليزية دون أي خطأ، وسجل التغييرات في الإصدار 6.0.0 يشرح السبب: إذا لم يوجد glyphs في التنسيق فإن text-font يعامل كقائمة أسماء خطوط، وترسم كل النصوص بخطوط الجهاز المحلية. وهذا أفضل من الفشل، ولكنه يعني أن الخريطة سوف تبدو مختلفة على Windows وAndroid وiPhone، لأن كل جهاز يختار خطاً مختلفاً. فإذا كان شكل الخريطة يهمك، أو كانت هويتك تعتمد على خط معين، فضع glyphs بخطوطك على سيرفرك كما فعلنا في الخطوة 3.
من التجربة إلى موقعك
- النسبة Attribution: اترك عنصر النسبة ظاهراً، وضع في كل مصدر نصه: «© OpenStreetMap» لخريطة الأساس، واسم Overture ومصادرها للأماكن كما في صفحة النسبة في توثيقها. وMapLibre تجمع نصوص كل المصادر في زاوية واحدة تلقائياً.
- التخزين المؤقت Cache: مكتبات JavaScript والخطوط والأيقونات وملف PMTiles لا تتغير إلا عندما تستبدلها، فضع لها مدة تخزين طويلة، وضع رقم الإصدار أو التاريخ في اسم الملف عند التحديث.
- حجم البيانات: ملف GeoJSON بخمسة آلاف نقطة 1.4 ميغابايت و334 كيلوبايت بعد الضغط، وهذا مقبول. أما إذا وصلت إلى مئات الآلاف من النقاط أو آلاف المضلعات فحولها إلى مربعات متجهة بأداة مثل tippecanoe أو من PostGIS، كما في نشر الخرائط مع GeoServer، حتى لا يحمل الزائر كل شيء مقدماً.
- بيانات تتغير: إذا كانت الأماكن من قاعدة بياناتك وتتغير كل دقيقة، فاستخدم
map.getSource('places').setData(...)بنتيجة واجهتك البرمجية، دون إعادة إنشاء الخريطة. - الأمان: لا تضع نصوص المستخدمين في
setHTMLدون تنظيف، واحفظ ملفات المكتبات على سيرفرك بإصدار مثبت بدل الربط بـ CDN خارجي يتغير محتواه. - الوصول Accessibility: الخريطة وحدها لا يقرؤها قارئ الشاشة، فضع بجانبها قائمة نصية بالأماكن نفسها، وهذا يفيد أيضاً محركات البحث والمستخدم على اتصال بطيء.
تنظيف التجربة
docker rm -f lab-webmap
rm -rf web/lib web/assets web/tiles web/dataأخطاء شائعة
- فتح الصفحة بالمسار file://: الوحدات وfetch لا تعمل، فقدمها من سيرفر ويب دائماً.
- إضافة المصادر قبل load: تحصل على Style is not done loading ويتوقف باقي الكود.
- عكس الإحداثيات: لا يوجد خطأ، والنقطة تذهب إلى مكان آخر من العالم، فتحقق من المستطيل قبل العرض.
- نسيان ملف CSS: العلامات والأزرار تتراص تحت الخريطة دون أي رسالة.
- آلاف العلامات Markers: مئة ألف عنصر في الصفحة وإطاران في الثانية، فاستخدم طبقة.
- الاعتماد على إضافة RTL في الإصدار 6: لم تعد مطلوبة، واحذف الاستدعاء المهمل عند الترقية.
- ترك عناصر الأرقام ترث rtl: مقياس الرسم وأي عنصر أرقام يحتاج
direction: ltr. - نسيان maxBounds مع ملف لمنطقة محددة: المستخدم يسحب الخريطة إلى منطقة رمادية.
- نسخ أمثلة الإصدارات القديمة: ملف
maplibre-gl.jsلم يعد موجوداً في الإصدار 6، وgetClusterExpansionZoomترجع Promise.
قائمة تحقق قبل النشر
- كل المكتبات والخطوط والبيانات من سيرفرك بإصدارات مثبتة، وأنواع الملفات صحيحة في السيرفر.
- الضغط gzip مفعل لـ GeoJSON وJavaScript، وطلبات النطاق تعمل لملف PMTiles حتى خلف الـ Reverse Proxy.
- كل الإضافات داخل
map.on('load')، والأخطاء تلتقط بـmap.on('error')وتسجل. - الإحداثيات بالترتيب [lng, lat]، وكلها داخل مستطيل منطقتك.
- أكثر من بضع عشرات من النقاط في طبقة لا في علامات، والتجميع مفعل للآلاف، و
clusterMaxZoomمناسب لكثافة منطقتك. - النسبة ظاهرة لكل مصدر، ومقياس الرسم وعناصر الأرقام بالاتجاه الصحيح، والنوافذ لا تخلط العربية والإنجليزية في سطر واحد.
maxBoundsمضبوط إذا كانت خريطة الأساس لمنطقة محددة، وfitBoundsبدل التقريب الثابت.
تدريب عملي
- أضف إلى صفحة التجميع قائمة اختيار للتصنيف، واستخدم
map.setFilter('place', ['==', ['get', 'category'], 'pharmacy'])لعرض الصيدليات وحدها، ولاحظ أن المجموعات لا تتأثر بالفلتر، ثم فكر لماذا، وكيف تحل ذلك بخاصيةfilterفي المصدر نفسه. - غير
clusterMaxZoomإلى 18، وأعد قراءة الأعداد في كل مستوى بالدالةqueryRenderedFeatures، وقارنها بالجدول أعلاه. - اكتب واجهة صغيرة ترجع أماكنك من PostgreSQL بصيغة GeoJSON، واستخدم
setDataلتحديث الخريطة كل دقيقة دون إعادة تحميل الصفحة.
الخلاصة
وصلنا لنهاية الموضوع، وأهم ما فيه:
- كل ما ترسمه MapLibre يأتي من ملف تنسيق فيه مصادر وطبقات وخطوط وأيقونات، والعلامات والنوافذ وحدها عناصر HTML فوقه.
- الإصدار 6 يرسم العربية دون إضافة RTL، والاستدعاء القديم لا يحمل شيئاً ولكن احذفه، ومشاكل العربية الباقية في البيانات وفي اتجاه عناصر HTML.
- fitBounds تعرض نقاطك على أي شاشة، وmaxBounds تمنع الخروج من منطقة بياناتك.
- 5,172 علامة أنتجت 103,463 عنصراً وإطارين في الثانية، والنقاط نفسها كطبقة واحدة 23 عنصراً و12 إطاراً، فالقوائم الطويلة طبقات مع التجميع.
- أغلب الأعطال لا تعطي رسالة: الإحداثيات المعكوسة، ونسيان CSS، والمنطقة الرمادية، فاعرف شكلها بالعين.
والخطوة التالية في هذه المرحلة أن تكون خريطة الأساس نفسها على سيرفرك بالتفصيل، ثم البحث عن العناوين وحساب المسارات على البيانات نفسها.
دليلخرائطك على سيرفرك مع OpenStreetMap وMapLibreكيف تعرض خريطة تفاعلية لمدينتك من سيرفرك ببيانات OpenStreetMap، بالعربية والإنجليزية ودون مفتاح API أو مزود خارجي.
دليلالبحث عن العناوين Geocoding مع Nominatimكيف تحول اسم المكان إلى إحداثيات والإحداثيات إلى عنوان على سيرفرك مع Nominatim، وما الذي يجيده بالعربية وما الذي يفوته.
دليلحساب أقصر طريق وزمن الوصول مع OSRM وValhallaكيف يحسب محرك المسارات أقصر طريق وزمن الوصول على شوارع مدينتك، وكيف تشغله على سيرفرك وتقيس سرعته بنفسك.
دليلكيف تبني تطبيق خرائط وملاحة مثل هدهد وGoogle Maps؟ما الذي يقف خلف كل ميزة في تطبيقات الخرائط، وكيف تبني نسخة أولى منها بأدوات مفتوحة المصدر وبيانات مرخصة بشكل صحيح.
دليلمن يرسم خريطة الشارع؟ Google وOSM وOvertureمن أين تأتي بيانات الخريطة التي تراها على هاتفك، ومن يملكها ويصلح أخطاءها، وما الذي تلزمك به رخصتها قبل أن تضعها في تطبيقك.
دليلنشر الخرائط مع GeoServer والمربعات المتجهة Vector Tilesكيف تنشر طبقات PostGIS كخرائط بمعايير WMS وWFS مع GeoServer، وكمربعات متجهة صغيرة مع Martin، وكم يزن كل مربع وكيف تخزنه مؤقتاً.
دليلكيف تعمل الخرائط الرقمية؟ المربعات Tiles والطبقات Layersالمدخل إلى مسار الخرائط، يشرح ما الخريطة الرقمية وكيف يحمل تطبيقك المربعات ويرسم الأسماء العربية، مع تجربة على مربعات حقيقية وخريطة لكل ما تقرأه بعده.سجل التحديثات
- 17 نوفمبر 2026: كتابة المقال، وتنفيذ التجربة بمكتبة MapLibre GL JS 6.18.0 وpmtiles 4.5.0 و@protomaps/basemaps 5.7.2 وfflate 0.8.3، وخريطة أساس من بناء Protomaps بتاريخ 20261116 مقصوصة بأداة go-pmtiles 1.31.2، وأماكن Overture من إصدار 2026-10-21.0، على nginx 1.29.8 في Docker Engine 29.8.0، والصور من Google Chrome 157 بلا واجهة على Windows 11.