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

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

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

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

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

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

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

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

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

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

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

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

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

العلامات

خيار التخصيص الأمثل:
- 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: *). ولا يمكن للخريطة تحميل النموذج في حال عدم توفّر هذا العنوان.