使用 Maps URLs 開啟 Google Maps 的路徑規劃功能

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

package tw.dh46.ithome23.sample.intent  
  
import android.content.Context  
import android.content.Intent  
import android.net.Uri  
import com.google.android.gms.maps.model.LatLng  
  
/**  
 * Created by danielhuang on 2025/2/7 
 * GoogleMapsIntentHelper 是一個工具類，用於使用 Google Maps App 啟動導航功能。  
 */  
object GoogleMapsIntentHelper {  
  
    // Google Maps 路徑規劃的基礎 URL    
    private const val MAPS_BASE_URL = "https://www.google.com/maps/dir/?"  
    // Google Maps 最大停靠點數  
    private const val MAX_WAYPOINTS = 8  
  
    /**  
     * 啟動 Google Maps 導航功能  
     *  
     * @param context  
     * @param navRequest 導航請求的詳細資料，包括起點、終點、停靠點與交通模式  
     */  
    fun startNavDirection(  
        context: Context,  
        navRequest: NavRequest  
    ) {  
        // 建立 Navigation URL        
        val navigationUrl = buildNavigationUrl(navRequest)  
  
        // 建立 Intent 並設定目標為 Google Maps App
        val intent = Intent(Intent.ACTION_VIEW, Uri.parse(navigationUrl))  
            .apply {  
                // 確保使用 Google Maps App                
                setPackage("com.google.android.apps.maps")  
            }  
  
        // 檢查是否安裝 Google Maps，並啟動導航  
        if (intent.resolveActivity(context.packageManager) != null) {  
            context.startActivity(intent)
        } else {  
            throw GoogleMapsNotFoundException()  
        }  
    }  
  
    /**  
     * 建立完整的導航 URL
     * @param navRequest  
     * @return  
     */  
    private fun buildNavigationUrl(navRequest: NavRequest): String {  
        // 固定參數  
        val apiType = "api=1"  
        // 起點  
        val originStr = "&origin=${navRequest.origin.latitude},${navRequest.origin.longitude}"  
        // 終點  
        val destinationStr =  
            "&destination=${navRequest.destination.latitude},${navRequest.destination.longitude}"  
        // 導航模式  
        val travelMode = "&travelmode=${navRequest.travelMode.value}"  
  
        // 轉換停靠點成字串格式  
        val waypointsStr = navRequest.waypoints.toWaypointsStr()  
  
        // 建立完整的導航 URL        
        return "$MAPS_BASE_URL$apiType$originStr$destinationStr$travelMode$waypointsStr"  
    }  
  
    /**  
     * 將停靠點座標列表轉換為 Google Maps URL 所需的字串格式  
     *  
     * @return 停靠點的字串，若無停靠點則為空字串  
     */  
    private fun List<LatLng>?.toWaypointsStr(): String {  
        if (isNullOrEmpty()) return ""  
  
        if (size > MAX_WAYPOINTS) {  
            throw TooManyWayPointsException()  
        }  
  
        val points = this.joinToString("|") {  
            "${it.latitude},${it.longitude}"  
        }  
        return "&waypoints=$points"  
    }  
  
    /**  
     * 導航模式  
     *  
     * @property value value 對應於 Google Maps 的導航模式參數值  
     * @constructor Create empty Travel mode  
     */    
     enum class TravelMode(val value: String) {  
        DRIVE("drive"), // 開車  
        WALKING("walking"), // 步行  
        BICYCLING("bicycling"), // 騎自行車  
        TRANSIT("transit"), // 大眾交通工具  
        TWO_WHEELER("two-wheeler") // 雙輪車 (如摩托車)  
    }  
  
    /**  
     * 導航請求的資料類  
     *  
     * @param origin 起點座標  
     * @param destination 終點座標  
     * @param waypoints 停靠點列表 (最多 8 個)  
     * @param travelMode 交通模式，預設為開車模式  
     */  
    data class NavRequest(  
        val origin: LatLng,  
        val destination: LatLng,  
        val waypoints: List<LatLng>? = null,  
        val travelMode: TravelMode = TravelMode.DRIVE  
    )  
}  
  
class GoogleMapsNotFoundException: RuntimeException("No Google Maps app found on device")  
  
class TooManyWayPointsException: IllegalArgumentException("Way points cannot exceed 8!")