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

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

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

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

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

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

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

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

نماذج جافا:

عيّنات لغة Kotlin:

نظرة عامة على التجوّل الافتراضي في خرائط Google SDK لنظام التشغيل Android

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

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

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

البدء

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

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

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

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

لغة 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 هي فئة فرعية من فئة جزء 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، سيتم تكبير الصورة بمقدار 2.

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

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

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