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

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

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

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

المكتبات المعروفة بأنّها غير متوافقة مع 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 الداخلية في Maps JavaScript API. هذا الإجراء غير مسموح به وقد يؤدي إلى تغييرات جذرية في موقعك الإلكتروني بدون إشعار. بدلاً من ذلك، ننصحك بإنشاء فئات CSS الخاصة بك كحاويات لخريطتك.

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

تجاوز 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;
}