الكاميرا والعرض

يمكن إمالة الخرائط الموجودة في SDK للخرائط لنظام التشغيل Android وتدويرها بإيماءات سهلة، مما يمنح المستخدمين القدرة على ضبط الخريطة باتجاه مناسب لهم. على أي مستوى من التكبير/التصغير، يمكنك تحريك الخريطة، أو تغيير منظورها بوقت استجابة قصير جدًا وذلك بفضل المساحة الأصغر في مربعات الخرائط المستندة إلى المتجه.

عيّنات تعليمات برمجية

يتضمن مستودع ApiDemos على GitHub نموذجًا يعرض ميزات الكاميرا:

• CameraDemoActivity - جافا: تغيير موضع الكاميرا
• CameraDemoActivity - Kotlin: تغيير موضع الكاميرا

المقدمة

مثل "خرائط Google" على الويب، تمثل "حِزمة تطوير البرامج" (SDK) لتطبيق "خرائط Google" لأجهزة Android سطح الكرة الأرضية (شاشة مسطّحة) على شاشة جهازك (طائرة مسطّحة) باستخدام ميزة إسقاط السوق. في الاتجاه الشرقي والغربي، تتكرر الخريطة إلى ما لا نهاية حيث يدور العالم حول نفسها بسلاسة. في اتجاه الشمال والجنوب، تقتصر الخريطة على حوالي 85 درجة شمالاً 85 درجة جنوبًا.

ملاحظة: يكون لإسقاط ماركاتور عرضًا محدودًا طوليًا ولكن بطول لا نهائي. لقد "قطعنا" صور الخريطة الأساسية باستخدام إسقاط ماركاتور بدرجة +/- 85 درجة تقريبًا لمربع الشكل الناتج عن الخريطة، والذي يتيح منطقًا أسهل لاختيار المربّع.

تتيح لك حزمة SDK للخرائط لنظام التشغيل Android تغيير وجهة نظر المستخدم للخريطة من خلال تعديل كاميرا الخريطة.

لن تؤدي التغييرات التي تجريها على الكاميرا إلى إجراء أي تغييرات على العلامات أو التراكبات أو الرسومات الأخرى التي أضفتها، على الرغم من أنك قد تحتاج إلى تغيير إضافاتك لتلائم العرض الجديد بشكل أفضل.

نظرًا لإمكانية الاستماع إلى إيماءات المستخدمين على الخريطة، يمكنك تغيير الخريطة استجابةً لطلبات المستخدمين. على سبيل المثال، تستجيب طريقة رد الاتصال OnMapClickListener.onMapClick() لنقرة واحدة على الخريطة. ونظرًا لأن الأسلوب يتلقى خط الطول وخط العرض لموقع النقر، يمكنك الاستجابة من خلال التحريك أو التكبير أو التصغير إلى هذه النقطة. تتوفر طرق مشابهة للرد على النقرات على فقاعة أداة التمييز أو للاستجابة لإيماءة السحب على العلامة.

يمكنك أيضًا الاستماع إلى تحركات الكاميرا بحيث سيتلقى تطبيقك إشعارًا عندما تبدأ الكاميرا في الحركة أو تتحرك حاليًا أو تتوقف عن الحركة. للحصول على التفاصيل، راجع دليل أحداث تغيير الكاميرا.

موضع الكاميرا

تم تصميم عرض الخريطة على هيئة كاميرا تنظر إلى الأسفل على متن طائرة مسطحة. يتم تحديد موضع الكاميرا (وبالتالي عرض الخريطة) من خلال الخصائص التالية: الهدف (موقع خط العرض/خط الطول)، والاتجاه، والإمالة، والتكبير/التصغير.

الهدف (الموقع الجغرافي)

هدف الكاميرا هو موقع مركز الخريطة، المحدد على هيئة إحداثيات خطوط الطول والعرض.

الاتجاه (الاتجاه)

يحدد اتجاه الكاميرا اتجاه البوصلة، ويتم القياس بالدرجات من الشمال الحقيقي، بما يتوافق مع الحافة العلوية للخريطة. إذا رسمت خطًا رأسيًا من مركز الخريطة إلى الحافة العلوية للخريطة، فإن الحامل يتوافق مع عنوان الكاميرا (يتم قياسه بالدرجات) بالنسبة إلى الشمال الحقيقي.

يشير الاتجاه 0 إلى أن الجزء العلوي من الخريطة يشير إلى الشمال صحيح. تعني القيمة الحاملة 90 أعلى نقاط الخريطة المستحقة شرقًا (90 درجة على البوصلة). تعني القيمة 180 أعلى نقاط الخريطة المستحقة للجنوب.

