Объекты на карте

Карты представлены в API классами GoogleMap и MapFragment.

Примеры кода

В репозитории ApiDemos на сайте GitHub доступны примеры, которые демонстрируют использование объектов GoogleMap и SupportMapFragment:

BasicMapDemoActivity: отображение базовой карты с маркером.
basic_demo.xml: добавление SupportMapFragment в определение макета.

Добавление карты в приложение для Android

Ниже перечислены основные шаги, которые необходимо выполнить для добавления карты.

Это нужно сделать всего один раз. Выполните инструкции, приведенные в руководстве по настройке проекта, чтобы задействовать API, получить ключ и добавить необходимые атрибуты в манифест своего приложения для Android.
Добавьте объект Fragment в компонент Activity, который отвечает за обработку карты. Самый простой способ сделать это – добавить элемент <fragment> в файл макета для объекта Activity.
Реализуйте интерфейс OnMapReadyCallback и используйте метод обратного вызова onMapReady(GoogleMap), чтобы получить дескриптор объекта GoogleMap. Объект GoogleMap является внутренним представлением самой карты. Чтобы установить параметры представления для карты, следует изменить ее объект GoogleMap.
Вызовите метод getMapAsync(), чтобы зарегистрировать обратный вызов.

Далее приведены подробные описания каждого шага.

Добавление фрагмента

Добавьте элемент <fragment> в файл шаблона для объекта activity, чтобы определить объект Fragment. Задайте для атрибута android:name значение "com.google.android.gms.maps.MapFragment". Объект MapFragment будет автоматически прикреплен к объекту activity.

Приведенный ниже файл макета содержит элемент <fragment>:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.gms.maps.MapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Вы также можете добавить MapFragment в объект Activity в коде. Для этого создайте новый экземпляр MapFragment и вызовите метод FragmentTransaction.add(), чтобы добавить Fragment к текущему объекту Activity.

 mMapFragment = MapFragment.newInstance();
 FragmentTransaction fragmentTransaction =
         getFragmentManager().beginTransaction();
 fragmentTransaction.add(R.id.my_container, mMapFragment);
 fragmentTransaction.commit();

Добавление кода карты

Для работы с картой внутри приложения вам необходимо будет реализовать интерфейс OnMapReadyCallback и установить экземпляр обратного вызова для объекта MapFragment или MapView. В этом руководстве используется MapFragment, поскольку это самый простой способ добавить карту в приложение. Сначала нужно реализовать интерфейс обратного вызова:

public class MainActivity extends FragmentActivity
    implements OnMapReadyCallback {
...
}

В методе onCreate() своего объекта Activity установите файл макета как представление контента. Например, если файл макета называется main.xml, используйте следующий код:

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    ...
}

Получите дескриптор фрагмента, вызвав метод FragmentManager.findFragmentById() и передав ему идентификатор ресурса своего элемента <fragment>. Обратите внимание на то, что идентификатор ресурса R.id.map добавляется в проект Android автоматически при создании файла макета.

Затем используйте метод getMapAsync(), чтобы установить обратный вызов для фрагмента.

MapFragment mapFragment = (MapFragment) getFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

Используйте метод обратного вызова onMapReady(GoogleMap), чтобы получить дескриптор объекта GoogleMap. Обратный вызов выполняется тогда, когда карта готова к использованию. В этом случае она предоставляет экземпляр GoogleMap, отличный от null. Объект GoogleMap можно использовать, например, чтобы устанавливать параметры просмотра карты или добавлять маркеры.

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}

Объект карты

Maps SDK for Android позволяет показывать карту Google в приложении для Android. Она выглядит и работает практически так же, как в приложении "Google Карты" для мобильных устройств. Между приложением "Google Карты" для мобильных устройств и картами, которые отображаются через Maps SDK for Android, есть два важных отличия:

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

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

При работе с объектом карты ключевое значение имеет класс GoogleMap. GoogleMap формирует объект карты в приложении. В пользовательском интерфейсе карта может быть представлена объектом MapFragment или MapView.

В GoogleMap автоматически обрабатываются следующие операции:

подключение к Google Картам;
загрузка фрагментов карты;
отображение фрагментов на экране устройства;
отображение элементов управления (например, панорамирования и масштабирования);
изменение вида карты в ответ на жесты панорамирования и масштабирования.

В дополнение к автоматизированным операциям поведение карты можно контролировать с помощью объектов и методов API. Например, GoogleMap использует методы обратного вызова, которые реагируют на нажатия клавиш и жесты касаний на карте. Можно также добавить на карту значки маркеров и наложить изображения, используя объекты, предоставленные классу GoogleMap.

MapFragment

MapFragment – это подкласс класса Fragment в Android. Он служит для размещения карты в пределах фрагмента. Объекты MapFragment выступают в роли контейнеров карты и обеспечивают доступ к объекту GoogleMap.

В отличие от View, объект Fragment представляет поведение или часть пользовательского интерфейса в объекте activity. Вы можете объединить несколько фрагментов в единый объект activity для создания многопанельного интерфейса и использовать один и тот же фрагмент в нескольких объектах activity. Подробнее…

MapView

MapView – это подкласс класса View в Android. Он служит для размещения карты в пределах объекта View. Объект View – это прямоугольный участок экрана, основной структурный элемент многих приложений и виджетов для Android. Как и MapFragment, объект MapView служит контейнером для карты и обеспечивает работу необходимых функций при помощи объекта GoogleMap.

При использовании API в полностью интерактивном режиме пользователи класса MapView должны передавать все методы жизненного цикла объекта activity соответствующим методам в классе MapView: onCreate(), onStart(), onResume(), onPause(), onStop(), onDestroy(), onSaveInstanceState() и onLowMemory(). В репозитории ApiDemos на сайте GitHub доступен пример, который демонстрирует передачу методов жизненного цикла объекта activity. При использовании API в упрощенном режиме передача событий жизненного цикла не является обязательной. Подробнее…

Типы карт

В Maps SDK for Android доступны разные типы карт. От типа карты зависит ее внешний вид. Например, в атласах обычно можно найти политические карты, на которых показаны границы государств, и дорожные карты, на которые наносятся транспортные сети города или региона.

В Maps SDK for Android предусмотрено четыре типа карт, однако ни один из них не является обязательным.

Обычный: Обычная дорожная карта. На ней показаны транспортные сети, некоторые техногенные и основные природные объекты, такие как реки. Кроме того, на такой карте представлены названия дорог и объектов.
Гибрид: Спутниковые снимки с добавленными дорожными картами. Кроме того, на такой карте представлены названия дорог и объектов.
Спутник: Спутниковые снимки. Названия дорог и компонентов не отображаются.
Рельеф: Топографические данные. На карте присутствуют цвета, контурные линии и метки, а также тени, отбрасываемые рельефом. Видны некоторые дороги и ярлыки.
Нет: Фрагменты карты не отображаются. Карта рисуется как пустая сетка.

Изменение типа карты

Чтобы установить тип карты, вызовите метод setMapType() объекта GoogleMap, передав ему одну из констант типов карты, определенных в GoogleMap. Например, следующий код отображает спутниковую карту:

GoogleMap map;
...
// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

Ниже показаны нормальная, гибридная и рельефная карты одной и той же области.

Схемы зданий

При максимальных уровнях масштабирования на карте отображаются поэтажные планы некоторых зданий, таких как аэропорты, вокзалы и торговые центры. Эти планы называются схемами зданий. Они отображаются на нормальных и спутниковых картах (GoogleMap.MAP_TYPE_NORMAL и GoogleMap.MAP_TYPE_SATELLITE), автоматически появляются, когда масштаб увеличивается, и исчезают, когда он уменьшается.

Уведомление о прекращении использования. В следующем выпуске схемы зданий будут отображаться только на картах типа normal. На картах типа satellite, terrain и hybrid они перестанут поддерживаться. Даже там, где схемы зданий не будут поддерживаться, метод isIndoorEnabled() будет по-прежнему возвращать значение, установленное с помощью метода setIndoorEnabled(), как и сейчас. По умолчанию для setIndoorEnabled задано значение true. В примечаниях к выпуску будет указано, когда прекратится поддержка схем зданий для определенных типов карт.

Работа со схемами зданий в API

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

Чтобы отключить схемы зданий, вызовите GoogleMap.setIndoorEnabled(false). По умолчанию схемы зданий включены. Они отображаются одновременно только на одной карте. По умолчанию это первая карта, добавленная в ваше приложение. Если вам необходимо отобразить схемы зданий на другой карте, сначала отключите их на первой карте, а затем вызовите setIndoorEnabled(true) на второй.
Чтобы отключить стандартный модуль выбора уровня (этажа), вызовите GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false). Подробнее…
Интерфейс OnIndoorStateChangeListener в GoogleMap, позволяет установить прослушиватель, когда в фокус попадает новое здание или активируется новый уровень в нем. Подробнее…
Чтобы получить данные о здании, которое в настоящий момент находится в фокусе, вызовите GoogleMap.getFocusedBuilding(). После этого вы можете найти текущий активный уровень, вызвав метод IndoorBuilding.getActiveLevelIndex(). Справочная документация содержит более подробную информацию об объектах IndoorBuilding и IndoorLevel.

Стили на базовой карте не распространяются на схемы зданий.

Как добавить схемы зданий

Схемы зданий (поэтажные планы) доступны только в некоторых местоположениях. Если данные поэтажных планов недоступны для здания, которое вы хотите выделить в своем приложении, можно выполнить следующие действия:

Добавить план непосредственно в Google Карты, после чего он станет доступен всем пользователям сервиса.
Отобразить поэтажный план как наземное наложение или наложение фрагмента карты, в результате чего он станет виден только пользователям вашего приложения.

Слой "Пробки"

Вы можете сделать так, чтобы пользователям был доступен слой с данными о загруженности дорог. По такой карте удобно оценивать обстановку в своем районе. Чтобы включить или отключить слой "Пробки", вызовите метод setTrafficEnabled(). Чтобы узнать, включен ли он в данный момент, вызовите метод isTrafficEnabled(). Ниже показано, как данные о загруженности дорог выглядят на карте.

Карта Google с информацией о загруженности дорог

Настройка исходного вида

API Карт позволяет настроить исходный вид карты. Вы можете указать следующие параметры:

Положение камеры, включая координаты, масштаб, наклон и поворот. Подробнее…
Тип карты.
Отображение на экране кнопок масштабирования и/или компаса.
Жесты, которые доступны пользователям для управления камерой.
Включение или отключение упрощенного режима. Карта в упрощенном режиме представляет собой битовое изображение, которое поддерживает частичный набор функций, доступных в полном API.

Эти настройки можно задать в XML-коде, если вы добавляли карту через файл макета для объекта activity, или программными средствами.

Использование атрибутов XML

В этом разделе описано, как установить исходные настройки карты, если она была добавлена через файл макета.

API Карт определяет набор изменяемых атрибутов XML для объектов MapFragment или MapView, которые можно использовать для настройки начального состояния карты непосредственно из файла макета. В настоящее время определены следующие атрибуты:

mapType. Позволяет указывать тип отображаемой карты. Допустимые значения: none, normal, hybrid, satellite и terrain.
cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt. Позволяют указывать начальное положение камеры. Подробнее…
uiZoomControls, uiCompass. Определяют, показывать ли поверх карты кнопки масштабирования и компас. Подробнее о UiSettings…
uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures. Определяют жесты, с помощью которых пользователь может управлять камерой. Подробнее о UiSettings…
zOrderOnTop. Определяет, располагать ли поверхность области просмотра поверх экрана. Подробнее… Учтите, что в результате могут оказаться скрыты все другие наложения на карту, включая инструменты масштабирования и кнопку "Мое местоположение".
useViewLifecycle. Действует только вместе с MapFragment. Этот атрибут определяет, к чему привязывать жизненный цикл карты: к области просмотра фрагмента или к самому фрагменту. Подробнее…
liteMode. Значение true устанавливает для карты упрощенный режим. Карта в упрощенном режиме представляет собой битовое изображение, которое поддерживает частичный набор функций, доступных в полном API. Значение этого атрибута по умолчанию – false.

Чтобы использовать эти настраиваемые атрибуты в XML-файле макета, необходимо сначала объявить пространство имен (оно может быть любым, не обязательно map):

xmlns:map="http://schemas.android.com/apk/res-auto"

После этого добавляйте к компонентам атрибуты с префиксом map:, как и при использовании стандартных атрибутов Android.

В примере ниже объекту MapFragment назначаются некоторые пользовательские атрибуты (те же атрибуты можно назначить и объекту MapView).

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:map="http://schemas.android.com/apk/res-auto"
  android:name="com.google.android.gms.maps.SupportMapFragment"
  android:id="@+id/map"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  map:cameraBearing="112.5"
  map:cameraTargetLat="-33.796923"
  map:cameraTargetLng="150.922433"
  map:cameraTilt="30"
  map:cameraZoom="13"
  map:mapType="normal"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

Программные средства

В этом разделе описано, как установить исходные настройки карты, если она была добавлена программными средствами.

Если вы добавили MapFragment (или MapView) с помощью программных средств, то для настройки начального состояния карты можно передать объект GoogleMapOptions с указанными вами параметрами. Вам доступны те же параметры, что и при использовании XML. Вы можете создать объект GoogleMapOptions следующего вида:

GoogleMapOptions options = new GoogleMapOptions();

Затем его можно настроить:

options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false);

Чтобы применить эти параметры при создании карты, выполните одно из указанных ниже действий.

Если вы используете MapFragment, примените статический метод генерации MapFragment.newInstance(GoogleMapOptions options), чтобы создать фрагмент и передать настроенные вами параметры.
Если вы используете MapView, вызовите конструктор MapView(Context, GoogleMapOptions) и передайте необходимые параметры.

Поля карты

В этом видеоролике демонстрируется пример использования отступов на карте.

По умолчанию карта занимает всю область, ограниченную ее контейнером (как правило, это объект MapView или MapFragment). Размеры контейнера определяют следующие аспекты отображения карты:

Камера будет нацелена на центр области с отступами.
Элементы управления упорядочиваются относительно краев карты.
Юридическая информация, например, заявления об авторских правах или логотип Google, отображается вдоль нижнего края карты.

Чтобы добавить вокруг карты поля, вызовите для объекта GoogleMapметод setPadding(). Сама карта будет и далее занимать весь контейнер, однако текст, элементы управления, жесты пользователя и движения камеры будут обрабатываться с учетом уменьшенной области. Это приведет к следующим изменениям:

Движения камеры, совершаемые в ответ на вызовы API или нажатия кнопок ("Мое местоположение", управление масштабированием и т. п.), будут обрабатываться относительно уменьшенной области.
Метод getCameraPosition() будет возвращать точку в центре уменьшенной области.
Метод Projection.getVisibleRegion() будет возвращать уменьшенную область.
Элементы управления в пользовательском интерфейсе будут сдвинуты от края контейнера на указанное число пикселей.

Поля рекомендуется добавлять, если пользовательский интерфейс закрывает часть карты. Например, на иллюстрации ниже добавлены верхнее и правое поле. Инструменты управления картой и юридические сведения отображаются вдоль краев уменьшенной области, которая обозначена на картинке зеленой рамкой, в то время как сама карта по-прежнему занимает весь контейнер (синяя рамка). Это позволяет разместить меню в правой части карты, не перекрывая инструменты управления.

Поля карты

Локализация карты

Если в приложение добавлен объект MapView или MapFragment, все текстовые элементы на карте показываются на языке, который определяется с учетом пользовательского местоположения и настроек устройства. Вы можете ограничить список доступных языков, добавив в файл Gradle элемент resConfigs. Исключив неиспользуемые языки, вы уменьшите размер исполняемого файла приложения. Пример:

defaultConfig {
    resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}

Подробнее о локализации приложений для Android…