المرجع السريع لـ Maps JavaScript API

‫Maps JavaScript API هي واجهة برمجة تطبيقات ويب من جهة العميل لإنشاء خرائط ثنائية وثلاثية الأبعاد على صفحات الويب، وإضافة علامات ورسومات مخصّصة ورسوم متحركة وطبقات بيانات تفاعلية، وإنشاء ميزات الموقع الجغرافي باستخدام مكتبة الأماكن.

‫Maps JavaScript API: معلومات أساسية

  • المنتج: Maps JavaScript API
  • تُعرف أيضًا باسم: Maps JS API وMaps JS API v3
  • الفئة: خرائط Google
  • المنصة: JavaScript (المتصفّح)
  • يعمل على: العميل (رمز التطبيق أو المتصفّح)
  • مرحلة الإطلاق: GA
  • Lifecycle: نشط
  • نظرة عامة: نظرة عامة على Maps JavaScript API
  • نطاق التوفّر الجغرافي: على مستوى العالم تختلف تغطية الميزات (مثل الخرائط الثلاثية الأبعاد وحركة المرور والاتجاهات وتصميم الحدود) حسب البلد أو المنطقة؛ تنطبق بنود الخدمة في المنطقة الاقتصادية الأوروبية على عناوين إرسال الفواتير في المنطقة الاقتصادية الأوروبية. (تفاصيل التغطية)

Maps JavaScript API: حالات الاستخدام

استخدِم Maps JavaScript API في الحالات التالية:

  • تحتاج إلى خريطة تفاعلية ثنائية أو ثلاثية الأبعاد تتضمّن محدّدات مواقع مخصّصة أو رسومات أو طبقات بيانات على صفحة ويب.
  • تحتاج إلى عرض المواقع الجغرافية لمواد العرض ومسارات السفر من مصدر البيانات الخاص بك باستخدام "العلامات المتقدّمة" والخطوط المتعدّدة.
  • عليك رسم حدود جغرافية (دوائر ومضلّعات) واختبار ما إذا كانت الإحداثيات تقع داخلها في المتصفّح.
  • تحتاج إلى ميزة "البحث عن الأماكن" أو "الإكمال التلقائي" أو "تفاصيل المكان" من جهة العميل في تطبيق ويب من خلال مكتبة الأماكن.

لا تستخدِم Maps JavaScript API في الحالات التالية:

  • تحتاج إلى تضمين خريطة للموقع الجغرافي الخاص بنشاط تجاري أو رابط للاتجاهات بدون كتابة رمز JavaScript مخصّص. استخدِم Maps Embed API بدلاً من ذلك.
  • ما عليك سوى استخدام رابط يفتح "خرائط Google" مع موقع جغرافي أو بحث أو اتجاهات. استخدِم عناوين URL لـ "خرائط Google" بدلاً من ذلك.
  • تحتاج إلى تتبُّع أسطول المركبات المخصّصة لمشاركة الرحلات أو عمليات التسليم المجدوَلة، على أن يكون ذلك مدمجًا مع حزمة تطوير البرامج (SDK) الخاصة بالسائق على الأجهزة الجوّالة ومصادقة JWT في الخلفية. استخدِم خدمة Fleet Engine بدلاً من ذلك.

‫Maps JavaScript API: الإعداد

حِزم Maps JavaScript API الرسمية:

  • npm: @googlemaps/js-api-loader
  • npm: @types/google.maps
  • npm: @googlemaps/markerclusterer

‫Maps JavaScript API: الأخطاء الشائعة

  • المشكلة: تظهر خريطة داكنة أو صورة سلبية من صور "التجوّل الافتراضي" تحمل علامة مائية على هيئة صورة "لأغراض التطوير فقط" بدلاً من رسالة خطأ عند ضبط مفتاح واجهة برمجة التطبيقات أو الفوترة بشكلٍ خاطئ. الحلّ: فعِّل الفوترة في مشروع على السحابة الإلكترونية، وأدرِج مفتاح واجهة برمجة تطبيقات صالحًا في كل طلب، وتحقَّق من وحدة تحكّم المتصفّح بحثًا عن رمز الخطأ المحدّد. يُرجى الاطّلاع على /maps/documentation/javascript/error-messages.
  • المشكلة: تعرض الخدمات القديمة، مثل PlacesService وDirectionsService وDistanceMatrixService، الخطأ LegacyApiNotActivatedMapError في المشاريع الجديدة التي لم يتم تفعيل واجهة برمجة التطبيقات القديمة فيها. الحلّ: استخدِم الفئات الجديدة المكافئة (Place وRoute وRouteMatrix) المستندة إلى Places API (الإصدار الجديد) وRoutes API. يُرجى الاطّلاع على /maps/legacy#LegacyApiNotActivatedMapError.
  • المشكلة: اعتبارًا من الإصدار 3.65، لم تعُد خرائط القمر الصناعي والخرائط المختلطة تنتقل إلى الصور بزاوية 45 درجة، ولم يعُد map.setTilt(45) له أي تأثير. الحلّ: استخدِم الخرائط الثلاثية الأبعاد بدلاً من الصور بزاوية 45 درجة. يُرجى الاطّلاع على /maps/deprecations.
  • المشكلة: تتطلّب "العلامات المتقدّمة" رقم تعريف خريطة، ولا يمكن للخرائط التي تم إنشاؤها بدون رقم تعريف استخدام AdvancedMarkerElement. الحلّ: أنشئ معرّف خريطة في Google Cloud Console (أو استخدِم DEMO_MAP_ID للاختبار) واضبط mapId على الخريطة. يُرجى الاطّلاع على /maps/documentation/javascript/advanced-markers/start.