تتيح لك API للخرائط تغيير اتجاه الخريطة. على سبيل المثال، غالبًا ما يحوّل شخص يقود سيارة خريطة طريق لمحاذاتها مع اتجاه سفره، بينما عادة ما يوجه المتنزهون الذين يستخدمون الخريطة والبوصلة الخريطة بحيث يكون الخط الرأسي باتجاه الشمال.

إمالة (زاوية العرض)

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

في الصور أدناه، زاوية العرض هي 0 درجة. تُظهر الصورة الأولى مخططًا لهذا، بينما يمثل الموضع 1 موضع الكاميرا، ويكون الموضع 2 هو موضع الخريطة الحالي. تظهر الخريطة التي تظهر أسفل منه.

في الصور أدناه، تبلغ زاوية العرض 45 درجة. لاحظ أن الكاميرا تتحرك في منتصف الطريق على شكل قوس بين ارتفاع مستقيم (0 درجة) وأرض (90 درجة)، إلى الموضع 3. لا تزال الكاميرا تشير إلى النقطة المركزية للخريطة، لكن المنطقة التي يمثلها الخط في الموضع 4 مرئية الآن.

لا تزال الخريطة في لقطة الشاشة هذه متمركزة على النقطة نفسها كما في الخريطة الأصلية، ولكن ظهرت المزيد من الميزات في أعلى الخريطة. مع زيادة الزاوية بمقدار 45 درجة، تظهر العناصر بين الكاميرا وموضع الخريطة أكبر نسبيًا، بينما تظهر العناصر خارج موضع الخريطة أصغر نسبيًا، مما ينتج عنه تأثير ثلاثي الأبعاد.

توسيع

يحدد مستوى تكبير/تصغير الكاميرا حجم الخريطة. على مستويات تكبير/تصغير أكبر، يمكن رؤية المزيد من التفاصيل على الشاشة، بينما في مستويات التكبير/التصغير الأصغر يمكن مشاهدة جزء أكبر من العالم على الشاشة. على مستوى التكبير/التصغير 0، يكون حجم الخريطة بحيث يكون عرض العالم 256dp تقريبًا (وحدات بكسل مستقلة الكثافة).

تؤدي زيادة مستوى التكبير/التصغير بمقدار 1 إلى مضاعفة عرض العالم على الشاشة. ومن ثم على مستوى التكبير N، يبلغ عرض العالم حوالي 256 * 2^N بكسل مستقل الكثافة. على سبيل المثال، في مستوى التكبير/التصغير 2، يبلغ عرض العالم بأسره 1024dp تقريبًا.

لا يلزم أن يكون مستوى التكبير/التصغير عددًا صحيحًا. يعتمد نطاق مستويات التكبير/التصغير المسموح به في الخريطة على عدد من العوامل بما في ذلك الهدف ونوع الخريطة وحجم الشاشة. وسيتم تحويل أي رقم خارج النطاق إلى أقرب قيمة صالحة تالية، والتي يمكن أن تكون إما الحد الأدنى لمستوى التكبير أو التصغير. تعرض القائمة التالية المستوى التقريبي للتفاصيل الذي يمكنك توقع مشاهدته في كل مستوى من مستويات التكبير:

• 1: العالم
• 5: مساحة اليابسة/القارة
• 10: مدينة
• 15: الشوارع
• 20: المباني

تحريك الكاميرا

تتيح لك API للخرائط تغيير أي جزء من العالم يمكن رؤيته على الخريطة. يمكن تحقيق ذلك من خلال تغيير موضع الكاميرا (بدلاً من تحريك الخريطة).

عند تغيير الكاميرا، سيكون لديك خيار تحريك حركة الكاميرا الناتجة. تدخل الصورة المتحركة بين سمات الكاميرا الحالية وسمات الكاميرا الجديدة. ويمكنك أيضًا التحكم في مدة تشغيل الصورة المتحركة.

لتغيير موضع الكاميرا، عليك تحديد موضع تحريك الكاميرا باستخدام CameraUpdate. تتيح لك واجهة برمجة تطبيقات الخرائط إنشاء العديد من أنواع CameraUpdate المختلفة باستخدام CameraUpdateFactory. تتوفّر الخيارات التالية:

تغيير مستوى التكبير/التصغير وضبط الحد الأدنى/الأقصى للتكبير/التصغير

يمنحك كل من CameraUpdateFactory.zoomIn() وCameraUpdateFactory.zoomOut() CameraUpdate تغييرًا لمستوى التكبير/التصغير بمقدار 1.0، مع الحفاظ على جميع الخصائص الأخرى بدون تغيير.

