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

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

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

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

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

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

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

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

عيّنات لغة Kotlin:

نماذج Java:

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

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

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

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

البدء

إعداد مشروع

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

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

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

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

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

استخدِم طريقة callback الخاصة بالعنصر 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);
}

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

على عكس الخريطة، لا يمكن ضبط الحالة الأولية لملف panoramic في "التجوّل الافتراضي" باستخدام ملف 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، وتتيح لك وضع panorama لميزة "التجوّل الافتراضي" في جزء Android. يعمل StreetViewPanoramaFragment عنصر حاويات للبانوراما وتوفر إمكانية الوصول إلى كائن StreetViewPanorama.

StreetViewPanoramaView

StreetViewPanoramaView، وهي فئة فرعية من نظام التشغيل Android صف View، يسمح لك بوضع صورة "التجوّل الافتراضي" بانوراما في View على جهاز Android. يمثّل العنصر View منطقة مستطيلة من الشاشة، وهو عنصر أساسي لتطبيقات Android والتطبيقات المصغّرة. تمامًا مثل StreetViewPanoramaFragment، يعمل StreetViewPanoramaView كأحد الحاويات للصورة البانورامية، ويعرض الوظيفة الأساسية من خلال العنصر StreetViewPanorama. على مستخدمي هذه الفئة إعادة توجيه جميع methodsactivity life cycle (مثل 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() لإنشاء كاميرا جديدة بإمالة الكاميرا الحالية واتجاهها، مع زيادة التكبير بنسبة خمسين بالمائة.

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.
إمالة
تمت إمالة المحور "ص" للأعلى أو للأسفل. يتراوح النطاق بين -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;