Android Academy · Урок

Отображение карты

Добавьте Google Maps в приложение

«Отображение карты» — бесплатный урок Android Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Android Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Android Academy содержит 4 уроков всего.

Размещаем приложение на карте

Карты превращают необработанные координаты в то, что пользователи могут видеть и исследовать. В этом уроке вы добавите интерактивную карту Google на экран Jetpack Compose с помощью официальной библиотеки maps-compose.

К концу урока вы сможете добавить в любой компонуемый элемент настоящую карту, которую можно перемещать и масштабировать. Давайте подготовим основные компоненты.

Библиотека Maps Compose

Google предоставляет оболочку для Compose под названием maps-compose. Она содержит компонуемый элемент GoogleMap, поэтому вам не придётся напрямую работать со старым XML-представлением MapView.

Добавьте эти зависимости в модульный файл build.gradle.kts. Артефакт play-services-maps предоставляет базовый SDK, а maps-compose адаптирует его для Compose.

// build.gradle.kts (module)
dependencies {
    implementation("com.google.maps.android:maps-compose:6.1.0")
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

Получение ключа API

Google Maps требует ключ API. Создайте его в Google Cloud Console, включите Maps SDK for Android, а затем разместите ключ в файле AndroidManifest.xml внутри тега <application>.

Никогда не прописывайте ключ непосредственно в исходном коде, который публикуется в открытом доступе. Храните его в local.properties и подставляйте через заполнитель манифеста.

<!-- AndroidManifest.xml, inside <application> -->
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

Ваша первая GoogleMap

Самая простая карта — это один компонуемый элемент GoogleMap. Передайте ему Modifier.fillMaxSize(), и вы сразу получите карту, которую можно перемещать и масштабировать.

Для отображения ей не нужны дочерние элементы — после проверки ключа API фрагменты карты Google отрисуются автоматически.

import com.google.maps.android.compose.GoogleMap

@Composable
fun MapScreen() {
    GoogleMap(
        modifier = Modifier.fillMaxSize()
    )
}

Управление камерой

Камера определяет, какую область карты показывать и насколько сильно её приблизить. Передайте CameraPositionState, сохранённое между рекомпозициями.

Создайте CameraPosition из LatLng (широта, долгота) и уровня масштабирования. Чем выше масштаб, тем ближе изображение.

import com.google.android.gms.maps.model.CameraPosition
import com.google.android.gms.maps.model.LatLng
import com.google.maps.android.compose.rememberCameraPositionState

val sanFrancisco = LatLng(37.7749, -122.4194)
val cameraPositionState = rememberCameraPositionState {
    position = CameraPosition.fromLatLngZoom(sanFrancisco, 12f)
}

Подключение камеры к карте

Передайте это состояние cameraPositionState в GoogleMap, чтобы карта открывалась с центром в нужном месте. Поскольку состояние сохраняется, перемещение и масштабирование карты пользователем переживают рекомпозицию.

@Composable
fun CenteredMap() {
    val sf = LatLng(37.7749, -122.4194)
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(sf, 12f)
    }
    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        cameraPositionState = cameraPositionState
    )
}

Свойства карты

MapProperties настраивает содержимое карты. К распространённым параметрам относятся тип карты (обычный, спутниковый, рельефный, гибридный) и включение синей точки моего местоположения.

Сохраните объект свойств, чтобы он не создавался заново при каждой рекомпозиции.

import com.google.maps.android.compose.MapProperties
import com.google.maps.android.compose.MapType

val properties = remember {
    MapProperties(
        mapType = MapType.NORMAL,
        isMyLocationEnabled = false
    )
}

Настройки интерфейса карты

MapUiSettings управляет элементами управления на экране: кнопками масштабирования, компасом, кнопкой моего местоположения и жестами.

Отключите ненужные элементы для более лаконичного вида — например, скройте кнопки масштабирования, но оставьте жесты масштабирования двумя пальцами.

import com.google.maps.android.compose.MapUiSettings

val uiSettings = remember {
    MapUiSettings(
        zoomControlsEnabled = false,
        compassEnabled = true,
        scrollGesturesEnabled = true,
        zoomGesturesEnabled = true
    )
}

Собираем всё вместе

Объедините камеру, свойства и настройки интерфейса в одну настроенную карту. Так обычно выглядит экран карты в рабочем приложении.

@Composable
fun ConfiguredMap() {
    val sf = LatLng(37.7749, -122.4194)
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(sf, 12f)
    }
    val properties = remember { MapProperties(mapType = MapType.NORMAL) }
    val uiSettings = remember { MapUiSettings(zoomControlsEnabled = false) }

    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        cameraPositionState = cameraPositionState,
        properties = properties,
        uiSettings = uiSettings
    )
}

Обработка нажатий на карту

GoogleMap предоставляет обратные вызовы, например onMapClick. Используйте их, чтобы реагировать на нажатие пользователем карты — например, сохранять выбранный объект LatLng.

Храните нажатую точку в состоянии, чтобы интерфейс мог реагировать на неё.

@Composable
fun ClickableMap() {
    var picked by remember { mutableStateOf<LatLng?>(null) }
    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        onMapClick = { latLng -> picked = latLng }
    )
    picked?.let { p ->
        Text("Picked: ${p.latitude}, ${p.longitude}")
    }
}

Жизненным циклом управляют за вас

При использовании классического XML-компонента MapView нужно было вручную передавать каждое событие жизненного цикла. Библиотека maps-compose автоматически связывает карту с жизненным циклом композиции.

Это избавляет от ручной настройки onResume/onPause/onDestroy — ещё одна причина предпочесть API Compose для новых экранов.

Быстрая проверка

Какой объект состояния Compose нужно сохранить и передать в GoogleMap, чтобы управлять центром и масштабом карты?

Итоги

Теперь вы умеете размещать настоящую карту Google в Compose:

Добавьте maps-compose и play-services-maps, а также ключ API в манифест.
Отобразите карту с помощью компонуемого компонента GoogleMap.
Задайте её центр и масштаб с помощью rememberCameraPositionState и CameraPosition.
Настройте её с помощью MapProperties и MapUiSettings, а нажатия обрабатывайте через onMapClick.

Далее вы получите фактическое местоположение устройства и разместите в его центре карту.

Часто задаваемые вопросы

Урок «Отображение карты» бесплатный?

Да — полный текст урока «Отображение карты» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Android Academy, подпишись на CoddyKit PRO. Курс Android Academy содержит 4 уроков всего.

Чему я научусь в уроке «Отображение карты»?

Добавьте Google Maps в приложение Ты практикуешь Android Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Android Academy?

Предыдущий опыт не требуется. Android Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Отображение карты»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Android Academy?

Да. Каждый урок Android Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к Android Academy