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

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

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

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

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

المقدمة

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

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

تتيح لك حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android تغيير منظور المستخدم على الخريطة من خلال تعديل كاميرا الخريطة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

توسيع

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

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

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

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

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

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

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

لتغيير موضع الكاميرا، يجب تحديد المكان الذي تريد تحريك الكاميرا فيه، باستخدام CameraUpdate. تتيح لك Maps API إنشاء العديد من الأنواع المختلفة من 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 الموجبة في تحرك الكاميرا إلى اليمين، بحيث تبدو الخريطة قد تحركت إلى اليسار. تؤدي القيمة ص الموجبة إلى تحرك الكاميرا لأسفل، بحيث تظهر الخريطة وكأنها قد تحركت إلى أعلى. وبالعكس، تتسبب قيم x السالبة في تحرّك الكاميرا جهة اليسار، بحيث تظهر الخريطة تحركها اليمين، بينما تؤدي قيم ص السالبة إلى تحرك الكاميرا للأعلى. يرتبط التمرير بالاتجاه الحالي للكاميرا. على سبيل المثال، إذا كان اتجاه الكاميرا نحو 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()` و `onFinished()`. بالنسبة إلى الرسوم المتحركة، يتم طلب الطرق في الحالات التالية:

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))