نمای خیابان

نمای خیابان گوگل نماهای پانوراما 360 درجه را از جاده های تعیین شده در سراسر منطقه تحت پوشش خود ارائه می دهد.

این ویدئو نشان می‌دهد که چگونه می‌توانید از سرویس نمای خیابان استفاده کنید تا به کاربران خود تجربه‌ای واقعی از یک آدرس روی نقشه ارائه دهید، و زمینه‌ای معنادار درباره مقصد یا هر مکانی که به آن علاقه‌مند هستند را برای آنها فراهم کنید.

پوشش موجود از طریق Google Maps Android API v2 مانند برنامه Google Maps در دستگاه Android شما است. می‌توانید درباره نمای خیابان بیشتر بخوانید و مناطق پشتیبانی شده را در نقشه تعاملی در درباره نمای خیابان مشاهده کنید.

کلاس StreetViewPanorama پانورامای نمای خیابان را در برنامه شما مدل می کند. در UI شما، یک پانوراما با یک شئ StreetViewPanoramaFragment یا StreetViewPanoramaView نشان داده می شود.

نمونه کد

مخزن ApiDemos در GitHub شامل نمونه هایی است که استفاده از نمای خیابان را نشان می دهد.

نمونه های کاتلین:

• StreetViewPanoramaBasicDemoActivity : اصول اولیه استفاده از نمای خیابان
• StreetViewPanoramaEventsDemoActivity : گوش دادن به رویدادها
• StreetViewPanoramaNavigationDemoActivity : کنترل پانورامای نمای خیابان به صورت برنامه ای
• StreetViewPanoramaOptionsDemoActivity : تغییر رابط کاربری و گزینه های اشاره
• StreetViewPanoramaViewDemoActivity : استفاده از StreetViewPanoramaView (به جای یک قطعه)
• SplitStreetViewPanoramaAndMapDemoActivity : استفاده از فعالیتی که نمای خیابان و نقشه را نمایش می دهد

نمونه های جاوا:

• StreetViewPanoramaBasicDemoActivity : اصول اولیه استفاده از نمای خیابان
• StreetViewPanoramaEventsDemoActivity : گوش دادن به رویدادها
• StreetViewPanoramaNavigationDemoActivity : کنترل پانورامای نمای خیابان به صورت برنامه ای
• StreetViewPanoramaOptionsDemoActivity : تغییر رابط کاربری و گزینه های اشاره
• StreetViewPanoramaViewDemoActivity : استفاده از StreetViewPanoramaView (به جای یک قطعه)
• SplitStreetViewPanoramaAndMapDemoActivity : ایجاد فعالیتی که نمای خیابان و نقشه را نمایش می دهد

نمای کلی از نمای خیابان در Maps SDK برای Android

Maps SDK برای Android یک سرویس نمای خیابان برای به دست آوردن و دستکاری تصاویر مورد استفاده در نمای خیابان Google ارائه می دهد. تصاویر به صورت پانوراما برگردانده می شوند.

هر پانورامای نمای خیابان یک تصویر یا مجموعه ای از تصاویر است که نمای کامل 360 درجه را از یک مکان ارائه می دهد. تصاویر منطبق بر طرح ریزی مستطیل شکل (Plate Carrée) هستند که شامل 360 درجه نمای افقی (یک دور کامل) و 180 درجه نمای عمودی (از مستقیم به بالا به پایین) است. پانورامای 360 درجه ای که به دست می آید، تصویری را بر روی یک کره تعریف می کند که تصویر به سطح دو بعدی آن کره پیچیده شده است.

StreetViewPanorama بیننده ای را ارائه می دهد که پانوراما را به صورت یک کره با دوربینی در مرکز آن ارائه می دهد. می‌توانید StreetViewPanoramaCamera را برای کنترل بزرگ‌نمایی و جهت (شیب و یاتاقان) دوربین دستکاری کنید.

شروع کنید

یک پروژه راه اندازی کنید

