Maps API در Wear OS

با استفاده از Maps SDK برای Android، می‌توانید یک برنامه پوشیدنی مبتنی بر نقشه ایجاد کنید که مستقیماً در دستگاه‌های Wear OS by Google اجرا می‌شود. کاربران برنامه شما فقط با نگاه کردن به مچ دست خود می توانند موقعیت مکانی خود را روی نقشه ببینند. آنها می توانند موقعیت خود را در یک مسیر ترسیم کنند، برای مثال، سپس برای جزئیات بزرگنمایی کنند، یا روی یک نشانگر ضربه بزنند تا پنجره اطلاعات ارائه شده توسط برنامه شما را ببینند.

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

شروع به کار با Wear OS

ساختن یک برنامه پوشیدنی با Maps SDK برای اندروید اساساً شبیه ساختن یک برنامه Google Maps برای هر دستگاه اندرویدی دیگری است. تفاوت در طراحی شما برای فرم کوچکتر دستگاه پوشیدنی نهفته است تا قابلیت استفاده و عملکرد برنامه را بهینه کنید.

Android Studio ابزار پیشنهادی برای توسعه Wear OS است، زیرا راه‌اندازی پروژه، گنجاندن کتابخانه و بسته‌بندی را فراهم می‌کند.

برای راهنمایی کلی در مورد طراحی اپلیکیشن پوشیدنی، به دستورالعمل‌های طراحی Wear OS مراجعه کنید. برای راهنمایی در مورد ایجاد اولین برنامه پوشیدنی خود، به راهنمای ایجاد برنامه های پوشیدنی مراجعه کنید.

ساختن اولین برنامه نقشه خود در Wear OS

این راهنمای سریع فرض می‌کند که با Maps SDK برای Android آشنا هستید، از راهنماهای Wear OS برای ایجاد یک ماژول پوشیدنی در برنامه خود پیروی کرده‌اید، و اکنون می‌خواهید یک نقشه به ماژول پوشیدنی اضافه کنید.

افزودن وابستگی ها برای ماژول پوشیدن شما

اطمینان حاصل کنید که وابستگی های زیر در فایل build.gradle.kts ماژول Wear OS برنامه شما گنجانده شده است:

dependencies {
    // ...
    compileOnly("com.google.android.wearable:wearable:2.9.0")
    implementation("com.google.android.support:wearable:2.9.0")
    implementation("com.google.android.gms:play-services-maps:19.0.0")

    // This dependency is necessary for ambient mode
    implementation("androidx.wear:wear:1.3.0")
}

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

اجرای یک حرکت تند کشیدن برای رد کردن و تنظیم رنگ پس‌زمینه اولیه

توصیه می شود از SwipeDismissFrameLayout برای نمایش نقشه در دستگاه پوشیدنی استفاده کنید. با استفاده از کلاس SwipeDismissFrameLayout ، می‌توانید ژست Swipe-to-Dimiss را اجرا کنید که به کاربران راهی برای خروج از برنامه با کشیدن انگشت از سمت چپ‌ترین لبه صفحه نمایش می‌دهد.

برای تنظیم یک رنگ پس‌زمینه اولیه سفارشی، از ویژگی map:backgroundColor XML برای تعیین رنگی که باید نمایش داده شود تا زمانی که کاشی‌های نقشه واقعی بارگیری می‌شوند، استفاده کنید.

عناصر SwipeDismissFrameLayout و backgroundColor را به عنوان کانتینر SupportMapFragment به تعریف طرح بندی خود اضافه کنید:

  <androidx.wear.widget.SwipeDismissFrameLayout
      android:id="@+id/map_container"
      android:layout_width="match_parent"
      android:layout_height="match_parent">
    <fragment
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        map:backgroundColor="#fff0b2dd" />
  </androidx.wear.widget.SwipeDismissFrameLayout>

هنگامی که شیء SwipeDismissFrameLayout را در فعالیت خود به دست می آورید، یک فراخوان اضافه کنید و رفتار پاسخ به تماس را برای انجام عمل رد کردن لازم مطابق شکل زیر تنظیم کنید:

class MainActivity : AppCompatActivity(), OnMapReadyCallback,
                     AmbientModeSupport.AmbientCallbackProvider {


    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(MainActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        val mapFrameLayout = findViewById<SwipeDismissFrameLayout>(R.id.map_container)
        mapFrameLayout.addCallback(object : SwipeDismissFrameLayout.Callback() {
            override fun onDismissed(layout: SwipeDismissFrameLayout) {
                onBackPressed()
            }
        })

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    // ...
}

      

public class MainActivity extends AppCompatActivity implements OnMapReadyCallback,
    AmbientModeSupport.AmbientCallbackProvider {


    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(MainActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        final SwipeDismissFrameLayout mapFrameLayout = (SwipeDismissFrameLayout) findViewById(
            R.id.map_container);
        mapFrameLayout.addCallback(new SwipeDismissFrameLayout.Callback() {
            @Override
            public void onDismissed(SwipeDismissFrameLayout layout) {
                onBackPressed();
            }
        });

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    // ...
}

      

اضافه کردن نقشه

از روش پاسخ به تماس onMapReady(GoogleMap) طبق معمول استفاده کنید تا یک دسته برای شیء GoogleMap بدست آورید. زمانی که نقشه آماده استفاده باشد، تماس پاسخ داده می شود. در روش برگشت به تماس، می توانید نشانگرها یا چند خطی را به نقشه اضافه کنید، شنونده ها را اضافه کنید یا دوربین را حرکت دهید. مثال زیر یک نشانگر در نزدیکی خانه اپرای سیدنی اضافه می کند:

private val sydney = LatLng(-33.85704, 151.21522)

override fun onMapReady(googleMap: GoogleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(
        MarkerOptions().position(sydney)
            .title("Sydney Opera House")
    )

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 10f))
}

      

private static final LatLng SYDNEY = new LatLng(-33.85704, 151.21522);

@Override
public void onMapReady(@NonNull GoogleMap googleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(new MarkerOptions().position(SYDNEY)
        .title("Sydney Opera House"));

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, 10));
}

      

فعال کردن حالت محیطی

Maps SDK برای Android از حالت محیطی برای برنامه‌های پوشیدنی پشتیبانی می‌کند. گاهی اوقات برنامه هایی که از حالت محیطی پشتیبانی می کنند همیشه در برنامه ها نامیده می شوند. حالت محیطی زمانی فعال می شود که کاربر دیگر به طور فعال از برنامه استفاده نمی کند و به برنامه اجازه می دهد در دستگاه پوشیدنی قابل مشاهده باقی بماند.

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

برای اطمینان از اینکه برنامه شما از حالت محیطی نقشه استفاده می کند، مراحل زیر را انجام دهید:

1. Android SDK خود را به‌روزرسانی کنید تا شامل Android 6.0 (API 23) یا پلت‌فرم بالاتر باشد، که APIهایی را ارائه می‌دهد که به فعالیت‌ها اجازه می‌دهد به حالت محیطی بروند. برای اطلاعات در مورد نحوه به‌روزرسانی SDK، به مستندات Android در مورد افزودن بسته‌های SDK مراجعه کنید.
2. با تنظیم targetSdkVersion روی 23 یا بالاتر در مانیفست برنامه ، مطمئن شوید که پروژه شما Android 6.0 یا بالاتر را هدف قرار می دهد.
3. وابستگی های پوشیدنی را به فایل build.gradle.kts برنامه خود اضافه کنید. نمونه را در این صفحه ببینید.
4. همانطور که در کلاس آموزشی Android در مورد قابل مشاهده نگه داشتن برنامه شما توضیح داده شده است، ورودی کتابخانه اشتراکی پوشیدنی را به مانیفست برنامه پوشیدنی اضافه کنید.
5. مجوز WAKE_LOCK را همانطور که در کلاس آموزشی Android در مورد قابل مشاهده نگه داشتن برنامه خود توضیح داده شده است به مانیفست برنامه دستی و پوشیدنی اضافه کنید.
6. در متد onCreate() فعالیت خود، متد AmbientModeSupport.attach() را فراخوانی کنید. این به سیستم عامل می گوید که برنامه همیشه روشن است، به طوری که وقتی دستگاه خاموش می شود، به جای بازگشت به صفحه ساعت، باید به حالت محیطی وارد شود.
7. رابط AmbientModeSupport.AmbientCallbackProvider را در Activity خود پیاده کنید تا بتواند تغییرات حالت محیطی را دریافت کند.
8. نقشه خود را طوری تنظیم کنید که از حالت محیطی پشتیبانی کند. می‌توانید این کار را با تنظیم ویژگی map:ambientEnabled="true" در فایل طرح‌بندی XML فعالیت انجام دهید، یا با تنظیم GoogleMapOptions.ambientEnabled(true) به صورت برنامه‌نویسی این کار را انجام دهید. این تنظیم به API اطلاع می دهد که باید کاشی های نقشه لازم را برای استفاده در حالت محیطی از قبل بارگذاری کند.
9. هنگامی که فعالیت به حالت محیطی تغییر می کند، سیستم متد onEnterAmbient() را در AmbientCallback که ارائه می کنید فراخوانی می کند. onEnterAmbient() لغو کنید و SupportMapFragment.onEnterAmbient(ambientDetails) یا MapView.onEnterAmbient(ambientDetails) را فراخوانی کنید. API به یک رندر غیر تعاملی و کم رنگ از نقشه تبدیل می شود.
10. به طور مشابه، در onExitAmbient() SupportMapFragment.onExitAmbient() یا MapView.onExitAmbient() را فراخوانی کنید. API به رندر معمولی نقشه تغییر می کند.