CameraUpdateFactory.zoomTo(float) تمنحك CameraUpdate تغيير مستوى التكبير/التصغير إلى القيمة المحددة، مع الحفاظ على جميع الخصائص الأخرى بدون تغيير.

CameraUpdateFactory.zoomBy(float) وCameraUpdateFactory.zoomBy(float, Point) منحك CameraUpdate زيادة (أو نقصان، إذا كانت القيمة سالبة) مستوى التكبير/التصغير بقيمة معيّنة. ويحدد هذا الأخير النقطة المحددة على الشاشة بحيث تظل في نفس الموقع (خط العرض/خط الطول) ولذلك قد تغير موقع الكاميرا لتحقيق ذلك.

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

private GoogleMap map;
    map.setMinZoomPreference(6.0f);
    map.setMaxZoomPreference(14.0f);

      

private lateinit var map: GoogleMap

    map.setMinZoomPreference(6.0f)
    map.setMaxZoomPreference(14.0f)

      

لاحظ أن هناك اعتبارات فنية قد تمنع واجهة برمجة التطبيقات من السماح للمستخدمين بالتكبير أو التصغير بشكل منخفض جدًا أو مرتفع جدًا. على سبيل المثال، قد يكون الحد الأقصى للتكبير/التصغير في القمر الصناعي أو التضاريس أقل من حدود الخريطة الأساسية.

تغيير موضع الكاميرا

هناك طريقتان مناسبتان لتغييرات الموضع الشائعة. CameraUpdateFactory.newLatLng(LatLng) يمنحك CameraUpdate تغيير خط العرض وخط الطول للكاميرا، مع الحفاظ على جميع الخصائص الأخرى. يمنحك CameraUpdateFactory.newLatLngZoom(LatLng, float) CameraUpdate إمكانية تغيير خط العرض وخط الطول والتكبير/التصغير للكاميرا، مع الحفاظ على جميع الخصائص الأخرى.

للحصول على المرونة الكاملة في تغيير موضع الكاميرا، يمكنك استخدام CameraUpdateFactory.newCameraPosition(CameraPosition) الذي يمنحك CameraUpdate لنقل الكاميرا إلى الموضع المحدّد. يمكن الحصول على CameraPosition إما مباشرةً باستخدام new CameraPosition() أو CameraPosition.Builder باستخدام new CameraPosition.Builder().

التحريك (التمرير)

يمنحك CameraUpdateFactory.scrollBy(float, float) CameraUpdate الذي يغيّر خط العرض وخط العرض للكاميرا بحيث تتحرك الخريطة بواسطة العدد المحدد من وحدات البكسل. يؤدي استخدام قيمة x موجبة إلى تحرك الكاميرا إلى اليمين، بحيث يبدو أن الخريطة قد تحركت إلى اليسار. تؤدي قيمة y الموجبة إلى تحرك الكاميرا لأسفل، بحيث يبدو أن الخريطة قد تحركت لأعلى. وعلى العكس، تؤدي قيم x السالبة إلى تحرك الكاميرا إلى اليسار، بحيث يبدو أن الخريطة قد تحركت يمينًا، وتتسبب قيم y السالبة في تحريك الكاميرا لأعلى. ويرتبط التمرير باتجاه الكاميرا الحالي. على سبيل المثال، إذا كان اتجاه الكاميرا 90 درجة، يكون الشرق شرقًا.

ضبط الحدود

تعيين حدود الخريطة

من المفيد أحيانًا تحريك الكاميرا بحيث تكون منطقة الاهتمام بأكملها مرئية بأعلى مستوى ممكن من التكبير. على سبيل المثال، إذا كنت تعرض جميع محطات الوقود في نطاق خمسة أميال من الموضع الحالي للمستخدم، فقد تحتاج إلى تحريك الكاميرا بحيث تكون جميعها مرئية على الشاشة. لإجراء ذلك، احسب أولاً LatLngBounds الذي تريد أن يكون مرئيًا على الشاشة. يمكنك بعد ذلك استخدام CameraUpdateFactory.newLatLngBounds(LatLngBounds bounds, int padding) للحصول على CameraUpdate الذي يغيّر موضع الكاميرا بحيث تتناسب LatLngBounds المحددة بالكامل مع الخريطة، مع مراعاة المساحة المتروكة (بالبكسل) المحددة. يضمن CameraUpdate المعروض أن الفجوة (بالبكسل) بين الحدود المعينة وحافة الخريطة ستكون على الأقل مساوية للمساحة المتروكة المحددة. لاحظ أن إمالة الخريطة ومحملها ستكون 0.

