דף זה תורגם על ידי Cloud Translation API.

Maps API ב-Wear OS

באמצעות SDK של מפות ל-Android, ניתן ליצור אפליקציה לבישה מבוססת מפה שפועלת ישירות במכשירי Wear OS by Google. משתמשי האפליקציה יכולים לראות את המיקום שלהם במפה באמצעות מבט על פרקי כפות הידיים. הם יכולים להציב את המיקום שלהם במסלול, לדוגמה, להגדיל את התצוגה כדי לראות פרטים או להקיש על סמן כדי לראות חלון מידע שסופק על ידי האפליקציה.

דף זה מתאר את הפונקציונליות של ה-API הזמינה במכשיר Wear ונעזור לכם להתחיל בבניית האפליקציה.

תחילת העבודה עם Wear OS

במהותם, בניית אפליקציה לבישה באמצעות SDK של מפות Google ל-Android דומה לפיתוח אפליקציה של מפות Google לכל מכשיר Android אחר. ההבדל הוא בעיצוב החלק הקטן יותר של המכשיר הלביש, כדי לשפר את נוחות השימוש והביצועים של האפליקציה.

Android Studio הוא הכלי המומלץ לפיתוח ב-Wear OS, כי הוא מאפשר להגדיר פרויקטים, לכלול את הספרייה ולהשתמש באריזה.

לקבלת עזרה כללית בעיצוב אפליקציה לבישה, כדאי לעיין בהנחיות העיצוב של Wear OS. לקבלת עזרה ביצירת האפליקציה הראשונה לבישה, עיינו במדריך ליצירת אפליקציות לבישות.

יוצרים את אפליקציית המפות הראשונה ב-Wear OS

המדריך המהיר הזה מבוסס על ההנחה שאתם מכירים את ה-SDK של מפות Google ל-Android, שפעלתם לפי המדריכים של Wear OS כדי ליצור באפליקציה מודול לביש, ועכשיו אתם רוצים להוסיף מפה למודול של הגאדג'ט הלביש.

הוספת יחסי תלות למודול Wear

חשוב לוודא שיחסי התלות הבאים כלולים בקובץ build.gradle במודול 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:18.1.0'

    // This dependency is necessary for ambient mode
    implementation 'androidx.wear:wear:1.2.0'
}

מידע נוסף על יחסי התלות זמין במדריך הוספת מודול של Wear OS לפרויקט הקיים.

הטמעה של תנועת החלקה לסגירה והגדרת צבע הרקע הראשוני

מומלץ להשתמש ב-SwipeDismissFrameLayout כדי להציג את המפה במכשיר הלביש. באמצעות המחלקה SwipeDismissFrameLayout, אפשר להטמיע את תנועת ההחלקה לטשטוש שנותנת למשתמשים דרך לצאת מהאפליקציה, על ידי החלקה מהקצה השמאלי ביותר של המסך.

כדי להגדיר צבע רקע ראשוני בהתאמה אישית, משתמשים במאפיין ה-XML של map:backgroundColor להגדרת הצבע שיש להציג עד לטעינה בפועל של אריחי המפה.

מוסיפים את הרכיבים 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 בפעילות, צריך להוסיף קריאה חוזרת (callback) ולהגדיר את אופן הפעולה של הקריאה החוזרת (callback) כדי לבצע את פעולת הסגירה הנדרשת, כפי שמוצג בהמשך:

Java


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

    // ...
}

Kotlin


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

    // ...
}

הוספת מפה

השתמשו כרגיל בשיטת הקריאה החוזרת onMapReady(GoogleMap), כדי לקבל מזהה לאובייקט Google Map. הקריאה החוזרת מופעלת כשהמפה מוכנה לשימוש. בשיטת הקריאה החוזרת אפשר להוסיף סמנים או קווים מרובים למפה, להוסיף מאזינים או להזיז את המצלמה. הדוגמה הבאה מוסיפה סמן ליד בית האופרה של סידני:

Java


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

Kotlin


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

הפעלת 'מצב רגישות לסביבה'

ה-SDK של מפות Google ל-Android תומך במצב אווירה באפליקציות לבישות. אפליקציות שתומכות במצב רגישות לסביבה נקראות לפעמים אפליקציות שפועלות כל הזמן. התאורה הקולנועית מופעלת כשהמשתמשים כבר לא משתמשים באפליקציה באופן פעיל, והאפליקציה יכולה להמשיך להופיע במכשיר הלביש.

