在地圖上選取 [目前位置] 和 [顯示詳細資訊]

本教學課程說明如何找出 Android 裝置的目前位置,並顯示該位置 (商家或其他搜尋點) 的詳細資訊。按照本教學課程,使用 Google Play 服務 location API 中的 Maps SDK for AndroidPlaces SDK for Android整合式位置預測提供工具來建立 Android 應用程式。

取得程式碼

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

查看 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.example.currentplacedetailsonmap;

import android.content.DialogInterface;
import android.content.pm.PackageManager;
import android.location.Location;
import android.os.Bundle;

import android.util.Log;
import android.view.Menu;
import android.view.MenuItem;
import android.view.View;
import android.widget.FrameLayout;
import android.widget.TextView;

import androidx.annotation.NonNull;
import androidx.appcompat.app.AlertDialog;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

import com.google.android.gms.location.FusedLocationProviderClient;
import com.google.android.gms.location.LocationServices;
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.CameraPosition;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.Marker;
import com.google.android.gms.maps.model.MarkerOptions;
import com.google.android.gms.tasks.OnCompleteListener;
import com.google.android.gms.tasks.Task;

import com.google.android.libraries.places.api.Places;
import com.google.android.libraries.places.api.model.Place;
import com.google.android.libraries.places.api.model.PlaceLikelihood;
import com.google.android.libraries.places.api.net.FindCurrentPlaceRequest;
import com.google.android.libraries.places.api.net.FindCurrentPlaceResponse;
import com.google.android.libraries.places.api.net.PlacesClient;

import java.util.Arrays;
import java.util.List;

/**
 * An activity that displays a map showing the place at the device's current location.
 */