LatLngBounds australiaBounds = new LatLngBounds(
    new LatLng(-44, 113), // SW bounds
    new LatLng(-10, 154)  // NE bounds
);
map.moveCamera(CameraUpdateFactory.newLatLngBounds(australiaBounds, 0));

      

val australiaBounds = LatLngBounds(
    LatLng((-44.0), 113.0),  // SW bounds
    LatLng((-10.0), 154.0) // NE bounds
)
map.moveCamera(CameraUpdateFactory.newLatLngBounds(australiaBounds, 0))

      

تحديد مركز الخريطة في منطقة

في بعض الحالات، قد تحتاج إلى توسيط الكاميرا داخل حدود بدلاً من تضمين الحدود القصوى. على سبيل المثال، لتوسيط الكاميرا في بلد مع الحفاظ على تكبير/تصغير ثابت. في هذه الحالة، يمكنك استخدام طريقة مشابهة، عن طريق إنشاء LatLngBounds واستخدام CameraUpdateFactory.newLatLngZoom(LatLng latLng, float zoom) مع LatLngBounds.طريقة واحدة (getCenter()). ستعرض طريقة getCenter() المركز الجغرافي لـ LatLngBounds.

LatLngBounds australiaBounds = new LatLngBounds(
    new LatLng(-44, 113), // SW bounds
    new LatLng(-10, 154)  // NE bounds
);
map.moveCamera(CameraUpdateFactory.newLatLngZoom(australiaBounds.getCenter(), 10));

      

val australiaBounds = LatLngBounds(
    LatLng((-44.0), 113.0),  // SW bounds
    LatLng((-10.0), 154.0) // NE bounds
)
map.moveCamera(CameraUpdateFactory.newLatLngZoom(australiaBounds.center, 10f))

      

تسمح زيادة الحمل على الطريقة، newLatLngBounds(boundary, width, height, padding) بتحديد عرض وارتفاع بوحدات البكسل لمستطيل، بقصد أن تتوافق مع أبعاد الخريطة. يتم وضع المستطيل بحيث يكون مركزه مطابقًا لوسط الخريطة (حتى إذا كانت الأبعاد المحددة هي نفسها أبعاد عرض الخريطة، يتزامن المستطيل مع عرض الخريطة). سيتم تحريك الكاميرا CameraUpdate المعروضة بحيث يتم توسيط LatLngBounds المحدد على الشاشة داخل المستطيل المحدد في أكبر مستوى ممكن من التكبير، مع الأخذ بعين الاعتبار المساحة المتروكة المطلوبة.

ملاحظة: استخدِم الطريقة الأبسط newLatLngBounds(boundary, padding) فقط لإنشاء CameraUpdate إذا كنت ستستخدمه لتحريك الكاميرا بعد خضوع الخريطة للتنسيق. أثناء التنسيق، تحتسب واجهة برمجة التطبيقات حدود العرض للخريطة اللازمة لإسقاط المربّع المحيط بشكل صحيح. في المقابل، يمكنك استخدام CameraUpdate التي يتم عرضها باستخدام طريقة أكثر تعقيدًا newLatLngBounds(boundary, width, height, padding) في أي وقت، حتى قبل خضوع الخريطة للتنسيق، لأن واجهة برمجة التطبيقات تحسب حدود العرض من الوسيطات التي تمررها.

حصر العرض الشامل للمستخدم على منطقة معينة

في السيناريوهات السابقة، يمكنك تعيين حدود الخريطة، ولكن يمكن للمستخدم بعد ذلك التمرير أو التنقل خارج هذه الحدود. وبدلاً من ذلك، قد ترغب في تقييد حدود المركز/خط الطول للنقطة المحورية في الخريطة (هدف الكاميرا) بحيث يمكن للمستخدمين التمرير والتحريك داخل هذه الحدود فقط. على سبيل المثال، قد يحتاج تطبيق للبيع بالتجزئة في مركز تسوق أو مطار إلى تقييد الخريطة بحدود معينة، مما يسمح للمستخدمين بالتمرير والتحريك داخل هذه الحدود.

// Create a LatLngBounds that includes the city of Adelaide in Australia.
LatLngBounds adelaideBounds = new LatLngBounds(
    new LatLng(-35.0, 138.58), // SW bounds
    new LatLng(-34.9, 138.61)  // NE bounds
);

// Constrain the camera target to the Adelaide bounds.
map.setLatLngBoundsForCameraTarget(adelaideBounds);

      

// Create a LatLngBounds that includes the city of Adelaide in Australia.
val adelaideBounds = LatLngBounds(
    LatLng(-35.0, 138.58),  // SW bounds
    LatLng(-34.9, 138.61) // NE bounds
)

