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

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

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

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

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

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

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

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

عيّنات Kotlin:

عيّنات Java:

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

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

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

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

البدء

إعداد مشروع

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

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

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

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

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

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

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

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

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

باختصار:

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

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

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

      

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

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

      
@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() لضبط دالة معاودة الاتصال في المقتطف.

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

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

      

استخدِم أسلوب callback onStreetViewPanoramaReady(StreetViewPanorama) لاسترداد مثيل غير فارغ من StreetViewPanorama، وهو جاهز للاستخدام.

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

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

      

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

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

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

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

      

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

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

StreetViewPanoramaView

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

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

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

setPanningGesturesEnabled()
يحدِّد ما إذا كان بإمكان المستخدم إعادة توجيه الكاميرا باستخدام السحب.
        mStreetViewPanorama.setPanningGesturesEnabled(false);
setUserNavigationEnabled()
يحدِّد ما إذا كان بإمكان المستخدم الانتقال إلى صورة بانورامية مختلفة. يمكن للمستخدمين النقر مرة واحدة على روابط التنقّل أو النقر مرّتين على العرض ل الانتقال إلى صورة بانورامية جديدة.
        mStreetViewPanorama.setUserNavigationEnabled(false);
setZoomGesturesEnabled()
يحدِّد ما إذا كان بإمكان المستخدم تصغير المحتوى أو تكبيره باستخدام إصبعَين.
        mStreetViewPanorama.setZoomGesturesEnabled(false);
setStreetNamesEnabled()
يحدِّد ما إذا كان بإمكان المستخدم الاطّلاع على أسماء الشوارع المعروضة على سطح الأرض.
        mStreetViewPanorama.setStreetNamesEnabled(false);
isPanningGesturesEnabled()
يحدِّد ما إذا كان بإمكان المستخدم إعادة توجيه الكاميرا باستخدام السحب.
        streetViewPanorama.isPanningGesturesEnabled = false
isUserNavigationEnabled
تحدد ما إذا كان المستخدم سيتمكّن من الانتقال إلى صورة بانورامية مختلفة. يمكن للمستخدمين النقر مرة واحدة على روابط التنقّل أو النقر مرّتين على العرض ل الانتقال إلى صورة بانورامية جديدة.
        streetViewPanorama.isUserNavigationEnabled = false
isZoomGesturesEnabled
يحدِّد ما إذا كان بإمكان المستخدم تكبير المحتوى أو تصغيره باستخدام إصبعَين.
        streetViewPanorama.isZoomGesturesEnabled = false
isStreetNamesEnabled
يحدِّد هذا الخيار ما إذا كان بإمكان المستخدم الاطّلاع على أسماء الشوارع المعروضة على سطح الشاشة.
        streetViewPanorama.isStreetNamesEnabled = false

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

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

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

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

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)

      
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، يحتوي كل منها على رقم تعريف لمشهد بانورامي مرتبط بالمشهد الحالي.

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

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

      

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

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

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

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

      
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 درجة إلى اليسار.

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

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

      

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

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

      
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.

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

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