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

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

إلغاء السلوك والتوافق مع المكتبة

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

في ما يلي المكتبات التي من المعروف أنّها غير متوافقة مع Maps JavaScript API:

  • ‫Prototype: تلغي 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

توفّر عمليات إلغاء `box-sizing` في CSS حلاً بديلاً محتملاً للتعارضات في أنماط الخرائط. يمكن أن يكون ذلك مفيدًا بشكل خاص إذا كنت تستخدم إطار عمل 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;
}