‫Maps JavaScript API: الميزات القديمة والمتوقفة نهائيًا

  • Directions Service (google.maps.DirectionsService): قديمة منذ ‎2025-03-01. البديل: الفئة Route. المشكلة: ظهور الخطأ LegacyApiNotActivatedMapError في المشاريع التي لم يتم تفعيل واجهة Directions API القديمة فيها. يُرجى الاطّلاع على دليل نقل البيانات.
  • خدمة Distance Matrix Service (google.maps.DistanceMatrixService): قديمة منذ ‎01-03-2025. البديل: الفئة RouteMatrix. المشكلة: ظهور الخطأ LegacyApiNotActivatedMapError في المشاريع التي لم يتم تفعيل واجهة Distance Matrix API القديمة فيها. يُرجى الاطّلاع على دليل نقل البيانات.
  • خدمة Places Service‏ (google.maps.places.PlacesService): قديمة منذ ‎01-03-2025. البديل: الفئة Place (Places API (New)). المشكلة: ظهور الخطأ LegacyApiNotActivatedMapError في المشاريع التي لم يتم تفعيل واجهة Places API القديمة فيها يُرجى الاطّلاع على دليل نقل البيانات.
  • google.maps.Marker: تم إيقافها نهائيًا منذ 22 فبراير 2024. الاستبدال: google.maps.marker.AdvancedMarkerElement. العلامة: لا يزال يعمل ولم يتم تحديد موعد لإيقافه نهائيًا، ولن يتم إصلاح الأخطاء الحالية. يُرجى الاطّلاع على دليل نقل البيانات.
  • KmlLayer: تم إيقافها نهائيًا منذ ‎30-04-2026. البديل: ميزة "التصميم المستند إلى البيانات" لمجموعات البيانات، أو المحلّلات اللغوية لملفات KML التابعة لجهات خارجية مع طبقة البيانات المشكلة: لا يتوفّر KmlLayer في الإصدار 3.66 والإصدارات الأحدث، وسيتم إيقاف الإصدار 3.65، وهو آخر إصدار متوافق معه، في مايو 2027. يُرجى الاطّلاع على دليل نقل البيانات.
  • طبقة خريطة التمثيل اللوني (مكتبة العروض المرئية): تم إيقافها نهائيًا اعتبارًا من ‎20/05/2026. البديل: مكتبات تابعة لجهات خارجية، مثل deck.gl HeatmapLayer. Symptom: لن تكون متاحة اعتبارًا من مايو 2026. يُرجى الاطّلاع على دليل نقل البيانات.
  • مكتبة الرسم: تم إيقافها نهائيًا في ‎04/06/2026. البديل: Terra Draw Symptom: لن تكون متاحة اعتبارًا من مايو 2026. يُرجى الاطّلاع على دليل نقل البيانات.
  • صور بزاوية 45 درجة: تم إيقافها نهائيًا منذ ‎2026-05-20. البديل: الخرائط الثلاثية الأبعاد المشكلة: لا يعمل map.setTilt(45)، ويظل عرض القمر الصناعي من الأعلى إلى الأسفل. يُرجى الاطّلاع على دليل نقل البيانات.
  • ‫google.maps.event.addDomListener() وaddDomListenerOnce(): تم إيقافهما نهائيًا منذ 7 نيسان (أبريل) 2022. البديل: نموذج DOM عادي addEventListener().
  • الخيارات bounds وlocation وradius في خدمة الإكمال التلقائي للأماكن: تم إيقافها نهائيًا منذ ‎18/05/2023. الاستبدال: locationBias وlocationRestriction
  • gmp-place-content-config (PlaceContentConfigElement) في حزمة أدوات "خرائط Google" الجاهزة للأماكن: متوقّفة نهائيًا. البديل: يمكنك إضافة عناصر المحتوى مباشرةً إلى عناصر تفاصيل المكان أو في إعدادات البحث عن الأماكن.
  • مكتبة السياقات المحلية: تم إيقافها نهائيًا. البديل: مكتبة الأماكن

الإجراءات التي تتيح Maps JavaScript API تنفيذها