راهنمای شروع را برای راه‌اندازی Maps SDK برای پروژه Android دنبال کنید.

قبل از افزودن پانوراما در دسترس بودن نمای خیابان را بررسی کنید

کتابخانه سرویس گیرنده SDK خدمات Google Play شامل چند نمونه نمای خیابان است که می توانید آنها را به پروژه خود وارد کرده و به عنوان پایه ای برای توسعه استفاده کنید. برای راهنمای واردات نمونه به مقدمه مراجعه کنید.

Maps SDK for Android Utility Library یک کتابخانه منبع باز از کلاس ها است که برای طیف وسیعی از برنامه ها مفید است. ابزار فراداده Street View در مخزن GitHub گنجانده شده است. این ابزار بررسی می‌کند که آیا یک مکان توسط نمای خیابان پشتیبانی می‌شود یا خیر. می‌توانید هنگام افزودن پانورامای نمای خیابان به برنامه Android با تماس با این ابزار فراداده و تنها در صورتی که پاسخ OK باشد، پانورامای نمای خیابان را اضافه کنید، از بروز خطا جلوگیری کنید.

از API استفاده کنید

برای افزودن پانورامای نمای خیابان به یک قطعه Android، دستورالعمل‌های زیر را دنبال کنید. این ساده ترین راه برای افزودن نمای خیابان به برنامه شما است. سپس درباره قطعات، نماها و سفارشی کردن پانوراما بیشتر بخوانید.

یک پانورامای نمای خیابان اضافه کنید

برای افزودن پانورامای نمای خیابان مانند این مراحل زیر را دنبال کنید:

به طور خلاصه:

1. یک شی Fragment به Activity اضافه کنید که پانورامای نمای خیابان را مدیریت می کند. ساده ترین راه برای انجام این کار اضافه کردن یک عنصر <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 استفاده می کند، زیرا این ساده ترین راه برای افزودن نمای خیابان به برنامه شما است. اولین قدم پیاده سازی واسط callback است:

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

      

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

      

در روش onCreate() Activity ، فایل طرح بندی را به عنوان نمای محتوا تنظیم کنید. برای مثال، اگر فایل layout نام main.xml دارد، از این کد استفاده کنید:

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

      

@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 به طور خودکار به پروژه اندروید اضافه می شود.

سپس از getStreetViewPanoramaAsync() برای تنظیم تماس برگشتی روی قطعه استفاده کنید.

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

      

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

      

برای بازیابی یک نمونه غیر تهی از StreetViewPanorama که آماده استفاده است، از روش پاسخ به تماس onStreetViewPanoramaReady(StreetViewPanorama) استفاده کنید.

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

      

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

      

بیشتر در مورد پیکربندی حالت اولیه

بر خلاف نقشه، پیکربندی وضعیت اولیه نمای خیابان از طریق XML امکان پذیر نیست. با این حال، می‌توانید پانوراما را به صورت برنامه‌نویسی با عبور از یک شی StreetViewPanoramaOptions که حاوی گزینه‌های مشخص‌شده شما است، پیکربندی کنید.

• اگر از StreetViewPanoramaFragment استفاده می‌کنید، از روش کارخانه ثابت StreetViewPanoramaFragment.newInstance(StreetViewPanoramaOptions options) برای ساخت قطعه و ارسال گزینه‌های پیکربندی سفارشی خود استفاده کنید.
• اگر از StreetViewPanoramaView استفاده می‌کنید، از سازنده StreetViewPanoramaView(Context, StreetViewPanoramaOptions) استفاده کنید و گزینه‌های پیکربندی سفارشی خود را ارسال کنید.

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

      

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 فعال یا غیرفعال کنید. وقتی ژست غیرفعال است، تغییرات برنامه‌ای همچنان امکان‌پذیر است.

مکان پانوراما را تنظیم کنید

برای تنظیم موقعیت پانورامای نمای خیابان، با عبور از LatLng با StreetViewPanorama.setPosition() تماس بگیرید. همچنین می توانید radius و source به عنوان پارامترهای اختیاری ارسال کنید.

