学习

概念	作用	简单理解
`GoogleMap`	显示地图本体	画布
`CameraPosition`	控制地图看哪里	镜头
`Marker`	在地图上标点	图钉

类型	写在哪里	作用
Manifest permission	`AndroidManifest.xml`	声明 App 需要权限
Runtime permission request	Kotlin code	向用户真正申请权限

地图元素	用途
`Marker`	标记一个点
`Polyline`	连接多个点形成路径
`Circle`	表示一个点周围的范围

Google Map Lab · Jimmy Huang's Blog

Dependency	作用
`play-services-maps`	Google Maps Android 原生 SDK
`maps-compose`	让 Google Map 可以在 Jetpack Compose 中使用
`play-services-location`	获取用户当前位置
`android-maps-utils`	提供距离计算等工具类

toml

[libraries]
play-services-maps = {group = "com.google.android.gms",name = "play-services-maps",version.ref = "playServicesMaps" }
play-services-location = {group = "com.google.android.gms",name = "play-services-location",version.ref = "playServicesLocation" }
maps-compose = {module = "com.google.maps.android:maps-compose",version.ref = "mapsCompose" }
maps-utils = {module = "com.google.maps.android:android-maps-utils",version.ref = "mapsUtils" }

xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.YourApp">

        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="PLACE_YOUR_API_KEY_HERE" />

        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:theme="@style/Theme.YourApp">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

    </application>

</manifest>

kotlin

package com.example.week10googlemap

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import com.google.android.gms.maps.model.CameraPosition
import com.google.android.gms.maps.model.LatLng
import com.google.maps.android.compose.GoogleMap
import com.google.maps.android.compose.Marker
import com.google.maps.android.compose.MarkerState
import com.google.maps.android.compose.rememberCameraPositionState

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val monashLocation = LatLng(-37.8770, 145.0443)

        setContent {
            MaterialTheme {
                MapScreen(
                    location = monashLocation,
                    title = "Monash University"
                )
            }
        }
    }
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MapScreen(
    location: LatLng,
    title: String
) {
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(location, 15f)
    }

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(title) }
            )
        }
    ) { innerPadding ->
        GoogleMap(
            modifier = Modifier
                .fillMaxSize()
                .padding(innerPadding),
            cameraPositionState = cameraPositionState
        ) {
            Marker(
                state = MarkerState(position = location),
                title = title
            )
        }
    }
}

kotlin

package com.example.week10googlemap

import android.Manifest
import android.annotation.SuppressLint
import android.content.pm.PackageManager
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.compose.setContent
import androidx.activity.result.contract.ActivityResultContracts
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.core.content.ContextCompat
import androidx.compose.ui.platform.LocalContext
import com.google.android.gms.location.LocationServices
import com.google.android.gms.location.Priority
import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.model.CameraPosition
import com.google.android.gms.maps.model.LatLng
import com.google.maps.android.compose.GoogleMap
import com.google.maps.android.compose.MapProperties
import com.google.maps.android.compose.MapUiSettings
import com.google.maps.android.compose.Marker
import com.google.maps.android.compose.MarkerState
import com.google.maps.android.compose.rememberCameraPositionState
import kotlinx.coroutines.launch

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            MaterialTheme {
                InteractiveLocationMapScreen()
            }
        }
    }
}

