الأدلّة

عرض خريطة

ضمّن خريطة أساس تفاعلية من Navvo Maps في تطبيقك.

عرض خريطة

اعرض خريطة أساس تفاعلية من Navvo Maps في المتصفح. تأتي Navvo Maps مع محرّك عرض GL خفيف بالإضافة إلى نمط متجهي كامل — وجّهها إلى رابط النمط الخاص بك وتكون قد انتهيت.

النطاق المطلوب: tiles

1. أضف Navvo Maps

حمّل حزمة تطوير Navvo Maps (محرّك العرض + الأنماط)، المُقدّمة من Navvo:

<link href="https://docs.navvo.io/navvo-maps/navvo-maps.css" rel="stylesheet" />
<script src="https://docs.navvo.io/navvo-maps/navvo-maps.js"></script>
<div id="map" style="width: 100%; height: 480px;"></div>

2. وجّهها إلى نمط Navvo

بما أنّ المتصفح لا يستطيع إضافة ترويسة x-api-key إلى طلبات الخريطة، مرّر مفتاحك على رابط النمط بصيغة api_key:

const map = new NavvoMaps.Map({
  container: "map",
  style: "https://navvo.io/api/v1/tiles/style?style=standard&api_key=nvvo_YOUR_KEY",
  center: [35.9106, 31.9539], // [lng, lat] — Amman
  zoom: 12,
});

map.addControl(new NavvoMaps.NavigationControl());

هذه خريطة أساس متجهية كاملة — تحريك وتكبير وتسميات وكل شيء.

التسميات العربية وغيرها من اليمين إلى اليسار. تُحمّل الحزمة إضافة صغيرة لتشكيل النص عند أول نص من اليمين إلى اليسار تصادفه، فتتّصل حروف أسماء الأماكن والشوارع العربية وتُقرأ في اتجاهها الصحيح. وتُجلب من https://docs.navvo.io/sdks/assets/rtl-text.min.js ولا تحتاج أي إعداد.وإن كانت صفحتك تحجب ذلك الطلب — وسياسة أمان محتوى صارمة في connect-src/script-src هي السبب المعتاد — فستظهر العربية غير مشكَّلة أو تختفي بينما تبدو بقية الخريطة سليمة. اسمح بالعنوان، أو استضِف الإضافة بنفسك ومرّر rtlTextPluginUrl عند إنشاء الخريطة:

const map = new NavvoMaps.Map({
  container: "map",
  style: "https://navvo.io/api/v1/tiles/style?style=standard&api_key=nvvo_YOUR_KEY",
  rtlTextPluginUrl: "/your/own/copy/rtl-text.min.js",
});

وتسجّل الحزمة [NavvoMaps] RTL text plugin failed to load في الطرفية عند فشل الجلب — وهو أول ما يستحق النظر إن بدت العربية خاطئة.

3. اختر نمطًا

استبدل قيمة style= للحصول على مظهر مختلف:

`style=`	المظهر
`standard`	خريطة أساس متجهية فاتحة (الافتراضي).
`dark`	خريطة أساس متجهية داكنة.
`positron`	خريطة أساس فاتحة بسيطة.
`satellite`	صور جوية تُرسم فوقها طرق Navvo وتسمياتها (هجين — يلزم إسناد صور الطرف الثالث، راجع ملاحظة الإسناد أدناه).
`terrain`	تظليل تضاريسي أسفل خريطة Navvo المتجهية الكاملة (هجين — مُستضاف بالكامل لدى Navvo).
`3d`	امتدادات مبانٍ ثلاثية الأبعاد (أضف `&terrain=1` لتضاريس الارتفاع).

map.setStyle("https://navvo.io/api/v1/tiles/style?style=dark&api_key=nvvo_YOUR_KEY");

4. أضف علامة

new NavvoMaps.Marker({ color: "#386BFF" })
  .setLngLat([35.9106, 31.9539])
  .setPopup(new NavvoMaps.Popup().setText("Amman"))
  .addTo(map);

تستخدم Navvo Maps ترتيب [lng, lat]. تعود إحداثيات أماكن Navvo بصيغة WKT POINT(lng lat) — وهي بالفعل بترتيب خط الطول أولًا، لذا يمكنك تحليلها وتمريرها مباشرةً.

