加入含有標記的地圖

本教學課程說明如何在 Android 應用程式中加入 Google 地圖。地圖中包含一個標記 (也稱為圖釘),用以表示特定位置。

請按照教學課程,使用 Maps SDK for Android 建構 Android 應用程式。建議的開發環境為 Android Studio

取得程式碼

從 GitHub 複製或下載 Google Maps Android API 第 2 版範例存放區

設定您的開發專案

如要在 Android Studio 中建立教學課程專案,請按照下列步驟操作。

  1. 下載安裝 Android Studio。
  2. Google Play 服務套件加入 Android Studio。
  3. 如果您在閱讀本教學課程時尚未複製或下載 Google Maps Android API 第 2 版範例存放區,請先複製或下載。
  4. 匯入教學課程專案:

    • 在 Android Studio 中,選取 [File] (檔案) > [New] (新增) > [Import Project] (匯入專案)
    • 下載完成後,請前往您儲存 Google Maps Android API 第 2 版範例存放區的位置。
    • 在這個位置找到 MapWithMarker 專案:
      PATH-TO-SAVED-REPO/android-samples/tutorials/MapWithMarker
    • 選取專案目錄,然後按一下 [OK] (確定)。Android Studio 現在會使用 Gradle 建構工具來建立您的專案。

取得 API 金鑰並啟用必要的 API

如想完成本教學課程,您必須取得獲授權使用 Maps SDK for Android 的 Google API 金鑰。

點選下方按鈕即可取得金鑰並啟用 API。

開始使用

詳情請參閱取得 API 金鑰的完整指南。

在應用程式中加入 API 金鑰

  1. 編輯專案的 gradle.properties 檔案。
  2. 將 API 金鑰貼到 GOOGLE_MAPS_API_KEY 屬性的值中。在您建構應用程式時,Gradle 會將 API 金鑰複製到應用程式的 Android 資訊清單中,如下文所述。

    GOOGLE_MAPS_API_KEY=PASTE-YOUR-API-KEY-HERE
    

建構並執行應用程式

  1. 將 Android 裝置連接到電腦。按照操作說明為 Android 裝置啟用開發人員選項,並將系統設定為偵測裝置 (您也可以使用 Android Virtual Device (AVD) Manager 來設定虛擬裝置。選擇模擬器時,請務必挑選包含 Google API 的映像檔。詳情請參閱入門指南)。
  2. 在 Android Studio 中,按一下 [Run] (執行) 選單選項 (或播放按鈕圖示), 然後按照系統提示選擇裝置。

Android Studio 會叫用 Gradle 來建構應用程式,然後在裝置或模擬器上執行應用程式。您應該會看到地圖,上面有一個標記指向澳洲東海岸的雪梨,與本頁中的圖片類似。

疑難排解:

  • 如果您未看到地圖,請按照上述步驟,檢查您是否已取得 API 金鑰並將其加入應用程式。在 Android Studio 查看 Android Monitor 中的記錄檔,看看是否有關於 API 金鑰的錯誤訊息。
  • 使用 Android Studio 偵錯工具查看記錄檔並為應用程式偵錯。

瞭解程式碼

本教學課程這一段將說明 MapWithMarker 應用程式最重要的部分,協助您瞭解如何建構類似的應用程式。

檢查您的 Android 資訊清單

請注意應用程式 AndroidManifest.xml 檔案中的下列元素:

  • 新增 meta-data 元素,以嵌入用來編譯應用程式的 Google Play 服務版本。

    <meta-data
        android:name="com.google.android.gms.version"
        android:value="@integer/google_play_services_version" />
    
  • 新增指定 API 金鑰的 meta-data 元素。本教學課程隨附的範例會將 API 金鑰的值對應至字串 google_maps_key。 在您建構應用程式時,Gradle 會將 API 金鑰從專案的 gradle.properties 檔案複製到字串值。

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

    如要瞭解 API 金鑰如何對應至字串值,請查看應用程式的 build.gradle。其中會包含以下這一行,將 google_maps_key 字串對應至 gradle 屬性 GOOGLE_MAPS_API_KEY

      resValue "string", "google_maps_key",
              (project.findProperty("GOOGLE_MAPS_API_KEY") ?: "")
    

以下是完整資訊清單的範例:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.mapwithmarker">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <meta-data
            android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />

        <!--
             The API key for Google Maps-based APIs.
        -->
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="@string/google_maps_key" />

        <activity
            android:name=".MapsMarkerActivity"
            android:label="@string/title_activity_maps">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

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

</manifest>

新增地圖

使用 Maps SDK for Android 顯示地圖。

  1. 在活動的版面配置檔案 activity_maps.xml 中加入 <fragment> 元素。這個元素會將 SupportMapFragment 定義為地圖的容器並提供 GoogleMap 物件的存取權。本教學課程使用 Android 支援資料庫版本的地圖片段,確保與舊版 Android 架構能回溯相容。

    <fragment xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:context="com.example.mapwithmarker.MapsMarkerActivity" />
    
    
  2. 在活動的 onCreate() 方法中,將版面配置檔案設為內容檢視畫面。呼叫 FragmentManager.findFragmentById() 以取得地圖片段的處理常式,然後使用 getMapAsync() 註冊地圖回呼:

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps);
        // Get the SupportMapFragment and request notification
        // when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }
    
  3. 導入 OnMapReadyCallback 介面並覆寫 onMapReady() 方法,以便在 GoogleMap 物件可用時設定地圖:

    public class MapsMarkerActivity extends AppCompatActivity
            implements OnMapReadyCallback {
        // Include the OnCreate() method here too, as described above.
        @Override
        public void onMapReady(GoogleMap googleMap) {
            // Add a marker in Sydney, Australia,
            // and move the map's camera to the same location.
            LatLng sydney = new LatLng(-33.852, 151.211);
            googleMap.addMarker(new MarkerOptions().position(sydney)
                    .title("Marker in Sydney"));
            googleMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
        }
    }
    

根據預設,Maps SDK for Android 會在使用者輕觸標記時顯示資訊視窗的內容。如果您可以接受使用預設行為,就不需要為標記新增點擊事件監聽器。

後續步驟

進一步瞭解地圖物件以及標記的用途。