開始使用

本指南提供快速入門說明,協助您建立可顯示地圖的 Android 應用程式。 使用 Maps SDK for Android 建立應用程式時,建議選擇 Android Studio 做為開發環境。

步驟 1:下載 Android Studio

按照指南下載安裝 Android Studio。

步驟 2:安裝 Google Play 服務 SDK

Google Play 服務加入 Android Studio。

步驟 3:建立 Google 地圖專案

請按照下列步驟建立包含地圖活動的新應用程式專案:

  1. 啟動 Android Studio。
  2. 建立新專案的步驟如下:
    • 如果系統顯示 [Welcome to Android Studio] (歡迎使用 Android Studio) 對話方塊,請在對話方塊右側的「Quick Start」(快速入門) 下方,選擇 [Start a new Android Studio project] (建立新的 Android Studio 專案)。
    • 否則,請按一下 Android Studio 選單列中的 [File] (檔案),然後依序點選 [New] (新增)、[New Project] (新增專案)。
  3. 在 [Choose your project] (選擇專案) 對話方塊中,選取與您要開發的平台對應的分頁。大部分使用者都會沿用預設選項 [Phone and Tablet] (手機和平板電腦)
  4. 選取 [Google Maps Activity] (Google 地圖活動),然後按一下 [Next] (下一步)。
  5. 輸入應用程式名稱、套件名稱和專案位置、程式設計語言 (Java 或 Kotlin),以及應用程式支援的最低 Android API 級別,然後按一下 [Finish] (完成)。

Android Studio 會啟動 Gradle 並開始建構您的專案。這項作業可能需要幾秒鐘的時間。如要進一步瞭解如何在 Android Studio 中建立專案,請參閱 [Android Studio documentation] (Android Studio 說明文件) > [studio-projects]。

建構完成後,Android Studio 會在編輯器中開啟 google_maps_api.xmlMapsActivity.java 檔案 (請注意,您的活動名稱可能有所不同,但會是您在設定期間採用的名稱)。請注意,執行應用程式之前必須取得 Google Maps API 金鑰,google_maps_api.xml 檔案內含此作業的操作說明。下節將詳細說明如何取得 API 金鑰。

步驟 4:設定 Google Maps API 金鑰

  1. 為專案啟用帳單功能。詳情請參閱建立帳單帳戶
  2. Cloud Console 中,為專案啟用 Maps SDK for Android。詳情請參閱啟用 API
  3. 按照取得 API 金鑰指南說明來取得、新增及限制 API 金鑰。

步驟 5:查看程式碼

檢查範本提供的程式碼。請特別留意 Android Studio 專案中的下列檔案。

XML 版面配置檔案

根據預設,定義應用程式版面配置的 XML 檔案位於 res/layout/activity_maps.xml,其中包含以下程式碼:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

地圖活動 Java 檔案

根據預設,定義地圖活動的 Java 檔案名稱為 MapsActivity.java,且套件名稱後面應包含下列程式碼:

Java

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      

Kotlin

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example.kotlin

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions
import com.google.maps.example.R

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}
      

如果您的地圖活動檔案未包含上述程式碼,請以上述程式碼取代套件名稱後面的檔案內容。

步驟 6:連結 Android 裝置

如要查看應用程式的實際運作情形,最簡單的方法是將 Android 裝置與電腦連結。按照操作說明為 Android 裝置啟用開發人員選項,並將應用程式和系統設定為偵測裝置。

或者,您也可以使用 Android Emulator 來執行應用程式。建構和執行應用程式時,可以搭配 Android Emulator 使用 Android 虛擬裝置管理程式 (AVD Manager),設定一或多個虛擬裝置。選擇模擬器時,請務必使用 Android 4.1.1 以上版本,並謹慎挑選內含 Google API 的映像檔,否則應用程式缺少必要的執行階段 API,將無法正常運作。此外,請記下設定虛擬機器加速的操作說明,並按指示搭配 x86 目標 Android 虛擬裝置進行作業,這有助於改善模擬器使用體驗。

步驟 7:部署及執行應用程式

在 Android Studio 中,按一下 [Run] (執行) 選單選項 (或播放按鈕圖示) 來執行應用程式。

系統提示您選擇裝置時,請選擇下列其中一個選項:

  • 選取與您電腦連結的 Android 裝置。
  • 或者,選取 [Launch emulator] (啟動模擬器) 圓形按鈕,然後選擇先前設定的虛擬裝置。

按一下 [OK] (確定)。Android Studio 將叫用 Gradle 來建構應用程式,然後在裝置或模擬器上顯示結果。開啟應用程式可能需要幾分鐘的時間。

後續步驟

建議您參考一些程式碼範例

如要進一步瞭解地圖物件,請參閱開發人員指南。