يوفر التجوّل الافتراضي من Google إطلالات بانورامية بزاوية 360 درجة من الطرق المحددة عبر منطقة التغطية.
يوضح هذا الفيديو كيفية استخدام خدمة "التجوّل الافتراضي" لمنح المستخدمين تجربة على أرض الواقع من عنوان على الخريطة، مما يوفر لهم سياقًا هادفًا حول وجهتهم أو أي مكان يهتمون به.
التغطية المتاحة من خلال الإصدار 2 من واجهة برمجة تطبيقات خرائط Google هي نفس التغطية لتطبيق خرائط Google على جهاز Android. يمكنك الاطلاع على المزيد من المعلومات حول التجوّل الافتراضي ومشاهدة المناطق المتاحة على خريطة تفاعلية، في حول التجوّل الافتراضي.
تُعين فئة StreetViewPanorama
نموذج بانوراما التجوّل الافتراضي في تطبيقك. داخل واجهة المستخدم، يتم تمثيل الصورة البانورامية
من خلال كائن StreetViewPanoramaFragment
أو
StreetViewPanoramaView
.
عيّنات تعليمات برمجية
يتضمن مستودع ApiDemos على GitHub نماذج توضح استخدام ميزة "التجوّل الافتراضي".
نماذج جافا:
- StreetViewPanoramaBasicDemoActivity: أساسيات استخدام "التجوّل الافتراضي"
- StreetViewPanoramaEventsDemoActivity: الاستماع إلى الأحداث
- التجوّل الافتراضي لميزة التنقل عبر التجوّل الافتراضي: التحكم في الصور البانورامية لميزة "التجوّل الافتراضي"
- StreetViewPanoramaOptionsDemoActivity: تغيير واجهة المستخدم وخيارات الإيماءات
- StreetViewPanoramaViewDemoActivity: باستخدام
StreetViewPanoramaView
(بدلاً من Fragment) - SplitStreetViewPanoramaAndMapDemoActivity: إنشاء نشاط يؤدي إلى عرض التجوّل الافتراضي وخريطة
عيّنات لغة Kotlin:
- StreetViewPanoramaBasicDemoActivity: أساسيات استخدام "التجوّل الافتراضي"
- StreetViewPanoramaEventsDemoActivity: الاستماع إلى الأحداث
- التجوّل الافتراضي لميزة التنقل عبر التجوّل الافتراضي: التحكم في الصور البانورامية لميزة "التجوّل الافتراضي"
- StreetViewPanoramaOptionsDemoActivity: تغيير واجهة المستخدم وخيارات الإيماءات
- StreetViewPanoramaViewDemoActivity: باستخدام
StreetViewPanoramaView
(بدلاً من Fragment) - SplitStreetViewPanoramaAndMapDemoActivity: استخدام نشاط يؤدي إلى عرض التجوّل الافتراضي وخريطة
نظرة عامة على التجوّل الافتراضي في خرائط Google SDK لنظام التشغيل Android
توفر حزمة SDK لخرائط Google لنظام التشغيل Android خدمة التجوّل الافتراضي للحصول على الصور المستخدمة في التجوّل الافتراضي من Google ومعالجتها. يتم عرض الصور على شكل بانوراما.
كل بانوراما للتجوّل الافتراضي هي صورة، أو مجموعة من الصور، والتي تقدم عرضًا كاملاً بزاوية 360 درجة من موقع واحد. تتوافق الصور مع إسقاط العرض المتساوي المستطيلات (Plate Carrée)، والذي يتضمن عرضًا أفقيًا بزاوية 360 درجة (ملفوف بالكامل) و180 درجة من العرض الرأسي (من مستقيم إلى أسفل مباشرة). تحدد بانوراما 360 درجة الناتجة الإسقاط على كرة ملتفة إلى السطح ثنائي الأبعاد لذلك المجال.
توفر أداة StreetViewPanorama
عارضًا يعرض البانوراما على شكل بانوراما 360 درجة مع وضع كاميرا في منتصفها. يمكنك التحكّم في
StreetViewPanoramaCamera
للتحكّم في تكبير/تصغير الكاميرا واتجاهها (الإمالة واتجاهها).
البدء
اتبع دليل الخطوات الأولى لإعداد تطبيق SDK لخرائط Google لنظام التشغيل Android. ثم أضف بانوراما صورة الشارع، كما هو موضح أدناه.
تحتوي مكتبة برامج SDK لخدمات Google Play على بعض نماذج التجوّل الافتراضي التي يمكنك استيرادها إلى مشروعك واستخدامها كأساس للتطوير. راجع المقدمة للحصول على إرشادات حول استيراد العينات.
استخدام واجهة برمجة التطبيقات
اتبع الإرشادات أدناه لإضافة صورة بانورامية للتجوّل الافتراضي إلى جزء من 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
هي فئة فرعية من فئة
جزء 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()
:
