حزمة أدوات Places UI Kit: هي مكتبة جاهزة للاستخدام تتيح للمطوّرين إمكانية التخصيص والتحكّم. ننصحك بتجربتها ومشاركة ملاحظاتك حول تجربتك مع حزمة واجهة المستخدم.

أفضل الممارسات المتعلّقة بـ "خرائط ثلاثية الأبعاد"

يقدّم هذا الدليل نظرة تفصيلية على مكوّنات الويب الخاصة بـ "خرائط Google الثلاثية الأبعاد" والاعتبارات التي يجب مراعاتها عند دمجها مع تطبيقك.

مثال على حالة استخدام البحث عن الأماكن والعثور على الطرق — مثال على البحث عن الأماكن والعثور على المسارات

اعتبارات الأداء

لضمان تجربة سلسة ومتجاوبة للتفاعل والعناصر المرئية، ننصحك باتّباع الطرق التالية.

تحميل الخريطة

يجمع الإعداد الأوّلي للتحميل والعرض في "خرائط ثلاثية الأبعاد" بين تقنيات ضبط المتصفّح وأفضل ممارسات واجهة المستخدم لتقديم تجربة مثالية للمستخدم.

تحميل واجهة برمجة التطبيقات: استخدِم التحميل الديناميكي غير المتزامن لـ "خرائط ثلاثية الأبعاد" من أجل تحميل Maps JavaScript API عند تحميل الصفحة في البداية.
المكتبات: حمِّل المكتبات آليًا عند الحاجة، مثل google.maps.importLibrary("maps3d"). بدلاً من ذلك، إذا كنت تستخدم مكوّنات ويب مثل <gmp-map-3d> مباشرةً في صفحة HTML مع تحميل النص البرمجي المباشر، سيتم تحميل المكتبات تلقائيًا في الوقت المناسب.
إدارة ميزات الخريطة الأساسية: استخدِم mapId مخصّصًا لفلترة نقاط الاهتمام في الخريطة الأساسية (الوضع المختلط)، والتحكّم في كثافتها، خاصةً إذا كان التطبيق يتضمّن مجموعة من العناصر المخصّصة، مثل العلامات أو الخطوط المتعددة. يمنع ذلك التشويش المرئي والتداخل المحتمل. بدلاً من ذلك، يمكنك إيقاف ميزات مربّعات المتجهات الخاصة بالخريطة الأساسية، مثل نقاط الاهتمام وخطوط الطرق المتعددة وأسماء الطرق وأسماء الشوارع (وضع القمر الصناعي).
الأحداث: استمع إلى الأحداث gmp-steadystate أو gmp-error لإنشاء منطقك اللاحق، مثل تحميل العلامات وتحريك الكاميرا.

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

تفاعل المستخدم: انتظِر حدث gmp-steadystate قبل إجراء تغييرات على محتوى الخريطة. إذا بدأ المستخدم التفاعل (تحريك، تكبير/تصغير) مع الخريطة قبل الحدث الأوّلي gmp-steadystate، لن يتم تنشيط الحدث إلا بعد أن يتوقف المستخدم عن التفاعل. تجنَّب عرض المحتوى المتراكب أو تعديله (مثل العلامات أو المضلّعات) أثناء تحريك المستخدم للخريطة أو تكبيرها أو تصغيرها، وتجنَّب عرض المحتوى المتراكب أو تعديله (مثل العلامات أو المضلّعات) من خلال الاستماع إلى الأحداث التالية: gmp-centerchange وgmp-headingchange وgmp-rangechange وgmp-rollchange وgmp-tiltchange.
استخدِم requestAnimationFrame() (rAF) للحصول على تحديثات مستمرة وافصل تمامًا العمليات الحسابية المكثّفة عن طلبات الرسم.
- استخدام rAF: تتم مزامنة التحديثات مع معدّل عرض المتصفّح للحصول على صورة متحركة سلسة بمعدّل 60 لقطة في الثانية وتقليل استهلاك الطاقة.
- تجنُّب العمل المكثّف في الرسم: لا تنفِّذ مهامًا ثقيلة لا تتعلّق بالرسم أثناء التحديث النهائي.
- المنطق المنفصل: نفِّذ جميع العمليات المنطقية المكثّفة قبل إجراء الحد الأدنى من طلبات تعديل مكوّنات الويب ضمن حلقة rAF.
إعدادات المشهد الأوّلية: <gmp-map-3d> ستؤثر إعدادات الكاميرا، مثل الميل، في سرعة التحميل. كلما تم تكبير المشهد أو إمالته، سيتم عرض المزيد من المضلّعات التفصيلية التي تتطلّب التحميل. سيعتمد مستوى التفاصيل أيضًا على الموقع الجغرافي (مثلاً: مدينة تضم العديد من المباني مقابل ريف يضم ميزات طبيعية فقط).
- يُفضّل استخدام صور غير مقرّبة (على ارتفاع عالٍ) وغير مائلة أو مائلة بشكل طفيف.
- أضِف حدودًا (مثال) إلى الخريطة لكي يركّز المستخدمون على منطقة معيّنة ويتم تحميل المربّعات بالكامل.
المرئيات الخاصة بأداة التحميل المسبق: على الرغم من أنّ <gmp-map-3d> يتم تحميلها بسرعة فائقة، قد يستغرق عرضها بالدقة الكاملة بعض الوقت لدى المستخدمين الذين لديهم أجهزة منخفضة المواصفات (وحدة معالجة الرسومات منخفضة المواصفات) أو نطاق ترددي منخفض (شبكة الجيل الرابع البطيئة). في هذه الحالة، يمكنك إنشاء أداة تحميل مسبق باستخدام صورة أو رسم متحرك أو نص مع تحميل المشهد الثلاثي الأبعاد في الخلفية. اطّلِع على الحدث الرئيسي الذي يجب استخدامه أدناه:

// create the map in the background and wait for gmp-steadystate event
async function initMap() {
    await google.maps.importLibrary("maps3d");
    const map = document.querySelector('gmp-map-3d');
    const div = document.querySelector('div'); // preloader "
    map.addEventListener('gmp-steadystate', ({isSteady}) => {
        if (isSteady) {
            div.style.display = 'none';
        }
    });
}
initMap();

خريطة ثنائية الأبعاد:
- يمكن عرض خريطة ثنائية الأبعاد بديلة (SATELLITE) لهؤلاء المستخدمين مع تضمين بياناتك الجغرافية، مثل العلامات.

بدلاً من ذلك، يمكن عرض خريطة ثابتة ثنائية الأبعاد تكميلية في وضع القمر الصناعي ليتمكّن المستخدمون من رؤية مكان معيّن أثناء التحميل.

أداء العناصر المرئية وإدارتها

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

العلامات

خيار التخصيص الأمثل:
- PinElement: لإجراء تغييرات أساسية على العلامات (اللون والحجم والحد والنص والرمز)، استخدِم العنصر <gmp-pin> أو الفئة PinElement. هذه هي طريقة التخصيص الأفضل أداءً.
- استخدام علامات HTMLImageElement أو SVGElement بشكل مقتصد: استخدِمها لإجراء المزيد من التخصيصات، مثل إضافة الشفافية أو إدراج صورة مثل رمز في SVGElement (يتطلّب ذلك ترميز base64). سيتم تحويلها إلى صور نقطية عند التحميل، ما سيؤدي إلى زيادة الحمل على الأداء. يجب تضمين HTMLImageElement وSVGElement في عنصر <template> قبل تعيينهما إلى الفتحة التلقائية في Marker3DElement.
- لا يمكن حاليًا إضافة HTML أو CSS عاديَين.
إدارة سلوك التصادم: استفِد من السمة collisionBehavior الخاصة بالعلامة. بالنسبة إلى العلامات المهمة التي يجب أن تكون مرئية دائمًا، اضبط السلوك وفقًا لذلك. بالنسبة إلى العلامات الأقل أهمية، اسمح بإخفائها للحفاظ على تجربة خريطة أكثر وضوحًا وأقل ازدحامًا، خاصةً عند مستويات التكبير العالية.
نقاط الاهتمام المهمة فقط: استخدِم drawsWhenOccluded فقط (أو اضبط السمة آليًا) للعلامات التي يجب أن تكون مرئية من خلال المباني أو التضاريس (مثل هدف إنقاذ أو خط مرافق مدفون أو صورة رمزية للمستخدم).
اختبار الانسداد: بما أنّ الخريطة ثلاثية الأبعاد، يمكن أن تحجب المباني أو التضاريس العلامات بصريًا (تتسبب في انسدادها). جرِّب زوايا مختلفة للكاميرا وارتفاعات مختلفة للعلامات لضمان بقاء نقاط الاهتمام المهمة مرئية، أو نفِّذ منطقًا لتعديل مستوى الظهور والارتفاع عند الحجب.
الاستفادة من الارتفاع: في الخرائط الثلاثية الأبعاد، يجب أن تستخدم العلامات الموضع مع قيمة ارتفاع. بالنسبة إلى العلامات المرتبطة بالتضاريس أو المباني، استخدِم altitudeMode: 'RELATIVE_TO_GROUND', 'RELATIVE_TO_MESH' أو إعدادات مشابهة لضمان تثبيت العلامة بشكل صحيح عند إمالة الخريطة أو تدويرها.

المضلّعات والخطوط المتعددة

مثال على تحميل المضلّعات — سيناريو مثال: من 100 إلى 150 ملي ثانية لتحميل 1, 000 مضلّع (كمبيوتر محمول حديث: macOS M3 Pro، Chrome)

