التجوّل الافتراضي

اختَر النظام الأساسي: Android iOS JavaScript

توفّر ميزة "التجوّل الافتراضي من Google" إطلالات بانورامية بزاوية 360 درجة من طرق معيّنة في جميع أنحاء منطقة التغطية.

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

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

تعمل الصف StreetViewPanorama على تصميم بانوراما "التجوّل الافتراضي" في تطبيقك. في واجهة المستخدم، يتم تمثيل البانوراما بكائن StreetViewPanoramaFragment أو StreetViewPanoramaView.

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

يشمل مستودع ApiDemos على GitHub نماذج توضّح استخدام ميزة "التجوّل الافتراضي".

عيّنات Kotlin:

عيّنات Java:

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

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

كل بانوراما في التجوّل الافتراضي هي صورة أو مجموعة من الصور التي توفر عرضًا كاملاً بزاوية 360 درجة من موقع واحد. تتوافق الصور مع الإسقاط المتساوي المستطيلات (Plate Carrée) الذي يحتوي على 360 درجة من العرض الأفقي (الالتفاف الكامل) و180 درجة من العرض الرأسي (من مباشرة إلى أسفل). تعمل البانوراما الناتجة بنطاق 360 درجة على تحديد الإسقاط على الكرة مع التفاف الصورة بالسطح الثنائي الأبعاد لتلك الكرة.

يوفر StreetViewPanorama عارضًا يعرض الصورة البانورامية على شكل كرة مع وجود كاميرا في منتصفها. يمكنك التحكّم في StreetViewPanoramaCamera للتحكّم في التكبير أو التصغير واتجاه الكاميرا (إمالة واتجاه الكاميرا).

بدء

إعداد مشروع

اتّبِع دليل البدء لإعداد حزمة SDK لـ "خرائط Google" لنظام التشغيل Android.

تحقق من توفر بانوراما في "التجوّل الافتراضي" قبل إضافة صورة بانوراما

تتضمن مكتبة عملاء SDK لخدمات Google Play بعض نماذج التجوّل الافتراضي التي يمكنك استيرادها إلى مشروعك واستخدامها كأساس للتطوير. راجِع المقدمة للاطّلاع على إرشادات حول استيراد النماذج.

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

استخدام واجهة برمجة التطبيقات

اتّبِع التعليمات أدناه لإضافة بانوراما في "التجوّل الافتراضي" إلى أحد أجزاء Android. هذه هي أبسط طريقة لإضافة ميزة "التجوّل الافتراضي" إلى تطبيقك. ثم اقرأ المزيد حول الأجزاء وطرق العرض وتخصيص البانوراما.

إضافة بانوراما في "التجوّل الافتراضي"

اتبع الخطوات أدناه لإضافة بانوراما في ميزة "التجوّل الافتراضي" مثل هذه:

عرض توضيحي لميزة بانوراما في ميزة "التجوّل الافتراضي"

باختصار:

  1. أضِف كائن جزء إلى النشاط الذي سيتعامل مع بانوراما "التجوّل الافتراضي". أسهل طريقة للقيام بذلك هي إضافة عنصر <fragment> إلى ملف التنسيق لـ Activity.
  2. نفِّذ واجهة OnStreetViewPanoramaReadyCallback واستخدِم طريقة معاودة الاتصال onStreetViewPanoramaReady(StreetViewPanorama) للتعامل مع الكائن StreetViewPanorama.
  3. عليك استدعاء getStreetViewPanoramaAsync() على الجزء لتسجيل معاودة الاتصال.

في ما يلي مزيد من التفاصيل حول كل خطوة.

إضافة جزء

أضِف عنصر <fragment> إلى ملف تنسيق النشاط لتحديد عنصر جزء. في هذا العنصر، اضبط السمة class على com.google.android.gms.maps.StreetViewPanoramaFragment (أو SupportStreetViewPanoramaFragment).

في ما يلي مثال على جزء في ملف تنسيق:

<fragment
    android:name="com.google.android.gms.maps.StreetViewPanoramaFragment"
    android:id="@+id/streetviewpanorama"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

إضافة رمز "التجوّل الافتراضي"

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

Kotlin



