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

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

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

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

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

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

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

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

عيّنات Kotlin:

عيّنات Java:

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

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

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

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

البدء

إعداد مشروع

اتّبِع دليل البدء لإعداد مشروع حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android.

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

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

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

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

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

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

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

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

باختصار:

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

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

إضافة جزء

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

Kotlin

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

Java

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

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

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

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

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

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

Kotlin

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

Java

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

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

Kotlin

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

Java

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

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

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

Kotlin

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

Java

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

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

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

StreetViewPanoramaView

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

تخصيص الميزة التي يتحكّم فيها المستخدم

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

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

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

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

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

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)

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

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

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

Kotlin

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

Java

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

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

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

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

Kotlin

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

Java

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

Kotlin

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

Java

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

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

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

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

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

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

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)

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

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

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