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

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

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

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

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

مقدمة

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

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

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

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

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

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

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

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

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

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

الاتجاه

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

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

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

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

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

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

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

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

Zoom

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

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

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

• 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 lateinit var map: GoogleMap

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

      

private GoogleMap map;
    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.

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

      

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

      

وضع الخريطة في منتصف منطقة معيّنة

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

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

      

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

      

تتيح لك طريقة 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.
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)

      

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

      

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

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

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

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

لتطبيق 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

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

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

      

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