지도 표시
앱에 Google Maps를 추가합니다.
지도 표시은(는) CoddyKit의 무료 Android Academy 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Android Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Android Academy 강의에는 총 4개의 강의가 포함되어 있습니다.
앱을 지도에 올리기
지도는 원시 좌표를 사용자가 보고 탐색할 수 있는 정보로 바꿔 줍니다. 이 단원에서는 공식 maps-compose 라이브러리를 사용하여 Jetpack Compose 화면에 대화형 Google 지도를 추가합니다.
단원이 끝나면 어떤 컴포저블에든 실제로 이동하고 확대/축소할 수 있는 지도를 배치할 수 있습니다. 먼저 필요한 구성 요소를 준비해 보겠습니다.
Maps Compose 라이브러리
Google은 maps-compose라는 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
)
}지도 UI 설정
MapUiSettings는 화면에 표시되는 컨트롤을 설정합니다. 확대·축소 버튼, 나침반, 내 위치 버튼, 제스처 등을 켜거나 끌 수 있습니다.
더 깔끔하게 보이도록 필요하지 않은 컨트롤은 끄세요. 예를 들어 확대·축소 버튼은 숨기고 두 손가락으로 확대·축소하는 제스처는 유지할 수 있습니다.
import com.google.maps.android.compose.MapUiSettings
val uiSettings = remember {
MapUiSettings(
zoomControlsEnabled = false,
compassEnabled = true,
scrollGesturesEnabled = true,
zoomGesturesEnabled = true
)
}모든 요소 결합하기
카메라, 속성, UI 설정을 하나의 구성된 지도에 결합하세요. 이것이 실제 앱의 지도 화면에서 일반적으로 사용하는 형태입니다.
@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를 저장할 수 있습니다.
탭한 지점을 상태에 보관하면 UI가 해당 변경에 반응할 수 있습니다.
@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으로 탭에 반응합니다.
다음으로는 기기의 실제 위치를 가져와 사용자를 중심으로 지도를 표시하는 방법을 알아봅니다.
자주 묻는 질문
“지도 표시” 강의는 무료인가요?
네 — “지도 표시” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Android Academy 강의 전체를 잠금 해제할 수 있습니다. Android Academy 강의에는 총 4개의 강의가 포함되어 있습니다.
“지도 표시”에서 뭘 배우나요?
앱에 Google Maps를 추가합니다. 브라우저에서 직접 실행하는 실습 코드로 Android Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.
Android Academy을(를) 시작하는 데 경험이 필요한가요?
사전 경험은 필요하지 않습니다. CoddyKit의 Android Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.
“지도 표시” 강의는 얼마나 걸리나요?
대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.
이 Android Academy 강의에서 코드를 작성하고 실행할 수 있나요?
네. 모든 Android Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.