تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

عيّنات Java:

StreetViewPanorama BasicDemoActivity: أساسيات استخدام "التجوّل الافتراضي".
StreetViewPanoramaEventsDemoActivity: الاستماع إلى الأحداث
StreetViewPanoramaTrackingDemoActivity: التحكم في الصور البانورامية لميزة "التجوّل الافتراضي" آليًا
StreetViewPanoramaOptionsDemoActivity: تغيير واجهة المستخدم وخيارات الإيماءات
StreetViewPanoramaViewDemoActivity: استخدام StreetViewPanoramaView (بدلاً من جزء)
SplitStreetViewPanoramaAndMapDemoActivity: إنشاء نشاط يعرض تجوّل افتراضي وخريطة

عيّنات Kotlin:

StreetViewPanorama BasicDemoActivity: أساسيات استخدام "التجوّل الافتراضي".
StreetViewPanoramaEventsDemoActivity: الاستماع إلى الأحداث
StreetViewPanoramaTrackingDemoActivity: التحكم في الصور البانورامية لميزة "التجوّل الافتراضي" آليًا
StreetViewPanoramaOptionsDemoActivity: تغيير واجهة المستخدم وخيارات الإيماءات
StreetViewPanoramaViewDemoActivity: استخدام StreetViewPanoramaView (بدلاً من جزء)
SplitStreetViewPanoramaAndMapDemoActivity: استخدام نشاط يعرض تجوّل افتراضي وخريطة

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

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

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

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

البدء

إعداد مشروع

اتبع دليل البدء لإعداد حزمة SDK للخرائط لمشروع Android.

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

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

تُعد حزمة SDK للخرائط الخاصة بـ Android Utility Library مكتبة مفتوحة المصدر للفئات تكون مفيدة لمجموعة من التطبيقات. يتم تضمين أداة مساعدة البيانات الوصفية لميزة "التجوّل الافتراضي" في مستودع جيت هب. تتحقق هذه الأداة مما إذا كان الموقع متوافقًا مع ميزة "التجوّل الافتراضي" أم لا. يمكنك تجنُّب الأخطاء عند إضافة صورة بانوراما 360 درجة إلى أحد تطبيقات Android من خلال استدعاء أداة البيانات الوصفية هذه وإضافة صورة بانورامية للتجوّل الافتراضي فقط إذا كان الردّ OK.

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

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

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

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

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

باختصار:

أضِف كائن جزء إلى النشاط الذي سيتعامل مع بانوراما التجوّل الافتراضي. أسهل طريقة للقيام بذلك هي إضافة عنصر <fragment> إلى ملف التنسيق لـ Activity.
نفِّذ واجهة OnStreetViewPanoramaReadyCallback واستخدِم طريقة معاودة الاتصال في onStreetViewPanoramaReady(StreetViewPanorama) للتعامل مع الكائن StreetViewPanorama.
اطلب الرمز 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 يحتوي على الخيارات المحدّدة.

في حال استخدام StreetViewPanoramaFragment، استخدِم طريقة StreetViewPanoramaFragment.newInstance(StreetViewPanoramaOptions options) المصنعة الثابتة لإنشاء الجزء وتمرير خيارات الضبط المخصّصة.
إذا كنت تستخدم StreetViewPanoramaView، استخدِم الدالة الإنشائية StreetViewPanoramaView(Context, 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

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

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

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

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

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

< > إظهار/إخفاء طرق Java.

setPanningالإيماءاتsEnabled()

تحدد ما إذا كان المستخدم سيتمكن من إعادة توجيه الكاميرا من خلال السحب.

        mStreetViewPanorama.setPanningGesturesEnabled(false);

setUserالتنقلEnabled()

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

        mStreetViewPanorama.setUserNavigationEnabled(false);

setZoom للتعليمsEnabled() ،

تحدد ما إذا كان المستخدم سيتمكن من التصغير أو التكبير بإصبعين.

        mStreetViewPanorama.setZoomGesturesEnabled(false);

setStreetNamesEnabled()

تحدد ما إذا كان بإمكان المستخدم الاطّلاع على أسماء الشوارع المعروضة على الأرض.

        mStreetViewPanorama.setStreetNamesEnabled(false);

< > إظهار/إخفاء طرق Kotlin.

isPanningالإيماءاتsEnabled()

تحدد ما إذا كان المستخدم سيتمكن من إعادة توجيه الكاميرا من خلال السحب.

        streetViewPanorama.isPanningGesturesEnabled = false

isUserالتنقلEnabled

        streetViewPanorama.isUserNavigationEnabled = false

isZoomAnimationsEnabled

تحدد ما إذا كان المستخدم سيتمكن من التصغير أو التكبير بإصبعين.

        streetViewPanorama.isZoomGesturesEnabled = false

isStreetNamesEnabled

تحدد ما إذا كان بإمكان المستخدم الاطّلاع على أسماء الشوارع المعروضة على الأرض.

        streetViewPanorama.isStreetNamesEnabled = false

ضبط موقع البانوراما

لتحديد موقع الصورة البانورامية للتجوّل الافتراضي، اتصل بالرمز 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():

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