車輛應用程式

使用手冊程式碼範例

API 參考資料
androidx.car.app
androidx.car.app.model
androidx.car.app.navigation
androidx.car.app.notification
androidx.car.app.serialization
androidx.car.app.validation
androidx.car.app.versioning

打造 Android Auto 專用的導航、停車和充電應用程式。

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2022 年 3 月 23 日	1.1.0	1.2.0-rc01	-	-

宣告依附元件

如要為車輛應用程式程式庫新增依附元件，您必須為專案新增 Google Maven 存放區。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增您需要的構件依附元件：

Groovy

dependencies {
    implementation "androidx.car.app:app:1.1.0"

    // For Android Auto specific functionality
    implementation "androidx.car.app:app-projected:1.1.0"

    // For Android Automotive specific functionality
    implementation "androidx.car.app:app-automotive:1.1.0"

    // For testing
    testImplementation "androidx.car.app:app-testing:1.2.0-rc01"
}

Kotlin

dependencies {
    implementation("androidx.car.app:app:1.1.0")

    // For Android Auto specific functionality
    implementation("androidx.car.app:app-projected:1.1.0")

    // For Android Automotive specific functionality
    implementation("androidx.car.app:app-automotive:1.1.0")

    // For testing
    testImplementation("androidx.car.app:app-testing:1.2.0-rc01")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。發現新的問題或有改善這個程式庫的想法時，請告訴我們。請先查看此程式庫中的現有問題，再建立新的程式庫。只要點選星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.2 版本

1.2.0-rc01 版本

2022 年 3 月 23 日

發布 androidx.car.app:app-*:1.2.0-rc01。1.2.0-rc01 版包含這些修訂版本。

這是穩定版本，與 v1.2.0-beta02 相比沒有任何 API 異動。新增實驗功能 (API 級別 5)，預計在 Android Auto 和 Android Automotive 的未來版本中推出。

修正錯誤

修正在 State.DESTROYED 之後修改畫面堆疊時發生的例外狀況。(I3c8eb)
更新 CarSensors API，表示 AAOS 並未導入這些 API (Idd57b)
更新 PlaceListMapTempalte.Builder#setCurrentLocationEnabled，表示 ACCESS_COARSE_LOCATION 已可滿足未來的需求 (I510c2)
讓有指定角度的環島路駕駛方式可自選出口號碼 (Ife7d1)

1.2.0-beta02 版本

2022 年 1 月 26 日

androidx.car.app:app-*:1.2.0-beta02 發布。1.2.0-beta02 版本包含這些修訂版本。

凡是使用這個程式庫版本建立並指定 Android Automotive OS 平台的車輛應用程式，現在都可以發布到 Play 商店公開測試管道了。詳情請參閱開發指南。

加上 API 級別 4 以下註解的功能可相容於 Android Auto 7.2 以上和新的 Android Automotive OS 平台。請參閱下方的 Known Issues 一節，瞭解注意事項。

API 相關異動

已將實驗性 setOnContentRefreshListener API 新增到搜尋點範本 (I6bf22)

修正錯誤

修正車輛主機解除繫結時，CarAppService 中的記憶體流失問題。(I5c9ca，b/203594731)
更新 CarAppActivity javadoc，為 singleTask 啟動模式納入相關規定 (Id2f95)
減少繼續使用時的視覺故障。(Iff7e0)

已知問題

PlaceListNavigationTemplate 和 RoutePreviewNavigateTemplate 中的地圖 ActionStrip 將於下一個 Android Auto 和 Android Automotive OS 版本中推出。

1.2.0-alpha02 版本

2021 年 12 月 15 日

androidx.car.app:app-*:1.2.0-alpha02 發布。1.2.0-alpha02 版本包含這些修訂版本。

加上 API 級別 4 註解的功能已從實驗版升級為穩定版，包括 PlaceListNavigationTemplate 和 RoutePreviewNavigateTemplate 中的地圖 ActionStrip，Pane 中的 CarIcon 圖片、QRCodeSignInMethod 和在 Action 中設定算繪提示的功能 (例如旗標)。

新功能

在 Android Auto 7.1 以上版本中，Pane 的項目上限已從 2 個增加到 4 個。

API 相關異動

已將實驗性的 toString() 方法新增至 CarUnit(I36a3b)

修正錯誤

修正回呼失敗時 CarAppPermissionActivity 中發生的當機問題 (If9823)
已將 Pane 預設清單上限變更為 4 (I0068b)

1.2.0-alpha01 版本

2021 年 11 月 3 日

androidx.car.app:app-*:1.2.0-alpha01 發布。1.2.0-alpha01 版本包含這些修訂版本。

所有新的 v1.2.0 功能 (API 4+) 目前都在實驗階段，目標是在未來的 Android Auto 和 Android Automotive OS 版本中推出。詳情請參閱開發指南。

API 相關異動

AutomotiveCarInfo API 進入實驗階段 (Ia13e5)
新增 Car App Library API 級別 4 (I2a2e7)
API 級別 4：新增了在 Pane 中設定 CarIcon 的支援功能 (Ifcc12)
API 級別 4：新增了 QR 圖碼登入方法 (Ib623e)
API 級別 4：在 Action 中新增了設定/getFlags (Ic03ab)
API 級別 4：新增在 PlaceListNavigationTemplate 和 RoutePreviewNavigationTemplate 中支援平移和縮放的功能 (I9d8a3)

修正錯誤

API 級別 4：新增了允許應用程式將位置更新通知傳送至車輛主機的機制 (I3bad3)
修正主機驗證邏輯無法正確尋找 TEMPLATE_RENDERER 權限的問題 (I62618)

1.1.0 版本

2021 年 12 月 15 日

androidx.car.app:app-*:1.1.0 發布。1.1.0 版本包含這些修訂版本。

這是穩定版本，與 v1.1.0-rc01 相比沒有任何異動。另請參閱 v1.2.0-alpha02 的版本資訊，進一步瞭解車輛應用程式程式庫的新功能。

自 1.0.0 版以來的重要異動

API 級別 2：車輛停放時可用於登入流程的 SignInTemplate 和 LongMessageTemplate
API 級別 2：NavigationTemplate 中的地圖互動支援
API 級別 2：支援多重長度文字，讓應用程式能根據車輛螢幕尺寸提供多個版本的字串以供顯示。
API 級別 3：可用來查詢車輛硬體資料 (例如型號和品牌、油量和其他感應器) 的 CarHardwareManager。

1.1.0-rc01 版本

2021 年 11 月 3 日

androidx.car.app:app-*:1.1.0-rc01 發布。1.1.0-rc01 版本包含這些修訂版本。

這是穩定版本，與 v1.1.0-beta01 相比沒有任何 API 異動。已新增實驗性功能 (API 級別 4)，可望在 Android Auto 未來的版本中推出。如要進一步瞭解實驗性 API，請參閱 v1.2.0-alpha01 的版本資訊。

1.1.0-beta01 版本

2021 年 9 月 1 日

androidx.car.app:app-*:1.1.0-beta01 發布。1.1.0-beta01 版本包含這些修訂版本。

所有 v1.1.0 功能 (API 2+) 都完全相容於 Android Auto 6.7 以上版本。詳情請參閱開發指南。

API 相關異動

不再以 Manager 做為公共介面 (Ie381b)
新增為權限要求設定自訂品牌背景的功能 (I74b76)
新增 ScreenManager.getStackSize (I0b16a)
移除會明確採用 TestCarContext 的 ScreenController 建構函式 (Iefebc)

修正錯誤

新增建立 CarHardwareManager 時的 API 級別檢查 (I48f9b)
針對整個 API 的無效 CarSpan 用途新增檢查作業 (I65ae6)
修正以下問題：如果 Screen 在建立期間標示為完成，會使堆疊處於損毀狀態 (I81b13)
修正以下問題：如果 CarAppExtender 中有含圖示的動作，則 CarNotificationManager.notify 會為 AutomotiveOS 記錄一次錯誤 (I3633d)
為應用程式和主機新增握手方法，以建立 API 版本 (I7d6f8)

1.1.0-alpha02 版本

2021 年 7 月 21 日

androidx.car.app:app-*:1.1.0-alpha02 發布。1.1.0-alpha02版本包含這些修訂版本。

新功能

API 級別 3：新增 CarHardwareManager，可用來查詢車輛硬體資料，例如型號和品牌、油量和其他感應器。這項功能目前只開放 Android Auto 6.7 以上版本在公開測試頻道中使用。如要在電腦環境中測試這項功能，則需要使用新版 Desktop Head Unit (將另行發布)。請密切關注測試 Android 車輛應用程式網頁，掌握關於新版本推出時間的詳細資訊。
請參閱開發指南和程式庫參考資料瞭解詳情；設計指南則可協助您瞭解如何使用這些相容於 API 級別 3 的車輛主機中的功能。

API 相關異動

將 SessionController 和 ScreenController 生命週期方法合併至單一 moveToState 方法 (I1ed00)
新增 CarContext#getHostInfo() (I8977e)
移除已淘汰的欄位 (I67168)
更新 SessionController 和 ScreenController 以直接顯示建構函式 (Iabf22)
移除 PinSignInMethod.Builder 和 ProviderSignInMethod.Builder (I9f0cb)
新增「setCarAppResult()」以啟用在 AAOS 中使用範本應用程式「for result」的功能 (I37741)
以 @MainThread 為 CarHardware 介面加註。(Ib2f85)
OnCarDataListener 已重新命名為 OnCarDataAvailableListener (I518ca)
更新 CarInfo、Speed、Mileage 方法名稱和 javadoc (I86672)
Toll 已重新命名為 TollCard (I3e7c8)
移除已淘汰的 PinSignInMethod.getPin，替換成 PinSignInMethod.getPinCode (I996ce)
移除 OnInputCompletedListener，替換成 InputCallback (Ib5be1)
PinSignInMethod 改為採用 CharSequence 而非 String (I275d5)

修正錯誤

為車輛硬體修正 Javadoc (I2abbc)

外部貢獻

已知問題

在 SignInTemplate 中，使用 InputSignInMethod 可能會在車輛主機中造成 NullPointerException。我們會在下一個程式庫版本中解決這個問題。如要暫時繞過這個問題，請在您應用程式的 ProGuard 設定中納入這一行：-keep class androidx.car.app.model.signin.InputSignInMethod { *; }

1.1.0-alpha01 版本

2021 年 6 月 16 日

androidx.car.app:app:1.1.0-alpha01、androidx.car.app:app-automotive:1.1.0-alpha01 和 androidx.car.app:app-testing:1.1.0-alpha01 發布。1.1.0-alpha01 版本包含這些修訂版本。

新功能

API 級別 2：車輛停放時可用於登入流程的新 SignInTemplate 和 LongMessageTemplate
API 級別 2：NavigationTemplate 中的新地圖互動支援
API 級別 2：支援新的多重長度文字，讓應用程式能根據車輛螢幕尺寸提供多個版本的字串以供顯示。
請參閱開發指南和程式庫 Javadoc 瞭解詳情；設計指南則可協助您瞭解如何使用這些相容於 API 級別 2 的車輛主機中的功能。

API 相關異動

將所有 *Callback 介面方法設為預設，並將 OnRequestPermissionsCallback 重新命名為 OnRequestPermissionsListener (Ib3ec9)
更新 androidx.car.app.hardware 類別以移除不必要的建構工具和參數類別 (I67beb)
新增 androidx.car.app.hardware 類別以存取車輛專屬資料，例如燃料、電池和速度 (Iff3c9)
在 MessageTemplate 上新增 ActionStrip 支援 (Ida657)
將 setLoading 新增至 MessageTemplate (I2a4b5)
ConnectionToCar 已重新命名為 CarConnection (Ife9bd)
將 NavigationTemplate 變更為會傳回明確的 PanModeDelegate (I13877)
更新 CarContext.requestPermissions 的參數順序 (Ib890a)
更新中繼資料金鑰，將最低車輛 API 級別定義為 androidx.car.api.minCarApiLevel (Ib0d41)
建立允許觀察車輛連線狀態的 API (Ifc935)
新增可為 Action 設定切換開關的功能，並新增平移模式 Action 類型 (Ica6af)
建立了 CarNotificationManager 以支援在車上傳送通知的功能 (I10d7a)
新增 ConstraintManager 以提供主機的清單限制 (I8690e)
在 NavigationTemplate 中新增移模式和地圖操作清除 API (I77aa6)
在 SurfaceCallback 中為導航應用程式新增平移和縮放 API (Id5e9d)
將 CarAppApiLevel 更新為 2 (Ic1540)
新增可向 CarAppService 要求權限的功能 (I5421e)
將 RequiresCarApi(2) 註解新增至多重文字 API (Iacb62)
在半清單範本標題中允許多種文字變化版本 (Ib8df7)
新增 LongMessageTemplate (需要 Car API 級別 2) (Ic5cee)

修正錯誤

更新圖片大小規定，以配合較大的車輛螢幕 (I116dc)
不允許在範本內文中加入超過 2 個動作 (I32157)
已確保車輛應用程式程式庫中所有的 PendingIntent 建立作業都會設定旗標。(If84fe，b/186394900)
更新 javadoc，允許 Row 的文字在重新整理時變更 (If3f9c)
androidx.activity:activity:1.2.0 現在是 API 依附元件 (Id1cb9)
將 SignInTemplate 和 LongMessageTemplate 設為在內文中要求僅限停車狀態動作，並更新說明文件，指明只有在車子停好時，才會顯示這兩者 (Iddaa9)
修正啟動期間彈出 Screen 時發生的例外狀況 (Ifcf40，b/184664896)
允許在 ForegroundCarColorSpan 中自訂文字顏色 (I69e59)
修正在某個 Screen 的 ON_DESTROY 之後，還會看到 Session 上的 ON_DESTROY 的問題 (I52e01，b/183696617)
更新 javadoc，說明何時允許將 TravelEstimate 的剩餘時間設為不明的時間。(I99610，b/183632456)
更新 Action，以支援標題中的 ForegroundColorSpan 以及任何自訂背景色彩 (I578e4)
如果在執行工具執行前已清除回呼，就不執行 NavigationManagerCallback#onStopNavigation (I7fc5e，b/181143772)
修正以下問題：要求應用程式必須在 lifecycle-common-java8 上明確採用依附元件 (I8b8c8)

已知問題

在 SignInTemplate 中，當使用者想要確認輸入內容時，螢幕小鍵盤會顯示「搜尋」圖示，而不是「輸入」圖示。輸入欄位成為焦點時，系統會啟動手機鍵盤，使用者可以存取這個鍵盤，當做暫時的因應方法。
在 Android Auto 6.5 版中，某些觸控手勢可能會錯誤叫用 SurfaceCallback 中的平移和縮放回呼。