أفضل الممارسات

أفضل الممارسات المتعلّقة بلغة JavaScript

تجاوز السلوك والتوافق مع المكتبة

تعمل Maps JavaScript API مع بيئة ECMAScript وW3C DOM العادية فقط. وهذا يعني أنّ تعديل سلوك الفئات والعناصر المضمّنة التي يوفّرها المتصفّح أو إلغاء هذا السلوك قد يؤدي إلى عدم عمل واجهة برمجة تطبيقات JavaScript للخرائط. في بعض الأحيان، يمكن أن تتعارض مكتبات أخرى مع واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" من خلال تغيير سلوك المتصفّح بحيث لا يعود بيئة ECMAScript عادية. لا تتوافق واجهة برمجة التطبيقات JavaScript الخاصة بخرائط Google مع هذه المكتبات.

المكتبات المعروفة بعدم توافقها مع Maps JavaScript API:

  • النموذج الأوّلي: يتجاوز Array.from() وElement.prototype.remove() بطرق غير عادية.
  • MooTools (الإصدارات القديمة): تتجاوز Array.from() بطريقة غير عادية.
  • ‫DateJS (الإصدارات القديمة): تتجاوز Date.now() بطريقة غير عادية.

في بعض الأحيان، يمكن تعديل المكتبات غير المتوافقة لإزالة عمليات الإلغاء غير العادية.

تحسين الأداء الداخلي

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

أفضل الممارسات المتعلّقة بـ CSS

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

تستخدم أُطر عمل CSS ومكوّنات أنماط JavaScript غالبًا عملية إعادة ضبط CSS أو أداة تسوية للتعامل مع اختلافات العرض بين المتصفّحات. تستخدم الأُطر غالبًا العنصر box-sizing لتغيير حجم الهوامش والحدود الخاصة بعناصر صفحات الويب. يتضمّن ذلك عادةً تغيير سلوك المتصفّح التلقائي من استخدام content-box إلى border-box.

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

لتجنُّب هذه التعارضات، لدينا العديد من الاقتراحات التي يجب أخذها في الاعتبار.

الدقة

يتم تطبيق CSS المضمّن والمرتبط على خريطتك قبل أنماط "خرائط Google". إذا تم تحديد جميع أنماط صفحتك في CSS مضمّن أو مرتبط، اتّبِع قواعد التحديد للتأكّد من تطبيق الأنماط الصحيحة على خريطتك.

يمكن استبدال عناصر CSS الشائعة، مثل img وbutton وa، بأنماط صفحتك. أحد السيناريوهات الأكثر شيوعًا هو عندما يتم ضبط السمة max-width لعنصر img على 100%. قد يؤدي ذلك إلى تشويه أو إخفاء عناصر الخريطة، خاصةً إذا كنت تستخدم InfoWindow.

لحلّ هذه المشكلة، يمكنك تعديل العنصر img الخاص بالخريطة لضبط السمة max-width على none. على سبيل المثال:

#map img
{
    max-width : none;
}

أسماء الفئات

لا تشِر إلى أسماء الفئات وعناصر DOM الداخلية في JavaScript Maps API. هذه الميزة غير متاحة وقد تؤدي إلى تغييرات غير متوافقة في موقعك الإلكتروني بدون إشعار. بدلاً من ذلك، ننصحك بإنشاء فئات CSS خاصة بك كحاويات لخريطتك.

إذا كان إطار عمل CSS أو مكوّن JavaScript يستخدمان هذا النوع من المراجع، قد يكون اقتراحنا بشأن إلغاء box-sizing حلاً بديلاً.

إلغاء box-sizing في CSS

توفّر عمليات إلغاء CSS box-sizing حلاً بديلاً محتملاً لتضارب أنماط الخرائط. ويمكن أن يكون ذلك مفيدًا بشكل خاص إذا كنت تستخدم إطار عمل CSS أو مكوّنًا لتصميم JavaScript. على سبيل المثال، إذا تم ضبط box-sizing على border-box، جرِّب ما يلي:

  • أنشئ عملية box-sizing تتجاوز القيمة التلقائية وتضبط العنصر <html> على border-box.
  • استخدِم box-sizing: inherit لجميع العناصر الأخرى غير الخريطة.
  • أنشئ حاوية خريطة مخصّصة تعيد ضبط العنصر box-sizing إلى initial.

مثال على CSS:

html {
  box-sizing: border-box;
}

*,
*::before,
*::after {
  box-sizing: inherit;
}

.container-map {
  box-sizing: initial;
}