5. أضف طبقة تراكب (اختياري)

اعرض حركة المرور الحيّة أو الحوادث أو الطقس فوق خريطة الأساس باستخدام نقاط نهاية التراكب. على سبيل المثال، أضف حركة المرور الحيّة كمصدر GeoJSON:

map.on("load", async () => {
  const res = await fetch(
    "https://navvo.io/api/v1/traffic/lines/tiles/14/9826/6656", // بلاطة في عمّان
    { headers: { "x-api-key": "nvvo_YOUR_KEY" } }
  );
  const geojson = await res.json();
  // حركة المرور الحيّة مُجمَّعة من مستخدمي Navvo، لذا تكون `geojson.hasData`
  // بقيمة `false` و`features` فارغة `[]` حيثما لم يُبلّغ أحد عن حركة مرور
  // حديثاً — وهذه استجابة طبيعية وليست خطأً. أضِف الطبقة على أي حال؛
  // ستمتلئ بخطوط ملوّنة مع توفّر التغطية.
  map.addSource("traffic", { type: "geojson", data: geojson });
  map.addLayer({
    id: "traffic",
    type: "line",
    source: "traffic",
    paint: { "line-color": ["get", "color"], "line-width": 3 },
  });
});

استجابة حركة المرور الفارغة أمر متوقّع — وهي ليست خريطة الأساس. إن /traffic/lines/tiles/{z}/{x}/{y} هي طبقة تراكب اختيارية لبيانات الازدحام الحيّة المُجمَّعة من مستخدمي Navvo، وتُعاد بصيغة GeoJSON. تستجيب بـ { "hasData": false, "features": [] } في أي مكان لم يُبلّغ فيه مستخدمو Navvo عن حركة مرور حديثة (لذا قد تكون فارغة غالباً اليوم). خريطتك تظل تُعرض — أما بلاطات خريطة الأساس الفعلية فتأتي من نقطة النهاية /tiles/style في الخطوة 1. راجع دليل طبقة حركة المرور الحيّة لتحميل كامل نطاق العرض باستخدام tile-cover والتعامل مع hasData.

راجع دليل طبقة حركة المرور الحيّة لتحميل منطقة العرض كاملةً بكفاءة باستخدام تغطية البلاطات.

الإسناد. تحمل خريطة أساس Navvo إسناد © Navvo. اعرض إسناد Navvo، وأبقِ عنصر التحكم المُصغَّر بالإسناد على الخريطة معروضًا — تعرضه الـ SDK افتراضيًا.وعند عرض النمط satellite يحمل مصدر الصور فيه إسنادًا إضافيًا هو Imagery © Esri, Maxar, Earthstar Geographics، ويجب عرضه هو الآخر إلى جانب © Navvo: فالصور الجوية مرخَّصة من طرف ثالث ويجلبها المتصفح مباشرةً من شبكة توصيل المحتوى الخاصة بمزوّدها.يلتقط عنصر التحكم بالإسناد في محرّك العرض كلتا السلسلتين تلقائيًا من مستند النمط، فلا يلزمك التعامل مع ذلك يدويًا إلا إن بنيت واجهة إسناد خاصة بك — وعندئذٍ اقرأ حقل attribution لكل مصدر في مستند النمط (وتُعيد GET /map/config كائن attribution يحمل إسناد Navvo).

بدون مفتاح API؟ الخريطة عليها علامة مائية. بدون مفتاح API، تُعرَض خريطة الأساس مع علامة مائية "Navvo Map Developer (Provide Your API Key)" مكرَّرة عبر كل بلاطة على خلفية داكنة شبه شفافة. مرِّر مفتاح api_key (كمعامل استعلام على رابط النمط، أو apiKey في الـ SDK) للحصول على خريطة نظيفة بلا علامة مائية.

صور الشوارع

صور على مستوى الشارع وميزات الطرق من شبكة صور Navvo.

مكتبة Java (Java SDK)

ثبّت واستخدم مكتبة Java الرسمية ‎io.navvo:navvo-java‎ لخدمات الترميز الجغرافي والمسارات والأماكن وحركة المرور والمركبات الكهربائية والنقل العام والمزيد من جهة الخادم.