اگر می‌خواهید ناحیه‌ای را که نمای خیابان در آن به دنبال پانورامای منطبق می‌گردد، گسترده یا باریک کنید، شعاع مفید است. شعاع 0 به این معنی است که پانوراما باید دقیقاً به LatLng مشخص شده مرتبط باشد. شعاع پیش فرض 50 متر است. اگر بیش از یک پانوراما در ناحیه تطبیق وجود داشته باشد، API بهترین تطابق را برمی‌گرداند.

اگر می‌خواهید نمای خیابان را محدود کنید تا فقط به دنبال تصاویر پانوراما در فضای باز بگردید، یک منبع مفید است. به‌طور پیش‌فرض، پانورامای نمای خیابان می‌تواند در داخل مکان‌هایی مانند موزه‌ها، ساختمان‌های عمومی، کافه‌ها و مشاغل باشد. توجه داشته باشید که پانورامای فضای باز ممکن است برای مکان مشخص شده وجود نداشته باشد.

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)

      

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 است که هر کدام شامل شناسه پانورامای متصل به پانورامای فعلی است.

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

      

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

      

بزرگنمایی و کوچکنمایی

می‌توانید با تنظیم StreetViewPanoramaCamera.zoom سطح بزرگ‌نمایی را به صورت برنامه‌نویسی تغییر دهید. با تنظیم زوم روی 1.0 تصویر را ضریب 2 بزرگنمایی می کنیم.

قطعه زیر از StreetViewPanoramaCamera.Builder() برای ساخت یک دوربین جدید با شیب و یاتاقان دوربین موجود استفاده می کند، در حالی که بزرگنمایی را پنجاه درصد افزایش می دهد.

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

      

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 درجه به سمت چپ تغییر می دهد.

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

      

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

      

قطعه زیر دوربین را 30 درجه به سمت بالا کج می کند.

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

      

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 تنظیم کنید.

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

      

// 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() نتیجه را نشان می دهد:

نمای خیابان گوگل نماهای پانوراما 360 درجه را از جاده های تعیین شده در سراسر منطقه تحت پوشش خود ارائه می دهد.

این ویدئو نشان می‌دهد که چگونه می‌توانید از سرویس نمای خیابان استفاده کنید تا به کاربران خود تجربه‌ای واقعی از یک آدرس روی نقشه ارائه دهید، و زمینه‌ای معنادار درباره مقصد یا هر مکانی که به آن علاقه‌مند هستند را برای آنها فراهم کنید.

پوشش موجود از طریق Google Maps Android API v2 مانند برنامه Google Maps در دستگاه Android شما است. می‌توانید درباره نمای خیابان بیشتر بخوانید و مناطق پشتیبانی شده را در نقشه تعاملی در درباره نمای خیابان مشاهده کنید.

کلاس StreetViewPanorama پانورامای نمای خیابان را در برنامه شما مدل می کند. در UI شما، یک پانوراما با یک شئ StreetViewPanoramaFragment یا StreetViewPanoramaView نشان داده می شود.

نمونه کد

مخزن ApiDemos در GitHub شامل نمونه هایی است که استفاده از نمای خیابان را نشان می دهد.

نمونه های کاتلین:

• StreetViewPanoramaBasicDemoActivity : اصول اولیه استفاده از نمای خیابان
• StreetViewPanoramaEventsDemoActivity : گوش دادن به رویدادها
• StreetViewPanoramaNavigationDemoActivity : کنترل پانورامای نمای خیابان به صورت برنامه ای
• StreetViewPanoramaOptionsDemoActivity : تغییر رابط کاربری و گزینه های اشاره
• StreetViewPanoramaViewDemoActivity : استفاده از StreetViewPanoramaView (به جای یک قطعه)
• SplitStreetViewPanoramaAndMapDemoActivity : استفاده از فعالیتی که نمای خیابان و نقشه را نمایش می دهد

نمونه های جاوا:

• StreetViewPanoramaBasicDemoActivity : اصول اولیه استفاده از نمای خیابان
• StreetViewPanoramaEventsDemoActivity : گوش دادن به رویدادها
• StreetViewPanoramaNavigationDemoActivity : کنترل پانورامای نمای خیابان به صورت برنامه ای
• StreetViewPanoramaOptionsDemoActivity : تغییر رابط کاربری و گزینه های اشاره
• StreetViewPanoramaViewDemoActivity : استفاده از StreetViewPanoramaView (به جای یک قطعه)
• SplitStreetViewPanoramaAndMapDemoActivity : ایجاد فعالیتی که نمای خیابان و نقشه را نمایش می دهد

نمای کلی از نمای خیابان در Maps SDK برای Android

Maps SDK برای Android یک سرویس نمای خیابان برای به دست آوردن و دستکاری تصاویر مورد استفاده در نمای خیابان Google ارائه می دهد. تصاویر به صورت پانوراما برگردانده می شوند.

هر پانورامای نمای خیابان یک تصویر یا مجموعه ای از تصاویر است که نمای کامل 360 درجه را از یک مکان ارائه می دهد. تصاویر منطبق بر طرح ریزی مستطیل شکل (Plate Carrée) هستند که شامل 360 درجه نمای افقی (یک دور کامل) و 180 درجه نمای عمودی (از مستقیم به بالا به پایین) است. پانورامای 360 درجه ای که به دست می آید، تصویری را بر روی یک کره تعریف می کند که تصویر به سطح دو بعدی آن کره پیچیده شده است.

StreetViewPanorama بیننده ای را ارائه می دهد که پانوراما را به صورت یک کره با دوربینی در مرکز آن ارائه می دهد. می‌توانید StreetViewPanoramaCamera را برای کنترل بزرگ‌نمایی و جهت (شیب و یاتاقان) دوربین دستکاری کنید.

شروع کنید

یک پروژه راه اندازی کنید

راهنمای شروع را برای راه‌اندازی Maps SDK برای پروژه Android دنبال کنید.

قبل از افزودن پانوراما در دسترس بودن نمای خیابان را بررسی کنید

کتابخانه سرویس گیرنده SDK خدمات Google Play شامل چند نمونه نمای خیابان است که می توانید آنها را به پروژه خود وارد کرده و به عنوان پایه ای برای توسعه استفاده کنید. برای راهنمای واردات نمونه به مقدمه مراجعه کنید.

Maps SDK for Android Utility Library یک کتابخانه منبع باز از کلاس ها است که برای طیف وسیعی از برنامه ها مفید است. ابزار فراداده Street View در مخزن GitHub گنجانده شده است. این ابزار بررسی می‌کند که آیا یک مکان توسط نمای خیابان پشتیبانی می‌شود یا خیر. می‌توانید هنگام افزودن پانورامای نمای خیابان به برنامه Android با تماس با این ابزار فراداده و تنها در صورتی که پاسخ OK باشد، پانورامای نمای خیابان را اضافه کنید، از بروز خطا جلوگیری کنید.

از API استفاده کنید

برای افزودن پانورامای نمای خیابان به یک قطعه Android، دستورالعمل‌های زیر را دنبال کنید. این ساده ترین راه برای افزودن نمای خیابان به برنامه شما است. سپس درباره قطعات، نماها و سفارشی کردن پانوراما بیشتر بخوانید.

یک پانورامای نمای خیابان اضافه کنید

برای افزودن پانورامای نمای خیابان مانند این مراحل زیر را دنبال کنید:

به طور خلاصه:

1. یک شی Fragment به Activity اضافه کنید که پانورامای نمای خیابان را مدیریت می کند. ساده ترین راه برای انجام این کار اضافه کردن یک عنصر <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 استفاده می کند، زیرا این ساده ترین راه برای افزودن نمای خیابان به برنامه شما است. اولین قدم پیاده سازی واسط callback است:

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

      

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

      

