如何在Android Fragment中完成Google Maps API的集成？

云原生阿岚

2026-5-22

嘿，你已经搞定了前期的关键准备工作，接下来我带你一步步走完剩余的Google Maps API集成到Android Fragment的完整流程，保证你能顺利跑起来：

完整Google Maps API集成到Android Fragment流程

第一步：添加Gradle依赖（容易漏掉的关键项）

在你app模块的build.gradle（Module级别）的dependencies块中，添加Google Maps的核心依赖，要是需要位置服务功能也可以一并加上：

dependencies {
    // Google Maps SDK核心依赖
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
    // 可选：如果需要获取用户位置等功能，添加这个
    implementation 'com.google.android.gms:play-services-location:21.0.1'
}

添加完记得点击同步Gradle，确保依赖下载完成。

第二步：补全Fragment布局文件

你已经写了布局开头，现在把MapView组件加进去，完整的fragment_map.xml示例（以RelativeLayout为根布局）：

<RelativeLayout 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"
    tools:context=".ui.MapFragment">

    <!-- Google MapView组件，占满整个布局 -->
    <com.google.android.gms.maps.MapView
        android:id="@+id/map_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</RelativeLayout>

第三步：编写Fragment的业务代码

这里给你提供Kotlin和Java两种版本的实现，按需选择：

Kotlin版本（MapFragment.kt）

import android.os.Bundle
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import androidx.fragment.app.Fragment
import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.MapView
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

class MapFragment : Fragment(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap
    private lateinit var mapView: MapView

    // 用于保存MapView状态的常量
    companion object {
        private const val MAP_VIEW_BUNDLE_KEY = "MapViewBundleKey"
    }

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View? {
        return inflater.inflate(R.layout.fragment_map, container, false)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        mapView = view.findViewById(R.id.map_view)
        
        // 恢复MapView的保存状态
        val mapViewBundle = savedInstanceState?.getBundle(MAP_VIEW_BUNDLE_KEY)
        mapView.onCreate(mapViewBundle)
        // 监听地图加载完成事件
        mapView.getMapAsync(this)
    }

    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // 示例：添加标记并将相机移动到纽约位置
        val newYork = LatLng(40.7128, -74.0060)
        mMap.addMarker(MarkerOptions().position(newYork).title("Marker in New York"))
        mMap.moveCamera(CameraUpdateFactory.newLatLngZoom(newYork, 12f))

        // 可选：启用地图交互控件
        mMap.uiSettings.isZoomControlsEnabled = true
        mMap.uiSettings.isCompassEnabled = true
    }

    // 必须重写MapView对应的生命周期方法，避免地图异常
    override fun onStart() {
        super.onStart()
        mapView.onStart()
    }

    override fun onResume() {
        super.onResume()
        mapView.onResume()
    }

    override fun onPause() {
        super.onPause()
        mapView.onPause()
    }

    override fun onStop() {
        super.onStop()
        mapView.onStop()
    }

    override fun onDestroy() {
        super.onDestroy()
        mapView.onDestroy()
    }

    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        var mapViewBundle = outState.getBundle(MAP_VIEW_BUNDLE_KEY)
        if (mapViewBundle == null) {
            mapViewBundle = Bundle()
            outState.putBundle(MAP_VIEW_BUNDLE_KEY, mapViewBundle)
        }
        mapView.onSaveInstanceState(mapViewBundle)
    }

    override fun onLowMemory() {
        super.onLowMemory()
        mapView.onLowMemory()
    }
}

Java版本（MapFragment.java）

import android.os.Bundle;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.fragment.app.Fragment;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.MapView;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapFragment extends Fragment implements OnMapReadyCallback {

    private GoogleMap mMap;
    private MapView mapView;
    private static final String MAP_VIEW_BUNDLE_KEY = "MapViewBundleKey";

    @Nullable
    @Override
    public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) {
        return inflater.inflate(R.layout.fragment_map, container, false);
    }

    @Override
    public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
        super.onViewCreated(view, savedInstanceState);
        mapView = view.findViewById(R.id.map_view);
        
        Bundle mapViewBundle = null;
        if (savedInstanceState != null) {
            mapViewBundle = savedInstanceState.getBundle(MAP_VIEW_BUNDLE_KEY);
        }
        mapView.onCreate(mapViewBundle);
        mapView.getMapAsync(this);
    }

    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // 示例：添加纽约位置的标记
        LatLng newYork = new LatLng(40.7128, -74.0060);
        mMap.addMarker(new MarkerOptions().position(newYork).title("Marker in New York"));
        mMap.moveCamera(CameraUpdateFactory.newLatLngZoom(newYork, 12f));

        // 启用基础交互控件
        mMap.getUiSettings().setZoomControlsEnabled(true);
        mMap.getUiSettings().setCompassEnabled(true);
    }

    @Override
    public void onStart() {
        super.onStart();
        mapView.onStart();
    }

    @Override
    public void onResume() {
        super.onResume();
        mapView.onResume();
    }

    @Override
    public void onPause() {
        super.onPause();
        mapView.onPause();
    }

    @Override
    public void onStop() {
        super.onStop();
        mapView.onStop();
    }

    @Override
    public void onDestroy() {
        super.onDestroy();
        mapView.onDestroy();
    }

    @Override
    public void onSaveInstanceState(@NonNull Bundle outState) {
        super.onSaveInstanceState(outState);
        Bundle mapViewBundle = outState.getBundle(MAP_VIEW_BUNDLE_KEY);
        if (mapViewBundle == null) {
            mapViewBundle = new Bundle();
            outState.putBundle(MAP_VIEW_BUNDLE_KEY, mapViewBundle);
        }
        mapView.onSaveInstanceState(mapViewBundle);
    }

    @Override
    public void onLowMemory() {
        super.onLowMemory();
        mapView.onLowMemory();
    }
}

第四步：测试与常见问题排查

确认API Key已启用Maps SDK for Android：登录Google Cloud控制台，找到你的项目，在API库中搜索并启用该服务，否则地图会显示空白。
权限检查：如果需要获取用户位置，在AndroidManifest.xml中添加必要权限：

<!-- 网络权限（地图加载必须） -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- 位置权限（按需添加） -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

空白地图排查：如果运行后地图空白，查看Logcat的错误信息，常见原因是API Key无效、服务未启用、权限不足或网络问题。

内容的提问来源于stack exchange，提问作者Sergio Iglesias Garcia

如何在Android Fragment中完成Google Maps API的集成？

第一步：添加Gradle依赖（容易漏掉的关键项） #

第二步：补全Fragment布局文件 #

第三步：编写Fragment的业务代码 #

Kotlin版本（MapFragment.kt） #

Java版本（MapFragment.java） #