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

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

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

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

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

مقدمة

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

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

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

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

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

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

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

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

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

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

الاتجاه (التوجيه)

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

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

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

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

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

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

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

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

Zoom

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

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

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

• ‫1: العالم
• ‫5: كتلة أرضية/قارة
• ‫10: المدينة
• ‫15: الشوارع
• ‫20: المباني

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

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

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

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

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

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

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

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

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

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

      

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