ה-SDK של מפות Google ל-Android מספק רינדור פשוט של המפה בצבע נמוך לשימוש במצב רגישות לסביבה, וסגנון המפה מתאים באופן אוטומטי כשהמכשיר עובר ממצב אינטראקטיבי למצב אווירה. כל הסמנים, האובייקטים ופקדים של ממשק המשתמש נעלמים במצב רגישות לסביבה. כך ניתן לצמצם את צריכת החשמל של האפליקציה ולהבטיח מראה ותחושה עקביים באפליקציות אחרות לסביבה, כמו תצוגות שעון.

יש לבצע את השלבים הבאים כדי לוודא שהאפליקציה משתמשת במצב האווירה של המפה:

צריך לעדכן את Android SDK כך שתכלול את הפלטפורמה ל-Android מגרסה 6.0 (API 23) ואילך, שמספקת את ממשקי ה-API שמאפשרים לפעילויות לעבור למצב רגישות לסביבה. למידע על עדכון ה-SDK, תוכלו לקרוא את מאמרי העזרה של Android על הוספת חבילות SDK.
כדי לוודא שהפרויקט שלכם מטרגט את Android 6.0 ואילך, יש להגדיר את targetSdkVersion לערך 23 ואילך במניפסט האפליקציה.
צריך להוסיף את יחסי התלות של הגאדג'טים הלבישים לקובץ build.gradle של האפליקציה. תוכלו לעיין בדוגמה בדף הזה.
יש להוסיף את הערך של הספרייה המשותפת הלבישה לקובץ המניפסט של האפליקציה הלביש, כפי שמתואר בשיעור ההדרכה של Android לגבי שמירה על האפליקציה גלויה.
מוסיפים את ההרשאה WAKE_LOCK למניפסטים של אפליקציות לבישים או ידניים, כפי שמתואר בשיעור ההדרכה של Android לגבי שמירה על האפליקציה גלויה.
בשיטה onCreate() של הפעילות, קוראים ל-method AmbientModeSupport.attach(). כך מערכת ההפעלה תמיד פועלת ומיידעת את מערכת ההפעלה שהאפליקציה פועלת כל הזמן, כך שכשהמכשיר נכבה הוא צריך לעבור למצב רגישות לסביבה במקום לחזור לתצוגת השעון.
צריך להטמיע את הממשק AmbientModeSupport.AmbientCallbackProvider בפעילות, כדי שהוא יוכל לקבל שינויים במצב רגישות לסביבה.
יש להגדיר את המפה כך שתתמוך במצב רגישות לסביבה. תוכלו לעשות זאת על ידי הגדרת המאפיין map:ambientEnabled="true" בקובץ פריסת ה-XML של הפעילות, או באופן פרוגרמטי על ידי הגדרת GoogleMapOptions.ambientEnabled(true). ההגדרה הזו מזינה את ה-API לטעון מראש את אריחי המפה הנחוצים לשימוש במצב רגישות לסביבה.
כשהפעילות עוברת למצב רגישות לסביבה, המערכת מפעילה את השיטה onEnterAmbient() ב-AmbientCallback שמספקים. אפשר לבטל את השירות onEnterAmbient() ולהתקשר ל-SupportMapFragment.onEnterAmbient(ambientDetails) או ל-MapView.onEnterAmbient(ambientDetails). ה-API יוחלף ברינדור לא אינטראקטיבי ובצבע נמוך של המפה.
באופן דומה, ב-onExitAmbient() אפשר להתקשר אל SupportMapFragment.onExitAmbient() או MapView.onExitAmbient(). ממשק ה-API עובר לעיבוד הרגיל של המפה.

דוגמת הקוד הבאה מפעילה מצב רגישות לסביבה בפעילות:

Java


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

Kotlin


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

אפשר לעדכן את המסך בזמן שהאפליקציה במצב רגישות לסביבה. למידע נוסף על עדכון תוכן ועל 'מצב אווירה' באופן כללי, קראו את שיעור האימון של Android בנושא שמירת האפליקציה גלויה.

שימוש ב-Street View ב-Wear OS

יש תמיכה מלאה ב-Street View במכשירים לבישים.

כדי לאפשר למשתמשים לצאת מהאפליקציה כשהם צופים בפנורמה ב-Street View, מומלץ להשתמש בממשק StreetViewPanorama.OnStreetViewPanoramaLongClickListener כדי להאזין לתנועה של לחיצה ארוכה. כשמשתמש לוחץ לחיצה ארוכה על תמונה של Street View, מתקבל אירוע onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation). צריך להתקשר אל DismissOverlayView.show() כדי להציג לחצן יציאה.

קוד לדוגמה

ב-GitHub יש אפליקציה לדוגמה, ואפשר להשתמש בה כנקודת התחלה לאפליקציה. בדוגמה תוכלו לראות איך מגדירים מפה בסיסית של מפות Google ב-Wear OS.

תכונות נתמכות ב-API של מפות Google ב-Wear OS

בקטע הזה מתוארים ההבדלים בפונקציונליות הנתמכת של מפות במכשירים לבישים בהשוואה למכשירים ניידים (טלפונים וטאבלטים). כל תכונות ה-API שאינן מפורטות בהמשך אמורות לפעול כפי שהן מופיעות בממשק ה-API המלא.

פונקציונליות
מצב אינטראקטיבי באופן מלא ומצב בסיסי	אפשר להשתמש ב-SDK של מפות Google ל-Android במצב אינטראקטיבי מלא או במצב בסיסי. כדאי להשתמש במצב בסיסי אם רוצים לשפר את הביצועים במכשיר הלביש והאפליקציה לא צריכה לתמוך באינטראקציות כמו תנועות, או בהזזה או בשינוי מרחק התצוגה של המפה. במצב בסיסי, הכוונה להפעיל את אפליקציית מפות Google לנייד כאשר המשתמש מקיש על המפה מושבתת ולא ניתן להפעיל אותה במכשיר לביש. לרשימה המלאה של ההבדלים בין מצב בסיסי למצב אינטראקטיבי מלא, תוכלו לעיין במסמכי התיעוד בנושא מצב בסיסי.
סרגל הכלים של המפה	סרגל הכלים של המפה מושבת ולא ניתן להפעיל אותו במכשיר לביש.
פקדים בממשק המשתמש	פקדי ממשק המשתמש מושבתים כברירת מחדל במכשירים לבישים. הנתונים האלה כוללים את הזום, המצפן ופקדי המיקום שלי. אפשר להפעיל אותם כרגיל באמצעות המחלקה `UiSettings`.
תנועות	תנועות במגע יחיד פועלות כמצופה. לדוגמה, אפשר לגעת ולגרור כדי להזיז את המפה, להקיש הקשה כפולה כדי להתקרב או להקיש בשתי אצבעות כדי להתרחק. התמיכה בתנועות עם כמה נקודות מגע משתנה בהתאם למכשיר של המשתמש. למשל, תנועות עם כמה נקודות מגע כוללות דחיפה של שתי אצבעות כדי להטות את המפה, תנועת צביטה כדי לשנות את מרחק התצוגה וסיבוב עם שתי אצבעות.
מפות ובניינים בתוך מבנים	מפות פנים מושבתות כברירת מחדל במכשיר לביש. כדי להפעיל אותם, אפשר להתקשר אל `GoogleMap.setIndoorEnabled(true)`. אם מפות פנים מופעלות, במפה תוצג מפלס ברירת המחדל של הקומה. אלמנט ממשק המשתמש של בוחר הרמה לא נתמך במכשירים לבישים.
שכבות-על של משבצות	שכבות-על של משבצות לא נתמכות במכשירים לבישים.

שיטות מומלצות לפיתוח עם Maps API ב-Wear OS

איך לספק את חוויית המשתמש הטובה ביותר באפליקציה:

המפה צריכה לתפוס חלק גדול מהמסך. הפרטים האלה נחוצים כדי לשפר את נוחות השימוש של המפה בהתאם לגורם הצורה הקטן של המכשיר לביש.
כשאתם מתכננים את חוויית המשתמש באפליקציה, יש להביא בחשבון את העובדה שהסוללה של מכשיר לביש חלשה. אם המסך יישאר פעיל והמפה מוצגת, זה ישפיע על ביצועי הסוללה.