如何建立地圖 ID

選取平台： Android Android 3D iOS iOS 3D JavaScript 網路服務

付費功能：加入地圖 ID 後即可使用此功能，使用時會觸發地圖載入 (依照 Android 和 iOS 版 Dynamic Maps SKU 計費)，詳情請參閱「Google 地圖計費方式」一文。

地圖 ID 是不重複的識別碼，代表儲存在 Google Cloud 中的 Google 地圖樣式和設定。您可以使用地圖 ID 啟用功能，或管理及設定網站和應用程式中的地圖樣式。在 Google Cloud 控制台專案的「地圖管理」頁面中，您可以為需要的每個平台 (JavaScript、Android、iOS 或靜態地圖) 建立地圖 ID。

如要進一步瞭解地圖 ID 和使用地圖 ID 的功能，請參閱「地圖 ID 總覽」。

所需權限

如要在專案中建立或管理任何地圖 ID，您必須在專案的 Cloud 控制台 IAM 頁面，使用具備適當角色層級權限 (編輯者或擁有者) 的主體。詳情請參閱「IAM 基本與預先定義角色參考資料」。

建立地圖 ID

在 Cloud 控制台中建立地圖 ID，步驟如下：

1. 登入並開啟具有必要權限的 Cloud 控制台專案。

2. 前往 Cloud 控制台中的「地圖管理」頁面。

3. 按一下「建立地圖 ID」。

   

4. 在「建立新地圖 ID」頁面中，執行下列操作：

   1. 在「Name」(名稱) 中為地圖 ID 命名。
   2. 選用：在「說明」中，說明地圖 ID 的用途。
   3. 在「地圖類型」中，選取您打算使用地圖 ID 的平台。 如果您選擇 JavaScript，請同時選擇「光柵」 (預設) 或「向量」地圖類型。如要進一步瞭解向量地圖，請參閱「向量地圖」。
   4. 按一下「儲存」，即可查看新的地圖 ID。

將地圖 ID 與地圖樣式建立關聯

如果您使用雲端式地圖樣式設定，請將地圖樣式與地圖 ID 建立關聯。詳情請參閱「將樣式與地圖 ID 建立關聯」。

在應用程式中加入地圖 ID

Android

您可以使用 MapView 類別 (或藉由程式輔助方式使用 GoogleMapOptions 類別)，透過活動版面配置檔案中的 <fragment> 元素來新增地圖 ID。

舉例來說，假設您建立了名為 map_id 的地圖 ID，並以字串值形式儲存於 res/values/strings.xml 中：

<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="map_id">MAP_ID</string>
</resources>

如果是透過活動版面配置檔案中的 <fragment> 元素新增的地圖，所有要設定自訂樣式的地圖片段都必須在 map:mapId 屬性中指定地圖 ID：

<fragment xmlns:map="http://schemas.android.com/apk/res-auto"
    map:name="com.google.android.gms.maps.SupportMapFragment"
    …
    map:mapId="@string/map_id" />

您也可以使用 MapView 類別的 map:mapId 屬性指定地圖 ID：

<com.google.android.gms.maps.MapView
    xmlns:map="http://schemas.android.com/apk/res-auto"
    ....
    map:mapId="@string/map_id" />

如要透過程式輔助方式指定地圖 ID，請使用 GoogleMapOptions 類別將 ID 傳送至 MapFragment 例項：

Java

 MapFragment mapFragment = MapFragment.newInstance(
     new GoogleMapOptions()
         .mapId(getResources().getString(R.string.map_id)));

Kotlin

 val mapFragment = MapFragment.newInstance(
     GoogleMapOptions()
         .mapId(resources.getString(R.string.map_id))
 )

在 Android Studio 中，按照平常的操作方式建構及執行應用程式。在第一個步驟中設定的自訂樣式會套用至所有具備指定地圖 ID 的地圖。

Android 3D

以程式輔助方式或使用版面配置屬性，將 mapId 字串屬性設為 Map3DOptions。Map3DOptions 會在例項化期間提供給 Map3DView 物件，且 Map3DView 建構完成後就無法變更。

開發人員可以選擇實作新的 OnMapIdErrorListener，以便在系統偵測到無效或找不到的地圖 ID 時收到通知並做出反應。

新增地圖 ID、以程式輔助方式建立地圖，並設定 OnMapIdErrorListener：

import com.google.android.gms.maps3d.GoogleMap3D
import com.google.android.gms.maps3d.Map3DOptions
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.OnMap3DViewReadyCallback
import com.google.android.gms.maps3d.model.Map3DMode

