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