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

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

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

يتضمن مستودع ApiDemos على GitHub عيّنة تعرض ميزات الكاميرا:

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

المقدمة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

توسيع

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

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

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

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

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

تتيح لك Maps 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 الموجبة إلى انتقال الكاميرا إلى اليمين، بحيث يبدو أن الخريطة قد تم تحريكها إلى اليسار. وعند ضبط قيمة موجبة، ستتسبب الكاميرا في التحرّك للأسفل بحيث يظهر أنّ الخريطة تتحرّك للأعلى. وفي المقابل، تؤدي قيم 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))