// Constrain the camera target to the Adelaide bounds.
map.setLatLngBoundsForCameraTarget(adelaideBounds)

      

يوضّح الرسم البياني التالي سيناريو عندما يكون هدف الكاميرا مقتصرًا على منطقة أكبر قليلاً من إطار العرض. يمكن للمستخدم التمرير والتحريك، بشرط أن يظل هدف الكاميرا داخل المنطقة المرتبطة. يمثل المقطع المتقاطع هدف الكاميرا:

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

في الرسم التخطيطي التالي، يتم تحديد حدود لاستخدام الكاميرا بشكل محدود للغاية، مما يمنح المستخدم فرصة ضئيلة جدًا للتمرير أو تحريك الخريطة. يمثل الصليب هدف الكاميرا:

تحديث عرض الكاميرا

لتطبيق CameraUpdate على الخريطة، يمكنك إما تحريك الكاميرا فورًا أو تحريك الكاميرا بسلاسة. لتحريك الكاميرا في الحال باستخدام CameraUpdate، يمكنك استدعاء GoogleMap.moveCamera(CameraUpdate).

يمكنك جعل تجربة المستخدم أكثر إرضاءً، خاصةً لحركات قصيرة، عن طريق تحريك التغيير. ولتنفيذ ذلك بدلاً من الاتصال بالرقم GoogleMap.moveCamera اتصل برقم GoogleMap.animateCamera. وستنتقل الخريطة بسلاسة إلى السمات الجديدة. ويقدم الشكل الأكثر تفصيلاً لهذه الطريقة، GoogleMap.animateCamera(cameraUpdate, duration, callback)، ثلاث وسيطات:

cameraUpdate

عبارة CameraUpdate التي توضّح موضع تحريك الكاميرا.

callback

كائن ينفِّذ GoogleMap.CancellableCallback. تحدد هذه الواجهة العامة للتعامل مع المهام طريقتين "onCancel()" و`onFinish()`. بالنسبة إلى الرسوم المتحركة، يتم استدعاء الطرق في الحالات التالية:

onFinish()

يتم استدعاؤها إذا تكتمل الصورة المتحركة بدون انقطاع.

onCancel()

يتم استدعاءها إذا تمت مقاطعة الصورة المتحركة عن طريق طلب stopAnimation() أو بدء حركة كاميرا جديدة.

ويمكن بدلاً من ذلك أن يحدث ذلك أيضًا عند استدعاء GoogleMap.stopAnimation().

duration

المدة المطلوبة للرسوم المتحركة، بالمللي ثانية، كـ int.

توضح مقتطفات الشفرة التالية بعض الطرق الشائعة لنقل الكاميرا.

LatLng sydney = new LatLng(-33.88,151.21);
LatLng mountainView = new LatLng(37.4, -122.1);

// Move the camera instantly to Sydney with a zoom of 15.
map.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 15));

// Zoom in, animating the camera.
map.animateCamera(CameraUpdateFactory.zoomIn());

// Zoom out to zoom level 10, animating with a duration of 2 seconds.
map.animateCamera(CameraUpdateFactory.zoomTo(10), 2000, null);

// Construct a CameraPosition focusing on Mountain View and animate the camera to that position.
CameraPosition cameraPosition = new CameraPosition.Builder()
    .target(mountainView )      // Sets the center of the map to Mountain View
    .zoom(17)                   // Sets the zoom
    .bearing(90)                // Sets the orientation of the camera to east
    .tilt(30)                   // Sets the tilt of the camera to 30 degrees
    .build();                   // Creates a CameraPosition from the builder
map.animateCamera(CameraUpdateFactory.newCameraPosition(cameraPosition));

      

val sydney = LatLng(-33.88, 151.21)
val mountainView = LatLng(37.4, -122.1)

// Move the camera instantly to Sydney with a zoom of 15.
map.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 15f))

// Zoom in, animating the camera.
map.animateCamera(CameraUpdateFactory.zoomIn())

// Zoom out to zoom level 10, animating with a duration of 2 seconds.
map.animateCamera(CameraUpdateFactory.zoomTo(10f), 2000, null)

// Construct a CameraPosition focusing on Mountain View and animate the camera to that position.
val cameraPosition = CameraPosition.Builder()
    .target(mountainView) // Sets the center of the map to Mountain View
    .zoom(17f)            // Sets the zoom
    .bearing(90f)         // Sets the orientation of the camera to east
    .tilt(30f)            // Sets the tilt of the camera to 30 degrees
    .build()              // Creates a CameraPosition from the builder
map.animateCamera(CameraUpdateFactory.newCameraPosition(cameraPosition))