Maps Compose 程式庫

Jetpack Compose 是宣告式原生 UI 工具包,可以簡化和加速 UI 開發作業。只要使用 Jetpack Compose 描述想要呈現的應用程式外觀,Jetpack Compose 就能接手完成之後的工作。

Maps SDK for Android 的 Maps Compose 程式庫收錄開放原始碼的可組合函式和資料類型,可與 Jetpack Compose 搭配使用來建構應用程式。

Maps Compose 程式庫包含可組合函式和資料類型,可用於執行多項常見工作。以下列舉一些常用的可組合函式和資料類型:

可組合函式 說明
Circle 可在地圖上新增圓形的可組合函式。
GoogleMap 用於新增地圖的可組合函式。
GroundOverlay 可在地圖上新增區域疊加層的可組合函式。
MapProperties 地圖上可修改屬性的資料類型。
MapUISettings 地圖上 UI 相關設定的資料類型。
Marker 可在地圖上新增標記的可組合函式。
Polygon 可在地圖上新增多邊形的可組合函式。
Polyline 可在地圖上新增折線的可組合函式。
TileOverlay 可在地圖上新增圖塊疊加層的可組合函式。

如需所有可組合函式和資料類型的完整清單,請參閱 Maps Compose 程式庫參考資料

需求條件

如要將 Maps Compose 程式庫與 Maps SDK for Android 搭配使用,您必須完成以下步驟:

  • 下載並安裝 Android Studio Arctic Fox。
  • 在 Android Studio 中,按照以下方式建立 Google 地圖專案

    • 範本類型為「Empty Compose Activity」(空白撰寫活動)。這個範本會新增 Jetpack Compose 所需的必要依附元件。
    • 將「Minimum SDK」(SDK 最低版本) 設為「API 21: Android 5.0 (Lollipop)」或更新版本。
    • 將「Language」(語言) 設為「Kotlin」
  • 取得 API 金鑰並加進專案。

  • 按照下一節的說明,在專案中安裝 Maps Compose 程式庫。

安裝

如要在 Google 地圖專案中安裝 Maps Compose 程式庫,請按照下列步驟操作:

  1. 將以下依附元件加進模組層級 build.gradle 檔案:

      dependencies {
        implementation 'com.google.maps.android:maps-compose:2.11.4'
        implementation 'com.google.android.gms:play-services-maps:18.1.0'
    }

  2. 在 Android Studio 中重新建立專案,以同步處理這些變更。

在應用程式中新增地圖

以下範例說明如何使用 GoogleMap 可組合函式新增地圖。

val singapore = LatLng(1.35, 103.87)
val cameraPositionState = rememberCameraPositionState {
  position = CameraPosition.fromLatLngZoom(singapore, 10f)
}
GoogleMap(
  modifier = Modifier.fillMaxSize(),
  cameraPositionState = cameraPositionState
) {
  Marker(
    state = MarkerState(position = singapore),
    title = "Singapore",
    snippet = "Marker in Singapore"
  )
}

在這個範例中,地圖佔用了允許使用的最大空間,且相機位置是以新加坡為中心。cameraPositionState 中也會建立並提供 CameraPositionState,以便設定相機的位置。

接著,範例呼叫地圖內容中的 Marker 可組合函式,以在地圖上新增標記。

如要將本範例與使用 Views 新增地圖的範例進行比較,請參閱快速入門導覽課程。請留意可組合函式所需的程式碼較少,而且您不必擔心地圖的生命週期。

設定地圖上的屬性

透過提供 MapProperties 物件,或為 UI 相關屬性提供 MapUiSettings 物件,即可設定地圖上的屬性。您可以修改這些物件來觸發地圖重新組合。

以下範例使用 Switch (一種質感設計元件) 來切換地圖上的縮放控制項。

var uiSettings by remember { mutableStateOf(MapUiSettings()) }
var properties by remember {
  mutableStateOf(MapProperties(mapType = MapType.SATELLITE))
}

Box(Modifier.fillMaxSize()) {
  GoogleMap(
    modifier = Modifier.matchParentSize(),
    properties = properties,
    uiSettings = uiSettings
  )
  Switch(
    checked = uiSettings.zoomControlsEnabled,
    onCheckedChange = {
      uiSettings = uiSettings.copy(zoomControlsEnabled = it)
    }
  )
}

後續主題