public class MapsActivityCurrentPlace extends AppCompatActivity
        implements OnMapReadyCallback {

    private static final String TAG = MapsActivityCurrentPlace.class.getSimpleName();
    private GoogleMap map;
    private CameraPosition cameraPosition;

    // The entry point to the Places API.
    private PlacesClient placesClient;

    // The entry point to the Fused Location Provider.
    private FusedLocationProviderClient fusedLocationProviderClient;

    // A default location (Sydney, Australia) and default zoom to use when location permission is
    // not granted.
    private final LatLng defaultLocation = new LatLng(-33.8523341, 151.2106085);
    private static final int DEFAULT_ZOOM = 15;
    private static final int PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION = 1;
    private boolean locationPermissionGranted;

    // The geographical location where the device is currently located. That is, the last-known
    // location retrieved by the Fused Location Provider.
    private Location lastKnownLocation;

    // Keys for storing activity state.
    private static final String KEY_CAMERA_POSITION = "camera_position";
    private static final String KEY_LOCATION = "location";

    // Used for selecting the current place.
    private static final int M_MAX_ENTRIES = 5;
    private String[] likelyPlaceNames;
    private String[] likelyPlaceAddresses;
    private List[] likelyPlaceAttributions;
    private LatLng[] likelyPlaceLatLngs;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Retrieve location and camera position from saved instance state.
        if (savedInstanceState != null) {
            lastKnownLocation = savedInstanceState.getParcelable(KEY_LOCATION);
            cameraPosition = savedInstanceState.getParcelable(KEY_CAMERA_POSITION);
        }

        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps);

        // Construct a PlacesClient
        Places.initialize(getApplicationContext(), BuildConfig.MAPS_API_KEY);
        placesClient = Places.createClient(this);

        // Construct a FusedLocationProviderClient.
        fusedLocationProviderClient = LocationServices.getFusedLocationProviderClient(this);

        // Build the map.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Saves the state of the map when the activity is paused.
     */
    @Override
    protected void onSaveInstanceState(Bundle outState) {
        if (map != null) {
            outState.putParcelable(KEY_CAMERA_POSITION, map.getCameraPosition());
            outState.putParcelable(KEY_LOCATION, lastKnownLocation);
        }
        super.onSaveInstanceState(outState);
    }

    /**
     * Sets up the options menu.
     * @param menu The options menu.
     * @return Boolean.
     */
    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        getMenuInflater().inflate(R.menu.current_place_menu, menu);
        return true;
    }

    /**
     * Handles a click on the menu option to get a place.
     * @param item The menu item to handle.
     * @return Boolean.
     */
    @Override
    public boolean onOptionsItemSelected(MenuItem item) {
        if (item.getItemId() == R.id.option_get_place) {
            showCurrentPlace();
        }
        return true;
    }

    /**
     * Manipulates the map when it's available.
     * This callback is triggered when the map is ready to be used.
     */
    @Override
    public void onMapReady(GoogleMap map) {
        this.map = map;

        // Use a custom info window adapter to handle multiple lines of text in the
        // info window contents.
        this.map.setInfoWindowAdapter(new GoogleMap.InfoWindowAdapter() {

            @Override
            // Return null here, so that getInfoContents() is called next.
            public View getInfoWindow(Marker arg0) {
                return null;
            }

            @Override
            public View getInfoContents(Marker marker) {
                // Inflate the layouts for the info window, title and snippet.
                View infoWindow = getLayoutInflater().inflate(R.layout.custom_info_contents,
                        (FrameLayout) findViewById(R.id.map), false);

                TextView title = infoWindow.findViewById(R.id.title);
                title.setText(marker.getTitle());

                TextView snippet = infoWindow.findViewById(R.id.snippet);
                snippet.setText(marker.getSnippet());

                return infoWindow;
            }
        });

        // Prompt the user for permission.
        getLocationPermission();

        // Turn on the My Location layer and the related control on the map.
        updateLocationUI();

        // Get the current location of the device and set the position of the map.
        getDeviceLocation();
    }

    /**
     * Gets the current location of the device, and positions the map's camera.
     */
    private void getDeviceLocation() {
        /*
         * Get the best and most recent location of the device, which may be null in rare
         * cases when a location is not available.
         */
        try {
            if (locationPermissionGranted) {
                Task<Location> locationResult = fusedLocationProviderClient.getLastLocation();
                locationResult.addOnCompleteListener(this, new OnCompleteListener<Location>() {
                    @Override
                    public void onComplete(@NonNull Task<Location> task) {
                        if (task.isSuccessful()) {
                            // Set the map's camera position to the current location of the device.
                            lastKnownLocation = task.getResult();
                            if (lastKnownLocation != null) {
                                map.moveCamera(CameraUpdateFactory.newLatLngZoom(
                                        new LatLng(lastKnownLocation.getLatitude(),
                                                lastKnownLocation.getLongitude()), DEFAULT_ZOOM));
                            }
                        } else {
                            Log.d(TAG, "Current location is null. Using defaults.");
                            Log.e(TAG, "Exception: %s", task.getException());
                            map.moveCamera(CameraUpdateFactory
                                    .newLatLngZoom(defaultLocation, DEFAULT_ZOOM));
                            map.getUiSettings().setMyLocationButtonEnabled(false);
                        }
                    }
                });
            }
        } catch (SecurityException e)  {
            Log.e("Exception: %s", e.getMessage(), e);
        }
    }

    /**
     * Prompts the user for permission to use the device location.
     */
    private void getLocationPermission() {
        /*
         * Request location permission, so that we can get the location of the
         * device. The result of the permission request is handled by a callback,
         * onRequestPermissionsResult.
         */
        if (ContextCompat.checkSelfPermission(this.getApplicationContext(),
                android.Manifest.permission.ACCESS_FINE_LOCATION)
                == PackageManager.PERMISSION_GRANTED) {
            locationPermissionGranted = true;
        } else {
            ActivityCompat.requestPermissions(this,
                    new String[]{android.Manifest.permission.ACCESS_FINE_LOCATION},
                    PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
        }
    }

    /**
     * Handles the result of the request for location permissions.
     */
    @Override
    public void onRequestPermissionsResult(int requestCode,
                                           @NonNull String[] permissions,
                                           @NonNull int[] grantResults) {
        locationPermissionGranted = false;
        switch (requestCode) {
            case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION: {
                // If request is cancelled, the result arrays are empty.
                if (grantResults.length > 0
                        && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                    locationPermissionGranted = true;
                }
            }
        }
        updateLocationUI();
    }

    /**
     * Prompts the user to select the current place from a list of likely places, and shows the
     * current place on the map - provided the user has granted location permission.
     */
    private void showCurrentPlace() {
        if (map == null) {
            return;
        }

        if (locationPermissionGranted) {
            // Use fields to define the data types to return.
            List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.ADDRESS,
                    Place.Field.LAT_LNG);

            // Use the builder to create a FindCurrentPlaceRequest.
            FindCurrentPlaceRequest request =
                    FindCurrentPlaceRequest.newInstance(placeFields);

            // Get the likely places - that is, the businesses and other points of interest that
            // are the best match for the device's current location.
            @SuppressWarnings("MissingPermission") final
            Task<FindCurrentPlaceResponse> placeResult =
                    placesClient.findCurrentPlace(request);
            placeResult.addOnCompleteListener (new OnCompleteListener<FindCurrentPlaceResponse>() {
                @Override
                public void onComplete(@NonNull Task<FindCurrentPlaceResponse> task) {
                    if (task.isSuccessful() && task.getResult() != null) {
                        FindCurrentPlaceResponse likelyPlaces = task.getResult();

                        // Set the count, handling cases where less than 5 entries are returned.
                        int count;
                        if (likelyPlaces.getPlaceLikelihoods().size() < M_MAX_ENTRIES) {
                            count = likelyPlaces.getPlaceLikelihoods().size();
                        } else {
                            count = M_MAX_ENTRIES;
                        }

                        int i = 0;
                        likelyPlaceNames = new String[count];
                        likelyPlaceAddresses = new String[count];
                        likelyPlaceAttributions = new List[count];
                        likelyPlaceLatLngs = new LatLng[count];

                        for (PlaceLikelihood placeLikelihood : likelyPlaces.getPlaceLikelihoods()) {
                            // Build a list of likely places to show the user.
                            likelyPlaceNames[i] = placeLikelihood.getPlace().getName();
                            likelyPlaceAddresses[i] = placeLikelihood.getPlace().getAddress();
                            likelyPlaceAttributions[i] = placeLikelihood.getPlace()
                                    .getAttributions();
                            likelyPlaceLatLngs[i] = placeLikelihood.getPlace().getLatLng();

                            i++;
                            if (i > (count - 1)) {
                                break;
                            }
                        }

                        // Show a dialog offering the user the list of likely places, and add a
                        // marker at the selected place.
                        MapsActivityCurrentPlace.this.openPlacesDialog();
                    }
                    else {
                        Log.e(TAG, "Exception: %s", task.getException());
                    }
                }
            });
        } else {
            // The user has not granted permission.
            Log.i(TAG, "The user did not grant location permission.");

            // Add a default marker, because the user hasn't selected a place.
            map.addMarker(new MarkerOptions()
                    .title(getString(R.string.default_info_title))
                    .position(defaultLocation)
                    .snippet(getString(R.string.default_info_snippet)));

            // Prompt the user for permission.
            getLocationPermission();
        }
    }

    /**
     * Displays a form allowing the user to select a place from a list of likely places.
     */
    private void openPlacesDialog() {
        // Ask the user to choose the place where they are now.
        DialogInterface.OnClickListener listener = new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialog, int which) {
                // The "which" argument contains the position of the selected item.
                LatLng markerLatLng = likelyPlaceLatLngs[which];
                String markerSnippet = likelyPlaceAddresses[which];
                if (likelyPlaceAttributions[which] != null) {
                    markerSnippet = markerSnippet + "\n" + likelyPlaceAttributions[which];
                }

                // Add a marker for the selected place, with an info window
                // showing information about that place.
                map.addMarker(new MarkerOptions()
                        .title(likelyPlaceNames[which])
                        .position(markerLatLng)
                        .snippet(markerSnippet));

                // Position the map's camera at the location of the marker.
                map.moveCamera(CameraUpdateFactory.newLatLngZoom(markerLatLng,
                        DEFAULT_ZOOM));
            }
        };

        // Display the dialog.
        AlertDialog dialog = new AlertDialog.Builder(this)
                .setTitle(R.string.pick_place)
                .setItems(likelyPlaceNames, listener)
                .show();
    }

    /**
     * Updates the map's UI settings based on whether the user has granted location permission.
     */
    private void updateLocationUI() {
        if (map == null) {
            return;
        }
        try {
            if (locationPermissionGranted) {
                map.setMyLocationEnabled(true);
                map.getUiSettings().setMyLocationButtonEnabled(true);
            } else {
                map.setMyLocationEnabled(false);
                map.getUiSettings().setMyLocationButtonEnabled(false);
                lastKnownLocation = null;
                getLocationPermission();
            }
        } catch (SecurityException e)  {
            Log.e("Exception: %s", e.getMessage());
        }
    }
}

    

