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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختَر النظام الأساسي: Android iOS JavaScript

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

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

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

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

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

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

نماذج جافا:

نماذج Kotlin:

نظرة عامة على التجوّل الافتراضي في حزمة تطوير البرامج (SDK) للخرائط لنظام التشغيل Android

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

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

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

البدء

اتّبع دليل البدء لإعداد حزمة تطوير برامج (SDK) للخرائط لنظام التشغيل Android. ثم أضِف صورة بانورامية للتجوّل الافتراضي، كما هو موضح أدناه.

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

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

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

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

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

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

باختصار:

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

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

إضافة جزء

يمكنك إضافة عنصر <fragment> إلى ملف التنسيق's لتحديد كائن جزء.. في هذا العنصر، اضبط السمة 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، لأن هذه الطريقة هي أسهل طريقة لإضافة"التجوّل الافتراضي"إلى تطبيقك. تتمثل الخطوة الأولى في تنفيذ واجهة معاودة الاتصال:

Java


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

      

Kotlin


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

      

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

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

      

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

      

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

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

Java


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

      

Kotlin


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

      

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

Java


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

      

Kotlin


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

      

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

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

Java


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

      

Kotlin


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

      

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

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

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

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

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

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

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

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

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

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

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

      

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)

      

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

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

Java


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

      

Kotlin


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

      

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

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

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

Java


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

      

Kotlin


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

      

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

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

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

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

Java


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

      

Kotlin


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

      

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

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

      

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

      

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

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

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

      

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)

      

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

إصدار تجريبي من الصور البانورامية في ميزة &quot;التجوّل الافتراضي&quot;