يمكنك الاطّلاع على الأدلة المرتبطة أدناه لكل مهمة، أو المقارنة بين المنتجات في مستكشف الإمكانات.

‫Maps JavaScript API: التحقّق من صحة العنوان

‫Maps JavaScript API: تصميم مستند إلى البيانات للحدود

‫Maps JavaScript API: تصميم مستند إلى البيانات لمجموعات البيانات

‫Maps JavaScript API: مجموعات البيانات

  • إضافة طبقة KML إلى خريطة ملاحظة: في Maps JavaScript API، تم إيقاف KmlLayer نهائيًا (آخر إصدار متوافق هو 3.65، وسيتم إيقافه نهائيًا في مايو 2027). يُرجى نقل البيانات إلى ميزة "التصميم المستند إلى البيانات" للحدود أو مجموعات البيانات، أو تحميل GeoJSON على طبقة البيانات. ستبقى طبقات KML متاحة على أجهزة Android وiOS من خلال مكتبات خدمات حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google".
  • إضافة طبقة GeoRSS إلى خريطة ملاحظة: تم إيقاف هذه الميزة نهائيًا في Maps JavaScript API (آخر إصدار يتوافق مع KmlLayer هو 3.65، وسيتم إيقافها نهائيًا في مايو 2027). يمكنك تحويل خلاصات GeoRSS إلى GeoJSON وتحميلها على طبقة البيانات باستخدام map.data.addGeoJson().
  • إضافة بيانات GeoJSON إلى خريطة

‫Maps JavaScript API: الاتجاهات والمسارات

‫Maps JavaScript API: الارتفاع

‫Maps JavaScript API: Fleet Engine

‫Maps JavaScript API: الترميز الجغرافي

‫Maps JavaScript API: الخرائط

‫Maps JavaScript API: التعليقات التوضيحية في الخرائط

‫Maps JavaScript API: تصميم الخرائط

‫Maps JavaScript API: أخرى

‫Maps JavaScript API: خرائط ثلاثية الأبعاد لصور واقعية

‫Maps JavaScript API: الأماكن

Maps JavaScript API: حزمة أدوات "خرائط Google" الجاهزة للأماكن

  • يمكنك إضافة عنصر في واجهة المستخدم يعرض ملخّصات ومراجعات مستنِدة إلى الذكاء الاصطناعي حول أماكن معيّنة إلى صفحة ويب أو تطبيق على الأجهزة الجوّالة. ملاحظة: تتوفّر هذه الميزة على الويب فقط (حزمة أدوات "خرائط Google" الجاهزة للأماكن في Maps JavaScript API). لا تتضمّن حِزم أدوات "خرائط Google" الجاهزة للأماكن على الأجهزة الجوّالة عنصر ملخّص من إنشاء الذكاء الاصطناعي. متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل ضمن Maps JavaScript API بدلاً من طلب خدمات الويب في Places API من خادم خلفي. للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • تطبيق نمط CSS على عنصر في واجهة المستخدم لبيانات الأماكن ملاحظة: تنطبق الخصائص المخصّصة في CSS على عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن في Maps JavaScript API. أمّا حزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل Android وحزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل iOS، فتصمّمان طرق عرض حزمة أدوات "خرائط Google" الجاهزة للأماكن آليًا باستخدام سمات المظهر والنمط. متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تستدعِ خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • تخصيص تصميم وإعدادات عناصر واجهة المستخدم لبيانات الأماكن باستخدام أداة تخصيص عناصر واجهة المستخدم: ملاحظة: متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تطلب خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • أضِف عنصرًا في واجهة المستخدم يعرض معلومات عن مكان معيّن على صفحة ويب أو تطبيق للأجهزة الجوّالة. ملاحظة: متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تطلب خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • أضِف عنصرًا في واجهة المستخدم يعرض قائمة بالأماكن استنادًا إلى سلسلة طلب بحث إلى صفحة ويب. ملاحظة: تتوفّر هذه الميزة على كلّ من صفحات الويب (Maps JavaScript API) والتطبيقات على الأجهزة الجوّالة (Places SDK for Android وPlaces SDK for iOS). متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تستدعِ خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • أضِف عنصرًا في واجهة المستخدم يعرض قائمة بالأماكن القريبة من موقع جغرافي معيّن إلى صفحة ويب. ملاحظة: تتوفّر هذه الميزة على كلّ من صفحات الويب (Maps JavaScript API) والتطبيقات على الأجهزة الجوّالة (Places SDK for Android وPlaces SDK for iOS). متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تستدعِ خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
  • يمكنك إضافة عنصر أساسي في واجهة المستخدم للإكمال التلقائي إلى صفحة ويب أو تطبيق يعرض معرّفات الأماكن على Google استنادًا إلى سلسلة طلب بحث. ملاحظة: متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تطلب خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq

‫Maps JavaScript API: ميزة "التجوّل الافتراضي"