class MainActivity : Activity(), OnMap3DViewReadyCallback, OnMapIdError {
  fun onCreate(...) {
    val map3DOptions = Map3DOptions(mapMode = Map3DMode.HYBRID, mapId = "MAP_ID")
    val map3DView = Map3DView(context, map3DOptions)
    map3DView.getMap3dViewAsync(this)
  }

  override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
    googleMap3D.setMapIdErrorListener(
      object : OnMapIdErrorListener {
        override fun onMapIdError() {
          // Handle error event.
        }
      }
    )
  }
}

使用版面配置屬性新增地圖 ID：

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout
   xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:map3d="http://schemas.android.com/apk/res-auto"
   android:layout_width="match_parent" android:layout_height="match_parent">
 <com.google.android.gms.maps3d.Map3DView
     android:id="@+id/map3dView"
     android:layout_width="fill_parent"
     android:layout_height="fill_parent"
     map3d:mode="hybrid"
     map3d:mapId="MAP_ID"/>
</LinearLayout>

iOS

如要使用地圖 ID 例項化地圖，請按照下列步驟操作：

1. 使用 Cloud 控制台中的地圖 ID 字串建立 GMSMapID。
2. 建立 GMSMapView，並指定您剛建立的地圖 ID。

Swift

let camera = GMSCameraPosition(latitude: 47.0169, longitude: -122.336471, zoom: 12)
let mapID = GMSMapID(identifier: "MAP_ID")
let mapView = GMSMapView(frame: .zero, mapID: mapID, camera: camera)
self.view = mapView

Objective-C

GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:47.0169
                                                        longitude:-122.336471
                                                             zoom:12];
GMSMapID *mapID = [GMSMapID mapIDWithIdentifier:@"MAP_ID"];
GMSMapView *mapView = [GMSMapView mapWithFrame:CGRectZero mapID:mapID camera:camera];
self.view = mapView;

如果您使用自己的地圖 ID，隨時可以在 Cloud 控制台中設定地圖 ID 的新樣式，大約六小時後，您和使用者就會在自己的地圖檢視畫面中看到新樣式。

如要立即查看變更，請關閉並重新啟動應用程式：先退出應用程式，然後從最近使用的應用程式清單強制結束應用程式，再重新開啟。隨即會顯示更新後的地圖。

iOS 3D

iOS 開發人員可以在 Map 上設定新的 style 修飾符。這個修飾符會接受地圖 ID，並視需要接受在 ID 無效或找不到時叫用的閉包。

import SwiftUI
import GoogleMaps3D

struct ContentView: View {
  init () {
    Map.apiKey = "YOUR_API_KEY"
  }
  var body: some View {
    Map(initialCamera: .init(
        latitude: 0.0,
        longitude: 0.0,
      ),
      mode: .hybrid
    )
    .style(
      with: "MAP_ID",
      error: {
        // Handle styling error.
      }
    )
    // Could also use trailing closure syntax
    //  .style(with: "MAP_ID") {
    //     // Handle styling error.
    //  }
  }
}

JavaScript

如要在應用程式程式碼中建立含有地圖 ID 的地圖，請按照下列步驟操作：

1. 如果您已使用內嵌的 JSON 程式碼自訂地圖，請從 MapOptions 物件中移除 styles 屬性；否則請略過這個步驟。

2. 使用 mapId 屬性在地圖中新增地圖 ID。例如：

map = new google.maps.Map(document.getElementById('map'), {
center: {lat: -34.397, lng: 150.644},
zoom: 8,
mapId: 'MAP_ID'
});

JavaScript 3D

如要在應用程式中建立含有地圖 ID 的地圖，請使用 mapId 屬性將地圖 ID 新增至地圖。例如：

async function init() {
    const { Map3DElement } = await google.maps.importLibrary('maps3d');

    const map = new Map3DElement({
        center: {
            lat: 37.75183154601466,
            lng: -119.52369070507672,
            altitude: 2200,
        },
        tilt: 67.5,
        heading: 108.94057782079429,
        range: 6605.57279990986,
        mapId: 'bcce776b92de1336e22c569f', // Styles are associated with map IDs.
        mode: 'HYBRID',
    });

    document.body.append(map);
}

void init();
index.js

靜態地圖介面集

如要將地圖 ID 新增至使用其中一個網路服務 API 的新地圖或現有地圖，請附加 map_id 網址參數，並將其設為地圖 ID。這個範例說明如何使用 Maps Static API，在地圖中加入地圖 ID。

<img src="https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318&markers=color:red%7Clabel:C%7C40.718217,-73.998284&key=YOUR_API_KEY&map_id=MAP_ID&signature=YOUR_SIGNATURE" />

如果在地圖 ID 之前，地圖靜態網址中已有數位簽章，您必須在加入地圖 ID 後建立並新增新的數位簽章。產生新的網址簽署密鑰時，請記得從網址中移除先前的數位簽章。