@SuppressLint("MissingPermission")
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun InteractiveLocationMapScreen(
    title: String = "My Google Map"
) {
    val context = LocalContext.current
    val scope = rememberCoroutineScope()

    val fusedLocationClient = remember {
        LocationServices.getFusedLocationProviderClient(context)
    }

    var hasLocationPermission by remember {
        mutableStateOf(
            ContextCompat.checkSelfPermission(
                context,
                Manifest.permission.ACCESS_FINE_LOCATION
            ) == PackageManager.PERMISSION_GRANTED
        )
    }

    var selectedLocation by remember {
        mutableStateOf<LatLng?>(null)
    }

    var statusText by remember {
        mutableStateOf("Waiting for location permission...")
    }

    val defaultLocation = LatLng(-37.8770, 145.0443)

    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(defaultLocation, 12f)
    }

    val permissionLauncher = rememberLauncherForActivityResult(
        contract = ActivityResultContracts.RequestPermission()
    ) { granted ->
        hasLocationPermission = granted

        statusText = if (granted) {
            "Permission granted. Fetching current location..."
        } else {
            "Location permission denied. You can still tap the map to place a marker."
        }
    }

    LaunchedEffect(Unit) {
        if (!hasLocationPermission) {
            permissionLauncher.launch(Manifest.permission.ACCESS_FINE_LOCATION)
        } else {
            statusText = "Fetching current location..."
        }
    }

    LaunchedEffect(hasLocationPermission) {
        if (hasLocationPermission) {
            fusedLocationClient
                .getCurrentLocation(Priority.PRIORITY_HIGH_ACCURACY, null)
                .addOnSuccessListener { location ->
                    if (location != null) {
                        val currentLatLng = LatLng(location.latitude, location.longitude)

                        selectedLocation = currentLatLng
                        statusText = "Current location found."

                        scope.launch {
                            cameraPositionState.animate(
                                CameraUpdateFactory.newLatLngZoom(currentLatLng, 16f)
                            )
                        }
                    } else {
                        statusText = "Could not get current location. Try setting emulator location or tap the map."
                    }
                }
                .addOnFailureListener { exception ->
                    statusText = "Failed to get location:${exception.message}"
                }
        }
    }

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(title) }
            )
        }
    ) { innerPadding ->

        Box(
            modifier = Modifier
                .fillMaxSize()
                .padding(innerPadding)
        ) {
            GoogleMap(
                modifier = Modifier.fillMaxSize(),
                cameraPositionState = cameraPositionState,
                properties = MapProperties(
                    isMyLocationEnabled = hasLocationPermission
                ),
                uiSettings = MapUiSettings(
                    myLocationButtonEnabled = hasLocationPermission,
                    zoomControlsEnabled = true
                ),
                onMapClick = { tappedLocation ->
                    selectedLocation = tappedLocation
                    statusText = "Marker placed at: %.5f, %.5f".format(
                        tappedLocation.latitude,
                        tappedLocation.longitude
                    )
                }
            ) {
                selectedLocation?.let { location ->
                    Marker(
                        state = MarkerState(position = location),
                        title = "Selected Location",
                        snippet = "%.5f, %.5f".format(
                            location.latitude,
                            location.longitude
                        )
                    )
                }
            }

            Column(
                modifier = Modifier
                    .align(Alignment.BottomCenter)
                    .padding(16.dp),
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.spacedBy(8.dp)
            ) {
                Text(
                    text = statusText,
                    modifier = Modifier
                        .background(MaterialTheme.colorScheme.surface.copy(alpha = 0.85f))
                        .padding(8.dp)
                )

                Button(
                    onClick = {
                        selectedLocation = null
                        statusText = "Marker cleared. Tap the map to add a new marker."
                    }
                ) {
                    Text("Clear Marker")
                }
            }
        }
    }
}

kotlin

package com.example.week10googlemap

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import com.google.android.gms.maps.model.CameraPosition
import com.google.android.gms.maps.model.LatLng
import com.google.maps.android.SphericalUtil
import com.google.maps.android.compose.GoogleMap
import com.google.maps.android.compose.Marker
import com.google.maps.android.compose.MarkerState
import com.google.maps.android.compose.Polyline
import com.google.maps.android.compose.rememberCameraPositionState

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val locationList = listOf(
            LatLng(-37.8770, 145.0443), // Monash University Clayton
            LatLng(-37.8895, 145.0938),
            LatLng(-37.9021, 145.2019),
            LatLng(-37.8880, 145.0850)
        )

        setContent {
            MaterialTheme {
                RouteMapScreen(
                    visitedLocations = locationList
                )
            }
        }
    }
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun RouteMapScreen(
    visitedLocations: List<LatLng>,
    modifier: Modifier = Modifier,
    title: String = "Total Walk Distance"
) {
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(
            visitedLocations.firstOrNull() ?: LatLng(-37.8770, 145.0443),
            12f
        )
    }

    val totalDistanceKm = remember(visitedLocations) {
        if (visitedLocations.size < 2) {
            0.0
        } else {
            var distanceMeters = 0.0

            for (i in 0 until visitedLocations.size - 1) {
                distanceMeters += SphericalUtil.computeDistanceBetween(
                    visitedLocations[i],
                    visitedLocations[i + 1]
                )
            }

            distanceMeters / 1000.0
        }
    }

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(title) }
            )
        }
    ) { innerPadding ->

        Column(
            modifier = modifier
                .fillMaxSize()
                .padding(innerPadding)
        ) {
            Text(
                text = "Total Walk Distance Today: %.2f km".format(totalDistanceKm),
                style = MaterialTheme.typography.bodyLarge,
                modifier = Modifier.padding(16.dp)
            )

            GoogleMap(
                modifier = Modifier.fillMaxSize(),
                cameraPositionState = cameraPositionState
            ) {
                if (visitedLocations.size > 1) {
                    Polyline(
                        points = visitedLocations,
                        color = Color.Red,
                        width = 6f
                    )
                }

                visitedLocations.forEachIndexed { index, location ->
                    Marker(
                        state = MarkerState(position = location),
                        title = "Stop${index + 1}"
                    )
                }
            }
        }
    }
}

kotlin

package com.example.week10googlemap

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import com.google.android.gms.maps.model.CameraPosition
import com.google.android.gms.maps.model.LatLng
import com.google.maps.android.compose.Circle
import com.google.maps.android.compose.GoogleMap
import com.google.maps.android.compose.Marker
import com.google.maps.android.compose.MarkerState
import com.google.maps.android.compose.rememberCameraPositionState

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val monashLocation = LatLng(-37.8770, 145.0443)

        setContent {
            MaterialTheme {
                MapScreenWithCircle(
                    location = monashLocation
                )
            }
        }
    }
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MapScreenWithCircle(
    location: LatLng,
    title: String = "Monash Clayton Campus",
    circleRadiusMeters: Double = 1000.0
) {
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(location, 15f)
    }

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(title) }
            )
        }
    ) { innerPadding ->

        Surface(
            modifier = Modifier
                .fillMaxSize()
                .padding(innerPadding),
            color = MaterialTheme.colorScheme.background
        ) {
            GoogleMap(
                modifier = Modifier.fillMaxSize(),
                cameraPositionState = cameraPositionState
            ) {
                Marker(
                    state = MarkerState(position = location),
                    title = title
                )

                Circle(
                    center = location,
                    radius = circleRadiusMeters,
                    strokeColor = Color.Blue,
                    strokeWidth = 4f,
                    fillColor = Color.Blue.copy(alpha = 0.1f)
                )
            }
        }
    }
}

Google Map Lab

Overview

Google Map Lab

Overview

Goal

Task 0: 创建 Google Maps API Key

Step 0.1：使用个人 Gmail 登录 Google Cloud Console

Step 0.2：创建或选择 Google Cloud Project

Step 0.3：启用 Maps SDK for Android

Step 0.4：创建 API Key

Step 0.5：建议限制 API Key

Task 1: 配置 Android 项目

Task 1.1：打开 Android 项目中的 Manifest 文件

Step 1.2：在 libs.versions.toml 添加版本号

Step 1.3：在 libs.versions.toml 添加 libraries alias

Step 1.4：在 app-level Gradle 添加 dependencies

Step 1.5：Sync Gradle

Task 2: 显示基础 Google Map 和 Marker

Step 2.1：打开 MainActivity.kt

Step 2.2：写入基础地图代码

Step 2.3：运行 App

Task 3: 加入当前位置权限、My Location 蓝点、点击 Marker 和 Clear

Step 3.1：确认 Manifest 已经有定位权限

Step 3.2：替换 MainActivity.kt 为完整进阶版本

Step 3.3：运行 App 并允许定位权限

Step 3.4：如果当前位置获取不到，设置模拟器位置

Task 4: 使用 Polyline 连接多个地点并计算总距离

Step 4.1：确认已经添加 maps utils dependency

Step 4.2：把 MainActivity.kt 改成 RouteMapScreen 版本

Step 4.3：运行 App

Step 4.4：理解距离计算逻辑

Task 5: 使用 Circle 显示地点周围 1km 范围

Step 5.1：把 MainActivity.kt 改成 Circle 版本

Step 5.2：运行 App

Step 5.3：理解 Circle 参数

Task 6: 最终检查清单

Step 6.1：检查 Google Cloud 设置

Step 6.2：检查 AndroidManifest.xml

Step 6.3：检查 Gradle dependencies

本周必须理解的知识点

1. API Key 是什么

2. Manifest permission vs Runtime permission

3. LatLng 是什么

4. CameraPosition 是什么

5. Marker 是什么

6. Polyline 是什么

7. Circle 是什么

关键概念对比

GoogleMap vs CameraPosition vs Marker

Permission 声明 vs Permission 请求

Marker vs Polyline vs Circle

play-services-maps vs maps-compose

老师可能会问什么

1. 你为什么要在 Manifest 里放 API key？

2. 为什么 Manifest 写了 location permission，代码里还要 request permission？

3. rememberCameraPositionState 是做什么的？

4. LatLng(-37.8770, 145.0443) 中两个数字分别是什么？

5. 为什么要用 selectedLocation 作为 state？

6. 为什么 Polyline 需要一个 list of LatLng？

7. 为什么 Circle 的 radius 用 meters？

Summary

Step 1.2：在 `libs.versions.toml` 添加版本号

Step 1.3：在 `libs.versions.toml` 添加 libraries alias

Step 2.1：打开 `MainActivity.kt`

Step 3.2：替换 `MainActivity.kt` 为完整进阶版本

Step 4.2：把 `MainActivity.kt` 改成 RouteMapScreen 版本

Step 5.1：把 `MainActivity.kt` 改成 Circle 版本

`play-services-maps` vs `maps-compose`

3. `rememberCameraPositionState` 是做什么的？

4. `LatLng(-37.8770, 145.0443)` 中两个数字分别是什么？

5. 为什么要用 `selectedLocation` 作为 state？

6. 为什么 `Polyline` 需要一个 list of `LatLng`？