API Карт на Wear OS

Используя Maps SDK для Android, вы можете создать носимое приложение на основе карт, которое будет работать непосредственно на устройствах Wear OS by Google. Пользователи вашего приложения могут увидеть свое местоположение на карте, просто взглянув на свое запястье. Например, они могут указать свое положение на маршруте, а затем увеличить масштаб для получения подробной информации или коснуться маркера, чтобы увидеть информационное окно, предоставляемое вашим приложением.

На этой странице описываются функции API, доступные на носимых устройствах, и они помогут вам приступить к созданию приложения.

Начало работы с Wear OS

Создание носимого приложения с помощью Maps SDK для Android принципиально не отличается от создания приложения Google Maps для любого другого устройства Android. Разница заключается в вашем дизайне для меньшего форм-фактора носимого устройства, чтобы оптимизировать удобство использования и производительность приложения.

Android Studio — рекомендуемый инструмент для разработки Wear OS, поскольку он обеспечивает настройку проекта, включение библиотеки и удобство упаковки.

Для получения общей помощи по разработке приложения для носимых устройств см. руководство по проектированию Wear OS . Чтобы получить помощь в создании своего первого приложения для носимых устройств, см. руководство по созданию приложений для носимых устройств .

Создание вашего первого картографического приложения на Wear OS

В этом кратком руководстве предполагается, что вы знакомы с Maps SDK для Android, следовали руководствам Wear OS по созданию носимого модуля в своем приложении и теперь хотите добавить карту в носимый модуль.

Добавление зависимостей для вашего модуля износа

Убедитесь, что следующие зависимости включены в файл 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 в своей деятельности, добавьте обратный вызов и задайте поведение обратного вызова для выполнения необходимого действия отклонения, как показано ниже:

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

    // ...
}

      

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) , как обычно, чтобы получить дескриптор объекта GoogleMap . Обратный вызов запускается, когда карта готова к использованию. В методе обратного вызова вы можете добавить на карту маркеры или полилинии, добавить слушателей или переместить камеру. В приведенном ниже примере добавляется маркер рядом с Сиднейским оперным театром:

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

      

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

      

Включение окружающего режима

Maps SDK для Android поддерживает окружающий режим для носимых приложений. Приложения, поддерживающие фоновый режим, иногда называются всегда в приложениях. Режим Ambient активируется, когда пользователь больше не использует приложение активно, и позволяет приложению оставаться видимым на носимом устройстве.

Maps SDK для Android обеспечивает упрощенную малоцветную визуализацию карты для использования в фоновом режиме, а стиль карты автоматически настраивается при переключении устройства из интерактивного режима в фоновый режим. Все маркеры, объекты и элементы управления пользовательского интерфейса исчезают в фоновом режиме. Это снижает энергопотребление вашего приложения и обеспечивает согласованность внешнего вида с другими окружающими приложениями, такими как циферблаты.

Выполните следующие действия, чтобы убедиться, что ваше приложение использует окружающий режим карты:

1. Обновите Android SDK, включив в него платформу Android 6.0 (API 23) или более поздней версии, которая предоставляет API-интерфейсы, позволяющие выполнять действия в фоновом режиме. Информацию о том, как обновить SDK, см. в документации Android по добавлению пакетов SDK .
2. Убедитесь, что ваш проект нацелен на Android 6.0 или более позднюю версию, задав targetSdkVersion значение 23 или выше в манифесте приложения .
3. Добавьте носимые зависимости в файл build.gradle вашего приложения. См. образец на этой странице .
4. Добавьте запись общей библиотеки для носимых устройств в манифест приложения для носимых устройств, как описано в учебном классе Android по сохранению видимости вашего приложения .
5. Добавьте разрешение WAKE_LOCK в манифесты приложений для портативных и носимых устройств, как описано в учебном классе Android по обеспечению видимости вашего приложения .
6. В методе onCreate() вашей активности вызовите метод AmbientModeSupport.attach() . Это сообщает операционной системе, что приложение всегда включено, поэтому при выключении устройства оно должно переходить в режим ожидания, а не возвращаться к циферблату.
7. Реализуйте интерфейс AmbientModeSupport.AmbientCallbackProvider в своей деятельности, чтобы она могла получать изменения состояния внешнего режима.
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 переключается на обычную визуализацию карты.

В следующем образце кода включается фоновый режим в действии:

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

      

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 по сохранению видимости вашего приложения .

Использование просмотра улиц на Wear OS

Просмотр улиц полностью поддерживается на носимых устройствах.

Чтобы разрешить пользователям выходить из приложения при просмотре панорамы Просмотра улиц, используйте интерфейс StreetViewPanorama.OnStreetViewPanoramaLongClickListener для прослушивания жеста длинного щелчка. Когда пользователь долго щелкает где-либо на изображении просмотра улиц, вы получаете событие onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation) . Вызовите DismissOverlayView.show() , чтобы отобразить кнопку выхода.

Образец кода

На GitHub доступен пример приложения, который вы можете использовать в качестве отправной точки для своего приложения. В примере показано, как настроить базовую карту Google на Wear OS.

Поддерживаемые функции в Maps API на Wear OS

В этом разделе описываются различия поддерживаемых функций карт на носимых устройствах по сравнению с карманными устройствами (телефонами и планшетами). Все функции API, не упомянутые ниже, должны работать в соответствии с документацией для полного API.

Рекомендации по разработке с помощью Maps API в Wear OS

Как обеспечить лучший пользовательский опыт в вашем приложении:

• Карта должна занимать большую часть экрана. Это необходимо для оптимизации удобства использования карты на небольшом форм-факторе носимого устройства.
• При проектировании пользовательского интерфейса вашего приложения примите во внимание тот факт, что носимое устройство имеет низкий заряд батареи. Если экран будет активен, а карта будет отображаться, это повлияет на производительность батареи.