تبسيط الأشكال الهندسية: قبل العرض، طبِّق خوارزمية تبسيط على بيانات المسار. يؤدي ذلك إلى تقليل عدد الرؤوس مع الحفاظ على الشكل العام، ما يحسّن بشكل كبير سرعة العرض، خاصةً بالنسبة إلى الحدود أو المسارات المعقّدة.
التقليل من التفاصيل حسب مستوى التكبير/التصغير: بالنسبة إلى مجموعات البيانات الكبيرة جدًا، ننصحك بتحميل أشكال هندسية ذات تفاصيل أعلى فقط عندما يكبّر المستخدم المنطقة. عند مستوى تكبير/تصغير منخفض، لا يلزم سوى نسخة مبسطة للغاية من الخط المتعدد الأضلاع أو المضلّع.
الحساب المُسبَق للأشكال المضلّعة البارزة: إذا كانت الأشكال المضلّعة بارزة (extruded: true)، تحدّد بيانات المسار حجمًا ثلاثي الأبعاد (شبكة). تتطلّب معالجة المضلّعات المعقّدة ذات الرؤوس الكثيرة قدرًا كبيرًا من العمليات الحسابية. تأكَّد من أنّ بيانات المصدر الخاصة بالمضلّعات بسيطة قدر الإمكان.
اختبار أداء الخطوط المتعددة والرسومات المضلّعة: عند إضافة العديد من الخطوط المتعددة أو الرسومات المضلّعة المعقّدة، خاصةً عند بثقها لعرضها بشكل ثلاثي الأبعاد، تأكَّد من أنّها لا تؤدي إلى انخفاض عدد اللقطات في الثانية. قلِّل عدد الرؤوس أو استخدِم خوارزميات التبسيط إذا لزم الأمر.
عند تعديل شكل، عدِّل مصفوفة المسار بأكملها في عملية واحدة بدلاً من التكرار وتعديل العناصر الفردية. تكون عملية التعيين الفردية (على سبيل المثال، polyline.path = newPathArray;) أكثر فعالية بكثير من عمليات التعديل المتكرّرة المتعدّدة.
تجنُّب الخطوط المتعددة الأضلاع البارزة (حيثما أمكن): على الرغم من أنّ الخطوط المتعددة الأضلاع يمكن أن تستخدم قيمة ارتفاع ليتم وضعها في مساحة ثلاثية الأبعاد، إلا أنّ بروز الخط المتعدد الأضلاع (مثل منحه عرض خط وارتفاعًا كبيرًا) يمكن أن يكون مكثفًا من الناحية الرسومية. استخدِم خطوطًا متعددة الأضلاع ثنائية الأبعاد على الأرض (RELATIVE_TO_GROUND) أو عرضًا أدنى للخطوط كلما أمكن ذلك لتحسين الأداء.
لا تستخدِم drawsOccludedSegments إلا لعناصر التوجيه المهمة. بالنسبة إلى الأشكال الخلفية أو السياقية، اسمح بأن يتم حجبها بشكل طبيعي من خلال الأشكال الهندسية الثلاثية الأبعاد للخريطة. يؤدي عرض أشكال هندسية مخفية غير مهمة إلى زيادة تعقيد العرض بشكل غير ضروري.

التصاميم الثلاثية الأبعاد

تكون سرعة عرض نماذج ‎ .glb ثلاثية الأبعاد والتفاعل معها، مثل حدث gmp-click، عالية جدًا في <gmp-map-3d>.

مثال على تحميل تصميم ثلاثي الأبعاد — سيناريو المثال: يستغرق عرض 1,000 موضع ورود من تصميم ثلاثي الأبعاد (200 كيلوبايت) لضوء يتحرّك على طول مسار معيّن حوالي ثانيتَين. (كمبيوتر محمول حديث: macOS M3 Pro، متصفّح Chrome)

تقليل حجم الملف باستخدام الضغط: لضمان سرعة التحميل، خاصةً على شبكات الجوّال، يجب أن يكون حجم ملفات نماذج .glb المعقّدة أقل من 5 ميغابايت (ويُفضّل أن يكون أقل من ذلك). الطريقة الأساسية لتحقيق ذلك هي تطبيق ضغط Draco على بيانات الشبكة داخل ملفات .glb، ما يمكن أن يقلّل حجم الملف بشكل كبير (غالبًا بأكثر من %50) مع الحد الأدنى من فقدان الجودة المرئية.
توسيط نقطة الأصل في التصميم: تأكَّد من أنّ برنامج التصميم الثلاثي الأبعاد يصدّر التصميم مع نقطة الأصل (النقطة 0, 0, 0) في منتصف قاعدة التصميم. يؤدي ذلك إلى تبسيط عملية تحديد الموضع والتدوير على الخريطة، ما يضمن تثبيت النموذج بشكل صحيح على إحداثيات خط العرض وخط الطول.
إدارة CORS: إذا كانت ملفات النماذج مستضافة على نطاق أو شبكة توصيل محتوى (CDN) مختلفَين عن تطبيق الويب، عليك ضبط خادم الاستضافة لتضمين عناوين مشاركة المراجع مع نطاقات خارجية (CORS) اللازمة (مثل Access-Control-Allow-Origin: *). وإلا، لن تتمكّن الخريطة من تحميل النموذج.