افزودن نقشه سه‌بعدی به برنامه

پلاتفرم را انتخاب کنید: Android iOS JavaScript

نقشه‌های پایه سیاتل، سان‌فرانسیسکو، و پاریس

این صفحه نمونه‌ای از نحوه افزودن نقشه سه‌بعدی پایه به برنامه iOS را بااستفاده از «کیت توسعه نرم‌افزار سه‌بعدی Maps برای iOS» نشان می‌دهد. دستورالعمل‌های این صفحه فرض می‌کنند که شما قبلاً مراحل موجود در صفحه راه‌اندازی را تکمیل کرده‌اید و موارد زیر را دارید:

  • پروژه Google Cloud با کیت توسعه نرم‌افزار ۳ بعدی نقشه برای iOS فعال‌شده
  • کلید میانای برنامه‌سازی کاربردی برای کیت توسعه نرم‌افزار ۳ بعدی نقشه برای iOS
  • Xcode نسخه 16.0 یا جدیدتر با بسته کیت توسعه نرم‌افزار Maps 3D برای iOS اضافه شده است.

برای اطلاعات بیشتر درباره این پیش‌نیازها، به راه‌اندازی مراجعه کنید.

یک codelab پیشرفته‌تر را دنبال کنید.

نمونه‌های کد بیشتر را در GitHub ببینید.

بخش ۱: ایجاد کردن برنامه SwiftUI پایه

  1. برنامه جدیدی در Xcode ایجاد کنید.
  2. نام محصول خود را روی Hello3DWorld تنظیم کنید و شناسه سازمان را روی com.example تنظیم کنید. نام بسته باید com.example.Hello3DWorld باشد.
  3. میانای SwiftUI را انتخاب کنید.
  4. کتابخانه Maps 3D را به برنامه‌تان اضافه کنید. دستورالعمل‌ها را در بخش راه‌اندازی ببینید.

بخش ۲: افزودن نقشه

نقشه سه‌بعدی مینیمال از کره زمین

  1. فایل ContentView.swift را باز کن. این نقطه ورود و پیمایش اصلی برنامه شما است.

  2. SwiftUI و بسته GoogleMaps3D را وارد کنید.

  3. همه کدهای داخل اعلان بدنه را با Map(mode: .hybrid) جایگزین کنید.

    حداقل پیکربندی اولیه‌ای که باید برای مقداردهی اولیه Map ارائه دهید MapMode است:

    • .hybrid،
    • .roadmap، یا
    • .satellite

    فایل ContentView.swift شما باید شبیه به این باشد:

    import SwiftUI
import GoogleMaps3D

struct ContentView: View {
  var body: some View {
    Map(mode: .hybrid)
  }
}

#Preview {
  ContentView()
}

بخش ۳: کلید میانای API (کلید میانای برنامه‌سازی کاربردی) خود را تنظیم کنید.

  1. کلید API باید قبل‌از مقداردهی اولیه «نقشه» تنظیم شود. این کار را با تنظیم Map.apiKey در کنترل‌کننده رویداد init() از View که حاوی «نقشه» است انجام دهید.

    import SwiftUI
import GoogleMaps3D

struct ContentView: View {
  init () {
    Map.apiKey = "YOUR_API_KEY"
  }

  var body: some View {
    Map(mode: .hybrid)
  }
}

بخش ۴: استفاده از دوربین برای کنترل نمای نقشه

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

  1. فراخوانی تابع Map() را تغییر دهید تا شامل خصوصیت initialCamera شود. initialCamera را مقداردهی اولیه کنید تا نمایی از مرکز شهر منهتن نشان داده شود.

    import SwiftUI
import GoogleMaps3D

struct ContentView: View {
  init () {
    Map.apiKey = "YOUR_API_KEY"
  }
  var body: some View {
    Map(initialCamera: .init(
      center: .init(latitude: 40.748339, longitude: -73.985912, altitude: 211.1),
      heading: 52,
      tilt: 68,
      roll: 0.0,
      range: 1039,
      fieldOfView: .degrees(50)
    ), mode: .hybrid)
  }
}

کد بالا مقادیر این پارامترها را تنظیم می‌کند:

  • center: LatLngAltitude نشان‌دهنده مکان دوربین
  • heading: جهت برحسب درجه از شمال برای نشانه رفتن دوربین به‌سمت آن.
  • tilt: زاویه شیب به درجه، که ۰ مستقیماً بالای سر است و ۹۰ نگاه افقی است.
  • ‫roll: زاویه چرخش حول صفحه عمودی دوربین، به درجه.
  • range: فاصله دوربین از مکان عرض جغرافیایی و طول جغرافیایی به متر
  • ‫fieldOfView: زاویه‌ای که میدان دید دوربین را نشان می‌دهد

اگر هیچ‌کدام از این پارامترهای اضافی را ارائه نکنید، از مقدار پیش‌فرض استفاده خواهد شد.

برای اینکه نمای دوربین داده‌های سه‌بعدی بیشتری را نشان دهد، پارامترهای اولیه را طوری تنظیم کنید که نمای نزدیک‌تر و کج‌شده‌ای را نشان دهد.

بخش ۵: پیش‌نمایش و اجرای برنامه

نقشه سه‌بعدی پایه از شهر نیویورک

  1. افزودن Xcode Preview

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

    برای افزودن پیش‌نمایش، یک بلوک کد #Preview {} خارج از ساختار خود اضافه کنید.

    #Preview {
  ContentView()
}

  2. اجرای برنامه

برنامه را بسازید و اجرا کنید.

حالت‌های خطا و بارگیری نقشه

کیت توسعه نرم‌افزار Maps 3D برای iOS به‌طور خودکار بازخورد بصری داخلی را نمایش می‌دهد و درعین‌حال وضعیت Map را مدیریت می‌کند:

  • پوشش بار کردن: وقتی نمای نقشه برای اولین‌بار مقداردهی اولیه یا بار می‌شود، نشانگر پیشرفت در مرکز نمایش داده می‌شود.
  • خطای هم‌پوشانی: اگر نقشه بار نشود، خطای هم‌پوشانی نمایش داده می‌شود.

اگر سبک نقشه مبتنی بر فضای ابری را بااستفاده از style(mapID:error:) در Map اعمال کنید، می‌توانید یک بسته شدن error را برای رسیدگی به خطاهای بارگیری سبک ارسال کنید.

گوش دادن به رویدادهای ضربه زدن روی نقشه

برای گوش دادن به رویدادهای ضربه زدن روی نقشه، اصلاح‌کننده onTap(_:) را روی Map اعمال کنید. When a user taps the map, the closure receives a MapTapInfo value that provides the location (LatLngAltitude) and tapped content (MapTapInfo.Content.map or MapTapInfo.Content.place(id:)). For more information on point of interest interactions, see Interact with points of interest.

Map(mode: .hybrid)
  .onTap { tapInfo in
    print("Tapped at \(tapInfo.location), content: \(tapInfo.content)")
  }

تبریک!

باموفقیت نقشه سه‌بعدی به برنامه اضافه کردید!

سپس می‌توانید ویژگی‌های پیشرفته‌تر «کیت توسعه نرم‌افزار سه‌بعدی Maps برای iOS» را کاوش کنید، مانند پویانمایی‌های مسیر دوربین، نشانگرهای سه‌بعدی، یا چندضلعی‌ها.