Android开发：如何检测Google Maps未加载成功？

一、SDK自带的状态检测方式 #

Google Maps Android SDK没有提供直接的加载失败回调接口，但可以通过OnMapReadyCallback + OnMapLoadedCallback结合超时检测的方式，实现对加载异常的判断：

• OnMapReadyCallback：获取到GoogleMap实例，代表地图初始化完成，但此时地图瓦片可能还在加载中。
• OnMapLoadedCallback：在地图所有瓦片加载完成、完全渲染后触发，是判断地图加载成功的核心标志。

二、实现超时检测与异常处理 #

通过Handler设置超时任务，若超过指定时间（比如10秒）OnMapLoadedCallback仍未触发，则判定为加载异常，执行提示或重加载逻辑：

private var googleMap: GoogleMap? = null
private var mapLoadHandler: Handler? = null
private val mapLoadTimeoutTask = Runnable {
    handleMapLoadFailure()
}

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    val mapFragment = childFragmentManager.findFragmentById(R.id.map_container) as SupportMapFragment
    mapFragment.getMapAsync(this)
}

override fun onMapReady(map: GoogleMap) {
    googleMap = map
    // 注册加载完成回调
    map.setOnMapLoadedCallback {
        mapLoadHandler?.removeCallbacks(mapLoadTimeoutTask)
        // 加载成功后的后续逻辑
    }
    // 启动10秒超时检测
    mapLoadHandler = Handler(Looper.getMainLooper())
    mapLoadHandler?.postDelayed(mapLoadTimeoutTask, 10000)
}

private fun handleMapLoadFailure() {
    // 弹窗提示用户加载失败并提供重试选项
    AlertDialog.Builder(requireContext())
        .setTitle("提示")
        .setMessage("地图加载失败，是否重试？")
        .setPositiveButton("重试") { _, _ -> reloadMap() }
        .setNegativeButton("取消", null)
        .show()
}

private fun reloadMap() {
    // 销毁并重建地图Fragment
    childFragmentManager.beginTransaction().apply {
        remove(childFragmentManager.findFragmentById(R.id.map_container)!!)
        add(R.id.map_container, SupportMapFragment.newInstance())
        commitNow()
    }
    // 重新绑定回调
    (childFragmentManager.findFragmentById(R.id.map_container) as SupportMapFragment)
        .getMapAsync(this)
}

override fun onDestroyView() {
    super.onDestroyView()
    mapLoadHandler?.removeCallbacks(mapLoadTimeoutTask)
}

三、额外的辅助检测手段 #

1. 网络可用性二次验证：虽然你提到网络正常，但可通过ConnectivityManager确认当前网络是否真的能访问外网（避免出现连接但无数据的情况）。
2. 日志排查：加载异常时，Logcat会输出Google Maps SDK的错误日志（如瓦片加载失败、API验证波动等），可用于定位偶发问题的根源。
3. 地图交互监听：若地图加载失败，灰色区域不会响应点击事件，可设置setOnMapClickListener，在超时后若用户点击无响应，直接触发重加载提示。

四、注意事项 #

• 确保API密钥的权限配置正确（启用Maps SDK for Android，SHA-1指纹与包名匹配），偶发异常可能源于服务器端的临时验证波动。
• 避免在onMapReady中执行过多耗时操作，以免阻塞地图瓦片加载。
• 在Fragment生命周期的onResume中可再次检查地图状态，若未完成加载，重新触发初始化逻辑。

内容的提问来源于stack exchange，提问作者Flironic