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

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

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

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

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

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

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

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

نماذج جافا:

نماذج Kotlin:

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

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

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

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

البدء

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

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

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

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

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

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

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

باختصار:

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

مزيد من المعلومات حول StreetViewبانوراماFragment

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

التجول الافتراضيبانوراما

تسمح لك StreetViewPanoramaView، وهي فئة فرعية من فئة View على Android، بوضع صورة بانورامية للالتجوّل الافتراضي في 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 و00، و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;