class StreetViewActivity : AppCompatActivity(), OnStreetViewPanoramaReadyCallback {
    // ...
}

      

Java


class StreetViewActivity extends AppCompatActivity implements OnStreetViewPanoramaReadyCallback {
    // ...
}

      

في طريقة onCreate() في Activity، حدِّد ملف التنسيق كطريقة عرض المحتوى. على سبيل المثال، إذا كان ملف التنسيق يحمل الاسم main.xml، استخدِم الرمز التالي:

Kotlin



override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_street_view)
    val streetViewPanoramaFragment =
        supportFragmentManager
            .findFragmentById(R.id.street_view_panorama) as SupportStreetViewPanoramaFragment
    streetViewPanoramaFragment.getStreetViewPanoramaAsync(this)
}

      

Java


@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_street_view);
    SupportStreetViewPanoramaFragment streetViewPanoramaFragment =
        (SupportStreetViewPanoramaFragment) getSupportFragmentManager()
            .findFragmentById(R.id.street_view_panorama);
    streetViewPanoramaFragment.getStreetViewPanoramaAsync(this);
}

      

يمكنك التعامل مع الجزء من خلال استدعاء FragmentManager.findFragmentById()، وتمرير معرف المورد للعنصر <fragment>. لاحظ أنّ معرّف المورد R.id.streetviewpanorama تتم إضافته تلقائيًا إلى مشروع Android عند إنشاء ملف التنسيق.

بعد ذلك، استخدِم getStreetViewPanoramaAsync() لضبط معاودة الاتصال على الجزء.

Kotlin



val streetViewPanoramaFragment =
    supportFragmentManager
        .findFragmentById(R.id.street_view_panorama) as SupportStreetViewPanoramaFragment
streetViewPanoramaFragment.getStreetViewPanoramaAsync(this)

      

Java


SupportStreetViewPanoramaFragment streetViewPanoramaFragment =
    (SupportStreetViewPanoramaFragment) getSupportFragmentManager()
        .findFragmentById(R.id.street_view_panorama);
streetViewPanoramaFragment.getStreetViewPanoramaAsync(this);

      

استخدِم طريقة معاودة الاتصال onStreetViewPanoramaReady(StreetViewPanorama) لاسترجاع مثيل غير فارغ لـ StreetViewPanorama، وهو جاهز للاستخدام.

Kotlin



override fun onStreetViewPanoramaReady(streetViewPanorama: StreetViewPanorama) {
    val sanFrancisco = LatLng(37.754130, -122.447129)
    streetViewPanorama.setPosition(sanFrancisco)
}

      

Java


@Override
public void onStreetViewPanoramaReady(StreetViewPanorama streetViewPanorama) {
    LatLng sanFrancisco = new LatLng(37.754130, -122.447129);
    streetViewPanorama.setPosition(sanFrancisco);
}

      

مزيد من المعلومات حول ضبط الحالة الأولية

على عكس الخريطة، لا يمكن تهيئة الحالة الأولية للبانوراما في التجوّل الافتراضي عبر XML. ومع ذلك، يمكنك ضبط البانوراما بطريقة آلية من خلال تمرير عنصر StreetViewPanoramaOptions يحتوي على الخيارات المحدّدة.

Kotlin



val sanFrancisco = LatLng(37.754130, -122.447129)
val view = StreetViewPanoramaView(
    this,
    StreetViewPanoramaOptions().position(sanFrancisco)
)

      

Java


LatLng sanFrancisco = new LatLng(37.754130, -122.447129);
StreetViewPanoramaView view = new StreetViewPanoramaView(this,
    new StreetViewPanoramaOptions().position(sanFrancisco));

      

مزيد من المعلومات حول StreetViewPanoramaFragment

StreetViewPanoramaFragment هي فئة فرعية من فئة جزء Android، تسمح لك بوضع بانوراما في "التجوّل الافتراضي" في جزء من نظام Android. تعمل كائنات StreetViewPanoramaFragment كحاويات للعرض البانورامية، وتوفّر إمكانية الوصول إلى الكائن StreetViewPanorama.

StreetViewPanoramaView