در روش onCreate() Activity ، فایل طرح بندی را به عنوان نمای محتوا تنظیم کنید. برای مثال، اگر فایل layout نام main.xml دارد، از این کد استفاده کنید:

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

      

@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 به طور خودکار به پروژه اندروید اضافه می شود.

سپس از getStreetViewPanoramaAsync() برای تنظیم تماس برگشتی روی قطعه استفاده کنید.

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

      

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

      

برای بازیابی یک نمونه غیر تهی از StreetViewPanorama که آماده استفاده است، از روش پاسخ به تماس onStreetViewPanoramaReady(StreetViewPanorama) استفاده کنید.

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

      

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

      

بیشتر در مورد پیکربندی حالت اولیه

بر خلاف نقشه، پیکربندی وضعیت اولیه نمای خیابان از طریق XML امکان پذیر نیست. با این حال، می‌توانید پانوراما را به صورت برنامه‌نویسی با عبور از یک شی StreetViewPanoramaOptions که حاوی گزینه‌های مشخص‌شده شما است، پیکربندی کنید.

• اگر از StreetViewPanoramaFragment استفاده می‌کنید، از روش کارخانه ثابت StreetViewPanoramaFragment.newInstance(StreetViewPanoramaOptions options) برای ساخت قطعه و ارسال گزینه‌های پیکربندی سفارشی خود استفاده کنید.
• اگر از StreetViewPanoramaView استفاده می‌کنید، از سازنده StreetViewPanoramaView(Context, StreetViewPanoramaOptions) استفاده کنید و گزینه‌های پیکربندی سفارشی خود را ارسال کنید.

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

      

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 فعال یا غیرفعال کنید. وقتی ژست غیرفعال است، تغییرات برنامه‌ای همچنان امکان‌پذیر است.

مکان پانوراما را تنظیم کنید

برای تنظیم موقعیت پانورامای نمای خیابان، با عبور از LatLng با StreetViewPanorama.setPosition() تماس بگیرید. همچنین می توانید radius و source به عنوان پارامترهای اختیاری ارسال کنید.

اگر می‌خواهید ناحیه‌ای را که نمای خیابان در آن به دنبال پانورامای منطبق می‌گردد، گسترده یا باریک کنید، شعاع مفید است. شعاع 0 به این معنی است که پانوراما باید دقیقاً به LatLng مشخص شده مرتبط باشد. شعاع پیش فرض 50 متر است. اگر بیش از یک پانوراما در ناحیه تطبیق وجود داشته باشد، API بهترین تطابق را برمی‌گرداند.

اگر می‌خواهید نمای خیابان را محدود کنید تا فقط به دنبال تصاویر پانوراما در فضای باز بگردید، یک منبع مفید است. به‌طور پیش‌فرض، پانورامای نمای خیابان می‌تواند در داخل مکان‌هایی مانند موزه‌ها، ساختمان‌های عمومی، کافه‌ها و مشاغل باشد. توجه داشته باشید که پانورامای فضای باز ممکن است برای مکان مشخص شده وجود نداشته باشد.

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)

      

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 است که هر کدام شامل شناسه پانورامای متصل به پانورامای فعلی است.

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

      

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

      

بزرگنمایی و کوچکنمایی

می‌توانید با تنظیم StreetViewPanoramaCamera.zoom سطح بزرگ‌نمایی را به صورت برنامه‌نویسی تغییر دهید. با تنظیم زوم روی 1.0 تصویر را ضریب 2 بزرگنمایی می کنیم.

قطعه زیر از StreetViewPanoramaCamera.Builder() برای ساخت یک دوربین جدید با شیب و یاتاقان دوربین موجود استفاده می کند، در حالی که بزرگنمایی را پنجاه درصد افزایش می دهد.

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

      

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 درجه به سمت چپ تغییر می دهد.

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

      

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

      

قطعه زیر دوربین را 30 درجه به سمت بالا کج می کند.

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

      

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 تنظیم کنید.

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

      

// 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() نتیجه را نشان می دهد: