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

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

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

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

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

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

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

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

عيّنات Kotlin:

عيّنات Java:

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

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

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

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

البدء

إعداد مشروع

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

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

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

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

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

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

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

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

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

باختصار:

  1. أضِف عنصر Fragment إلى Activity الذي سيتولى التعامل مع المنظر البانورامي في "التجوّل الافتراضي". وأسهل طريقة لإجراء ذلك هي إضافة عنصر <fragment> إلى ملف التنسيق الخاص بالصفحة Activity.
  2. نفِّذ واجهة OnStreetViewPanoramaReadyCallback واستخدِم طريقة callback الخاصة بـ 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);

استخدِم طريقة callback الخاصة بمثيل 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);
}

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

على عكس الخريطة، لا يمكن ضبط الحالة الأولية لملف panoramic في "التجوّل الافتراضي" باستخدام ملف 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 Fragment، وتتيح لك وضع صورة بانورامية في "التجوّل الافتراضي" في جزء Android. تعمل عناصر StreetViewPanoramaFragment كسِيّارات للصورة البانورامية، و توفّر إمكانية الوصول إلى عنصر StreetViewPanorama.

StreetViewPanoramaView

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

تخصيص الميزة التي يتحكّم فيها المستخدم

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

تحديد موقع البانوراما

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

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

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

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. يحتوي هذا العنصر على معرّف المنظر panoramic الحالي ومصفوفة من عناصر StreetViewPanoramaLink، يحتوي كل منها على معرّف منظر panoramic مرتبط بالمشهد الحالي.

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 إلى تكبير الصورة بمقدار الضِعف.

تستخدِم المقتطف التالي 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.
إمالة
إمالة المحور Y للأعلى أو للأسفل يتراوح النطاق بين -90 و0 و90، مع توجيه -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);

تعرض الصورة التالية النتيجة عند جدولة الصورة المتحركة أعلاه لبدء تنفيذها كل 2, 000 ملي ثانية باستخدام Handler.postDelayed():

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