StreetViewPanoramaView، وهي فئة فرعية من فئة Android View، تسمح لك بوضع بانوراما للتجوّل الافتراضي في View Android. تمثّل السمة View منطقة مستطيلة من الشاشة، وهي لبنة أساسية لتطبيقات Android والتطبيقات المصغّرة. مثل StreetViewPanoramaFragment، يعمل StreetViewPanoramaView كحاوية للعرض البانورامية، ويعرض الوظائف الأساسية من خلال الكائن StreetViewPanorama. على مستخدمي هذه الفئة إعادة توجيه جميع طُرق دورة حياة النشاط (مثل onCreate() وonDestroy() وonResume() وonPause())) إلى الطرق المناسبة في الفئة StreetViewPanoramaView.

تخصيص الوظائف التي يتحكّم فيها المستخدم

بشكل افتراضي، تتوفر الوظيفة التالية للمستخدم عند عرض بانوراما التجوّل الافتراضي: العرض الشامل، والتكبير/التصغير، والانتقال إلى صور بانورامية مجاورة. يمكنك تفعيل الإيماءات التي يتحكّم فيها المستخدم وإيقافها من خلال الطرق على StreetViewPanorama. لا تزال التغييرات الآلية ممكنة عند إيقاف الإيماءة.

ضبط موقع الصورة البانورامية

لتحديد موقع الصورة البانورامية 360 درجة في "التجوّل الافتراضي"، اتصل بالعنوان StreetViewPanorama.setPosition()، مع تمرير LatLng. يمكنك أيضًا ضبط radius وsource كمَعلمتَين اختياريتَين.

يكون النطاق الجغرافي مفيدًا إذا كنت تريد توسيع أو تضييق المنطقة التي ستبحث فيها ميزة "التجوّل الافتراضي" عن صورة بانورامية مطابقة. ويعني نصف القطر 0 أنّه يجب ربط البانوراما بنطاق LatLng المحدّد بالضبط. النطاق الافتراضي هو 50 متر. إذا كان هناك أكثر من بانوراما واحدة في المنطقة المطابقة، ستعرض واجهة برمجة التطبيقات أفضل تطابق.

والمصدر مفيد إذا كنت ترغب في تقييد التجوّل الافتراضي للبحث عن الصور البانورامية في الهواء الطلق فقط. يمكن أن تكون الصور البانورامية 360 درجة في ميزة "التجوّل الافتراضي" داخل أماكن مثل المتاحف والمباني العامة والمقاهي والأنشطة التجارية. لاحظ أن الصور البانورامية الخارجية قد لا تكون موجودة للموقع المحدد.

Kotlin



val sanFrancisco = LatLng(37.754130, -122.447129)

// Set position with LatLng only.
streetViewPanorama.setPosition(sanFrancisco)

// Set position with LatLng and radius.
streetViewPanorama.setPosition(sanFrancisco, 20)

// Set position with LatLng and source.
streetViewPanorama.setPosition(sanFrancisco, StreetViewSource.OUTDOOR)

// Set position with LaLng, radius and source.
streetViewPanorama.setPosition(sanFrancisco, 20, StreetViewSource.OUTDOOR)

      

Java


LatLng sanFrancisco = new LatLng(37.754130, -122.447129);

// Set position with LatLng only.
streetViewPanorama.setPosition(sanFrancisco);

// Set position with LatLng and radius.
streetViewPanorama.setPosition(sanFrancisco, 20);

// Set position with LatLng and source.
streetViewPanorama.setPosition(sanFrancisco, StreetViewSource.OUTDOOR);

// Set position with LaLng, radius and source.
streetViewPanorama.setPosition(sanFrancisco, 20, StreetViewSource.OUTDOOR);

      

ويمكنك بدلاً من ذلك ضبط الموقع الجغرافي استنادًا إلى معرّف بانوراما من خلال تمرير panoId إلى StreetViewPanorama.setPosition().

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

Kotlin



streetViewPanorama.location.links.firstOrNull()?.let { link: StreetViewPanoramaLink ->
    streetViewPanorama.setPosition(link.panoId)
}

      

Java


StreetViewPanoramaLocation location = streetViewPanorama.getLocation();
if (location != null && location.links != null) {
    streetViewPanorama.setPosition(location.links[0].panoId);
}

      

التكبير والتصغير

يمكنك تغيير مستوى التكبير أو التصغير آليًا عن طريق ضبط StreetViewPanoramaCamera.zoom. يؤدي ضبط التكبير/التصغير على 1.0 إلى تكبير الصورة بمقدار 2.

يستخدم المقتطف التالي StreetViewPanoramaCamera.Builder() لإنشاء كاميرا جديدة بإمالة واتجاه الكاميرا الحالية، مع زيادة التكبير بمقدار خمسين في المئة.

Kotlin



val zoomBy = 0.5f
val camera = StreetViewPanoramaCamera.Builder()
    .zoom(streetViewPanorama.panoramaCamera.zoom + zoomBy)
    .tilt(streetViewPanorama.panoramaCamera.tilt)
    .bearing(streetViewPanorama.panoramaCamera.bearing)
    .build()

      

Java


float zoomBy = 0.5f;
StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder()
    .zoom(streetViewPanorama.getPanoramaCamera().zoom + zoomBy)
    .tilt(streetViewPanorama.getPanoramaCamera().tilt)
    .bearing(streetViewPanorama.getPanoramaCamera().bearing)
    .build();

      

ضبط اتجاه الكاميرا (وجهة النظر)

يمكنك تحديد اتجاه كاميرا "التجوّل الافتراضي" من خلال ضبط الاتجاه والإمالة على StreetViewPanoramaCamera.

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

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

Kotlin



val panBy = 30f
val camera = StreetViewPanoramaCamera.Builder()
    .zoom(streetViewPanorama.panoramaCamera.zoom)
    .tilt(streetViewPanorama.panoramaCamera.tilt)
    .bearing(streetViewPanorama.panoramaCamera.bearing - panBy)
    .build()

      

Java


float panBy = 30;
StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder()
    .zoom(streetViewPanorama.getPanoramaCamera().zoom)
    .tilt(streetViewPanorama.getPanoramaCamera().tilt)
    .bearing(streetViewPanorama.getPanoramaCamera().bearing - panBy)
    .build();

      

يميل المقتطف التالي الكاميرا إلى أعلى بمقدار 30 درجة.

Kotlin



var tilt = streetViewPanorama.panoramaCamera.tilt + 30
tilt = if (tilt > 90) 90f else tilt
val previous = streetViewPanorama.panoramaCamera
val camera = StreetViewPanoramaCamera.Builder(previous)
    .tilt(tilt)
    .build()

      

Java


float tilt = streetViewPanorama.getPanoramaCamera().tilt + 30;
tilt = (tilt > 90) ? 90 : tilt;

StreetViewPanoramaCamera previous = streetViewPanorama.getPanoramaCamera();

StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder(previous)
    .tilt(tilt)
    .build();

      

أضِف تأثيرات حركية إلى حركات الكاميرا.

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

Kotlin



// Keeping the zoom and tilt. Animate bearing by 60 degrees in 1000 milliseconds.
val duration: Long = 1000
val camera = StreetViewPanoramaCamera.Builder()
    .zoom(streetViewPanorama.panoramaCamera.zoom)
    .tilt(streetViewPanorama.panoramaCamera.tilt)
    .bearing(streetViewPanorama.panoramaCamera.bearing - 60)
    .build()
streetViewPanorama.animateTo(camera, duration)

      

Java


// Keeping the zoom and tilt. Animate bearing by 60 degrees in 1000 milliseconds.
long duration = 1000;
StreetViewPanoramaCamera camera =
    new StreetViewPanoramaCamera.Builder()
        .zoom(streetViewPanorama.getPanoramaCamera().zoom)
        .tilt(streetViewPanorama.getPanoramaCamera().tilt)
        .bearing(streetViewPanorama.getPanoramaCamera().bearing - 60)
        .build();
streetViewPanorama.animateTo(camera, duration);

      

تُظهر الصورة التالية النتيجة عند جدولة الصورة المتحركة أعلاه لتشغيلها كل 2000 ملّي ثانية، باستخدام Handler.postDelayed():

عرض توضيحي لميزة بانوراما في &quot;التجوّل الافتراضي&quot;