Android Academy · 课时

显示地图

Q: 「显示地图」这节课中我会学到什么？

将 Google Maps 添加到您的应用 你通过在浏览器中直接运行的动手代码来练习 Android Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

将 Google Maps 添加到您的应用

显示地图 是 CoddyKit 上的免费 Android Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Android Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Android Academy 课程共包含 4 节课。

将应用放到地图上

地图可以将原始坐标转化为用户能够查看和探索的内容。本课将使用官方的 maps-compose 库，将交互式谷歌地图添加到 Jetpack 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 地图需要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。

请根据 LatLng（纬度、经度）和缩放级别构建 CameraPosition。缩放级别越高，视图就越近。

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——这也是新界面优先使用 Compose API 的又一个理由。

快速检查

要控制地图的中心位置和缩放级别，您需要记住并传递给 GoogleMap 的组合状态对象是什么？

回顾

现在，您已经可以在 Compose 中放置真实的 Google 地图：

添加 maps-compose 和 play-services-maps，并在清单中配置 API 密钥。
使用 GoogleMap 组合函数渲染地图。
使用 rememberCameraPositionState 和 CameraPosition 设置地图的中心和缩放级别。
使用 MapProperties 和 MapUiSettings 自定义地图，并通过 onMapClick 响应点击。

接下来：获取设备的实际位置，将地图中心移到用户所在位置。

常见问题解答

「显示地图」课时是免费的吗？

是的 — 「显示地图」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Android Academy 课程的其余内容，请升级到 CoddyKit PRO。 Android Academy 课程共包含 4 节课。

「显示地图」这节课中我会学到什么？

将 Google Maps 添加到您的应用你通过在浏览器中直接运行的动手代码来练习 Android Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Android Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Android Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「显示地图」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Android Academy 课中编写并运行代码吗？

能。每节 Android Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Android Academy