查看 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.example.currentplacedetailsonmap

import android.Manifest
import android.annotation.SuppressLint
import android.content.DialogInterface
import android.content.pm.PackageManager
import android.location.Location
import android.os.Bundle
import android.util.Log
import android.view.Menu
import android.view.MenuItem
import android.view.View
import android.widget.FrameLayout
import android.widget.TextView
import androidx.appcompat.app.AlertDialog
import androidx.appcompat.app.AppCompatActivity
import androidx.core.app.ActivityCompat
import androidx.core.content.ContextCompat
import com.google.android.gms.location.FusedLocationProviderClient
import com.google.android.gms.location.LocationServices
import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.GoogleMap.InfoWindowAdapter
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.CameraPosition
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.Marker
import com.google.android.gms.maps.model.MarkerOptions
import com.google.android.libraries.places.api.Places
import com.google.android.libraries.places.api.model.Place
import com.google.android.libraries.places.api.net.FindCurrentPlaceRequest
import com.google.android.libraries.places.api.net.PlacesClient

/**
 * An activity that displays a map showing the place at the device's current location.
 */
class MapsActivityCurrentPlace : AppCompatActivity(), OnMapReadyCallback {
    private var map: GoogleMap? = null
    private var cameraPosition: CameraPosition? = null

    // The entry point to the Places API.
    private lateinit var placesClient: PlacesClient

    // The entry point to the Fused Location Provider.
    private lateinit var fusedLocationProviderClient: FusedLocationProviderClient

    // A default location (Sydney, Australia) and default zoom to use when location permission is
    // not granted.
    private val defaultLocation = LatLng(-33.8523341, 151.2106085)
    private var locationPermissionGranted = false

    // The geographical location where the device is currently located. That is, the last-known
    // location retrieved by the Fused Location Provider.
    private var lastKnownLocation: Location? = null
    private var likelyPlaceNames: Array<String?> = arrayOfNulls(0)
    private var likelyPlaceAddresses: Array<String?> = arrayOfNulls(0)
    private var likelyPlaceAttributions: Array<List<*>?> = arrayOfNulls(0)
    private var likelyPlaceLatLngs: Array<LatLng?> = arrayOfNulls(0)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Retrieve location and camera position from saved instance state.
        if (savedInstanceState != null) {
            lastKnownLocation = savedInstanceState.getParcelable(KEY_LOCATION)
            cameraPosition = savedInstanceState.getParcelable(KEY_CAMERA_POSITION)
        }

        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps)

        // Construct a PlacesClient
        Places.initialize(applicationContext, BuildConfig.MAPS_API_KEY)
        placesClient = Places.createClient(this)

        // Construct a FusedLocationProviderClient.
        fusedLocationProviderClient = LocationServices.getFusedLocationProviderClient(this)

        // Build the map.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment?
        mapFragment?.getMapAsync(this)
    }

    /**
     * Saves the state of the map when the activity is paused.
     */
    override fun onSaveInstanceState(outState: Bundle) {
        map?.let { map ->
            outState.putParcelable(KEY_CAMERA_POSITION, map.cameraPosition)
            outState.putParcelable(KEY_LOCATION, lastKnownLocation)
        }
        super.onSaveInstanceState(outState)
    }

    /**
     * Sets up the options menu.
     * @param menu The options menu.
     * @return Boolean.
     */
    override fun onCreateOptionsMenu(menu: Menu): Boolean {
        menuInflater.inflate(R.menu.current_place_menu, menu)
        return true
    }

    /**
     * Handles a click on the menu option to get a place.
     * @param item The menu item to handle.
     * @return Boolean.
     */
    override fun onOptionsItemSelected(item: MenuItem): Boolean {
        if (item.itemId == R.id.option_get_place) {
            showCurrentPlace()
        }
        return true
    }

    /**
     * Manipulates the map when it's available.
     * This callback is triggered when the map is ready to be used.
     */
    override fun onMapReady(map: GoogleMap) {
        this.map = map

        // Use a custom info window adapter to handle multiple lines of text in the
        // info window contents.
        this.map?.setInfoWindowAdapter(object : InfoWindowAdapter {
            // Return null here, so that getInfoContents() is called next.
            override fun getInfoWindow(arg0: Marker): View? {
                return null
            }

            override fun getInfoContents(marker: Marker): View {
                // Inflate the layouts for the info window, title and snippet.
                val infoWindow = layoutInflater.inflate(R.layout.custom_info_contents,
                    findViewById<FrameLayout>(R.id.map), false)
                val title = infoWindow.findViewById<TextView>(R.id.title)
                title.text = marker.title
                val snippet = infoWindow.findViewById<TextView>(R.id.snippet)
                snippet.text = marker.snippet
                return infoWindow
            }
        })

        // Prompt the user for permission.
        getLocationPermission()

        // Turn on the My Location layer and the related control on the map.
        updateLocationUI()

        // Get the current location of the device and set the position of the map.
        getDeviceLocation()
    }

    /**
     * Gets the current location of the device, and positions the map's camera.
     */
    private fun getDeviceLocation() {
        /*
         * Get the best and most recent location of the device, which may be null in rare
         * cases when a location is not available.
         */
        try {
            if (locationPermissionGranted) {
                val locationResult = fusedLocationProviderClient.lastLocation
                locationResult.addOnCompleteListener(this) { task ->
                    if (task.isSuccessful) {
                        // Set the map's camera position to the current location of the device.
                        lastKnownLocation = task.result
                        if (lastKnownLocation != null) {
                            map?.moveCamera(CameraUpdateFactory.newLatLngZoom(
                                LatLng(lastKnownLocation!!.latitude,
                                    lastKnownLocation!!.longitude), DEFAULT_ZOOM.toFloat()))
                        }
                    } else {
                        Log.d(TAG, "Current location is null. Using defaults.")
                        Log.e(TAG, "Exception: %s", task.exception)
                        map?.moveCamera(CameraUpdateFactory
                            .newLatLngZoom(defaultLocation, DEFAULT_ZOOM.toFloat()))
                        map?.uiSettings?.isMyLocationButtonEnabled = false
                    }
                }
            }
        } catch (e: SecurityException) {
            Log.e("Exception: %s", e.message, e)
        }
    }

    /**
     * Prompts the user for permission to use the device location.
     */
    private fun getLocationPermission() {
        /*
         * Request location permission, so that we can get the location of the
         * device. The result of the permission request is handled by a callback,
         * onRequestPermissionsResult.
         */
        if (ContextCompat.checkSelfPermission(this.applicationContext,
                Manifest.permission.ACCESS_FINE_LOCATION)
            == PackageManager.PERMISSION_GRANTED) {
            locationPermissionGranted = true
        } else {
            ActivityCompat.requestPermissions(this, arrayOf(Manifest.permission.ACCESS_FINE_LOCATION),
                PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION)
        }
    }

    /**
     * Handles the result of the request for location permissions.
     */
    override fun onRequestPermissionsResult(requestCode: Int,
                                            permissions: Array<String>,
                                            grantResults: IntArray) {
        locationPermissionGranted = false
        when (requestCode) {
            PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION -> {

                // If request is cancelled, the result arrays are empty.
                if (grantResults.isNotEmpty() &&
                    grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                    locationPermissionGranted = true
                }
            }
        }
        updateLocationUI()
    }

    /**
     * Prompts the user to select the current place from a list of likely places, and shows the
     * current place on the map - provided the user has granted location permission.
     */
    @SuppressLint("MissingPermission")
    private fun showCurrentPlace() {
        if (map == null) {
            return
        }
        if (locationPermissionGranted) {
            // Use fields to define the data types to return.
            val placeFields = listOf(Place.Field.NAME, Place.Field.ADDRESS, Place.Field.LAT_LNG)

            // Use the builder to create a FindCurrentPlaceRequest.
            val request = FindCurrentPlaceRequest.newInstance(placeFields)

            // Get the likely places - that is, the businesses and other points of interest that
            // are the best match for the device's current location.
            val placeResult = placesClient.findCurrentPlace(request)
            placeResult.addOnCompleteListener { task ->
                if (task.isSuccessful && task.result != null) {
                    val likelyPlaces = task.result

                    // Set the count, handling cases where less than 5 entries are returned.
                    val count = if (likelyPlaces != null && likelyPlaces.placeLikelihoods.size < M_MAX_ENTRIES) {
                        likelyPlaces.placeLikelihoods.size
                    } else {
                        M_MAX_ENTRIES
                    }
                    var i = 0
                    likelyPlaceNames = arrayOfNulls(count)
                    likelyPlaceAddresses = arrayOfNulls(count)
                    likelyPlaceAttributions = arrayOfNulls<List<*>?>(count)
                    likelyPlaceLatLngs = arrayOfNulls(count)
                    for (placeLikelihood in likelyPlaces?.placeLikelihoods ?: emptyList()) {
                        // Build a list of likely places to show the user.
                        likelyPlaceNames[i] = placeLikelihood.place.name
                        likelyPlaceAddresses[i] = placeLikelihood.place.address
                        likelyPlaceAttributions[i] = placeLikelihood.place.attributions
                        likelyPlaceLatLngs[i] = placeLikelihood.place.latLng
                        i++
                        if (i > count - 1) {
                            break
                        }
                    }

                    // Show a dialog offering the user the list of likely places, and add a
                    // marker at the selected place.
                    openPlacesDialog()
                } else {
                    Log.e(TAG, "Exception: %s", task.exception)
                }
            }
        } else {
            // The user has not granted permission.
            Log.i(TAG, "The user did not grant location permission.")

            // Add a default marker, because the user hasn't selected a place.
            map?.addMarker(MarkerOptions()
                .title(getString(R.string.default_info_title))
                .position(defaultLocation)
                .snippet(getString(R.string.default_info_snippet)))

            // Prompt the user for permission.
            getLocationPermission()
        }
    }

    /**
     * Displays a form allowing the user to select a place from a list of likely places.
     */
    private fun openPlacesDialog() {
        // Ask the user to choose the place where they are now.
        val listener = DialogInterface.OnClickListener { dialog, which -> // The "which" argument contains the position of the selected item.
            val markerLatLng = likelyPlaceLatLngs[which]
            var markerSnippet = likelyPlaceAddresses[which]
            if (likelyPlaceAttributions[which] != null) {
                markerSnippet = """
                    $markerSnippet
                    ${likelyPlaceAttributions[which]}
                    """.trimIndent()
            }

            // Add a marker for the selected place, with an info window
            // showing information about that place.
            map?.addMarker(MarkerOptions()
                .title(likelyPlaceNames[which])
                .position(markerLatLng!!)
                .snippet(markerSnippet))

            // Position the map's camera at the location of the marker.
            map?.moveCamera(CameraUpdateFactory.newLatLngZoom(markerLatLng,
                DEFAULT_ZOOM.toFloat()))
        }

        // Display the dialog.
        AlertDialog.Builder(this)
            .setTitle(R.string.pick_place)
            .setItems(likelyPlaceNames, listener)
            .show()
    }

    /**
     * Updates the map's UI settings based on whether the user has granted location permission.
     */
    private fun updateLocationUI() {
        if (map == null) {
            return
        }
        try {
            if (locationPermissionGranted) {
                map?.isMyLocationEnabled = true
                map?.uiSettings?.isMyLocationButtonEnabled = true
            } else {
                map?.isMyLocationEnabled = false
                map?.uiSettings?.isMyLocationButtonEnabled = false
                lastKnownLocation = null
                getLocationPermission()
            }
        } catch (e: SecurityException) {
            Log.e("Exception: %s", e.message, e)
        }
    }

    companion object {
        private val TAG = MapsActivityCurrentPlace::class.java.simpleName
        private const val DEFAULT_ZOOM = 15
        private const val PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION = 1

        // Keys for storing activity state.
        private const val KEY_CAMERA_POSITION = "camera_position"
        private const val KEY_LOCATION = "location"

        // Used for selecting the current place.
        private const val M_MAX_ENTRIES = 5
    }
}

    

設定開發專案

如要在 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 版範例存放區的位置。
    • 在這個位置找到 CurrentPlaceDetailsOnMap 專案:
      PATH-TO-SAVED-REPO/android-samples/tutorials/java/CurrentPlaceDetailsOnMap (Java) 或
      PATH-TO-SAVED-REPO/android-samples/tutorials/kotlin/CurrentPlaceDetailsOnMap (Kotlin)
    • 選取專案目錄,然後按一下 [OK]。Android Studio 現在會使用 Gradle 建構工具來建立您的專案。

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

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

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

開始使用

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