نمونه کد زیر حالت محیطی را در فعالیت فعال می کند:

class AmbientActivity : AppCompatActivity(), AmbientModeSupport.AmbientCallbackProvider {

    private lateinit var mapFragment: SupportMapFragment

    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(AmbientActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
    }

    override fun getAmbientCallback(): AmbientModeSupport.AmbientCallback {
        return object : AmbientModeSupport.AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            override fun onEnterAmbient(ambientDetails: Bundle) {
                super.onEnterAmbient(ambientDetails)
                mapFragment.onEnterAmbient(ambientDetails)
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            override fun onExitAmbient() {
                super.onExitAmbient()
                mapFragment.onExitAmbient()
            }
        }
    }
}

      

public class AmbientActivity extends AppCompatActivity implements
    AmbientModeSupport.AmbientCallbackProvider {

    private SupportMapFragment mapFragment;

    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(AmbientActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
    }

    @Override
    public AmbientCallback getAmbientCallback() {
        return new AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            @Override
            public void onEnterAmbient(Bundle ambientDetails) {
                super.onEnterAmbient(ambientDetails);
                mapFragment.onEnterAmbient(ambientDetails);
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            @Override
            public void onExitAmbient() {
                super.onExitAmbient();
                mapFragment.onExitAmbient();
            }
        };
    }
}

      

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

استفاده از نمای خیابان در Wear OS

نمای خیابان به طور کامل در دستگاه های پوشیدنی پشتیبانی می شود.

برای اینکه به کاربران اجازه دهید هنگام مشاهده پانورامای نمای خیابان از برنامه خارج شوند، از رابط StreetViewPanorama.OnStreetViewPanoramaLongClickListener برای گوش دادن به یک حرکت کلیک طولانی استفاده کنید. هنگامی که کاربر روی تصویر نمای خیابان طولانی کلیک می کند، یک رویداد onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation) دریافت خواهید کرد. برای نمایش دکمه خروج DismissOverlayView.show() فراخوانی کنید.

کد نمونه

یک برنامه نمونه در GitHub موجود است که می توانید از آن به عنوان نقطه شروع برنامه خود استفاده کنید. این نمونه به شما نشان می‌دهد که چگونه یک Google Map اولیه را در Wear OS تنظیم کنید.

قابلیت پشتیبانی شده در Maps API در Wear OS

این بخش تفاوت‌های عملکرد پشتیبانی شده برای نقشه‌های دستگاه‌های پوشیدنی را در مقایسه با دستگاه‌های دستی (تلفن و تبلت) نشان می‌دهد. همه ویژگی‌های API که در زیر ذکر نشده‌اند، باید طبق مستندات برای API کامل کار کنند.

بهترین روش‌ها برای توسعه با Maps API در Wear OS

نحوه ارائه بهترین تجربه کاربری در برنامه خود:

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