在應用程式中加入 API 金鑰

  1. 開啟專案的 local.properties 檔案。
  2. 加入以下字串,然後將 YOUR_API_KEY 替換成您的 API 金鑰值:

    MAPS_API_KEY=YOUR_API_KEY

    當您建構應用程式時,Secrets Gradle for Android 會複製 API 金鑰,並提供該金鑰做為 Android 資訊清單中的建構變數。

    建構並執行應用程式

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

    Android Studio 會叫用 Gradle 來建構應用程式,然後在裝置或模擬器上執行應用程式。您應該會看到一份地圖,上面有數個以您目前位置為中心的標記,與本頁的圖片類似。

    疑難排解:

    • 如未看到地圖,請確認您是否已按照上述步驟取得 API 金鑰,並將其加入應用程式。在 Android Studio 查看 Android Monitor 中的記錄檔,看看是否有關於 API 金鑰的錯誤訊息。
    • 如果地圖只顯示位於雪梨港灣大橋上的一個標記 (應用程式中指定的預設位置),請檢查您是否已授予應用程式位置存取權。應用程式執行時,會依照 Android 權限指南中所述的模式,提示您授予位置存取權。請注意,您也可以直接在裝置上設定權限,方法是選擇 [設定] > [應用程式] > [應用程式名稱] > [權限] > [位置]。如要進一步瞭解如何透過程式碼處理權限,請參閱下方指南,查看如何在應用程式中要求位置存取權
    • 使用 Android Studio 偵錯工具查看記錄檔並為應用程式偵錯。

    瞭解程式碼

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

    為 Places API 用戶端執行個體化

    下列物件是 Places SDK for Android 的主要進入點:

    • Places 類別會建立及管理 Places SDK for Android 的用戶端。
    • PlaceDetectionClient 介面會擷取裝置目前的所在位置和附近地點。

    LocationServices 介面是 Android 定位服務的主要進入點。

    如要使用 API,請在片段或活動的 onCreate() 方法中執行以下操作:

    1. 初始化 Places 物件。
    2. 建立 PlaceDetectionClient 物件。
    3. 建立 FusedLocationProviderClient 物件。

    舉例來說:

    Java

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    
        // ...
    
        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps);
    
        // Construct a PlacesClient
        Places.initialize(getApplicationContext(), getString(R.string.maps_api_key));
        placesClient = Places.createClient(this);
    
        // Construct a FusedLocationProviderClient.
        fusedLocationProviderClient = LocationServices.getFusedLocationProviderClient(this);
    }
    

    Kotlin

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    
        // ...
    
        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps)
    
        // Construct a PlacesClient
        Places.initialize(applicationContext, getString(R.string.maps_api_key))
        placesClient = Places.createClient(this)
    
        // Construct a FusedLocationProviderClient.
        fusedLocationProviderClient = LocationServices.getFusedLocationProviderClient(this)
    
    }
    

    要求位置存取權

    您的應用程式必須要求位置存取權,才能判斷裝置的位置,並讓使用者能輕觸地圖上的 [我的位置] 按鈕。

    本教學課程會提供可讓您要求精確位置存取權的相關程式碼。 詳情請參閱 Android 權限指南。

    1. 將權限新增為 Android 資訊清單中 <manifest> 元素的子項:

      <manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.currentplacedetailsonmap">
          <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
      </manifest>
      
    2. 在應用程式中要求執行階段權限,讓使用者有機會允許或拒絕位置存取權。下列程式碼會檢查使用者是否已授予精確位置存取權;如果未授予,程式碼就會要求權限:

      Java

      private void getLocationPermission() {
          /*
           * Request location permission, so that we can get the location of the
           * device. The result of the permission request is handled by a callback,
           * onRequestPermissionsResult.
           */
          if (ContextCompat.checkSelfPermission(this.getApplicationContext(),
                  android.Manifest.permission.ACCESS_FINE_LOCATION)
                  == PackageManager.PERMISSION_GRANTED) {
              locationPermissionGranted = true;
          } else {
              ActivityCompat.requestPermissions(this,
                      new String[]{android.Manifest.permission.ACCESS_FINE_LOCATION},
                      PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
          }
      }
      

      Kotlin

      private fun getLocationPermission() {
          /*
           * Request location permission, so that we can get the location of the
           * device. The result of the permission request is handled by a callback,
           * onRequestPermissionsResult.
           */
          if (ContextCompat.checkSelfPermission(this.applicationContext,
                  Manifest.permission.ACCESS_FINE_LOCATION)
              == PackageManager.PERMISSION_GRANTED) {
              locationPermissionGranted = true
          } else {
              ActivityCompat.requestPermissions(this, arrayOf(Manifest.permission.ACCESS_FINE_LOCATION),
                  PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION)
          }
      }
      
    3. 覆寫 onRequestPermissionsResult() 回呼以處理權限要求的結果:

      Java

      @Override
      public void onRequestPermissionsResult(int requestCode,
                                             @NonNull String[] permissions,
                                             @NonNull int[] grantResults) {
          locationPermissionGranted = false;
          switch (requestCode) {
              case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION: {
                  // If request is cancelled, the result arrays are empty.
                  if (grantResults.length > 0
                          && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                      locationPermissionGranted = true;
                  }
              }
          }
          updateLocationUI();
      }
      

      Kotlin

      override fun onRequestPermissionsResult(requestCode: Int,
                                              permissions: Array<String>,
                                              grantResults: IntArray) {
          locationPermissionGranted = false
          when (requestCode) {
              PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION -> {
      
                  // If request is cancelled, the result arrays are empty.
                  if (grantResults.isNotEmpty() &&
                      grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                      locationPermissionGranted = true
                  }
              }
          }
          updateLocationUI()
      }
      

      本教學課程的後續章節會說明 updateLocationUI() 方法。

    新增地圖

    使用 Maps SDK for Android 顯示地圖。

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

      <!--
       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.
      -->
      
      <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.currentplacedetailsonmap.MapsActivityCurrentPlace" />
      
      
    2. 在活動的 onCreate() 方法中,將版面配置檔案設為內容檢視畫面:

      Java

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
      
          // Retrieve the content view that renders the map.
          setContentView(R.layout.activity_maps);
      
      }
      

      Kotlin

      override fun onCreate(savedInstanceState: Bundle?) {
          super.onCreate(savedInstanceState)
      
          // Retrieve the content view that renders the map.
          setContentView(R.layout.activity_maps)
      
      }
      
    3. 導入 OnMapReadyCallback 介面並覆寫 onMapReady() 方法,以便在 GoogleMap 物件可用時設定地圖:

      Java

      @Override
      public void onMapReady(GoogleMap map) {
          this.map = map;
      
          // ...
      
          // Turn on the My Location layer and the related control on the map.
          updateLocationUI();
      
          // Get the current location of the device and set the position of the map.
          getDeviceLocation();
      }
      

      Kotlin

      override fun onMapReady(map: GoogleMap) {
          this.map = map
      
          // ...
      
          // Turn on the My Location layer and the related control on the map.
          updateLocationUI()
      
          // Get the current location of the device and set the position of the map.
          getDeviceLocation()
      }
      
    4. 在活動的 onCreate() 方法中,呼叫 FragmentManager.findFragmentById() 以取得地圖片段的處理常式,然後使用 getMapAsync() 註冊地圖回呼:

      Java

      SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
              .findFragmentById(R.id.map);
      mapFragment.getMapAsync(this);
      

      Kotlin

      val mapFragment = supportFragmentManager
          .findFragmentById(R.id.map) as SupportMapFragment?
      mapFragment?.getMapAsync(this)
      
    5. 撰寫 updateLocationUI() 方法來設定地圖上的位置控制項。如果使用者已授予位置存取權,請在地圖上啟用「我的位置」圖層和相關控制項,否則請停用圖層和控制項,並將目前位置設為空值:

      Java

      private void updateLocationUI() {
          if (map == null) {
              return;
          }
          try {
              if (locationPermissionGranted) {
                  map.setMyLocationEnabled(true);
                  map.getUiSettings().setMyLocationButtonEnabled(true);
              } else {
                  map.setMyLocationEnabled(false);
                  map.getUiSettings().setMyLocationButtonEnabled(false);
                  lastKnownLocation = null;
                  getLocationPermission();
              }
          } catch (SecurityException e)  {
              Log.e("Exception: %s", e.getMessage());
          }
      }
      

      Kotlin

      private fun updateLocationUI() {
          if (map == null) {
              return
          }
          try {
              if (locationPermissionGranted) {
                  map?.isMyLocationEnabled = true
                  map?.uiSettings?.isMyLocationButtonEnabled = true
              } else {
                  map?.isMyLocationEnabled = false
                  map?.uiSettings?.isMyLocationButtonEnabled = false
                  lastKnownLocation = null
                  getLocationPermission()
              }
          } catch (e: SecurityException) {
              Log.e("Exception: %s", e.message, e)
          }
      }
      

    取得 Android 裝置的位置並在地圖上定位

    使用整合式位置預測提供工具,找出裝置的最後已知位置,然後使用該位置來定位地圖。本教學課程會提供您需要的程式碼。如要進一步瞭解如何取得裝置的位置資訊,請參閱 Google Play 服務 location API 中的整合式位置預測提供工具指南。

    Java

    private void getDeviceLocation() {
        /*
         * Get the best and most recent location of the device, which may be null in rare
         * cases when a location is not available.
         */
        try {
            if (locationPermissionGranted) {
                Task<Location> locationResult = fusedLocationProviderClient.getLastLocation();
                locationResult.addOnCompleteListener(this, new OnCompleteListener<Location>() {
                    @Override
                    public void onComplete(@NonNull Task<Location> task) {
                        if (task.isSuccessful()) {
                            // Set the map's camera position to the current location of the device.
                            lastKnownLocation = task.getResult();
                            if (lastKnownLocation != null) {
                                map.moveCamera(CameraUpdateFactory.newLatLngZoom(
                                        new LatLng(lastKnownLocation.getLatitude(),
                                                lastKnownLocation.getLongitude()), DEFAULT_ZOOM));
                            }
                        } else {
                            Log.d(TAG, "Current location is null. Using defaults.");
                            Log.e(TAG, "Exception: %s", task.getException());
                            map.moveCamera(CameraUpdateFactory
                                    .newLatLngZoom(defaultLocation, DEFAULT_ZOOM));
                            map.getUiSettings().setMyLocationButtonEnabled(false);
                        }
                    }
                });
            }
        } catch (SecurityException e)  {
            Log.e("Exception: %s", e.getMessage(), e);
        }
    }
    

    Kotlin

    private fun getDeviceLocation() {
        /*
         * Get the best and most recent location of the device, which may be null in rare
         * cases when a location is not available.
         */
        try {
            if (locationPermissionGranted) {
                val locationResult = fusedLocationProviderClient.lastLocation
                locationResult.addOnCompleteListener(this) { task ->
                    if (task.isSuccessful) {
                        // Set the map's camera position to the current location of the device.
                        lastKnownLocation = task.result
                        if (lastKnownLocation != null) {
                            map?.moveCamera(CameraUpdateFactory.newLatLngZoom(
                                LatLng(lastKnownLocation!!.latitude,
                                    lastKnownLocation!!.longitude), DEFAULT_ZOOM.toFloat()))
                        }
                    } else {
                        Log.d(TAG, "Current location is null. Using defaults.")
                        Log.e(TAG, "Exception: %s", task.exception)
                        map?.moveCamera(CameraUpdateFactory
                            .newLatLngZoom(defaultLocation, DEFAULT_ZOOM.toFloat()))
                        map?.uiSettings?.isMyLocationButtonEnabled = false
                    }
                }
            }
        } catch (e: SecurityException) {
            Log.e("Exception: %s", e.message, e)
        }
    }
    

    取得目前地點

    使用 Places SDK for Android 取得裝置目前位置的可能地點清單。在這種情況下,「地點」是指商家或其他搜尋點。

    本教學課程將示範如何在使用者按一下 [取得地點] 按鈕後顯示目前地點。系統會提供可能的地點清單,讓使用者從中選擇,並在地圖上為該地點新增位置標記。本教學課程會提供您使用 Places SDK for Android 時需要的程式碼。詳情請參閱取得目前地點指南。

    1. 為選項選單建立版面配置檔案 (current_place_menu.xml),並覆寫 onCreateOptionsMenu() 方法來設定選項選單。請參閱隨附的程式碼範例應用程式。
    2. 在使用者按一下 [取得地點] 選項時覆寫 onOptionsItemSelected() 方法,以取得目前地點:

      Java

      @Override
      public boolean onOptionsItemSelected(MenuItem item) {
          if (item.getItemId() == R.id.option_get_place) {
              showCurrentPlace();
          }
          return true;
      }
      

      Kotlin

      override fun onOptionsItemSelected(item: MenuItem): Boolean {
          if (item.itemId == R.id.option_get_place) {
              showCurrentPlace()
          }
          return true
      }
      
    3. 建立 showCurrentPlace() 方法,取得裝置目前位置的可能地點清單:

      Java

      private void showCurrentPlace() {
          if (map == null) {
              return;
          }
      
          if (locationPermissionGranted) {
              // Use fields to define the data types to return.
              List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.ADDRESS,
                      Place.Field.LAT_LNG);
      
              // Use the builder to create a FindCurrentPlaceRequest.
              FindCurrentPlaceRequest request =
                      FindCurrentPlaceRequest.newInstance(placeFields);
      
              // Get the likely places - that is, the businesses and other points of interest that
              // are the best match for the device's current location.
              @SuppressWarnings("MissingPermission") final
              Task<FindCurrentPlaceResponse> placeResult =
                      placesClient.findCurrentPlace(request);
              placeResult.addOnCompleteListener (new OnCompleteListener<FindCurrentPlaceResponse>() {
                  @Override
                  public void onComplete(@NonNull Task<FindCurrentPlaceResponse> task) {
                      if (task.isSuccessful() && task.getResult() != null) {
                          FindCurrentPlaceResponse likelyPlaces = task.getResult();
      
                          // Set the count, handling cases where less than 5 entries are returned.
                          int count;
                          if (likelyPlaces.getPlaceLikelihoods().size() < M_MAX_ENTRIES) {
                              count = likelyPlaces.getPlaceLikelihoods().size();
                          } else {
                              count = M_MAX_ENTRIES;
                          }
      
                          int i = 0;
                          likelyPlaceNames = new String[count];
                          likelyPlaceAddresses = new String[count];
                          likelyPlaceAttributions = new List[count];
                          likelyPlaceLatLngs = new LatLng[count];
      
                          for (PlaceLikelihood placeLikelihood : likelyPlaces.getPlaceLikelihoods()) {
                              // Build a list of likely places to show the user.
                              likelyPlaceNames[i] = placeLikelihood.getPlace().getName();
                              likelyPlaceAddresses[i] = placeLikelihood.getPlace().getAddress();
                              likelyPlaceAttributions[i] = placeLikelihood.getPlace()
                                      .getAttributions();
                              likelyPlaceLatLngs[i] = placeLikelihood.getPlace().getLatLng();
      
                              i++;
                              if (i > (count - 1)) {
                                  break;
                              }
                          }
      
                          // Show a dialog offering the user the list of likely places, and add a
                          // marker at the selected place.
                          MapsActivityCurrentPlace.this.openPlacesDialog();
                      }
                      else {
                          Log.e(TAG, "Exception: %s", task.getException());
                      }
                  }
              });
          } else {
              // The user has not granted permission.
              Log.i(TAG, "The user did not grant location permission.");
      
              // Add a default marker, because the user hasn't selected a place.
              map.addMarker(new MarkerOptions()
                      .title(getString(R.string.default_info_title))
                      .position(defaultLocation)
                      .snippet(getString(R.string.default_info_snippet)));
      
              // Prompt the user for permission.
              getLocationPermission();
          }
      }
      

      Kotlin

      @SuppressLint("MissingPermission")
      private fun showCurrentPlace() {
          if (map == null) {
              return
          }
          if (locationPermissionGranted) {
              // Use fields to define the data types to return.
              val placeFields = listOf(Place.Field.NAME, Place.Field.ADDRESS, Place.Field.LAT_LNG)
      
              // Use the builder to create a FindCurrentPlaceRequest.
              val request = FindCurrentPlaceRequest.newInstance(placeFields)
      
              // Get the likely places - that is, the businesses and other points of interest that
              // are the best match for the device's current location.
              val placeResult = placesClient.findCurrentPlace(request)
              placeResult.addOnCompleteListener { task ->
                  if (task.isSuccessful && task.result != null) {
                      val likelyPlaces = task.result
      
                      // Set the count, handling cases where less than 5 entries are returned.
                      val count = if (likelyPlaces != null && likelyPlaces.placeLikelihoods.size < M_MAX_ENTRIES) {
                          likelyPlaces.placeLikelihoods.size
                      } else {
                          M_MAX_ENTRIES
                      }
                      var i = 0
                      likelyPlaceNames = arrayOfNulls(count)
                      likelyPlaceAddresses = arrayOfNulls(count)
                      likelyPlaceAttributions = arrayOfNulls<List<*>?>(count)
                      likelyPlaceLatLngs = arrayOfNulls(count)
                      for (placeLikelihood in likelyPlaces?.placeLikelihoods ?: emptyList()) {
                          // Build a list of likely places to show the user.
                          likelyPlaceNames[i] = placeLikelihood.place.name
                          likelyPlaceAddresses[i] = placeLikelihood.place.address
                          likelyPlaceAttributions[i] = placeLikelihood.place.attributions
                          likelyPlaceLatLngs[i] = placeLikelihood.place.latLng
                          i++
                          if (i > count - 1) {
                              break
                          }
                      }
      
                      // Show a dialog offering the user the list of likely places, and add a
                      // marker at the selected place.
                      openPlacesDialog()
                  } else {
                      Log.e(TAG, "Exception: %s", task.exception)
                  }
              }
          } else {
              // The user has not granted permission.
              Log.i(TAG, "The user did not grant location permission.")
      
              // Add a default marker, because the user hasn't selected a place.
              map?.addMarker(MarkerOptions()
                  .title(getString(R.string.default_info_title))
                  .position(defaultLocation)
                  .snippet(getString(R.string.default_info_snippet)))
      
              // Prompt the user for permission.
              getLocationPermission()
          }
      }
      
    4. 建立 openPlacesDialog() 方法以顯示表單,讓使用者從可能的地點清單中選取地點。在地圖上為已選取的地點新增標記。標記內容包含地點的名稱和地址,以及 API 提供的任何屬性:

      Java

      private void openPlacesDialog() {
          // Ask the user to choose the place where they are now.
          DialogInterface.OnClickListener listener = new DialogInterface.OnClickListener() {
              @Override
              public void onClick(DialogInterface dialog, int which) {
                  // The "which" argument contains the position of the selected item.
                  LatLng markerLatLng = likelyPlaceLatLngs[which];
                  String markerSnippet = likelyPlaceAddresses[which];
                  if (likelyPlaceAttributions[which] != null) {
                      markerSnippet = markerSnippet + "\n" + likelyPlaceAttributions[which];
                  }
      
                  // Add a marker for the selected place, with an info window
                  // showing information about that place.
                  map.addMarker(new MarkerOptions()
                          .title(likelyPlaceNames[which])
                          .position(markerLatLng)
                          .snippet(markerSnippet));
      
                  // Position the map's camera at the location of the marker.
                  map.moveCamera(CameraUpdateFactory.newLatLngZoom(markerLatLng,
                          DEFAULT_ZOOM));
              }
          };
      
          // Display the dialog.
          AlertDialog dialog = new AlertDialog.Builder(this)
                  .setTitle(R.string.pick_place)
                  .setItems(likelyPlaceNames, listener)
                  .show();
      }
      

      Kotlin

      private fun openPlacesDialog() {
          // Ask the user to choose the place where they are now.
          val listener = DialogInterface.OnClickListener { dialog, which -> // The "which" argument contains the position of the selected item.
              val markerLatLng = likelyPlaceLatLngs[which]
              var markerSnippet = likelyPlaceAddresses[which]
              if (likelyPlaceAttributions[which] != null) {
                  markerSnippet = """
                      $markerSnippet
                      ${likelyPlaceAttributions[which]}
                      """.trimIndent()
              }
      
              // Add a marker for the selected place, with an info window
              // showing information about that place.
              map?.addMarker(MarkerOptions()
                  .title(likelyPlaceNames[which])
                  .position(markerLatLng!!)
                  .snippet(markerSnippet))
      
              // Position the map's camera at the location of the marker.
              map?.moveCamera(CameraUpdateFactory.newLatLngZoom(markerLatLng,
                  DEFAULT_ZOOM.toFloat()))
          }
      
          // Display the dialog.
          AlertDialog.Builder(this)
              .setTitle(R.string.pick_place)
              .setItems(likelyPlaceNames, listener)
              .show()
      }
      
    5. 為資訊視窗內容建立自訂版面配置,這樣就能在資訊視窗中顯示多行內容。首先,請新增 XML 版面配置檔案 custom_info_contents.xml,其中包含資訊視窗標題的文字檢視區塊,以及其他程式碼片段的文字檢視區塊 (即資訊視窗的文字內容):

      <?xml version="1.0" encoding="utf-8"?>
      <!--
       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.
      -->
      
      <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:layoutDirection="locale"
          android:orientation="vertical">
          <TextView
              android:id="@+id/title"
              android:layout_width="wrap_content"
              android:layout_height="wrap_content"
              android:layout_gravity="center_horizontal"
              android:textColor="#ff000000"
              android:textStyle="bold" />
      
          <TextView
              android:id="@+id/snippet"
              android:layout_width="wrap_content"
              android:layout_height="wrap_content"
              android:textColor="#ff7f7f7f" />
      </LinearLayout>
      
      
    6. 導入 InfoWindowAdapter 介面以加載版面配置,並載入資訊視窗內容:

      Java

      // Use a custom info window adapter to handle multiple lines of text in the
      // info window contents.
      this.map.setInfoWindowAdapter(new GoogleMap.InfoWindowAdapter() {
      
          @Override
          // Return null here, so that getInfoContents() is called next.
          public View getInfoWindow(Marker arg0) {
              return null;
          }
      
          @Override
          public View getInfoContents(Marker marker) {
              // Inflate the layouts for the info window, title and snippet.
              View infoWindow = getLayoutInflater().inflate(R.layout.custom_info_contents,
                      (FrameLayout) findViewById(R.id.map), false);
      
              TextView title = infoWindow.findViewById(R.id.title);
              title.setText(marker.getTitle());
      
              TextView snippet = infoWindow.findViewById(R.id.snippet);
              snippet.setText(marker.getSnippet());
      
              return infoWindow;
          }
      });
      

      Kotlin

      // Use a custom info window adapter to handle multiple lines of text in the
      // info window contents.
      this.map?.setInfoWindowAdapter(object : InfoWindowAdapter {
          // Return null here, so that getInfoContents() is called next.
          override fun getInfoWindow(arg0: Marker): View? {
              return null
          }
      
          override fun getInfoContents(marker: Marker): View {
              // Inflate the layouts for the info window, title and snippet.
              val infoWindow = layoutInflater.inflate(R.layout.custom_info_contents,
                  findViewById<FrameLayout>(R.id.map), false)
              val title = infoWindow.findViewById<TextView>(R.id.title)
              title.text = marker.title
              val snippet = infoWindow.findViewById<TextView>(R.id.snippet)
              snippet.text = marker.snippet
              return infoWindow
          }
      })
      

    儲存地圖的狀態

    儲存地圖的攝影機位置和裝置位置。當使用者旋轉 Android 裝置或變更設定時,Android 架構會銷毀並重建地圖活動。為確保使用者獲得流暢的使用體驗,建議您儲存相關的應用程式狀態,並在需要時復原。

    本教學課程會提供儲存地圖狀態時需要用到的所有程式碼。詳情請參閱 savedInstanceState 軟體包指南。

    1. 在地圖活動中設定存放活動狀態的鍵/值:

      Java

      private static final String KEY_CAMERA_POSITION = "camera_position";
      private static final String KEY_LOCATION = "location";
      

      Kotlin

      private const val KEY_CAMERA_POSITION = "camera_position"
      private const val KEY_LOCATION = "location"
      
    2. 執行 onSaveInstanceState() 回呼以在活動暫停時儲存狀態:

      Java

      @Override
      protected void onSaveInstanceState(Bundle outState) {
          if (map != null) {
              outState.putParcelable(KEY_CAMERA_POSITION, map.getCameraPosition());
              outState.putParcelable(KEY_LOCATION, lastKnownLocation);
          }
          super.onSaveInstanceState(outState);
      }
      

      Kotlin

      override fun onSaveInstanceState(outState: Bundle) {
          map?.let { map ->
              outState.putParcelable(KEY_CAMERA_POSITION, map.cameraPosition)
              outState.putParcelable(KEY_LOCATION, lastKnownLocation)
          }
          super.onSaveInstanceState(outState)
      }
      
    3. 在活動的 onCreate() 方法中,擷取裝置位置及地圖相機位置 (如果先前已儲存過):

      Java

      // Retrieve location and camera position from saved instance state.
      if (savedInstanceState != null) {
          lastKnownLocation = savedInstanceState.getParcelable(KEY_LOCATION);
          cameraPosition = savedInstanceState.getParcelable(KEY_CAMERA_POSITION);
      }
      

      Kotlin

      if (savedInstanceState != null) {
          lastKnownLocation = savedInstanceState.getParcelable(KEY_LOCATION)
          cameraPosition = savedInstanceState.getParcelable(KEY_CAMERA_POSITION)
      }